@gibs/quotes 1.13.0

package/dist/single-flight.d.ts

@@ -0,0 +1,90 @@
+import { type DisplayProviderSlot } from './quote-service-contract.js';
+/**
+ * The bucket-and-amount-aware in-flight coordinator `docs/quote-service.md`'s
+ * "Cache" section describes: "identical concurrent requests wait on one
+ * upstream call. An `estimate-ok` request joins an in-flight call for another
+ * amount in the same bucket and gets a scaled answer."
+ *
+ * WHY THIS IS SEPARATE FROM `cache.ts`'S OWN `joinOrRun`. `AnswerCache.joinOrRun`
+ * only ever dedups CALLERS OF THE IDENTICAL KEY, and a key already collapses
+ * every amount in a two-significant-figure bucket (`displayQuoteCacheKey`) —
+ * so it already gives an `estimate-ok` ask sharing behaviour for free. What it
+ * cannot do is the ONE THING this module exists for: telling an `exact` ask
+ * apart from an `estimate-ok` one sharing the same key, so that an `exact`
+ * ask NEVER receives another asker's answer for a different literal amount —
+ * `docs/quote-service.md`'s rule, "`precision: 'exact'` never takes a scaled
+ * answer" — while an `estimate-ok` ask still gets to share, scaled to its own
+ * amount. This module keys its own two in-flight maps directly on
+ * `(bucketKey, precision, askedAmount)` rather than reusing `AnswerCache`'s
+ * single, coarser key space.
+ */
+/** Whether an ask may join an in-flight call for a different literal amount in the same bucket. */
+export type SingleFlightPrecision = 'estimate-ok' | 'exact';
+/** One caller's own request entering single-flight de-duplication. */
+export type SingleFlightRequest = {
+    /** The bucket-level key this ask maps to — a {@link displayQuoteCacheKey} result. */
+    readonly bucketKey: string;
+    /** This caller's own literal amount, in the asked token's base units. */
+    readonly askedAmount: bigint;
+    /** `'exact'` only ever shares a call with an identical literal amount; `'estimate-ok'` shares any call in the bucket. */
+    readonly precision: SingleFlightPrecision;
+};
+/** What running the shared upstream call produces: the raw answer, and the literal amount it was actually asked for. */
+export type SingleFlightOutcome = {
+    readonly answer: DisplayProviderSlot;
+    /** The amount `answer` is a genuine, un-scaled reply to — the FIRST caller's own amount, since only the first caller's `run` is ever invoked. */
+    readonly askedAmount: bigint;
+};
+/** What {@link SingleFlightGroup.ask} hands back to one caller. */
+export type SingleFlightResult = {
+    /** This caller's own answer — scaled to its own amount when it joined a call for a different one. */
+    readonly answer: DisplayProviderSlot;
+    /** Whether this caller joined another's in-flight call rather than starting its own. */
+    readonly joined: boolean;
+};
+/** Runs the shared upstream call for a key, if nobody else is already running one. */
+export type SingleFlightRun = () => Promise<SingleFlightOutcome>;
+/**
+ * Thrown when `run` does not settle before {@link SingleFlightConfig.timeoutMs}.
+ * Every caller sharing that call — the one that started it and every joiner —
+ * rejects with this.
+ *
+ * A CALLER'S OWN ABORT NEVER REACHES THIS FAR. `SingleFlightGroup.ask` takes
+ * no `AbortSignal`, by design: `docs/quote-service.md`'s rule, "a client
+ * disconnect never cancels the shared call," is upheld structurally, by never
+ * giving a caller a channel to cancel it, rather than by remembering to
+ * ignore one. Only this module's OWN timeout — never a caller — ends a call
+ * that runs too long.
+ */
+export declare class SingleFlightTimeoutError extends Error {
+    readonly key: string;
+    readonly timeoutMs: number;
+    constructor(key: string, timeoutMs: number);
+}
+/** The bucket-and-amount-aware in-flight coordinator. */
+export type SingleFlightGroup = {
+    /**
+     * Asks for `request`, sharing an already in-flight call when this
+     * request's own precision allows it, or starting `run` when it does not.
+     *
+     * @param request - this caller's own bucket key, amount and precision
+     * @param run - the upstream call to make, if nobody joinable is already running one
+     * @returns this caller's own answer, and whether it joined another's call
+     * @throws {SingleFlightTimeoutError} when the shared call does not settle within the timeout
+     */
+    readonly ask: (request: SingleFlightRequest, run: SingleFlightRun) => Promise<SingleFlightResult>;
+};
+/** How a host builds a {@link SingleFlightGroup}. */
+export type SingleFlightConfig = {
+    /** How long a shared call may run before every caller sharing it rejects with {@link SingleFlightTimeoutError}. Defaults to {@link DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+};
+/** The 15 s default timeout `docs/quote-service.md`'s "Cache" section names: "own 15 s timeout." */
+export declare const DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 15000;
+/**
+ * Builds a fresh, empty {@link SingleFlightGroup}.
+ *
+ * @param config - see {@link SingleFlightConfig}
+ * @returns the group
+ */
+export declare const createSingleFlightGroup: (config?: SingleFlightConfig) => SingleFlightGroup;

package/dist/single-flight.js

@@ -0,0 +1,142 @@
+import { scaleToAskedAmount } from './quote-guards.js';
+import { decodeBaseUnitsAmount, encodeBaseUnitsAmount, toEstimatedDelivery, } from './quote-service-contract.js';
+/**
+ * Thrown when `run` does not settle before {@link SingleFlightConfig.timeoutMs}.
+ * Every caller sharing that call — the one that started it and every joiner —
+ * rejects with this.
+ *
+ * A CALLER'S OWN ABORT NEVER REACHES THIS FAR. `SingleFlightGroup.ask` takes
+ * no `AbortSignal`, by design: `docs/quote-service.md`'s rule, "a client
+ * disconnect never cancels the shared call," is upheld structurally, by never
+ * giving a caller a channel to cancel it, rather than by remembering to
+ * ignore one. Only this module's OWN timeout — never a caller — ends a call
+ * that runs too long.
+ */
+export class SingleFlightTimeoutError extends Error {
+    key;
+    timeoutMs;
+    constructor(key, timeoutMs) {
+        super(`no answer for "${key}" within ${timeoutMs}ms`);
+        this.key = key;
+        this.timeoutMs = timeoutMs;
+        this.name = 'SingleFlightTimeoutError';
+    }
+}
+/** The 15 s default timeout `docs/quote-service.md`'s "Cache" section names: "own 15 s timeout." */
+export const DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS = 15_000;
+const scheduleTimer = (callback, delayMs) => {
+    const handle = setTimeout(callback, Math.max(0, delayMs));
+    if (typeof handle === 'object' && handle !== null && 'unref' in handle) {
+        handle.unref();
+    }
+    return () => clearTimeout(handle);
+};
+/**
+ * Turns the shared call's own outcome into ONE joiner's own answer: unchanged
+ * when the joiner's amount matches the amount actually asked upstream (a
+ * genuine, un-scaled reply for that joiner too), or scaled via
+ * {@link scaleToAskedAmount} and re-labelled `basis: 'scaled-from-nearby-amount'`
+ * otherwise. A refusal or a `pending` slot carries no figure to scale, so it
+ * passes through unchanged either way — only `cache` is set to `'joined'` on
+ * a `quoted` answer, since only that status carries the field.
+ *
+ * @param outcome - the shared call's own outcome
+ * @param joinerAskedAmount - this joiner's own literal amount
+ * @returns this joiner's own answer
+ */
+const answerForJoiner = (outcome, joinerAskedAmount) => {
+    const { answer } = outcome;
+    if (answer.status !== 'quoted')
+        return answer;
+    if (outcome.askedAmount === joinerAskedAmount) {
+        return { ...answer, cache: 'joined' };
+    }
+    const rawExpected = decodeBaseUnitsAmount(answer.expectedAmount);
+    const scaledExpected = scaleToAskedAmount(rawExpected, joinerAskedAmount, outcome.askedAmount);
+    const scaledMinimum = answer.minimumAmount === undefined
+        ? undefined
+        : scaleToAskedAmount(decodeBaseUnitsAmount(answer.minimumAmount), joinerAskedAmount, outcome.askedAmount);
+    return {
+        status: 'quoted',
+        basis: 'scaled-from-nearby-amount',
+        askedAmount: encodeBaseUnitsAmount(joinerAskedAmount),
+        quotedAt: answer.quotedAt,
+        ageMs: answer.ageMs,
+        cache: 'joined',
+        expectedAmount: toEstimatedDelivery(scaledExpected),
+        ...(scaledMinimum === undefined ? {} : { minimumAmount: toEstimatedDelivery(scaledMinimum) }),
+        scaledFrom: { askedAmount: answer.askedAmount, expectedAmount: answer.expectedAmount },
+    };
+};
+/**
+ * Builds a fresh, empty {@link SingleFlightGroup}.
+ *
+ * @param config - see {@link SingleFlightConfig}
+ * @returns the group
+ */
+export const createSingleFlightGroup = (config = {}) => {
+    const timeoutMs = config.timeoutMs ?? DEFAULT_SINGLE_FLIGHT_TIMEOUT_MS;
+    // `estimate-ok` asks share ONE call per bucket, regardless of literal
+    // amount — matching "joins an in-flight call for another amount in the
+    // same bucket." `exact` asks share only with an identical literal amount,
+    // in their OWN map, so they never inherit an estimate-ok call's amount.
+    const estimateInFlightByBucket = new Map();
+    const exactInFlightByAmountKey = new Map();
+    const runWithTimeout = (key, run) => new Promise((resolve, reject) => {
+        let settled = false;
+        const cancelTimer = scheduleTimer(() => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new SingleFlightTimeoutError(key, timeoutMs));
+        }, timeoutMs);
+        run().then((outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            cancelTimer();
+            resolve(outcome);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cancelTimer();
+            reject(error);
+        });
+    });
+    return {
+        ask: async (request, run) => {
+            if (request.precision === 'exact') {
+                const amountKey = `${request.bucketKey}#exact#${request.askedAmount.toString()}`;
+                const existing = exactInFlightByAmountKey.get(amountKey);
+                if (existing !== undefined) {
+                    const outcome = await existing;
+                    return { answer: answerForJoiner(outcome, request.askedAmount), joined: true };
+                }
+                const promise = runWithTimeout(amountKey, run);
+                exactInFlightByAmountKey.set(amountKey, promise);
+                try {
+                    const outcome = await promise;
+                    return { answer: outcome.answer, joined: false };
+                }
+                finally {
+                    exactInFlightByAmountKey.delete(amountKey);
+                }
+            }
+            const existing = estimateInFlightByBucket.get(request.bucketKey);
+            if (existing !== undefined) {
+                const outcome = await existing;
+                return { answer: answerForJoiner(outcome, request.askedAmount), joined: true };
+            }
+            const promise = runWithTimeout(request.bucketKey, run);
+            estimateInFlightByBucket.set(request.bucketKey, promise);
+            try {
+                const outcome = await promise;
+                return { answer: outcome.answer, joined: false };
+            }
+            finally {
+                estimateInFlightByBucket.delete(request.bucketKey);
+            }
+        },
+    };
+};