@zukhruf/single-flight 0.0.0-stage → 0.3.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezzabuzaid
+
+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

@@ -1,4 +1,204 @@
-# Temporary Holding Version
+# @zukhruf/single-flight
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+Callers of one key share the flight in progress, in one process or across the processes of a host. A caller that comes while a flight runs does not start a second flight and does not fail with a "busy" error. It joins the flight and gets its outcome. This pattern is also known as single-flight or request coalescing, as in Go's `golang.org/x/sync/singleflight`.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## The problem
+
+A user runs `sync`. A second `sync` starts while the first one runs. The mutex of `@zukhruf/mutex` gives two choices, and the user wants neither:
+
+- In the acquire mode skip if busy, the second `sync` fails with a "busy" error.
+- In the acquire mode wait, the second `sync` waits for the first one, and then runs a second sync.
+
+The user wanted a sync to happen. Thus the second `sync` must tell the user that a sync runs, wait for it, and report its outcome. That is a join:
+
+```ts
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { SingleFlight } from '@zukhruf/single-flight';
+
+const flights = new SingleFlight<string>();
+let builds = 0;
+
+async function buildReport() {
+  builds += 1;
+  await delay(100); // Building the report takes time.
+  return `report ${builds}`;
+}
+
+const calls = [1, 2, 3].map(() =>
+  flights.run('report:daily', buildReport, {
+    onJoin: () => console.log('A report is being built. Waiting for it…'),
+  }),
+);
+console.log(await Promise.all(calls), { builds });
+```
+
+Output:
+
+```
+A report is being built. Waiting for it…
+A report is being built. Waiting for it…
+[
+  { value: 'report 1', joined: false },
+  { value: 'report 1', joined: true },
+  { value: 'report 1', joined: true }
+] { builds: 1 }
+```
+
+The first caller is the leader: its call runs the flight. The other two callers join it. `onJoin` runs once for each joiner, before it waits. A call after the flight ended starts a new flight: a flight is not a cache. To keep a value after its flight, see the mutex recipe [Compute a value once and share it](../mutex/docs/recipes/compute-once-and-share-it.md).
+
+## Use it
+
+This project is an experiment.
+
+```sh
+npm install @zukhruf/single-flight @zukhruf/mutex
+```
+
+`@zukhruf/mutex` is a peer dependency. `SharedFlight` uses its mutex, and `SingleFlight` does not.
+
+## In one process: `SingleFlight`
+
+`flights.run(key, work, { onJoin, signal })` resolves with `{ value, joined }`. `joined` is `false` for the leader and `true` for each joiner.
+
+- A failed flight rejects each caller with the original error of the work.
+- `work` gets a signal that aborts when the flight is abandoned. Read it only when the work can stop early.
+
+## Across processes: `SharedFlight`
+
+A `SharedFlight` makes a flight visible to the other processes of the host. It uses three parts:
+
+- A `SingleFlight`: the callers in one process share one flight first.
+- The mutex: the holder of the key is the leader. The other processes learn that the key is busy.
+- The records: the leader writes the flight record, and joiners in other processes read it.
+
+```ts
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { Mutex, SqliteStore } from '@zukhruf/mutex';
+import { FileFlightRecords, SharedFlight } from '@zukhruf/single-flight';
+
+const directory = await mkdtemp(join(tmpdir(), 'app-'));
+
+const flights = new SharedFlight({
+  mutex: new Mutex(new SqliteStore(join(directory, 'locks'))),
+  records: new FileFlightRecords(join(directory, 'flights')),
+  parse: (value) => {
+    if (typeof value !== 'string') throw new TypeError('Not a sync summary.');
+    return value;
+  },
+});
+
+const { value, joined } = await flights.run(
+  'sync',
+  async () => 'synced 42 files',
+  {
+    onJoin: () => console.log('A sync is running. Waiting for it…'),
+  },
+);
+console.log({ value, joined });
+await rm(directory, { recursive: true, force: true });
+```
+
+Output:
+
+```
+{ value: 'synced 42 files', joined: false }
+```
+
+The program with three processes is in the recipe [Join a run that is still in flight](./docs/recipes/join-a-run-in-flight.md).
+
+| Option         | What it does                                                                                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mutex`        | Decides which caller is the leader. All processes must use one lock directory, with a host lock store such as `SqliteStore`.                                        |
+| `records`      | Keeps the flight records. All processes must use the same records. Give the records a directory of their own, never the lock directory.                             |
+| `parse`        | Turns a value read from a flight record into your type. The value travels as JSON, so a `Date` arrives as a string. The leader also gets `parse` of the JSON value. |
+| `pollInterval` | Milliseconds between two reads of a flight record while a caller joins. Defaults to `100`.                                                                          |
+
+The work gets the lease of the key. A leader whose lease is lost records the flight as interrupted, and the call rejects with the reason of the lease.
+
+A joiner never acquires the key. It reads the flight record until the flight has an outcome, and it asks the mutex only whether a running flight still has a holder. [ADR 0001](./docs/adr/0001-a-joiner-follows-its-flight-record-without-acquiring-the-key.md) tells why.
+
+## Errors
+
+| The caller is                          | The flight                                             | The call rejects with          |
+| -------------------------------------- | ------------------------------------------------------ | ------------------------------ |
+| The leader, or a joiner in its process | Failed                                                 | The original error of the work |
+| A joiner in another process            | Failed                                                 | `FlightFailedError`            |
+| A joiner in another process            | Interrupted: the holder stopped, or its lease was lost | `FlightInterruptedError`       |
+| A joiner in another process            | Its flight record is gone, before the joiner read it   | `FlightOutcomeLostError`       |
+| The leader, or a joiner in its process | Ended, and the records refused its outcome             | The error of the records       |
+| A joiner in another process            | Ended, and the records refused its outcome             | `FlightInterruptedError`       |
+
+`FlightFailedError` has the `key` and the `failure`: the `name`, the `message` and the `code` of the error. A thrown value that is not an error keeps only its text. A value that JSON cannot carry, such as a `BigInt`, fails the flight.
+
+When the holder of a flight stops and the next holder begins a new flight, the new flight is the successor. A joiner of the stopped flight continues with the successor and gets its outcome.
+
+## Cancel a wait
+
+Give a signal to stop the wait of one caller: `flights.run(key, work, { signal: AbortSignal.timeout(30_000) })`. The call rejects with the reason of the signal. The flight continues for the other callers, also when the leader's caller cancels.
+
+When all callers of a flight cancel, the flight is abandoned:
+
+- The next call of the key starts a new flight.
+- In `SingleFlight`, the signal of the work aborts.
+- In `SharedFlight`, a process that joins stops to read the flight record, and it never starts a flight for callers that left. A flight that a process leads continues to its end, because joiners in other processes can wait for its outcome.
+
+[ADR 0002](./docs/adr/0002-a-flight-that-all-callers-left-is-abandoned.md) tells how other tools solve this.
+
+## Records
+
+`new FileFlightRecords(directory, { keepFor })` keeps one JSON file for each key. The name of the file is the SHA-256 of the key, so any key is a valid file name. The leader replaces the file in one step, so a joiner never reads a part of it.
+
+`keepFor` is the keep window, in milliseconds. It defaults to `60_000`. Keep it at least 20 times the `pollInterval` of each joiner. A joiner that reads the flight record after the keep window gets `FlightOutcomeLostError`.
+
+To keep the flight records in another place, for example a table of your database, write your own `FlightRecords`:
+
+```ts
+interface FlightRecords {
+  begin(key: string): Promise<string>;
+  finish(key: string, id: string, outcome: Finished): Promise<void>;
+  latest(key: string): Promise<LatestFlight | undefined>;
+  outcome(key: string, id: string): Promise<Outcome>;
+}
+```
+
+- `begin` records a new running flight and returns a new id. A flight of the key that is still running becomes interrupted, and the new flight is its successor.
+- `finish` records the outcome. It does nothing when the flight is not running.
+- `outcome` returns `running`, the outcome, or `missing` when the flight record is gone.
+- Only the holder of the key calls `begin` and `finish`. Joiners call only `latest` and `outcome`.
+
+## Documentation
+
+- [Join a run that is still in flight](./docs/recipes/join-a-run-in-flight.md): three processes, one sync.
+- [ADR 0001: A joiner follows its flight record without acquiring the key](./docs/adr/0001-a-joiner-follows-its-flight-record-without-acquiring-the-key.md)
+- [ADR 0002: A flight that all callers left is abandoned](./docs/adr/0002-a-flight-that-all-callers-left-is-abandoned.md)
+
+## Development
+
+This package is part of the [zukhruf](../../README.md) workspace. Run the commands from the workspace root.
+
+```sh
+npm install
+npx nx run single-flight:test        # builds, then runs the tests in src/
+npx nx run single-flight:typecheck   # formats, lints, then type checks
+npx nx run single-flight:build       # compiles src/ to dist/
+```
+
+The tests run from `src/`, not from `dist/`. The tests across processes start `src/testing/caller.fixture.ts` in child processes.
+
+```
+src/
+  single-flight.ts         SingleFlight: the flights of one process
+  flight.ts                one flight of this process and its callers
+  shared-flight.ts         SharedFlight: the leader, and joiners across processes
+  follow.ts                how a joiner finds and follows a flight record
+  flight-records.ts        the FlightRecords interface and the outcomes
+  file-flight-records.ts   FileFlightRecords: one JSON file for each key
+  errors.ts                FlightFailedError, FlightInterruptedError, FlightOutcomeLostError
+  testing/                 the caller process that the tests start
+```

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+import type { RecordedError } from './flight-records.ts';
+/** The flight that this caller joined in another process failed. `failure` is the error that its leader recorded. */
+export declare class FlightFailedError extends Error {
+    readonly key: string;
+    readonly failure: RecordedError;
+    constructor(key: string, failure: RecordedError);
+}
+/**
+ * The holder of the flight that this caller joined stopped before the flight
+ * had an outcome: its process stopped, its lease was lost, or its records
+ * refused the outcome.
+ */
+export declare class FlightInterruptedError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/** The record of the flight that this caller joined was gone before the caller read its outcome. */
+export declare class FlightOutcomeLostError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,qHAAqH;AACrH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;gBAEpB,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa;CAQhD;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAET,GAAG,EAAE,MAAM;CAOxB;AAED,oGAAoG;AACpG,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBAET,GAAG,EAAE,MAAM;CAOxB"}

package/dist/errors.js

@@ -0,0 +1,34 @@
+/** The flight that this caller joined in another process failed. `failure` is the error that its leader recorded. */
+export class FlightFailedError extends Error {
+    key;
+    failure;
+    constructor(key, failure) {
+        super(`The flight of ${JSON.stringify(key)} failed: ${failure.name}: ${failure.message}`);
+        this.name = 'FlightFailedError';
+        this.key = key;
+        this.failure = failure;
+    }
+}
+/**
+ * The holder of the flight that this caller joined stopped before the flight
+ * had an outcome: its process stopped, its lease was lost, or its records
+ * refused the outcome.
+ */
+export class FlightInterruptedError extends Error {
+    key;
+    constructor(key) {
+        super(`The flight of ${JSON.stringify(key)} that this caller joined stopped before it had an outcome.`);
+        this.name = 'FlightInterruptedError';
+        this.key = key;
+    }
+}
+/** The record of the flight that this caller joined was gone before the caller read its outcome. */
+export class FlightOutcomeLostError extends Error {
+    key;
+    constructor(key) {
+        super(`The record of the flight of ${JSON.stringify(key)} that this caller joined was gone before the caller read its outcome.`);
+        this.name = 'FlightOutcomeLostError';
+        this.key = key;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,qHAAqH;AACrH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,GAAG,CAAS;IACZ,OAAO,CAAgB;IAEhC,YAAY,GAAW,EAAE,OAAsB;QAC7C,KAAK,CACH,iBAAiB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CACnF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACtC,GAAG,CAAS;IAErB,YAAY,GAAW;QACrB,KAAK,CACH,iBAAiB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,4DAA4D,CACjG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;CACF;AAED,oGAAoG;AACpG,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACtC,GAAG,CAAS;IAErB,YAAY,GAAW;QACrB,KAAK,CACH,+BAA+B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,uEAAuE,CAC1H,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;CACF"}

package/dist/file-flight-records.d.ts

@@ -0,0 +1,22 @@
+import { type Finished, type FlightRecords, type LatestFlight, type Outcome } from './flight-records.ts';
+export interface FileFlightRecordsOptions {
+    /**
+     * Milliseconds that the outcome of a flight stays readable after the flight
+     * ended. A joiner reads it once per poll interval, so keep it at least 20
+     * times the `pollInterval` of every joiner. Defaults to 60 000.
+     */
+    keepFor?: number;
+}
+/**
+ * Keeps the flight records of each key in one JSON file in `directory`. Give
+ * the records a directory of their own, never the lock directory of a mutex.
+ */
+export declare class FileFlightRecords implements FlightRecords {
+    #private;
+    constructor(directory: string, { keepFor }?: FileFlightRecordsOptions);
+    begin(key: string): Promise<string>;
+    finish(key: string, id: string, outcome: Finished): Promise<void>;
+    latest(key: string): Promise<LatestFlight | undefined>;
+    outcome(key: string, id: string): Promise<Outcome>;
+}
+//# sourceMappingURL=file-flight-records.d.ts.map

package/dist/file-flight-records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-flight-records.d.ts","sourceRoot":"","sources":["../src/file-flight-records.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,OAAO,EAGb,MAAM,qBAAqB,CAAC;AAyB7B,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,aAAa;;gBAKnD,SAAS,EAAE,MAAM,EACjB,EAAE,OAAgB,EAAE,GAAE,wBAA6B;IAW/C,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBnC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAejE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAKtD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CA0DzD"}

package/dist/file-flight-records.js

@@ -0,0 +1,124 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isOutcome, isRecord, } from "./flight-records.js";
+import { patiently } from "./patiently.js";
+const isEntry = (value) => isRecord(value) &&
+    typeof value['id'] === 'string' &&
+    isOutcome(value['outcome']) &&
+    value['outcome'].status !== 'missing' &&
+    (value['endedAt'] === undefined || typeof value['endedAt'] === 'number');
+const isFlightFile = (value) => isRecord(value) &&
+    Array.isArray(value['flights']) &&
+    value['flights'].every(isEntry);
+/**
+ * Keeps the flight records of each key in one JSON file in `directory`. Give
+ * the records a directory of their own, never the lock directory of a mutex.
+ */
+export class FileFlightRecords {
+    #directory;
+    #keepFor;
+    constructor(directory, { keepFor = 60_000 } = {}) {
+        if (!(keepFor >= 0) || !Number.isFinite(keepFor)) {
+            throw new RangeError(`keepFor must be a finite number of milliseconds >= 0, got ${keepFor}.`);
+        }
+        this.#directory = directory;
+        this.#keepFor = keepFor;
+    }
+    async begin(key) {
+        const id = randomUUID();
+        const endedAt = Date.now();
+        const flights = (await this.#read(key)).map((flight) => flight.outcome.status === 'running'
+            ? {
+                id: flight.id,
+                outcome: { status: 'interrupted', successor: id },
+                endedAt,
+            }
+            : flight);
+        await this.#write(key, [
+            ...flights,
+            { id, outcome: { status: 'running' } },
+        ]);
+        return id;
+    }
+    async finish(key, id, outcome) {
+        const flights = await this.#read(key);
+        const running = flights.some((flight) => flight.id === id && flight.outcome.status === 'running');
+        if (!running)
+            return;
+        const endedAt = Date.now();
+        await this.#write(key, flights.map((flight) => flight.id === id ? { id, outcome, endedAt } : flight));
+    }
+    async latest(key) {
+        const last = (await this.#read(key)).at(-1);
+        return last && { id: last.id, status: last.outcome.status };
+    }
+    async outcome(key, id) {
+        const flight = (await this.#read(key)).find((flight) => flight.id === id);
+        return flight?.outcome ?? { status: 'missing' };
+    }
+    /**
+     * A key can hold characters that no file name can, such as `:` on Windows
+     * or `/`, and two keys can differ only by case, which a case-insensitive
+     * file system ignores. The hex digest has none of these problems. It digests
+     * the UTF-16 code units: UTF-8 would turn every lone surrogate into U+FFFD
+     * and give such keys one record.
+     */
+    #pathOf(key) {
+        const name = createHash('sha256').update(key, 'utf16le').digest('hex');
+        return join(this.#directory, `${name}.json`);
+    }
+    /**
+     * A finished flight leaves once it ended `keepFor` ago. The flight that
+     * began last always stays, so `latest` still knows it.
+     */
+    #kept(flights, now) {
+        return flights.filter((flight, index) => index === flights.length - 1 ||
+            flight.endedAt === undefined ||
+            now - flight.endedAt < this.#keepFor);
+    }
+    async #read(key) {
+        const path = this.#pathOf(key);
+        let text;
+        try {
+            text = await patiently(() => readFile(path, 'utf8'));
+        }
+        catch (error) {
+            if (isErrno(error, 'ENOENT'))
+                return [];
+            throw error;
+        }
+        const content = parseJson(text, path);
+        if (!isFlightFile(content))
+            throw notAFlightFile(path);
+        return content.flights;
+    }
+    /** Replaces the file in one step, so a joiner reads the old records or the new ones, never a part. */
+    async #write(key, flights) {
+        const path = this.#pathOf(key);
+        const draft = `${path}.${randomUUID()}.tmp`;
+        const kept = this.#kept(flights, Date.now());
+        await mkdir(this.#directory, { recursive: true });
+        try {
+            await writeFile(draft, JSON.stringify({ key, flights: kept }));
+            await patiently(() => rename(draft, path));
+        }
+        catch (error) {
+            await rm(draft, { force: true });
+            throw error;
+        }
+    }
+}
+function parseJson(text, path) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw notAFlightFile(path, { cause: error });
+    }
+}
+const notAFlightFile = (path, options) => new Error(`${JSON.stringify(path)} is not a file of flight records. Give the records a directory of their own.`, options);
+function isErrno(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+//# sourceMappingURL=file-flight-records.js.map

package/dist/file-flight-records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-flight-records.js","sourceRoot":"","sources":["../src/file-flight-records.ts"],"names":[],"mappings":"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"}

package/dist/flight-records.d.ts

@@ -0,0 +1,67 @@
+/** An error as a flight record keeps it: the parts that JSON carries to another process. */
+export interface RecordedError {
+    readonly name: string;
+    readonly message: string;
+    readonly code?: string | number;
+}
+/** Where a flight is: still running, or how it ended. */
+export type Status = 'running' | 'succeeded' | 'failed' | 'interrupted';
+/** How a flight ended, as its leader records it. */
+export type Finished = {
+    readonly status: 'succeeded';
+    readonly value: unknown;
+} | {
+    readonly status: 'failed';
+    readonly error: RecordedError;
+} | {
+    readonly status: 'interrupted';
+};
+/** What a joiner reads about a flight: running, how it ended, or missing when its record is gone. */
+export type Outcome = {
+    readonly status: 'running';
+} | {
+    readonly status: 'succeeded';
+    readonly value: unknown;
+} | {
+    readonly status: 'failed';
+    readonly error: RecordedError;
+} | {
+    readonly status: 'interrupted';
+    readonly successor?: string;
+} | {
+    readonly status: 'missing';
+};
+/** The flight that a key began last. */
+export interface LatestFlight {
+    readonly id: string;
+    readonly status: Status;
+}
+/**
+ * Where the outcomes of flights live, so that callers in other processes can
+ * join a flight. Only the holder of a key writes the records of the key.
+ * Joiners only read them.
+ */
+export interface FlightRecords {
+    /**
+     * Records a new running flight of `key` and returns its id. A flight of the
+     * key that is still running stopped before it had an outcome: it becomes
+     * interrupted, with the new flight as its successor.
+     */
+    begin(key: string): Promise<string>;
+    /** Records how flight `id` ended. Does nothing when the flight is no longer running. */
+    finish(key: string, id: string, outcome: Finished): Promise<void>;
+    /** The flight that `key` began last, or `undefined` when the key has no record. */
+    latest(key: string): Promise<LatestFlight | undefined>;
+    /**
+     * The outcome of flight `id`. An outcome stays readable for a time after
+     * its flight ended, so a joiner that reads it late finds it after newer
+     * flights of the key began.
+     */
+    outcome(key: string, id: string): Promise<Outcome>;
+}
+/** The parts of a thrown value that a record keeps. A value that is not an error keeps only its text. */
+export declare function recordedError(error: unknown): RecordedError;
+export declare const isRecord: (value: unknown) => value is Readonly<Record<string, unknown>>;
+export declare function isRecordedError(value: unknown): value is RecordedError;
+export declare function isOutcome(value: unknown): value is Outcome;
+//# sourceMappingURL=flight-records.d.ts.map

package/dist/flight-records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight-records.d.ts","sourceRoot":"","sources":["../src/flight-records.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACjC;AAED,yDAAyD;AACzD,MAAM,MAAM,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,aAAa,CAAC;AAExE,oDAAoD;AACpD,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC;AAEvC,qGAAqG;AACrG,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAEnC,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,wFAAwF;IACxF,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,mFAAmF;IACnF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IACvD;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD;AAED,yGAAyG;AACzG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAQ3D;AAED,eAAO,MAAM,QAAQ,GACnB,OAAO,OAAO,KACb,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACC,CAAC;AAE9C,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAQtE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAkB1D"}

package/dist/flight-records.js

@@ -0,0 +1,38 @@
+/** The parts of a thrown value that a record keeps. A value that is not an error keeps only its text. */
+export function recordedError(error) {
+    if (!(error instanceof Error))
+        return { name: 'Error', message: String(error) };
+    const { name, message } = error;
+    const code = 'code' in error ? error.code : undefined;
+    return typeof code === 'string' || typeof code === 'number'
+        ? { name, message, code }
+        : { name, message };
+}
+export const isRecord = (value) => typeof value === 'object' && value !== null;
+export function isRecordedError(value) {
+    if (!isRecord(value))
+        return false;
+    const { name, message, code } = value;
+    return (typeof name === 'string' &&
+        typeof message === 'string' &&
+        (code === undefined || typeof code === 'string' || typeof code === 'number'));
+}
+export function isOutcome(value) {
+    if (!isRecord(value))
+        return false;
+    switch (value['status']) {
+        case 'running':
+        case 'missing':
+            return true;
+        case 'succeeded':
+            return 'value' in value;
+        case 'failed':
+            return isRecordedError(value['error']);
+        case 'interrupted':
+            return (value['successor'] === undefined ||
+                typeof value['successor'] === 'string');
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=flight-records.js.map

package/dist/flight-records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight-records.js","sourceRoot":"","sources":["../src/flight-records.ts"],"names":[],"mappings":"AAsDA,yGAAyG;AACzG,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAC3B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IACnD,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAChC,MAAM,IAAI,GAAG,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ;QACzD,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE;QACzB,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,KAAc,EAC8B,EAAE,CAC9C,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AAE9C,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IACtC,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,OAAO,OAAO,KAAK,QAAQ;QAC3B,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAC7E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,QAAQ,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxB,KAAK,SAAS,CAAC;QACf,KAAK,SAAS;YACZ,OAAO,IAAI,CAAC;QACd,KAAK,WAAW;YACd,OAAO,OAAO,IAAI,KAAK,CAAC;QAC1B,KAAK,QAAQ;YACX,OAAO,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACzC,KAAK,aAAa;YAChB,OAAO,CACL,KAAK,CAAC,WAAW,CAAC,KAAK,SAAS;gBAChC,OAAO,KAAK,CAAC,WAAW,CAAC,KAAK,QAAQ,CACvC,CAAC;QACJ;YACE,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC"}

package/dist/flight.d.ts

@@ -0,0 +1,12 @@
+/** One run of the work for a key in this process. Every caller that joins it gets how it ended. */
+export declare class Flight<T> {
+    #private;
+    constructor(work: (abandoned: AbortSignal) => Promise<T>);
+    /** Settles as the work settled. */
+    get ended(): Promise<T>;
+    /** Aborts when every caller cancelled its wait before the flight ended. */
+    get abandoned(): AbortSignal;
+    /** Waits for the flight for one caller, until it ends or `signal` aborts. */
+    wait(signal: AbortSignal | undefined): Promise<T>;
+}
+//# sourceMappingURL=flight.d.ts.map

package/dist/flight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight.d.ts","sourceRoot":"","sources":["../src/flight.ts"],"names":[],"mappings":"AAEA,mGAAmG;AACnG,qBAAa,MAAM,CAAC,CAAC;;gBAMP,IAAI,EAAE,CAAC,SAAS,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC;IAOxD,mCAAmC;IACnC,IAAI,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAEtB;IAED,2EAA2E;IAC3E,IAAI,SAAS,IAAI,WAAW,CAE3B;IAED,6EAA6E;IAC7E,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC;CAWlD"}

package/dist/flight.js

@@ -0,0 +1,33 @@
+import { untilAborted } from "./until-aborted.js";
+/** One run of the work for a key in this process. Every caller that joins it gets how it ended. */
+export class Flight {
+    #ended = Promise.withResolvers();
+    #abandoned = new AbortController();
+    /** The callers that wait for the flight now. */
+    #waiting = 0;
+    constructor(work) {
+        Promise.try(work, this.#abandoned.signal).then(this.#ended.resolve, this.#ended.reject);
+    }
+    /** Settles as the work settled. */
+    get ended() {
+        return this.#ended.promise;
+    }
+    /** Aborts when every caller cancelled its wait before the flight ended. */
+    get abandoned() {
+        return this.#abandoned.signal;
+    }
+    /** Waits for the flight for one caller, until it ends or `signal` aborts. */
+    wait(signal) {
+        this.#waiting++;
+        const leave = () => {
+            this.#waiting--;
+            if (this.#waiting === 0)
+                this.#abandoned.abort();
+        };
+        signal?.addEventListener('abort', leave, { once: true });
+        const stopListening = () => signal?.removeEventListener('abort', leave);
+        this.#ended.promise.then(stopListening, stopListening);
+        return untilAborted(this.#ended.promise, signal);
+    }
+}
+//# sourceMappingURL=flight.js.map

package/dist/flight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight.js","sourceRoot":"","sources":["../src/flight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,mGAAmG;AACnG,MAAM,OAAO,MAAM;IACR,MAAM,GAAG,OAAO,CAAC,aAAa,EAAK,CAAC;IACpC,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IAC5C,gDAAgD;IAChD,QAAQ,GAAG,CAAC,CAAC;IAEb,YAAY,IAA4C;QACtD,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAC5C,IAAI,CAAC,MAAM,CAAC,OAAO,EACnB,IAAI,CAAC,MAAM,CAAC,MAAM,CACnB,CAAC;IACJ,CAAC;IAED,mCAAmC;IACnC,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;IAC7B,CAAC;IAED,2EAA2E;IAC3E,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;IAChC,CAAC;IAED,6EAA6E;IAC7E,IAAI,CAAC,MAA+B;QAClC,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC;gBAAE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACnD,CAAC,CAAC;QACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;QACvD,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;CACF"}

package/dist/follow.d.ts

@@ -0,0 +1,31 @@
+import type { Mutex } from '@zukhruf/mutex';
+import type { FlightRecords, LatestFlight } from './flight-records.ts';
+/** What a joiner watches while it waits for a flight in another process, and how often it looks. */
+export interface Watch {
+    readonly records: FlightRecords;
+    readonly mutex: Mutex;
+    readonly key: string;
+    readonly pollInterval: number;
+    /** Aborts when no caller in this process waits any more: the watch then stops. */
+    readonly abandoned: AbortSignal;
+}
+/**
+ * The flight that holds the key now, found by its record. `undefined` when
+ * the key became free and no new flight began, so the caller can try to lead.
+ */
+export declare function findFlight({ records, mutex, key, pollInterval, abandoned }: Watch, before: LatestFlight | undefined): Promise<string | undefined>;
+/** How following ended: with the value of the flight, or with no flight to follow, so the caller tries to lead. */
+export type Followed = {
+    readonly followed: true;
+    readonly value: unknown;
+} | {
+    readonly followed: false;
+};
+/**
+ * Waits for flight `id` to end and gives its value. It reads the record, not
+ * the lock: back-to-back holders can keep the key held at every look, so
+ * waiting for a free key could wait forever. The lock only tells whether a
+ * running flight still has a holder.
+ */
+export declare function follow({ records, mutex, key, pollInterval, abandoned }: Watch, first: string): Promise<Followed>;
+//# sourceMappingURL=follow.d.ts.map

package/dist/follow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow.d.ts","sourceRoot":"","sources":["../src/follow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAO5C,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEvE,oGAAoG;AACpG,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,EAAE,SAAS,EAAE,EAAE,KAAK,EACvD,MAAM,EAAE,YAAY,GAAG,SAAS,GAC/B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B;AAED,mHAAmH;AACnH,MAAM,MAAM,QAAQ,GAChB;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAC;AAEjC;;;;;GAKG;AACH,wBAAsB,MAAM,CAC1B,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,EAAE,SAAS,EAAE,EAAE,KAAK,EACvD,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC,CAkCnB"}

package/dist/follow.js

@@ -0,0 +1,60 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { FlightFailedError, FlightInterruptedError, FlightOutcomeLostError, } from "./errors.js";
+/**
+ * The flight that holds the key now, found by its record. `undefined` when
+ * the key became free and no new flight began, so the caller can try to lead.
+ */
+export async function findFlight({ records, mutex, key, pollInterval, abandoned }, before) {
+    for (;;) {
+        await delay(pollInterval, undefined, { signal: abandoned });
+        const now = await records.latest(key);
+        if (now && (now.id !== before?.id || before.status === 'running'))
+            return now.id;
+        if (!(await mutex.isHeld(key)))
+            return undefined;
+    }
+}
+/**
+ * Waits for flight `id` to end and gives its value. It reads the record, not
+ * the lock: back-to-back holders can keep the key held at every look, so
+ * waiting for a free key could wait forever. The lock only tells whether a
+ * running flight still has a holder.
+ */
+export async function follow({ records, mutex, key, pollInterval, abandoned }, first) {
+    let id = first;
+    let seenHeld = false;
+    for (;;) {
+        const outcome = await records.outcome(key, id);
+        switch (outcome.status) {
+            case 'succeeded':
+                return { followed: true, value: outcome.value };
+            case 'failed':
+                throw new FlightFailedError(key, outcome.error);
+            case 'interrupted':
+                if (outcome.successor === undefined)
+                    throw new FlightInterruptedError(key);
+                // The next holder closed a flight whose holder stopped, and began its own.
+                id = outcome.successor;
+                seenHeld = false;
+                continue;
+            case 'running':
+                if (await mutex.isHeld(key)) {
+                    seenHeld = true;
+                    await delay(pollInterval, undefined, { signal: abandoned });
+                    continue;
+                }
+                // The holder can finish between the two looks: read the record again.
+                if ((await records.outcome(key, id)).status !== 'running')
+                    continue;
+                // A record that was running before this joiner came was left by a
+                // holder that stopped long ago: there is no flight to join.
+                if (!seenHeld)
+                    return { followed: false };
+                // This joiner saw the holder run the flight, and the holder stopped.
+                throw new FlightInterruptedError(key);
+            case 'missing':
+                throw new FlightOutcomeLostError(key);
+        }
+    }
+}
+//# sourceMappingURL=follow.js.map

package/dist/follow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow.js","sourceRoot":"","sources":["../src/follow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAI3D,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAarB;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,EAAE,SAAS,EAAS,EACvD,MAAgC;IAEhC,SAAS,CAAC;QACR,MAAM,KAAK,CAAC,YAAY,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QAC5D,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,MAAM,EAAE,EAAE,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC;YAC/D,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;IACnD,CAAC;AACH,CAAC;AAOD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,YAAY,EAAE,SAAS,EAAS,EACvD,KAAa;IAEb,IAAI,EAAE,GAAG,KAAK,CAAC;IACf,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,SAAS,CAAC;QACR,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC/C,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC;YACvB,KAAK,WAAW;gBACd,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAClD,KAAK,QAAQ;gBACX,MAAM,IAAI,iBAAiB,CAAC,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;YAClD,KAAK,aAAa;gBAChB,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;oBACjC,MAAM,IAAI,sBAAsB,CAAC,GAAG,CAAC,CAAC;gBACxC,2EAA2E;gBAC3E,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;gBACvB,QAAQ,GAAG,KAAK,CAAC;gBACjB,SAAS;YACX,KAAK,SAAS;gBACZ,IAAI,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;oBAC5B,QAAQ,GAAG,IAAI,CAAC;oBAChB,MAAM,KAAK,CAAC,YAAY,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;oBAC5D,SAAS;gBACX,CAAC;gBACD,sEAAsE;gBACtE,IAAI,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS;oBAAE,SAAS;gBACpE,kEAAkE;gBAClE,4DAA4D;gBAC5D,IAAI,CAAC,QAAQ;oBAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;gBAC1C,qEAAqE;gBACrE,MAAM,IAAI,sBAAsB,CAAC,GAAG,CAAC,CAAC;YACxC,KAAK,SAAS;gBACZ,MAAM,IAAI,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { type FlightValue, type RunOptions, SingleFlight, } from './single-flight.ts';
+export type { Finished, FlightRecords, LatestFlight, Outcome, RecordedError, Status, } from './flight-records.ts';
+export { FileFlightRecords, type FileFlightRecordsOptions, } from './file-flight-records.ts';
+export { SharedFlight, type SharedFlightOptions } from './shared-flight.ts';
+export { FlightFailedError, FlightInterruptedError, FlightOutcomeLostError, } from './errors.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,OAAO,EACP,aAAa,EACb,MAAM,GACP,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { SingleFlight, } from "./single-flight.js";
+export { FileFlightRecords, } from "./file-flight-records.js";
+export { SharedFlight } from "./shared-flight.js";
+export { FlightFailedError, FlightInterruptedError, FlightOutcomeLostError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,YAAY,GACb,MAAM,oBAAoB,CAAC;AAS5B,OAAO,EACL,iBAAiB,GAElB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAA4B,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,aAAa,CAAC"}

package/dist/patiently.d.ts

@@ -0,0 +1,3 @@
+/** Runs `operation`, and runs it again while Windows refuses the file for a moment. */
+export declare function patiently<T>(operation: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=patiently.d.ts.map

package/dist/patiently.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patiently.d.ts","sourceRoot":"","sources":["../src/patiently.ts"],"names":[],"mappings":"AAoBA,uFAAuF;AACvF,wBAAsB,SAAS,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAc1E"}

package/dist/patiently.js

@@ -0,0 +1,31 @@
+import { setTimeout as delay } from 'node:timers/promises';
+/** How long to retry a file operation that Windows refuses for a moment. */
+const WINDOWS_PATIENCE = 1000;
+/**
+ * Windows refuses a file for a moment while another process has it open, for
+ * example a joiner that reads the record while the holder replaces it. The
+ * error code is the same as for a real permission denial, so a refusal is
+ * retried only for a limited time.
+ */
+function isRefusedForNow(error) {
+    return (process.platform === 'win32' &&
+        error instanceof Error &&
+        'code' in error &&
+        ['EPERM', 'EACCES', 'EBUSY'].includes(String(error.code)));
+}
+/** Runs `operation`, and runs it again while Windows refuses the file for a moment. */
+export async function patiently(operation) {
+    const started = performance.now();
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!isRefusedForNow(error) ||
+                performance.now() - started > WINDOWS_PATIENCE)
+                throw error;
+            await delay(Math.min(5 * 2 ** attempt, 100));
+        }
+    }
+}
+//# sourceMappingURL=patiently.js.map

package/dist/patiently.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patiently.js","sourceRoot":"","sources":["../src/patiently.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,CAAC,QAAQ,KAAK,OAAO;QAC5B,KAAK,YAAY,KAAK;QACtB,MAAM,IAAI,KAAK;QACf,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAC1D,CAAC;AACJ,CAAC;AAED,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,SAA2B;IAC5D,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,OAAO,MAAM,SAAS,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IACE,CAAC,eAAe,CAAC,KAAK,CAAC;gBACvB,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,gBAAgB;gBAE9C,MAAM,KAAK,CAAC;YACd,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/shared-flight.d.ts

@@ -0,0 +1,25 @@
+import { type Lease, type Mutex } from '@zukhruf/mutex';
+import { type FlightRecords } from './flight-records.ts';
+import { type FlightValue, type RunOptions } from './single-flight.ts';
+export interface SharedFlightOptions<T> {
+    /** Decides who flies: only the holder of the key runs the work. */
+    mutex: Mutex;
+    /** Where the outcomes live, so callers in other processes can join. Never the lock directory of the mutex. */
+    records: FlightRecords;
+    /** Turns a value read back from a record into `T`. Every caller, the leader too, gets `parse` of the value as JSON. */
+    parse: (value: unknown) => T;
+    /** Milliseconds between two looks at a record while a caller joins. Defaults to 100. */
+    pollInterval?: number;
+}
+/**
+ * Callers of one key share the flight in progress, in this process and in
+ * other processes. Callers in this process share one flight first. The holder
+ * of the key leads the flight, and the records let callers in other
+ * processes join it.
+ */
+export declare class SharedFlight<T> {
+    #private;
+    constructor({ mutex, records, parse, pollInterval, }: SharedFlightOptions<T>);
+    run(key: string, work: (lease: Lease) => Promise<T>, options?: RunOptions): Promise<FlightValue<T>>;
+}
+//# sourceMappingURL=shared-flight.d.ts.map

package/dist/shared-flight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-flight.d.ts","sourceRoot":"","sources":["../src/shared-flight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAS,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,qBAAqB,CAAC;AAExE,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,mEAAmE;IACnE,KAAK,EAAE,KAAK,CAAC;IACb,8GAA8G;IAC9G,OAAO,EAAE,aAAa,CAAC;IACvB,uHAAuH;IACvH,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC;IAC7B,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAcD;;;;;GAKG;AACH,qBAAa,YAAY,CAAC,CAAC;;gBAOb,EACV,KAAK,EACL,OAAO,EACP,KAAK,EACL,YAAkB,GACnB,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAYnB,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,EAClC,OAAO,GAAE,UAAe,GACvB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;CA0E3B"}

package/dist/shared-flight.js

@@ -0,0 +1,89 @@
+import { Modes } from '@zukhruf/mutex';
+import { recordedError } from "./flight-records.js";
+import { findFlight, follow } from "./follow.js";
+import { SingleFlight, } from "./single-flight.js";
+const skipIfBusy = Modes.skipIfBusy();
+/** Values travel as JSON, so every caller gets the value in the shape that a joiner in another process reads. */
+const encode = (value) => JSON.parse(JSON.stringify(value) ?? 'null');
+/**
+ * Callers of one key share the flight in progress, in this process and in
+ * other processes. Callers in this process share one flight first. The holder
+ * of the key leads the flight, and the records let callers in other
+ * processes join it.
+ */
+export class SharedFlight {
+    #local = new SingleFlight();
+    #mutex;
+    #records;
+    #parse;
+    #pollInterval;
+    constructor({ mutex, records, parse, pollInterval = 100, }) {
+        if (!(pollInterval >= 0) || !Number.isFinite(pollInterval)) {
+            throw new RangeError(`pollInterval must be a finite number of milliseconds >= 0, got ${pollInterval}.`);
+        }
+        this.#mutex = mutex;
+        this.#records = records;
+        this.#parse = parse;
+        this.#pollInterval = pollInterval;
+    }
+    async run(key, work, options = {}) {
+        const { value, joined } = await this.#local.run(key, (abandoned) => this.#leadOrFollow(key, work, options.onJoin, abandoned), options);
+        return { value: value.value, joined: joined || value.followed };
+    }
+    /**
+     * Runs for the first caller in this process. The callers that joined it
+     * here heard `onJoin` already; this caller hears it once it joins a flight
+     * of another process. Once no caller here waits (`abandoned`), it stops
+     * looking and never takes the key; a flight that it leads runs to its end,
+     * because callers in other processes can wait for its outcome.
+     */
+    async #leadOrFollow(key, work, onJoin, abandoned) {
+        const watch = {
+            records: this.#records,
+            mutex: this.#mutex,
+            key,
+            pollInterval: this.#pollInterval,
+            abandoned,
+        };
+        let told = false;
+        for (;;) {
+            const before = await this.#records.latest(key);
+            const led = await this.#mutex.acquire(key, (lease) => this.#lead(key, work, lease), { mode: skipIfBusy, signal: abandoned });
+            if (led.acquired)
+                return { value: led.value, followed: false };
+            const id = await findFlight(watch, before);
+            if (id === undefined)
+                continue;
+            if (!told)
+                onJoin?.();
+            told = true;
+            const followed = await follow(watch, id);
+            if (followed.followed)
+                return { value: this.#parse(followed.value), followed: true };
+        }
+    }
+    async #lead(key, work, lease) {
+        const id = await this.#records.begin(key);
+        let value;
+        try {
+            // A value that JSON cannot carry fails the flight: no joiner could read it.
+            value = encode(await work(lease));
+        }
+        catch (error) {
+            await this.#records.finish(key, id, {
+                status: 'failed',
+                error: recordedError(error),
+            });
+            throw error;
+        }
+        // Another holder may have run the work too: the value is not the outcome of one flight.
+        if (lease.signal.aborted) {
+            await this.#records.finish(key, id, { status: 'interrupted' });
+            throw lease.signal.reason;
+        }
+        // A throw here rejects the leader, although the work did its side effects.
+        await this.#records.finish(key, id, { status: 'succeeded', value });
+        return this.#parse(value);
+    }
+}
+//# sourceMappingURL=shared-flight.js.map

package/dist/shared-flight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-flight.js","sourceRoot":"","sources":["../src/shared-flight.ts"],"names":[],"mappings":"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"}

package/dist/single-flight.d.ts

@@ -0,0 +1,23 @@
+export interface RunOptions {
+    /** Called once, before this caller starts to wait for a flight that another caller started. */
+    onJoin?: (() => void) | undefined;
+    /** Stops the wait of this caller only, which then rejects with `signal.reason`. The flight runs on. */
+    signal?: AbortSignal | undefined;
+}
+/** What a caller gets: the value of the flight, and whether the caller joined a flight that another caller started. */
+export interface FlightValue<T> {
+    readonly value: T;
+    readonly joined: boolean;
+}
+/** Callers of one key in this process share the flight in progress. */
+export declare class SingleFlight<T> {
+    #private;
+    /**
+     * Runs `work` for `key`, or joins the flight of `key` in progress. `work`
+     * gets a signal that aborts only when every caller of the flight cancelled:
+     * work that can stop early may read it. Work that ignores it runs on, and
+     * the next call starts a new flight either way.
+     */
+    run(key: string, work: (abandoned: AbortSignal) => Promise<T>, { onJoin, signal }?: RunOptions): Promise<FlightValue<T>>;
+}
+//# sourceMappingURL=single-flight.d.ts.map

package/dist/single-flight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-flight.d.ts","sourceRoot":"","sources":["../src/single-flight.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IAClC,uGAAuG;IACvG,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAClC;AAED,uHAAuH;AACvH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,uEAAuE;AACvE,qBAAa,YAAY,CAAC,CAAC;;IAIzB;;;;;OAKG;IACG,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,CAAC,SAAS,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAC5C,EAAE,MAAM,EAAE,MAAM,EAAE,GAAE,UAAe,GAClC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;CAyB3B"}

package/dist/single-flight.js

@@ -0,0 +1,39 @@
+import { Flight } from "./flight.js";
+/** Callers of one key in this process share the flight in progress. */
+export class SingleFlight {
+    /** Only the flights in progress: a flight that ended leaves, so the next call starts a new one. */
+    #flights = new Map();
+    /**
+     * Runs `work` for `key`, or joins the flight of `key` in progress. `work`
+     * gets a signal that aborts only when every caller of the flight cancelled:
+     * work that can stop early may read it. Work that ignores it runs on, and
+     * the next call starts a new flight either way.
+     */
+    async run(key, work, { onJoin, signal } = {}) {
+        // A caller that already cancelled neither starts nor joins a flight.
+        signal?.throwIfAborted();
+        // No await before the flight is in the map: a second caller must find it.
+        const inProgress = this.#flights.get(key);
+        const flight = inProgress ?? this.#start(key, work);
+        const joined = inProgress !== undefined;
+        if (joined)
+            onJoin?.();
+        // The signal stops only this caller's wait. The work never sees it, so
+        // the other callers still get the value.
+        return { value: await flight.wait(signal), joined };
+    }
+    #start(key, work) {
+        const flight = new Flight(work);
+        this.#flights.set(key, flight);
+        const leave = () => {
+            if (this.#flights.get(key) === flight)
+                this.#flights.delete(key);
+        };
+        flight.ended.then(leave, leave);
+        // In the same step as the abort, so no caller joins a flight that nobody
+        // waits for (Go issue 22724: a new lookup joined a cancelled one).
+        flight.abandoned.addEventListener('abort', leave, { once: true });
+        return flight;
+    }
+}
+//# sourceMappingURL=single-flight.js.map

package/dist/single-flight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-flight.js","sourceRoot":"","sources":["../src/single-flight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAerC,uEAAuE;AACvE,MAAM,OAAO,YAAY;IACvB,mGAAmG;IAC1F,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;IAEjD;;;;;OAKG;IACH,KAAK,CAAC,GAAG,CACP,GAAW,EACX,IAA4C,EAC5C,EAAE,MAAM,EAAE,MAAM,KAAiB,EAAE;QAEnC,qEAAqE;QACrE,MAAM,EAAE,cAAc,EAAE,CAAC;QACzB,0EAA0E;QAC1E,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,UAAU,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,UAAU,KAAK,SAAS,CAAC;QACxC,IAAI,MAAM;YAAE,MAAM,EAAE,EAAE,CAAC;QACvB,uEAAuE;QACvE,yCAAyC;QACzC,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,CAAC,GAAW,EAAE,IAA4C;QAC9D,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,MAAM;gBAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnE,CAAC,CAAC;QACF,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAChC,yEAAyE;QACzE,mEAAmE;QACnE,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAClE,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}

package/dist/until-aborted.d.ts

@@ -0,0 +1,3 @@
+/** Settles like `promise`, or rejects with `signal.reason` first if `signal` aborts. */
+export declare function untilAborted<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+//# sourceMappingURL=until-aborted.d.ts.map

package/dist/until-aborted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"until-aborted.d.ts","sourceRoot":"","sources":["../src/until-aborted.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,CAAC,EAC5B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,CAAC,CAAC,CAiBZ"}

package/dist/until-aborted.js

@@ -0,0 +1,19 @@
+/** Settles like `promise`, or rejects with `signal.reason` first if `signal` aborts. */
+export function untilAborted(promise, signal) {
+    if (!signal)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        if (signal.aborted)
+            return abort();
+        signal.addEventListener('abort', abort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', abort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', abort);
+            reject(error);
+        });
+    });
+}
+//# sourceMappingURL=until-aborted.js.map

package/dist/until-aborted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"until-aborted.js","sourceRoot":"","sources":["../src/until-aborted.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAC1B,OAAmB,EACnB,MAA+B;IAE/B,IAAI,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC;IAC5B,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,KAAK,EAAE,CAAC;QACnC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE;YACR,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAC3C,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAC3C,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@zukhruf/single-flight",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.13",
+  "description": "Callers of one key share the run already in flight, in one process or across processes, and get its outcome instead of a busy error.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/single-flight"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/single-flight#readme",
+  "keywords": [
+    "single-flight",
+    "singleflight",
+    "request-coalescing",
+    "deduplication",
+    "mutex",
+    "inter-process"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@zukhruf/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@zukhruf/mutex": "^0.3.11"
+  },
+  "devDependencies": {
+    "@zukhruf/mutex": "^0.3.11"
+  }
+}