Quorin (pronounced KWOR-in) is the set of TypeScript utilities I use on almost every project: data structures, bytes, safe object access, bounded async work and channels, explicit results, validation, retries, caching, and log-safe state. Zero runtime dependencies, and every module plays by the same rules.
import { Channel, select } from 'quorin/async';
import { createCache } from 'quorin/cache';
import { withResilience } from 'quorin/resilience';
Status:
0.2.0preview. The API may still change before1.0.
See each primitive in motion, next to the quick version it replaces, on the visualizer site.
Why I built it
Quorin is the toolkit I kept rewriting. Whatever the project, an API, a background worker, or an app talking to flaky services, I end up building the same pieces before I can get to the actual product: a timeout that really cancels, a retry that only retries what is safe, a cache that collapses a burst of identical requests, a queue that pushes back instead of growing forever, validation at the edges, and a way to log objects without leaking tokens.
The quick versions always came with the same bugs:
- A
Promise.racetimeout stops waiting, but the request keeps running and its late rejection goes unhandled. - Helpers from different packages disagree on what an
AbortSignalmeans, so cancelling frees a slot in one and leaks it in another. - Retries fire on anything that throws, including requests that are not safe to repeat.
- Treating every
TypeErroras a bug also hides network failures, becausefetchthrowsTypeErrortoo. - An unbounded in-memory queue quietly grows until the process falls over.
- A late response overwrites newer cached data, and deep clones break the moment a method touches a private field.
So I pulled the versions I trust out of my day-to-day work into one library, gave them one set of rules, and tested them hard enough that I stop thinking about them:
- One cancellation model. Every async API takes an
AbortSignal, stops waiting promptly, and still accounts for work that ignores the signal. - Failures you can check. Results are real
[error, data]tuples with.ok, and every library error has a stablecode. - Clear ownership. Each function says whether it copies, mutates, or returns references.
- Bounded by default. Queues, caches, and in-flight work all have limits.
- Testable time. Timers run on an injectable clock, so tests advance fake time instead of sleeping.
The name comes from quorum, the smallest group that has to be present before a body can act: just enough primitives to make async work, data handling, and failure handling dependable.
Install
npm install quorin
One ESM build with type declarations. require('quorin') also works on every supported Node version. See compatibility for runtimes and TypeScript settings.
Quick start
A profile loader that validates input, coalesces concurrent requests, serves stale data while refreshing, and retries transient failures within a deadline:
import { z } from 'zod';
import { defineBoundary } from 'quorin/boundary';
import { createCache } from 'quorin/cache';
import { withResilience } from 'quorin/resilience';
const profiles = createCache<string, Profile>({
max: 500,
ttlMs: 30_000,
swrMs: 10_000,
load: async (id, { signal }) => {
const result = await withResilience(({ signal }) => fetchProfile(id, signal), {
signal,
retries: 2,
retrySafe: true,
shouldRetry: (error) => error instanceof TransientError,
attemptTimeoutMs: 2_000,
totalTimeoutMs: 6_000,
});
if (!result.ok) throw result.error;
return result.data;
},
});
const getProfile = defineBoundary(z.string().uuid(), (id) => profiles.getOrFetch(id));
const outcome = await getProfile(untrustedInput);
if (outcome.ok) render(outcome.data);
else report(outcome.error);
A worker pool fed by a bounded channel, where the first failure cancels the rest:
import { Channel, createTaskGroup } from 'quorin/async';
const jobs = new Channel<Job>(32);
const workers = createTaskGroup({ signal });
for (let i = 0; i < 4; i++) {
workers.run(async ({ signal }) => {
for await (const job of jobs.values({ signal })) await handle(job, signal);
});
}
for (const job of await loadJobs()) await jobs.send(job, { signal });
jobs.close();
const result = await workers.wait();
Modules
Import from the root or from a subpath. Both resolve to the same objects, and importing has no side effects.
| Subpath | Use it for | Docs |
|---|---|---|
quorin/struct |
Deque, ValueMap (structural keys), Multimap |
struct |
quorin/object |
Safe getPath/setPath, deepMerge, stableStringify |
object |
quorin/bytes |
UTF-8, strict hex and base64, fastHash |
bytes |
quorin/async |
Concurrency limits, mapAsync, rate limiting, singleFlight |
async |
quorin/async |
Channel, select, spawn, task groups, mutexes, tick |
concurrency |
quorin/signal |
onAbort, timeoutSignal |
signal |
quorin/result |
SafeResult, ok, err, trySafe |
result |
quorin/boundary |
Standard Schema validation: parseEnv, defineBoundary |
boundary |
quorin/resilience |
withResilience retries and deadlines, parseRetryAfter |
resilience |
quorin/cache |
LRU cache with TTL, stale-while-revalidate, coalesced loads | cache |
quorin/state |
safeClone, isEqual, redact |
state |
Shared behavior is documented once: errors and cancellation.
Agent skill
Quorin ships an agent skill that teaches coding agents how to use it, build on it, and contribute to it. Install it with the skills CLI:
npx skills add arnonsang/quorin
Contributing
npm run check runs typechecking, the skill examples, tests with coverage thresholds, and packed-package tests. See development for the layout and release process.
License
MIT. The vendored Standard Schema type declarations are MIT licensed by their authors; see THIRD_PARTY_NOTICES.md.