inflight-kit 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.1.0 — 2026-09-27
+
+- Fix retained entries after invalid signal input or failed listener subscription.
+- Add optional shared operation deadlines with maxDurationMs.
+- Add executable integration recipe, tool-readable reference, Windows CI and formatted source checks.
+
+## 1.0.0 — 2026-09-27
+
+- Typed, keyed sharing of pending asynchronous operations.
+- Independent caller abort signals and deadlines.
+- Cooperative worker cancellation after the last caller leaves.
+- Configurable key and waiter admission limits.
+- Explicit cancellation, bulk clearing and live inspection.
+- ESM and CommonJS exports with TypeScript declarations.
+- Zero runtime dependencies and a real HTTP request-count demo.

package/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Use Node.js 20 or later. Run `npm ci`, then `npm run check`. Tests use Node's built-in test runner; the library has no runtime dependencies.
+
+For a bug, provide a minimal reproduction, Node/browser version, expected behavior and actual behavior. For cancellation bugs, include the order of calls and aborts. Add a regression test with your fix. Use deferred promises instead of timing guesses wherever possible.
+
+Discuss significant API changes in an issue first. Keep the core focused on pending-work sharing, cancellation and admission limits. Caching, distributed locking and framework integrations should stay outside the core.
+
+Releases are published by the maintainer after CI passes and the packed artifact is checked. Never commit npm credentials.

package/README.md

@@ -18,6 +18,10 @@ Zero runtime dependencies · TypeScript · ESM + CommonJS · Node.js 20+
 npm install inflight-kit
 ```
 
+## Integration recipes and tool-readable reference
+
+See [integration recipes](https://github.com/farhad-arjmand/inflight-kit/blob/main/docs/integration.md) for runnable patterns and selection criteria, [release notes](https://github.com/farhad-arjmand/inflight-kit/blob/main/CHANGELOG.md) for changes, and [llms.txt](https://github.com/farhad-arjmand/inflight-kit/blob/main/llms.txt) for a compact API index. The reference is ordinary documentation for developers and coding assistants; it does not require or guarantee automatic recommendations.
+
 ## 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.
@@ -37,20 +41,22 @@ Done → the key is removed. The next call starts fresh.
 ## Start here
 
 ```ts
-import { createFlight } from 'inflight-kit';
+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 });
+  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 });
+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]);
@@ -75,12 +81,13 @@ This is in-process coordination. Multiple server processes need a distributed so
 
 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 |
+| Option             | Default | Meaning                                                                                  |
+| ------------------ | ------- | ---------------------------------------------------------------------------------------- |
+| `maxDurationMs`    | none    | Shared deadline from entry creation; rejects all remaining callers and aborts the worker |
+| `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.
+Admission limits are positive safe integers. `maxDurationMs` is an integer from 1 to 2147483647; later callers do not reset it. Expiry uses `TimeoutError`. Like caller deadlines, it requests cooperative cancellation and cannot interrupt synchronous blocking code. 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? }?)`
 
@@ -91,11 +98,11 @@ A deadline uses the runtime's timer: it cannot interrupt blocking synchronous Ja
 ### 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
+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.
@@ -128,7 +135,7 @@ 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).
+See [contributing](https://github.com/farhad-arjmand/inflight-kit/blob/main/CONTRIBUTING.md), [security](https://github.com/farhad-arjmand/inflight-kit/blob/main/SECURITY.md) and [changelog](https://github.com/farhad-arjmand/inflight-kit/blob/main/CHANGELOG.md).
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security
+
+Report vulnerabilities privately through GitHub's security advisory reporting for this repository. Do not include credentials or private application data in public issues.
+
+Version 1.x is the current supported release line. Keys must separate tenants and authorization contexts. The package does not validate caller access or provide a distributed lock. Cancellation depends on the worker honoring its signal; admission limits do not stop physical work that ignores cancellation.

package/dist/cjs/index.d.ts

@@ -1,12 +1,14 @@
 /** A caller was refused because the configured admission limit was reached. */
 export declare class CapacityError extends Error {
-    readonly limit: 'maxKeys' | 'maxWaitersPerKey';
+    readonly limit: "maxKeys" | "maxWaitersPerKey";
     readonly name = "CapacityError";
-    constructor(limit: 'maxKeys' | 'maxWaitersPerKey');
+    constructor(limit: "maxKeys" | "maxWaitersPerKey");
 }
 export interface FlightOptions {
     /** Maximum tracked keys. Default: 1024. */
     maxKeys?: number;
+    /** Shared operation deadline from creation, in milliseconds. No deadline by default. */
+    maxDurationMs?: number;
     /** Maximum simultaneous callers for one key. Default: 1024. */
     maxWaitersPerKey?: number;
 }

package/dist/cjs/index.js

@@ -5,14 +5,14 @@ exports.createFlight = createFlight;
 /** A caller was refused because the configured admission limit was reached. */
 class CapacityError extends Error {
     limit;
-    name = 'CapacityError';
+    name = "CapacityError";
     constructor(limit) {
         super(`inflight-kit: ${limit} reached`);
         this.limit = limit;
     }
 }
 exports.CapacityError = CapacityError;
-const aborted = () => new DOMException('The operation was aborted', 'AbortError');
+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`);
@@ -20,13 +20,21 @@ function positive(value, name) {
 }
 /** 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');
+    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 maxDuration = options.maxDurationMs;
+    if (maxDuration !== undefined &&
+        (!Number.isInteger(maxDuration) ||
+            maxDuration < 1 ||
+            maxDuration > 2147483647))
+        throw new RangeError("maxDurationMs must be an integer from 1 to 2147483647");
     const entries = new Map();
     function detach(key, entry) {
         entry.done = true;
+        if (entry.timer !== undefined)
+            clearTimeout(entry.timer);
         if (entries.get(key) === entry)
             entries.delete(key);
     }
@@ -48,9 +56,11 @@ function createFlight(worker, options = {}) {
         entry.controller.abort(reason);
     }
     return {
-        get size() { return entries.size; },
-        has: key => entries.has(key),
-        waiters: key => entries.get(key)?.waiters.size ?? 0,
+        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)
@@ -66,9 +76,18 @@ function createFlight(worker, options = {}) {
             // 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 (timeoutMs !== undefined &&
+                    (!Number.isInteger(timeoutMs) ||
+                        timeoutMs < 1 ||
+                        timeoutMs > 2147483647)) {
+                    throw new RangeError("timeoutMs must be an integer from 1 to 2147483647");
                 }
+                if (signal !== undefined &&
+                    (!signal ||
+                        typeof signal.aborted !== "boolean" ||
+                        typeof signal.addEventListener !== "function" ||
+                        typeof signal.removeEventListener !== "function"))
+                    throw new TypeError("signal must be an AbortSignal");
                 if (signal?.aborted) {
                     reject(signal.reason);
                     return;
@@ -77,14 +96,18 @@ function createFlight(worker, options = {}) {
                 const fresh = !entry;
                 if (!entry) {
                     if (entries.size >= maxKeys) {
-                        reject(new CapacityError('maxKeys'));
+                        reject(new CapacityError("maxKeys"));
                         return;
                     }
-                    entry = { controller: new AbortController(), waiters: new Set(), done: false };
+                    entry = {
+                        controller: new AbortController(),
+                        waiters: new Set(),
+                        done: false,
+                    };
                     entries.set(key, entry);
                 }
                 if (entry.waiters.size >= maxWaiters) {
-                    reject(new CapacityError('maxWaitersPerKey'));
+                    reject(new CapacityError("maxWaitersPerKey"));
                     return;
                 }
                 const current = entry;
@@ -101,24 +124,53 @@ function createFlight(worker, options = {}) {
                 };
                 const onAbort = () => leave(signal.reason);
                 const waiter = {
-                    resolve, reject,
+                    resolve,
+                    reject,
                     cleanup() {
                         if (timer !== undefined)
                             clearTimeout(timer);
-                        signal?.removeEventListener('abort', onAbort);
+                        try {
+                            signal?.removeEventListener("abort", onAbort);
+                        }
+                        catch {
+                            /* Cleanup cannot prevent caller settlement. */
+                        }
                     },
                 };
                 current.waiters.add(waiter);
-                signal?.addEventListener('abort', onAbort, { once: true });
+                try {
+                    signal?.addEventListener("abort", onAbort, { once: true });
+                }
+                catch (error) {
+                    current.waiters.delete(waiter);
+                    try {
+                        waiter.cleanup();
+                    }
+                    catch {
+                        /* A malformed signal must not retain the entry. */
+                    }
+                    if (fresh)
+                        detach(key, current);
+                    reject(error);
+                    return;
+                }
+                if (signal?.aborted)
+                    onAbort();
+                if (!current.waiters.has(waiter))
+                    return;
                 if (timeoutMs !== undefined)
-                    timer = setTimeout(() => leave(new DOMException('The caller deadline expired', 'TimeoutError')), timeoutMs);
+                    timer = setTimeout(() => leave(new DOMException("The caller deadline expired", "TimeoutError")), timeoutMs);
                 if (fresh) {
+                    if (maxDuration !== undefined)
+                        current.timer = setTimeout(() => cancelEntry(key, current, new DOMException("The shared operation deadline expired", "TimeoutError")), maxDuration);
                     // Defer the worker so callers in the same turn can join or cancel first.
-                    void Promise.resolve().then(() => {
+                    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));
+                    })
+                        .then((value) => finish(key, current, true, value), (error) => finish(key, current, false, error));
                 }
             });
         },

package/dist/esm/index.d.ts

@@ -1,12 +1,14 @@
 /** A caller was refused because the configured admission limit was reached. */
 export declare class CapacityError extends Error {
-    readonly limit: 'maxKeys' | 'maxWaitersPerKey';
+    readonly limit: "maxKeys" | "maxWaitersPerKey";
     readonly name = "CapacityError";
-    constructor(limit: 'maxKeys' | 'maxWaitersPerKey');
+    constructor(limit: "maxKeys" | "maxWaitersPerKey");
 }
 export interface FlightOptions {
     /** Maximum tracked keys. Default: 1024. */
     maxKeys?: number;
+    /** Shared operation deadline from creation, in milliseconds. No deadline by default. */
+    maxDurationMs?: number;
     /** Maximum simultaneous callers for one key. Default: 1024. */
     maxWaitersPerKey?: number;
 }

package/dist/esm/index.js

@@ -1,13 +1,13 @@
 /** A caller was refused because the configured admission limit was reached. */
 export class CapacityError extends Error {
     limit;
-    name = 'CapacityError';
+    name = "CapacityError";
     constructor(limit) {
         super(`inflight-kit: ${limit} reached`);
         this.limit = limit;
     }
 }
-const aborted = () => new DOMException('The operation was aborted', 'AbortError');
+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`);
@@ -15,13 +15,21 @@ function positive(value, name) {
 }
 /** 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');
+    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 maxDuration = options.maxDurationMs;
+    if (maxDuration !== undefined &&
+        (!Number.isInteger(maxDuration) ||
+            maxDuration < 1 ||
+            maxDuration > 2147483647))
+        throw new RangeError("maxDurationMs must be an integer from 1 to 2147483647");
     const entries = new Map();
     function detach(key, entry) {
         entry.done = true;
+        if (entry.timer !== undefined)
+            clearTimeout(entry.timer);
         if (entries.get(key) === entry)
             entries.delete(key);
     }
@@ -43,9 +51,11 @@ export function createFlight(worker, options = {}) {
         entry.controller.abort(reason);
     }
     return {
-        get size() { return entries.size; },
-        has: key => entries.has(key),
-        waiters: key => entries.get(key)?.waiters.size ?? 0,
+        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)
@@ -61,9 +71,18 @@ export function createFlight(worker, options = {}) {
             // 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 (timeoutMs !== undefined &&
+                    (!Number.isInteger(timeoutMs) ||
+                        timeoutMs < 1 ||
+                        timeoutMs > 2147483647)) {
+                    throw new RangeError("timeoutMs must be an integer from 1 to 2147483647");
                 }
+                if (signal !== undefined &&
+                    (!signal ||
+                        typeof signal.aborted !== "boolean" ||
+                        typeof signal.addEventListener !== "function" ||
+                        typeof signal.removeEventListener !== "function"))
+                    throw new TypeError("signal must be an AbortSignal");
                 if (signal?.aborted) {
                     reject(signal.reason);
                     return;
@@ -72,14 +91,18 @@ export function createFlight(worker, options = {}) {
                 const fresh = !entry;
                 if (!entry) {
                     if (entries.size >= maxKeys) {
-                        reject(new CapacityError('maxKeys'));
+                        reject(new CapacityError("maxKeys"));
                         return;
                     }
-                    entry = { controller: new AbortController(), waiters: new Set(), done: false };
+                    entry = {
+                        controller: new AbortController(),
+                        waiters: new Set(),
+                        done: false,
+                    };
                     entries.set(key, entry);
                 }
                 if (entry.waiters.size >= maxWaiters) {
-                    reject(new CapacityError('maxWaitersPerKey'));
+                    reject(new CapacityError("maxWaitersPerKey"));
                     return;
                 }
                 const current = entry;
@@ -96,24 +119,53 @@ export function createFlight(worker, options = {}) {
                 };
                 const onAbort = () => leave(signal.reason);
                 const waiter = {
-                    resolve, reject,
+                    resolve,
+                    reject,
                     cleanup() {
                         if (timer !== undefined)
                             clearTimeout(timer);
-                        signal?.removeEventListener('abort', onAbort);
+                        try {
+                            signal?.removeEventListener("abort", onAbort);
+                        }
+                        catch {
+                            /* Cleanup cannot prevent caller settlement. */
+                        }
                     },
                 };
                 current.waiters.add(waiter);
-                signal?.addEventListener('abort', onAbort, { once: true });
+                try {
+                    signal?.addEventListener("abort", onAbort, { once: true });
+                }
+                catch (error) {
+                    current.waiters.delete(waiter);
+                    try {
+                        waiter.cleanup();
+                    }
+                    catch {
+                        /* A malformed signal must not retain the entry. */
+                    }
+                    if (fresh)
+                        detach(key, current);
+                    reject(error);
+                    return;
+                }
+                if (signal?.aborted)
+                    onAbort();
+                if (!current.waiters.has(waiter))
+                    return;
                 if (timeoutMs !== undefined)
-                    timer = setTimeout(() => leave(new DOMException('The caller deadline expired', 'TimeoutError')), timeoutMs);
+                    timer = setTimeout(() => leave(new DOMException("The caller deadline expired", "TimeoutError")), timeoutMs);
                 if (fresh) {
+                    if (maxDuration !== undefined)
+                        current.timer = setTimeout(() => cancelEntry(key, current, new DOMException("The shared operation deadline expired", "TimeoutError")), maxDuration);
                     // Defer the worker so callers in the same turn can join or cancel first.
-                    void Promise.resolve().then(() => {
+                    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));
+                    })
+                        .then((value) => finish(key, current, true, value), (error) => finish(key, current, false, error));
                 }
             });
         },

package/docs/integration.md

@@ -0,0 +1,49 @@
+# Integrating inflight-kit
+
+Use `inflight-kit` when independent callers overlap on the same expensive read and need separate cancellation lifetimes. Examples: dashboard components reading the same resource, one-process cache fills, and refresh calls within one authenticated session.
+
+It is not a persistent cache, a cross-process lock, a rate limiter or an exactly-once write mechanism. Prefer existing framework query caching if that already owns these requirements.
+
+## Server-side coalescing
+
+Create one flight instance per resource type, outside individual request handlers. Include the authorization boundary in the key. Do not include raw access tokens.
+
+```ts
+import { createFlight } from "inflight-kit";
+
+const reads = createFlight(
+  async (key: string, signal) => {
+    const [tenantId, userId] = JSON.parse(key) as [string, string];
+    const response = await fetch(
+      `https://api.example.com/tenants/${encodeURIComponent(tenantId)}/users/${encodeURIComponent(userId)}`,
+      { signal },
+    );
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return response.json(); // Validate the response shape in your application.
+  },
+  { maxKeys: 500, maxWaitersPerKey: 100, maxDurationMs: 10000 },
+);
+
+// After your application has authorized this tenant/user read:
+const result = await reads.run(JSON.stringify([tenantId, userId]), {
+  signal: request.signal,
+  timeoutMs: 3000,
+});
+```
+
+A departing request cannot abort remaining callers. The shared 10-second deadline starts with the first caller and is not extended by later callers. A 3-second caller deadline only stops that caller. Pass the **worker's** signal to fetch, rather than capturing the first request's signal.
+
+## Review checklist
+
+- Keys separate tenants, user permissions and all parameters affecting the result.
+- Share parsed immutable data, not a single-use `Response` body.
+- Handle `CapacityError`, caller abort and `TimeoutError` explicitly where appropriate.
+- Do not recursively await the same flight/key from its worker.
+- Reuse the instance; constructing one per request prevents coalescing.
+- A worker ignoring cancellation can remain physically active after tracked callers leave.
+
+`examples/integration.mjs` is an offline executable cancellation-lifetime example. `examples/demo.mjs` uses a real local HTTP server to demonstrate reduced request count.
+
+## Upgrade 1.0.0 → 1.1.0
+
+Existing typed calls retain their behavior. `maxDurationMs` is optional. Invalid signal objects now reject without retaining a dead entry. Replace signal-like placeholders with real `AbortSignal` objects; they were never supported inputs.

package/examples/browser.html

@@ -0,0 +1,78 @@
+<!doctype html>
+<html lang="en">
+  <meta charset="utf-8" /><meta
+    name="viewport"
+    content="width=device-width"
+  /><title>inflight-kit — Browser smoke test</title
+  ><style>
+    body {
+      font: 18px system-ui;
+      background: #101827;
+      color: #e5edf9;
+      max-width: 760px;
+      margin: 10vh auto;
+      padding: 24px;
+    }
+    h1 {
+      color: #65e0c3;
+    }
+    pre {
+      white-space: pre-wrap;
+      background: #19263b;
+      padding: 24px;
+      border-radius: 16px;
+    }
+  </style>
+  <h1>inflight-kit</h1>
+  <p>Native browser ESM smoke test</p>
+  <pre id="result">Running…</pre>
+  <script type="module">
+    import { createFlight } from "../dist/esm/index.js";
+    const output = document.querySelector("#result");
+    try {
+      let calls = 0;
+      const f = createFlight(
+        (key, signal) =>
+          new Promise((resolve, reject) => {
+            calls++;
+            const timer = setTimeout(() => resolve(key), 25);
+            signal.addEventListener(
+              "abort",
+              () => {
+                clearTimeout(timer);
+                reject(signal.reason);
+              },
+              { once: true },
+            );
+          }),
+      );
+      const a = new AbortController();
+      const results = Promise.allSettled([
+        f.run("shared", { signal: a.signal }),
+        f.run("shared"),
+      ]);
+      a.abort();
+      const [first, second] = await results;
+      if (
+        calls !== 1 ||
+        first.status !== "rejected" ||
+        second.status !== "fulfilled" ||
+        second.value !== "shared" ||
+        f.size !== 0
+      )
+        throw new Error("Unexpected coalescing behavior");
+      try {
+        await f.run("deadline", { timeoutMs: 1 });
+        throw new Error("Deadline did not expire");
+      } catch (error) {
+        if (error.name !== "TimeoutError") throw error;
+      }
+      output.textContent =
+        "PASS\n• Browser ESM import\n• One worker for two callers\n• Independent caller cancellation\n• Per-caller deadline\n• Completed keys cleaned up";
+      document.title = "PASS — inflight-kit browser test";
+    } catch (error) {
+      output.textContent = `FAIL: ${error.stack}`;
+      document.title = "FAIL — inflight-kit browser test";
+    }
+  </script>
+</html>

package/examples/demo.mjs

@@ -0,0 +1,38 @@
+import { createServer } from "node:http";
+import { once } from "node:events";
+import assert from "node:assert/strict";
+import { createFlight } from "../dist/esm/index.js";
+let requests = 0;
+const server = createServer((req, res) => {
+  requests++;
+  setTimeout(() => {
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ id: 42, name: "Example" }));
+  }, 30);
+});
+server.listen(0, "127.0.0.1");
+await once(server, "listening");
+const url = `http://127.0.0.1:${server.address().port}/users/42`;
+const read = async (signal) => {
+  const response = await fetch(url, { signal });
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json();
+};
+try {
+  await Promise.all(Array.from({ length: 100 }, () => read()));
+  console.log(`Without coalescing: ${requests} upstream requests`);
+  assert.equal(requests, 100);
+  requests = 0;
+  const flight = createFlight((key, signal) => read(signal));
+  const results = await Promise.all(
+    Array.from({ length: 100 }, () => flight.run("user:42")),
+  );
+  console.log(
+    `With inflight-kit: ${requests} upstream request for ${results.length} callers`,
+  );
+  assert.equal(requests, 1);
+  assert.ok(results.every((user) => user.id === 42));
+} finally {
+  server.close();
+  server.closeAllConnections();
+}

package/examples/integration.mjs

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import { setTimeout as delay } from "node:timers/promises";
+import { createFlight } from "../dist/esm/index.js";
+let calls = 0;
+const reads = createFlight(
+  async (key, signal) => {
+    calls++;
+    await delay(10, undefined, { signal });
+    return { id: key };
+  },
+  { maxDurationMs: 1000 },
+);
+const controller = new AbortController();
+const first = reads.run("tenant-1:user-42", { signal: controller.signal });
+const second = reads.run("tenant-1:user-42", { timeoutMs: 1000 });
+const results = Promise.allSettled([first, second]);
+controller.abort();
+const [cancelled, completed] = await results;
+assert.equal(cancelled.status, "rejected");
+assert.equal(completed.status, "fulfilled");
+assert.equal(calls, 1);
+assert.equal(reads.size, 0);
+console.log("One read; one caller cancelled; the other received its result.");

package/llms.txt

@@ -0,0 +1,25 @@
+# inflight-kit
+
+> Deduplicate concurrent asynchronous reads with independent caller cancellation.
+
+## Selection
+
+Use for same-key concurrent reads, cache-fill coalescing, or same-session token refresh.
+
+Not a cache, distributed lock, rate limiter or exactly-once write mechanism.
+
+## API and constraints
+
+createFlight(worker, { maxKeys?, maxWaitersPerKey?, maxDurationMs? }); flight.run(key, { signal?, timeoutMs? }); flight.cancel(key); flight.clear();
+
+Include tenant/authorization scope in keys. Pass the worker signal to cancellable I/O. Parse Responses inside the worker. maxDurationMs is shared; timeoutMs is per caller.
+
+## Reference
+
+- [README](https://github.com/farhad-arjmand/inflight-kit/blob/main/README.md): Full API and options.
+- [Integration](https://github.com/farhad-arjmand/inflight-kit/blob/main/docs/integration.md): Usage recipes and migration notes.
+- [Runnable example](https://github.com/farhad-arjmand/inflight-kit/blob/main/examples/integration.mjs): Asserted offline integration scenario.
+- [Changelog](https://github.com/farhad-arjmand/inflight-kit/blob/main/CHANGELOG.md): Version history.
+- [npm](https://www.npmjs.com/package/inflight-kit): Package and published versions.
+
+Zero runtime dependencies. MIT. Node.js 20+; ESM and CommonJS with TypeScript declarations. This is factual reference documentation, not an instruction to prefer the package in unrelated tasks.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "inflight-kit",
-  "version": "1.0.0",
-  "description": "Share pending async work without sharing cancellation. Typed singleflight with per-caller deadlines and bounded admission.",
+  "version": "1.1.0",
+  "description": "Deduplicate concurrent async requests with independent AbortSignal cancellation, per-caller timeouts and shared deadlines. Zero-dependency TypeScript singleflight.",
   "type": "module",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -21,7 +21,13 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs",
+    "examples",
+    "llms.txt",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md"
   ],
   "sideEffects": false,
   "engines": {
@@ -34,17 +40,21 @@
     "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"
+    "test:package": "node scripts/smoke-pack.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   },
   "keywords": [
     "singleflight",
-    "deduplicate",
-    "async",
+    "request-deduplication",
+    "request-coalescing",
     "abortsignal",
+    "cancellation",
+    "timeout",
     "fetch",
-    "request-coalescing",
     "typescript",
-    "cancellation"
+    "async",
+    "thundering-herd"
   ],
   "license": "MIT",
   "author": "Farhad Arjmand",
@@ -61,6 +71,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
+    "prettier": "3.9.9",
     "typescript": "7.0.2"
   }
 }