inflight-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Farhad Arjmand
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+<div align="center">
+
+# inflight-kit
+
+**Share the work. Keep your own cancel button.**
+
+[![npm version](https://img.shields.io/npm/v/inflight-kit.svg)](https://www.npmjs.com/package/inflight-kit)
+[![CI](https://github.com/farhad-arjmand/inflight-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/farhad-arjmand/inflight-kit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+One pending operation per key. Independent cancellation and deadlines for every caller.
+
+Zero runtime dependencies · TypeScript · ESM + CommonJS · Node.js 20+
+
+</div>
+
+```sh
+npm install inflight-kit
+```
+
+## The problem
+
+Three components ask for the same user. Three requests hit your API. You share a promise to fix it—then one component unmounts and aborts the request for everyone.
+
+`inflight-kit` gives each caller its own promise, signal and deadline, while sharing one underlying operation. The worker receives a separate signal that aborts only when the last caller leaves (or you explicitly cancel the key).
+
+```text
+Caller A ── run("user:42") ─┐
+Caller B ── run("user:42") ─┼── ONE worker ── API
+Caller C ── run("user:42") ─┘
+
+A cancels → A rejects; B and C still receive the result.
+All cancel → the worker's signal aborts.
+Done → the key is removed. The next call starts fresh.
+```
+
+## Start here
+
+```ts
+import { createFlight } from 'inflight-kit';
+
+type User = { id: string; name: string };
+
+// Keep this instance outside the function that calls it.
+const users = createFlight(async (id: string, signal): Promise<User> => {
+  const response = await fetch(`/api/users/${encodeURIComponent(id)}`, { signal });
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json(); // Validate untrusted data here if your app needs it.
+});
+
+const controller = new AbortController();
+const first = users.run('42', { signal: controller.signal });
+const second = users.run('42', { timeoutMs: 3000 });
+
+// Attach handlers before cancellation, as with any promise.
+const results = Promise.allSettled([first, second]);
+controller.abort();
+console.log(await results); // first rejects; second can still succeed
+```
+
+**Parse responses inside the worker.** A shared `Response` has a single-use body. Share the parsed value instead, and treat shared objects as immutable.
+
+## Useful places to use it
+
+- Coalesce repeated profile, settings or metadata reads across components.
+- Collapse a burst of cache misses for one key into a single database lookup.
+- Share an expensive computation while each caller keeps its own deadline.
+- Deduplicate token refresh calls **within the same authenticated session**.
+
+This is in-process coordination. Multiple server processes need a distributed solution if they must coordinate with one another.
+
+## API
+
+### `createFlight(worker, options?)`
+
+The worker is `(key, sharedSignal) => value | PromiseLike<value>`. Key and result types are inferred from it. Synchronous throws and asynchronous rejections reach every remaining caller. Work begins in a microtask so same-turn calls can join before execution.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `maxKeys` | `1024` | Maximum currently tracked keys |
+| `maxWaitersPerKey` | `1024` | Maximum callers waiting on one key |
+
+Limits are positive safe integers. Excess callers reject with `CapacityError` and its `limit` field. There is no hidden queue. Existing keys can still accept callers when `maxKeys` is reached, up to their own waiter limit.
+
+### `flight.run(key, { signal?, timeoutMs? }?)`
+
+Returns a separate `Promise<V>` for each caller. Same-key calls share the worker while it is pending. `timeoutMs` is a per-caller deadline, an integer between `1` and `2147483647`. Deadline expiry rejects with a `DOMException` named `TimeoutError`; abort preserves `signal.reason`. An already-aborted caller never starts or joins work.
+
+A deadline uses the runtime's timer: it cannot interrupt blocking synchronous JavaScript. Handle returned promises to avoid unhandled rejections.
+
+### Control and inspection
+
+```ts
+users.size;             // number of tracked keys
+users.has('42');         // is this key pending?
+users.waiters('42');     // number of callers still waiting
+users.cancel('42');      // reject callers, abort worker, remove key; returns boolean
+users.clear();          // cancel a snapshot of all currently tracked keys
+```
+
+`cancel(key, reason?)` and `clear(reason?)` accept a custom rejection reason. They default to an `AbortError`. A new call may immediately start a replacement operation. Late results from old work cannot delete or settle that replacement.
+
+## Boundaries that matter
+
+- **Keys are your isolation boundary.** Include tenant, user, permission scope and relevant parameters. Do not share a key between different authorization contexts. Avoid putting secrets directly in keys.
+- **Map semantics apply.** Strings compare by value; object keys compare by identity. There is no implicit JSON serialization or hashing.
+- **No settled cache, retries or rate limiting.** Once work settles, its key is removed. Use your existing cache around the worker if you need cached values.
+- **Cancellation is cooperative.** Pass the worker's signal to `fetch` or another cancellation-aware operation. Ignoring it can leave physical work running after its key is removed. Admission limits bound tracked work, not uncancellable operations.
+- **Reads and safe computations are the intended use.** Deduplicating writes can suppress actions that were meant to happen separately.
+- **Do not recursively await the same flight/key inside its worker.** That would wait on itself.
+- Runtime uses standard `Map`, `Promise`, `AbortController`, `DOMException` and timers. Node.js 20/22/24 are tested in CI; modern browser ESM is smoke-tested separately during development. No Node-specific runtime imports.
+
+## Why another async utility?
+
+The focus is a small combination: keyed pending-work sharing, **independent caller lifetimes**, cooperative last-caller cancellation, and bounded admission. If you need a query cache, use a query cache. If you need a concurrency queue or distributed lock, use one. This package deliberately keeps a single typed worker per instance so callers cannot accidentally associate incompatible result types with the same key.
+
+The singleflight pattern predates this project; see [Go's singleflight](https://pkg.go.dev/golang.org/x/sync/singleflight) and the cancellation-aware [janos/singleflight](https://github.com/janos/singleflight). This JavaScript implementation is independent.
+
+## Run the demo and tests
+
+```sh
+git clone https://github.com/farhad-arjmand/inflight-kit.git
+cd inflight-kit
+npm ci
+npm run demo
+npm run check
+```
+
+The local demo starts a real HTTP server and compares 100 direct requests with 100 coalesced callers. It measures upstream request count, not a performance speedup claim.
+
+See [contributing](CONTRIBUTING.md), [security](SECURITY.md) and [changelog](CHANGELOG.md).
+
+## License
+
+MIT © Farhad Arjmand

package/dist/cjs/index.d.ts

@@ -0,0 +1,31 @@
+/** A caller was refused because the configured admission limit was reached. */
+export declare class CapacityError extends Error {
+    readonly limit: 'maxKeys' | 'maxWaitersPerKey';
+    readonly name = "CapacityError";
+    constructor(limit: 'maxKeys' | 'maxWaitersPerKey');
+}
+export interface FlightOptions {
+    /** Maximum tracked keys. Default: 1024. */
+    maxKeys?: number;
+    /** Maximum simultaneous callers for one key. Default: 1024. */
+    maxWaitersPerKey?: number;
+}
+export interface RunOptions {
+    /** Cancels only this caller, unless it is the last caller. */
+    signal?: AbortSignal;
+    /** Per-caller deadline, in milliseconds (1 to 2147483647). */
+    timeoutMs?: number;
+}
+export interface Flight<K, V> {
+    run(key: K, options?: RunOptions): Promise<V>;
+    /** Tracked keys, not physical operations that ignore cancellation. */
+    readonly size: number;
+    has(key: K): boolean;
+    waiters(key: K): number;
+    /** Reject current callers and request cooperative cancellation. */
+    cancel(key: K, reason?: unknown): boolean;
+    /** Cancel a snapshot of all currently tracked keys. */
+    clear(reason?: unknown): void;
+}
+/** One worker per key while callers are waiting. Results and failures are never cached. */
+export declare function createFlight<K, V>(worker: (key: K, signal: AbortSignal) => V | PromiseLike<V>, options?: FlightOptions): Flight<K, V>;

package/dist/cjs/index.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapacityError = void 0;
+exports.createFlight = createFlight;
+/** A caller was refused because the configured admission limit was reached. */
+class CapacityError extends Error {
+    limit;
+    name = 'CapacityError';
+    constructor(limit) {
+        super(`inflight-kit: ${limit} reached`);
+        this.limit = limit;
+    }
+}
+exports.CapacityError = CapacityError;
+const aborted = () => new DOMException('The operation was aborted', 'AbortError');
+function positive(value, name) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RangeError(`${name} must be a positive safe integer`);
+    return value;
+}
+/** One worker per key while callers are waiting. Results and failures are never cached. */
+function createFlight(worker, options = {}) {
+    if (typeof worker !== 'function')
+        throw new TypeError('worker must be a function');
+    const maxKeys = positive(options.maxKeys ?? 1024, 'maxKeys');
+    const maxWaiters = positive(options.maxWaitersPerKey ?? 1024, 'maxWaitersPerKey');
+    const entries = new Map();
+    function detach(key, entry) {
+        entry.done = true;
+        if (entries.get(key) === entry)
+            entries.delete(key);
+    }
+    function finish(key, entry, ok, value) {
+        if (entry.done)
+            return;
+        detach(key, entry);
+        for (const waiter of entry.waiters) {
+            waiter.cleanup();
+            if (ok)
+                waiter.resolve(value);
+            else
+                waiter.reject(value);
+        }
+        entry.waiters.clear();
+    }
+    function cancelEntry(key, entry, reason) {
+        finish(key, entry, false, reason);
+        entry.controller.abort(reason);
+    }
+    return {
+        get size() { return entries.size; },
+        has: key => entries.has(key),
+        waiters: key => entries.get(key)?.waiters.size ?? 0,
+        cancel(key, reason = aborted()) {
+            const entry = entries.get(key);
+            if (!entry)
+                return false;
+            cancelEntry(key, entry, reason);
+            return true;
+        },
+        clear(reason = aborted()) {
+            for (const [key, entry] of [...entries])
+                cancelEntry(key, entry, reason);
+        },
+        run(key, runOptions = {}) {
+            // Reject invalid run options through the returned promise, like worker errors.
+            return new Promise((resolve, reject) => {
+                const { signal, timeoutMs } = runOptions;
+                if (timeoutMs !== undefined && (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647)) {
+                    throw new RangeError('timeoutMs must be an integer from 1 to 2147483647');
+                }
+                if (signal?.aborted) {
+                    reject(signal.reason);
+                    return;
+                }
+                let entry = entries.get(key);
+                const fresh = !entry;
+                if (!entry) {
+                    if (entries.size >= maxKeys) {
+                        reject(new CapacityError('maxKeys'));
+                        return;
+                    }
+                    entry = { controller: new AbortController(), waiters: new Set(), done: false };
+                    entries.set(key, entry);
+                }
+                if (entry.waiters.size >= maxWaiters) {
+                    reject(new CapacityError('maxWaitersPerKey'));
+                    return;
+                }
+                const current = entry;
+                let timer;
+                const leave = (reason) => {
+                    if (!current.waiters.delete(waiter))
+                        return;
+                    waiter.cleanup();
+                    reject(reason);
+                    if (!current.done && current.waiters.size === 0) {
+                        detach(key, current);
+                        current.controller.abort(reason);
+                    }
+                };
+                const onAbort = () => leave(signal.reason);
+                const waiter = {
+                    resolve, reject,
+                    cleanup() {
+                        if (timer !== undefined)
+                            clearTimeout(timer);
+                        signal?.removeEventListener('abort', onAbort);
+                    },
+                };
+                current.waiters.add(waiter);
+                signal?.addEventListener('abort', onAbort, { once: true });
+                if (timeoutMs !== undefined)
+                    timer = setTimeout(() => leave(new DOMException('The caller deadline expired', 'TimeoutError')), timeoutMs);
+                if (fresh) {
+                    // Defer the worker so callers in the same turn can join or cancel first.
+                    void Promise.resolve().then(() => {
+                        if (current.done)
+                            return;
+                        return worker(key, current.controller.signal);
+                    }).then(value => finish(key, current, true, value), error => finish(key, current, false, error));
+                }
+            });
+        },
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,31 @@
+/** A caller was refused because the configured admission limit was reached. */
+export declare class CapacityError extends Error {
+    readonly limit: 'maxKeys' | 'maxWaitersPerKey';
+    readonly name = "CapacityError";
+    constructor(limit: 'maxKeys' | 'maxWaitersPerKey');
+}
+export interface FlightOptions {
+    /** Maximum tracked keys. Default: 1024. */
+    maxKeys?: number;
+    /** Maximum simultaneous callers for one key. Default: 1024. */
+    maxWaitersPerKey?: number;
+}
+export interface RunOptions {
+    /** Cancels only this caller, unless it is the last caller. */
+    signal?: AbortSignal;
+    /** Per-caller deadline, in milliseconds (1 to 2147483647). */
+    timeoutMs?: number;
+}
+export interface Flight<K, V> {
+    run(key: K, options?: RunOptions): Promise<V>;
+    /** Tracked keys, not physical operations that ignore cancellation. */
+    readonly size: number;
+    has(key: K): boolean;
+    waiters(key: K): number;
+    /** Reject current callers and request cooperative cancellation. */
+    cancel(key: K, reason?: unknown): boolean;
+    /** Cancel a snapshot of all currently tracked keys. */
+    clear(reason?: unknown): void;
+}
+/** One worker per key while callers are waiting. Results and failures are never cached. */
+export declare function createFlight<K, V>(worker: (key: K, signal: AbortSignal) => V | PromiseLike<V>, options?: FlightOptions): Flight<K, V>;

package/dist/esm/index.js

@@ -0,0 +1,121 @@
+/** A caller was refused because the configured admission limit was reached. */
+export class CapacityError extends Error {
+    limit;
+    name = 'CapacityError';
+    constructor(limit) {
+        super(`inflight-kit: ${limit} reached`);
+        this.limit = limit;
+    }
+}
+const aborted = () => new DOMException('The operation was aborted', 'AbortError');
+function positive(value, name) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RangeError(`${name} must be a positive safe integer`);
+    return value;
+}
+/** One worker per key while callers are waiting. Results and failures are never cached. */
+export function createFlight(worker, options = {}) {
+    if (typeof worker !== 'function')
+        throw new TypeError('worker must be a function');
+    const maxKeys = positive(options.maxKeys ?? 1024, 'maxKeys');
+    const maxWaiters = positive(options.maxWaitersPerKey ?? 1024, 'maxWaitersPerKey');
+    const entries = new Map();
+    function detach(key, entry) {
+        entry.done = true;
+        if (entries.get(key) === entry)
+            entries.delete(key);
+    }
+    function finish(key, entry, ok, value) {
+        if (entry.done)
+            return;
+        detach(key, entry);
+        for (const waiter of entry.waiters) {
+            waiter.cleanup();
+            if (ok)
+                waiter.resolve(value);
+            else
+                waiter.reject(value);
+        }
+        entry.waiters.clear();
+    }
+    function cancelEntry(key, entry, reason) {
+        finish(key, entry, false, reason);
+        entry.controller.abort(reason);
+    }
+    return {
+        get size() { return entries.size; },
+        has: key => entries.has(key),
+        waiters: key => entries.get(key)?.waiters.size ?? 0,
+        cancel(key, reason = aborted()) {
+            const entry = entries.get(key);
+            if (!entry)
+                return false;
+            cancelEntry(key, entry, reason);
+            return true;
+        },
+        clear(reason = aborted()) {
+            for (const [key, entry] of [...entries])
+                cancelEntry(key, entry, reason);
+        },
+        run(key, runOptions = {}) {
+            // Reject invalid run options through the returned promise, like worker errors.
+            return new Promise((resolve, reject) => {
+                const { signal, timeoutMs } = runOptions;
+                if (timeoutMs !== undefined && (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647)) {
+                    throw new RangeError('timeoutMs must be an integer from 1 to 2147483647');
+                }
+                if (signal?.aborted) {
+                    reject(signal.reason);
+                    return;
+                }
+                let entry = entries.get(key);
+                const fresh = !entry;
+                if (!entry) {
+                    if (entries.size >= maxKeys) {
+                        reject(new CapacityError('maxKeys'));
+                        return;
+                    }
+                    entry = { controller: new AbortController(), waiters: new Set(), done: false };
+                    entries.set(key, entry);
+                }
+                if (entry.waiters.size >= maxWaiters) {
+                    reject(new CapacityError('maxWaitersPerKey'));
+                    return;
+                }
+                const current = entry;
+                let timer;
+                const leave = (reason) => {
+                    if (!current.waiters.delete(waiter))
+                        return;
+                    waiter.cleanup();
+                    reject(reason);
+                    if (!current.done && current.waiters.size === 0) {
+                        detach(key, current);
+                        current.controller.abort(reason);
+                    }
+                };
+                const onAbort = () => leave(signal.reason);
+                const waiter = {
+                    resolve, reject,
+                    cleanup() {
+                        if (timer !== undefined)
+                            clearTimeout(timer);
+                        signal?.removeEventListener('abort', onAbort);
+                    },
+                };
+                current.waiters.add(waiter);
+                signal?.addEventListener('abort', onAbort, { once: true });
+                if (timeoutMs !== undefined)
+                    timer = setTimeout(() => leave(new DOMException('The caller deadline expired', 'TimeoutError')), timeoutMs);
+                if (fresh) {
+                    // Defer the worker so callers in the same turn can join or cancel first.
+                    void Promise.resolve().then(() => {
+                        if (current.done)
+                            return;
+                        return worker(key, current.controller.signal);
+                    }).then(value => finish(key, current, true, value), error => finish(key, current, false, error));
+                }
+            });
+        },
+    };
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "inflight-kit",
+  "version": "1.0.0",
+  "description": "Share pending async work without sharing cancellation. Typed singleflight with per-caller deadlines and bounded admission.",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:types": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --target ES2022 test/types.mts test/types.cts",
+    "check": "npm test && npm run test:types",
+    "demo": "npm run build && node examples/demo.mjs",
+    "prepack": "npm run build",
+    "test:package": "node scripts/smoke-pack.mjs"
+  },
+  "keywords": [
+    "singleflight",
+    "deduplicate",
+    "async",
+    "abortsignal",
+    "fetch",
+    "request-coalescing",
+    "typescript",
+    "cancellation"
+  ],
+  "license": "MIT",
+  "author": "Farhad Arjmand",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/farhad-arjmand/inflight-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/farhad-arjmand/inflight-kit/issues"
+  },
+  "homepage": "https://github.com/farhad-arjmand/inflight-kit#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2"
+  }
+}