lambder 6.0.2 → 7.0.2

package/dist/mock/LambderMockEntryRegistry.js

@@ -0,0 +1,126 @@
+/**
+ * Which of register()'s arguments is the rest entry rather than a slice.
+ *
+ * Read off the one field restNotMocked() writes, which is also why that field
+ * is named as it is: a slice is keyed by endpoint names holding entries, so
+ * what tells the two apart has to be a key no endpoint name plausibly is,
+ * carrying a value no entry is.
+ */
+const isRestNotMockedEntry = (slice) => typeof slice.restNotMockedReason === "string";
+/**
+ * Which mock answers an endpoint: the registered entries, and the overrides
+ * standing over them.
+ *
+ * One of the four pieces of state LambderMockApp holds that nothing else
+ * touches; it meets the rest of the runtime at one call, the lookup a request
+ * makes. The app keeps the whole caller-facing surface (register,
+ * registerPartial, override, restoreOverrides, registeredNames) as
+ * delegations, because that surface is contract-typed and the checks that
+ * make it safe are compile-time; what lives here is the bookkeeping.
+ *
+ * Generic over the contract only so the entries keep their type through the
+ * map; the registry itself never reads one.
+ */
+export class LambderMockEntryRegistry {
+    entries = new Map();
+    /**
+     * The overrides standing over one endpoint, innermost last. A stack
+     * rather than one slot because overrides nest: an override a describe
+     * scopes and one an it scopes are both live, and restoring the inner one
+     * has to uncover the outer rather than the registry.
+     */
+    overrideStacks = new Map();
+    /** The reason register() was given a rest entry with; null while it was given none. */
+    restReason = null;
+    /**
+     * What a call to an endpoint no slice registered is refused with, or null
+     * when no rest entry was registered. A registration like any other, so
+     * reset() keeps it.
+     */
+    get restNotMockedReason() {
+        return this.restReason;
+    }
+    /**
+     * Adds every entry of every slice, and the rest entry where one is among
+     * them. Slices are staged and committed together, so a slice that fails a
+     * check leaves nothing behind: a caller that catches the error and retries
+     * sees the problem it is fixing rather than a duplicate-name error from
+     * its own first attempt. The rest entry is staged with them, for the same
+     * reason.
+     */
+    addSlices(slices) {
+        const staged = new Map();
+        let stagedRestReason = null;
+        for (const slice of slices) {
+            if (isRestNotMockedEntry(slice)) {
+                // Two of them answer the same calls with two different
+                // reasons, and which one a call would get is registration
+                // order, which is exactly what a duplicate name is refused
+                // for.
+                const registered = this.restReason ?? stagedRestReason;
+                if (registered !== null) {
+                    throw new Error(`LambderMockApp: the rest of the contract is already registered as not mocked ("${registered}"). One restNotMocked entry covers every endpoint the slices leave out.`);
+                }
+                stagedRestReason = slice.restNotMockedReason;
+                continue;
+            }
+            for (const [key, entry] of Object.entries(slice)) {
+                // The compile-time completeness check reads the slice's KEYS
+                // and registration reads entry.name, so the two have to agree
+                // or the check is checking something else than what runs. A
+                // hand-written slice is where they part: `{ ...userMocks,
+                // "user.list": someOtherEntry }` registers the other endpoint
+                // and leaves "user.list" unanswered, and the first symptom is
+                // an overlap error naming an endpoint nobody wrote twice.
+                if (key !== entry.name) {
+                    throw new Error(`LambderMockApp: slice key "${key}" holds the mock for "${entry.name}". Key every entry by its own endpoint name, or build the slice with mockApp.apiSlice(...).`);
+                }
+                if (this.entries.has(entry.name) || staged.has(entry.name)) {
+                    throw new Error(`LambderMockApp: endpoint "${entry.name}" is mocked in more than one slice.`);
+                }
+                staged.set(entry.name, entry);
+            }
+        }
+        for (const [name, entry] of staged)
+            this.entries.set(name, entry);
+        if (stagedRestReason !== null)
+            this.restReason = stagedRestReason;
+    }
+    /** The registered entry for a name, before any override; null when there is none. */
+    registered(apiName) {
+        return this.entries.get(apiName) ?? null;
+    }
+    /** Stacks an override over a registered entry and hands back its removal. */
+    pushOverride(name, entry) {
+        const stack = this.overrideStacks.get(name) ?? [];
+        stack.push(entry);
+        this.overrideStacks.set(name, stack);
+        // Removes this override wherever it sits rather than popping the top:
+        // scopes do not always unwind innermost first (an outer handle
+        // restored by hand while an inner one is still standing), and popping
+        // would then take down somebody else's override. Restoring twice is a
+        // no-op.
+        const restore = () => {
+            const current = this.overrideStacks.get(name);
+            const at = current?.lastIndexOf(entry) ?? -1;
+            if (!current || at === -1)
+                return;
+            current.splice(at, 1);
+            if (!current.length)
+                this.overrideStacks.delete(name);
+        };
+        return { restore };
+    }
+    /** Puts every overridden handler back, however deeply they were stacked. */
+    restoreOverrides() {
+        this.overrideStacks.clear();
+    }
+    /** The registered endpoint names. */
+    get names() {
+        return [...this.entries.keys()];
+    }
+    /** What answers this call: the innermost override, else the registered entry. */
+    entryFor(apiName) {
+        return this.overrideStacks.get(apiName)?.at(-1) ?? this.entries.get(apiName) ?? null;
+    }
+}

package/dist/mock/LambderMockFailureInjector.d.ts

@@ -0,0 +1,60 @@
+import type { LambderApiAnswer } from "../api/LambderApiAnswer.js";
+import type { LambderApiRequest } from "../api/LambderApiRequest.js";
+import type { LambderMockFailure, LambderMockFailureReason, LambderMockLatency } from "./LambderMockTypes.js";
+/**
+ * A failure the transport reports rather than an answer the caller reads:
+ * an injected network failure or timeout. The caller maps a rejected
+ * transport to `network`, or `timeout` when its own abort fired.
+ */
+export declare class LambderMockTransportError extends Error {
+    readonly reason: "network" | "timeout" | "offline";
+    constructor(reason: "network" | "timeout" | "offline");
+}
+/**
+ * What a call fails with and how long it takes to do it: the queued and
+ * standing failures per endpoint, the offline switch, and the configured
+ * latency.
+ *
+ * One of the four pieces of state LambderMockApp holds that nothing else
+ * touches, so it is its own object. The app keeps the whole surface
+ * (failNext, setFailure, setOffline, setLatency) as one-line delegations,
+ * which is what a caller reads; what moved is the bookkeeping behind them.
+ *
+ * Injected refusals are rendered through the real envelope helpers, never
+ * hand-written: an injected 429 and an earned one have to be the same bytes,
+ * or a test written against the injected shape passes while the real one
+ * would fail.
+ */
+export declare class LambderMockFailureInjector {
+    private readonly failuresNext;
+    private readonly failuresSet;
+    private offlineFlag;
+    private latency;
+    /** What latency was configured at creation, so reset() can put it back. */
+    private readonly initialLatency;
+    private readonly apiVersion;
+    constructor(options: {
+        apiVersion: string | null;
+        latency: LambderMockLatency;
+    });
+    /** True while every call should reject at the transport, as with no network at all. */
+    get offline(): boolean;
+    /** The next call to the endpoint fails this way; several calls queue in order. */
+    failNext(apiName: string, failure: LambderMockFailure | LambderMockFailureReason): void;
+    /** Every call to the endpoint fails this way until cleared with null. */
+    setFailure(apiName: string, failure: LambderMockFailure | LambderMockFailureReason | null): void;
+    setOffline(offline: boolean): void;
+    setLatency(latency: LambderMockLatency): void;
+    /** The failure this call should take, queued one first; null when the call should run. */
+    take(apiName: string): LambderMockFailure | null;
+    /** Milliseconds this call should take before it is answered. */
+    latencyFor(apiName: string): number;
+    /** Waits the configured latency, cancelled by the caller's abort. */
+    wait(ms: number, signal: AbortSignal | undefined): Promise<void>;
+    /** Waits for the caller's own abort, which is what a timeout is; a call with no signal waits for ever. */
+    waitForAbort(signal: AbortSignal | undefined): Promise<never>;
+    /** The answer an injected failure produces, or a throw for the ones that never reach the caller as answers. */
+    answerFor(failure: LambderMockFailure, request: LambderApiRequest): Promise<LambderApiAnswer>;
+    /** Clears every injected failure and puts the configured latency back. */
+    reset(): void;
+}

package/dist/mock/LambderMockFailureInjector.js

@@ -0,0 +1,138 @@
+import { LambderApiRefusal } from "../shared/wire/LambderApiRefusal.js";
+import { crashAnswer, refusalAnswer, sessionExpiredAnswer, versionExpiredAnswer } from "../api/LambderApiEnvelope.js";
+import { rateLimitRefusal } from "../api/LambderApiRateLimits.js";
+/** An injected refusal's message, from a string, a full message, or the reason's own wording. */
+const toRefusalMessage = (message, fallback) => typeof message === "string" ? { type: "warning", content: message }
+    : message ?? { type: "warning", content: fallback };
+/**
+ * A failure the transport reports rather than an answer the caller reads:
+ * an injected network failure or timeout. The caller maps a rejected
+ * transport to `network`, or `timeout` when its own abort fired.
+ */
+export class LambderMockTransportError extends Error {
+    reason;
+    constructor(reason) {
+        super(`LambderMockApp: ${reason === "offline" ? "the mock is offline" : `injected ${reason} failure`}`);
+        this.name = "LambderMockTransportError";
+        this.reason = reason;
+    }
+}
+/**
+ * What a call fails with and how long it takes to do it: the queued and
+ * standing failures per endpoint, the offline switch, and the configured
+ * latency.
+ *
+ * One of the four pieces of state LambderMockApp holds that nothing else
+ * touches, so it is its own object. The app keeps the whole surface
+ * (failNext, setFailure, setOffline, setLatency) as one-line delegations,
+ * which is what a caller reads; what moved is the bookkeeping behind them.
+ *
+ * Injected refusals are rendered through the real envelope helpers, never
+ * hand-written: an injected 429 and an earned one have to be the same bytes,
+ * or a test written against the injected shape passes while the real one
+ * would fail.
+ */
+export class LambderMockFailureInjector {
+    failuresNext = new Map();
+    failuresSet = new Map();
+    offlineFlag = false;
+    latency;
+    /** What latency was configured at creation, so reset() can put it back. */
+    initialLatency;
+    apiVersion;
+    constructor(options) {
+        this.apiVersion = options.apiVersion;
+        this.latency = options.latency;
+        this.initialLatency = options.latency;
+    }
+    /** True while every call should reject at the transport, as with no network at all. */
+    get offline() { return this.offlineFlag; }
+    /** The next call to the endpoint fails this way; several calls queue in order. */
+    failNext(apiName, failure) {
+        const queue = this.failuresNext.get(apiName) ?? [];
+        queue.push(typeof failure === "string" ? { reason: failure } : failure);
+        this.failuresNext.set(apiName, queue);
+    }
+    /** Every call to the endpoint fails this way until cleared with null. */
+    setFailure(apiName, failure) {
+        if (failure === null)
+            this.failuresSet.delete(apiName);
+        else
+            this.failuresSet.set(apiName, typeof failure === "string" ? { reason: failure } : failure);
+    }
+    setOffline(offline) { this.offlineFlag = offline; }
+    setLatency(latency) { this.latency = latency; }
+    /** The failure this call should take, queued one first; null when the call should run. */
+    take(apiName) {
+        const queue = this.failuresNext.get(apiName);
+        if (queue?.length) {
+            const next = queue.shift();
+            if (!queue.length)
+                this.failuresNext.delete(apiName);
+            return next;
+        }
+        return this.failuresSet.get(apiName) ?? null;
+    }
+    /** Milliseconds this call should take before it is answered. */
+    latencyFor(apiName) {
+        const latency = this.latency;
+        if (typeof latency === "number")
+            return latency;
+        if (typeof latency === "function")
+            return latency(apiName);
+        return latency.min + Math.random() * Math.max(0, latency.max - latency.min);
+    }
+    /** Waits the configured latency, cancelled by the caller's abort. */
+    wait(ms, signal) {
+        if (ms <= 0)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { signal?.removeEventListener("abort", onAbort); resolve(); }, ms);
+            const onAbort = () => { clearTimeout(timer); reject(new LambderMockTransportError("network")); };
+            if (signal?.aborted) {
+                clearTimeout(timer);
+                reject(new LambderMockTransportError("network"));
+                return;
+            }
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    /** Waits for the caller's own abort, which is what a timeout is; a call with no signal waits for ever. */
+    waitForAbort(signal) {
+        return new Promise((_resolve, reject) => {
+            if (!signal)
+                return;
+            if (signal.aborted) {
+                reject(new LambderMockTransportError("timeout"));
+                return;
+            }
+            signal.addEventListener("abort", () => reject(new LambderMockTransportError("timeout")), { once: true });
+        });
+    }
+    /** The answer an injected failure produces, or a throw for the ones that never reach the caller as answers. */
+    async answerFor(failure, request) {
+        switch (failure.reason) {
+            case "network": throw new LambderMockTransportError("network");
+            case "timeout": return await this.waitForAbort(request.signal);
+            case "server": return crashAnswer(this.apiVersion);
+            case "refusal": {
+                const message = toRefusalMessage(failure.message, "Injected refusal.");
+                return refusalAnswer(new LambderApiRefusal(message.content, { errorMessage: message, statusCode: failure.statusCode }), this.apiVersion);
+            }
+            case "notAuthorized": {
+                const message = toRefusalMessage(failure.message, "Injected authorization refusal.");
+                return refusalAnswer(new LambderApiRefusal(message.content, { errorMessage: message, notAuthorized: true }), this.apiVersion);
+            }
+            case "sessionExpired": return sessionExpiredAnswer(this.apiVersion);
+            case "versionExpired": return versionExpiredAnswer(this.apiVersion);
+            case "rateLimited": return refusalAnswer(rateLimitRefusal("Injected rate limit.", failure.retryAfterSeconds ?? 30, failure.message), this.apiVersion);
+        }
+    }
+    /** Clears every injected failure and puts the configured latency back. */
+    reset() {
+        this.failuresNext.clear();
+        this.failuresSet.clear();
+        this.offlineFlag = false;
+        this.latency = this.initialLatency;
+    }
+}