@snail-js/api 0.1.27 → 1.0.0

package/dist/plugins/interceptor/type.d.ts

@@ -0,0 +1,45 @@
+import type { AxiosResponse, InternalAxiosRequestConfig } from "axios";
+import type { SnailContext } from "../../core/context.js";
+/**
+ * Shared shapes of the interceptor plugin.
+ *
+ * ## Why these are not axios' own interceptors
+ *
+ * axios keeps its interceptor lists on the *instance* (`axios.interceptors`), so
+ * `use()` there can only express "every request of this instance". A decorator
+ * such as `@BeforeRequest()` needs the opposite granularity — this one method,
+ * plus this one api class — and it has to be ordered against the other plugins
+ * (see `docs/guide/plugin-lifecycle.md` §2.1). Both are impossible at instance level, which
+ * is why interceptors run on the plugin lifecycle instead.
+ */
+/**
+ * One request or response interceptor.
+ *
+ * `T` is `InternalAxiosRequestConfig` while the request is being prepared and
+ * `AxiosResponse` once a response exists. Both callbacks receive the live
+ * {@link SnailContext} as a second argument, so an interceptor may read the
+ * method identity (`ctx.fullName`) without the plugin having to inject it.
+ *
+ * Returning `undefined` from `onFulfilled` keeps the value it received: most
+ * interceptors mutate in place, and forcing every one of them to return the
+ * config would make the common case noisy.
+ */
+export interface InterceptorEntry<T = unknown> {
+    /** Runs before the request is handed to axios, or against the response. */
+    onFulfilled?: (value: T, ctx: SnailContext) => T | void | Promise<T | void>;
+    /**
+     * Runs when `onFulfilled` — or an earlier interceptor in the same phase —
+     * throws.
+     *
+     * The plugin calls it with the thrown value while the request is still
+     * recoverable, unlike `onError` which only observes a settled failure. Any
+     * value other than `undefined` is adopted as the current config/response;
+     * returning `undefined` or throwing re-propagates the failure.
+     */
+    onRejected?: (error: unknown, ctx: SnailContext) => unknown;
+}
+/** An entry that runs while the outgoing axios config is still mutable. */
+export type RequestInterceptorEntry = InterceptorEntry<InternalAxiosRequestConfig>;
+/** An entry that runs against a response that already exists. */
+export type ResponseInterceptorEntry = InterceptorEntry<AxiosResponse>;
+//# sourceMappingURL=type.d.ts.map

package/dist/plugins/interceptor/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/plugins/interceptor/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,OAAO,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,2EAA2E;IAC3E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,YAAY,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAE5E;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC;CAC7D;AAED,2EAA2E;AAC3E,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,CAAC,0BAA0B,CAAC,CAAC;AAEnF,iEAAiE;AACjE,MAAM,MAAM,wBAAwB,GAAG,gBAAgB,CAAC,aAAa,CAAC,CAAC"}

package/dist/plugins/pool/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Request pool plugin.
+ *
+ * ```ts
+ * import { RequestPool } from "@snail-js/api/plugins";
+ *
+ * Service.use(RequestPool({ concurrency: 4, maxQueue: 50, queueTimeout: 10_000 }));
+ * ```
+ *
+ * Bounds how many requests are in flight at once, with a priority-ordered, bounded,
+ * time-limited queue. It exists because the browser's own request queue is FIFO,
+ * invisible and unprioritised — see `RequestPoolOptions` for the full reasoning,
+ * including why HTTP/2 does not remove the need for it.
+ *
+ * `priority: -150` puts it below the cache (`-100`), so it is the last thing to run
+ * before the transport and a cache hit never consumes a slot.
+ *
+ * @packageDocumentation
+ */
+export { RequestPool, POOL_PLUGIN_NAME, POOL_PRIORITY, clearPool, isPoolError, poolStats } from "./plugin.js";
+export type { RequestPoolPlugin } from "./plugin.js";
+export { RequestPoolScheduler } from "./scheduler.js";
+export type { AbortLike, PoolTicket, RequestPoolOptions, RequestPoolStats } from "./scheduler.js";
+export { POOL_ERROR_CODES, SnailPoolError } from "./type.js";
+export type { PoolErrorCode } from "./type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/pool/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/pool/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,WAAW,EACX,SAAS,EACV,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EACV,SAAS,EACT,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC"}

package/dist/plugins/pool/plugin.d.ts

@@ -0,0 +1,83 @@
+import { SnailPoolError } from "./type.js";
+import { RequestPoolScheduler, type RequestPoolOptions, type RequestPoolStats } from "./scheduler.js";
+/** Plugin name; also the identity used by `Service.use()` / `Service.remove()`. */
+export declare const POOL_PLUGIN_NAME = "pool";
+/**
+ * Priority of the pool band.
+ *
+ * **Below** the cache (`-100`), which is the whole point: forward hooks run
+ * highest-priority first, so the pool is the very last thing to run before the
+ * transport. A request that the cache can answer never reaches the pool and never
+ * consumes a slot. Putting the pool above the cache would let a handful of cached
+ * reads occupy the entire pool and starve the real requests behind them.
+ */
+export declare const POOL_PRIORITY = -150;
+/** The pool plugin object plus live access to its scheduler. */
+export interface RequestPoolPlugin {
+    readonly name: string;
+    readonly priority: number;
+    /**
+     * The scheduler, available once `install` has run.
+     *
+     * Exposed so an application can read {@link RequestPoolScheduler.stats} for a
+     * loading indicator, or widen `concurrency` when it learns the backend is
+     * coping.
+     */
+    readonly scheduler: RequestPoolScheduler | undefined;
+}
+/**
+ * Bound how many requests are in flight at once.
+ *
+ * ```ts
+ * Service.use(RequestPool({ concurrency: 4, maxQueue: 50, queueTimeout: 10_000 }));
+ *
+ * // `ctx.state` is readable from the priority callback, so an interactive request
+ * // can jump ahead of a background prefetch.
+ * Service.use(RequestPool({ concurrency: 4, priority: (ctx) => (ctx.state.get("prefetch") ? 100 : 0) }));
+ * ```
+ *
+ * ## What problem this solves
+ *
+ * See {@link RequestPoolOptions} for why the browser's own queue is not enough.
+ * In short: the built-in one is FIFO, invisible and unprioritised, so a burst from
+ * one screen can starve the request the user is actually waiting for, and nothing
+ * fails fast when the backlog grows without bound.
+ *
+ * ## Where it sits
+ *
+ * Last in forward order, immediately before the network call, and it holds its slot
+ * only for the transport — `next()` resolves once the response has been received,
+ * so validation, transformation and the caller's reactive updates happen after the
+ * slot is already back in the pool.
+ *
+ * A cache hit short-circuits `beforeRequest` upstream of this plugin, so cached
+ * reads cost no concurrency.
+ *
+ * ## One path it does not cover
+ *
+ * `useTokenAuth` replays a request that came back `401` by re-running the transport
+ * directly, deliberately without re-entering `beforeRequest` (re-entering would
+ * loop). Those replays therefore **do not pass through this pool** and are not
+ * counted against `concurrency`.
+ *
+ * The practical impact is small — replays are bounded by the number of requests
+ * that were in flight when the token expired, which were already uncapped — but it
+ * is worth knowing before reaching for the pool to protect a backend from an auth
+ * storm. If that matters, cap it at the source: use `useRequest`'s own concurrency
+ * control, or let `useTokenAuth` refresh proactively rather than on the first 401.
+ */
+export declare function RequestPool(options?: RequestPoolOptions): RequestPoolPlugin;
+/** Read the live counters of an installed pool plugin, or `undefined`. */
+export declare function poolStats(plugin: RequestPoolPlugin): RequestPoolStats | undefined;
+/** Drop every queued request of an installed pool plugin. */
+export declare function clearPool(plugin: RequestPoolPlugin, reason?: unknown): void;
+/**
+ * `true` when `error` came from the pool rather than from the transport.
+ *
+ * Lets a caller tell "refused before it was ever sent" — safe to retry later —
+ * apart from a real network failure. Covers all four refusal paths: a full queue,
+ * a queue wait that timed out, a request abandoned while waiting, and a queue
+ * cleared by an uninstall.
+ */
+export declare function isPoolError(error: unknown): error is SnailPoolError;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/pool/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/pool/plugin.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EACL,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AAErB,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,oBAAoB,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,CAgD3E;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,SAAS,CAEjF;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAEnE"}

package/dist/plugins/pool/scheduler.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The slice of `AbortSignal` the scheduler uses.
+ *
+ * Structurally typed rather than declared as `AbortSignal` because axios hands the
+ * plugin its own `GenericAbortSignal`, which does not satisfy the DOM interface —
+ * it lacks `reason`/`throwIfAborted` and even types the listener methods as
+ * optional. In practice the object is a real `AbortSignal`, so the listener path is
+ * always available; the optional methods are handled anyway, and a signal that
+ * cannot be listened to simply means an already-queued request is not withdrawn
+ * early — it still gets its slot and is rejected by the transport.
+ */
+export interface AbortLike {
+    readonly aborted: boolean;
+    addEventListener?(type: "abort", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener?(type: "abort", listener: () => void): void;
+}
+/**
+ * Options accepted by the request-pool plugin.
+ *
+ * ## Why a pool exists at all
+ *
+ * A browser already queues requests: HTTP/1.1 allows about six connections per
+ * origin, and everything beyond that waits inside the network stack. That built-in
+ * queue is FIFO, invisible, and unprioritised — an application that fires fifty
+ * requests from one screen cannot say that the one the user is looking at should
+ * go first, cannot observe how many are waiting, and cannot avoid a burst that
+ * starves the rest of the page.
+ *
+ * HTTP/2 does not remove the need either: multiplexing replaces the six-connection
+ * cap with a *stream* limit (commonly 100), and the server still has a finite
+ * capacity. A burst of five hundred requests over HTTP/2 will happily saturate it.
+ *
+ * A pool gives three things the browser cannot: a hard ceiling that holds on both
+ * protocols, a priority order, and a bounded queue that fails fast instead of
+ * silently piling up.
+ */
+export interface RequestPoolOptions {
+    /**
+     * Maximum requests in flight at once. Defaults to `6`.
+     *
+     * Six is the classic HTTP/1.1 per-origin connection cap, so it is the largest
+     * value that cannot make things worse on an old server while still bounding an
+     * HTTP/2 burst. Raising it helps only when the backend is known to cope.
+     */
+    concurrency?: number;
+    /**
+     * Maximum requests allowed to *wait*. Defaults to `Infinity`.
+     *
+     * Set a finite value to fail fast: once the queue is full, an extra request
+     * rejects immediately rather than joining an unbounded backlog the user will
+     * never see resolved.
+     */
+    maxQueue?: number;
+    /**
+     * How long a queued request may wait, in milliseconds. Defaults to `0`, meaning
+     * no limit.
+     *
+     * A request the user has stopped waiting for is worse than a failed one — it
+     * still consumes a slot eventually and may overwrite fresher data.
+     */
+    queueTimeout?: number;
+    /**
+     * Ordering weight for a queued request. **Lower runs first**; ties keep arrival
+     * order, and a request that finds a free slot never queues at all.
+     *
+     * @example
+     * ```ts
+     * // Requests the user is looking at jump ahead of background prefetches.
+     * priority: (ctx) => (ctx.state.get("prefetch") ? 100 : 0)
+     * ```
+     */
+    priority?: (ctx: unknown) => number;
+}
+/** Live counters for a {@link RequestPoolScheduler}. */
+export interface RequestPoolStats {
+    /** Requests currently holding a slot. */
+    active: number;
+    /** Requests waiting for a slot. */
+    queued: number;
+    /** Configured ceiling. */
+    concurrency: number;
+}
+/** A resolve/reject pair plus the bookkeeping the queue needs to drop it. */
+export interface PoolTicket {
+    /** Give the slot back. Idempotent. */
+    readonly release: () => void;
+}
+/**
+ * The scheduling core of the request pool.
+ *
+ * Deterministic and free of any request or plugin concept: it hands out `release`
+ * callbacks and knows nothing about what they guard. That makes the hard part —
+ * ordering, fairness and the guarantee that a slot is always returned — testable
+ * on its own, without a server or a network.
+ *
+ * ## Messages come from the plugin
+ *
+ * The refusal messages are contributed by `RequestPool`'s `setup`, following the
+ * plugin-owned-strings convention. Using this class **standalone** therefore yields
+ * the raw message keys rather than translated text — the `code` on each
+ * {@link SnailPoolError} is always correct, and that is what callers should branch
+ * on. Registering a catalogue yourself is enough if you want the text too.
+ *
+ * ## The invariant that matters
+ *
+ * `active` must never drift from the number of outstanding tickets. Every failure
+ * path (a queue that is full, a wait that times out, a request that is aborted,
+ * a waiter dropped by `clear`) either never increments `active` or has already
+ * been counted, and `release()` is idempotent so a double release from a `finally`
+ * plus an abort listener cannot leak a slot. A leaked slot is invisible until the
+ * pool permanently deadlocks at its ceiling, at which point every later request
+ * hangs — which is why it is enforced here rather than at the call site.
+ */
+export declare class RequestPoolScheduler {
+    private concurrency;
+    private readonly maxQueue;
+    private readonly queueTimeout;
+    private readonly priorityOf;
+    private active;
+    private sequence;
+    private readonly waiters;
+    constructor(options?: RequestPoolOptions);
+    /** Current counters. */
+    get stats(): RequestPoolStats;
+    /** Change the ceiling at runtime; raising it immediately admits queued work. */
+    setConcurrency(value: number): void;
+    /**
+     * Take a slot, or wait for one.
+     *
+     * Resolves with a ticket whose `release()` returns the slot. Rejects when the
+     * queue is full or the wait exceeds `queueTimeout`. `signal` lets an abandoned
+     * request leave the queue instead of holding a place it will never use.
+     */
+    acquire(ctx: unknown, signal?: AbortLike): Promise<PoolTicket>;
+    /**
+     * Drop every waiter, rejecting each with `reason`.
+     *
+     * Used on uninstall: a queued request must not sit forever waiting for a pool
+     * that will never admit it.
+     */
+    clear(reason?: unknown): void;
+    /** Hand out one slot. */
+    private issue;
+    /** Admit as many waiters as there are free slots. */
+    private pump;
+    /** Lowest priority number first, then arrival order. */
+    private sort;
+    private priorityOfFor;
+    private abortError;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/plugins/pool/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/plugins/pool/scheduler.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3F,mBAAmB,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACjE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;CACrC;AAED,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyC;IAEpE,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC,YAAY,OAAO,GAAE,kBAAuB,EAU3C;IAED,wBAAwB;IACxB,IAAI,KAAK,IAAI,gBAAgB,CAE5B;IAED,gFAAgF;IAChF,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAIlC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAqE7D;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAQ5B;IAID,yBAAyB;IACzB,OAAO,CAAC,KAAK;IAcb,qDAAqD;IACrD,OAAO,CAAC,IAAI;IAOZ,wDAAwD;IACxD,OAAO,CAAC,IAAI;IAMZ,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,UAAU;CAGnB"}

package/dist/plugins/pool/type.d.ts

@@ -0,0 +1,38 @@
+import { SnailError } from "../../error/base.js";
+/**
+ * The error codes a request-pool refusal can carry.
+ *
+ * `isPoolError()` is the supported way to test them, but the strings are exported
+ * so an application can switch on one precisely — for example to distinguish "the
+ * queue was full, try again shortly" from "the user navigated away".
+ */
+export declare const POOL_ERROR_CODES: {
+    /** `maxQueue` was reached; the request was never sent. */
+    readonly queueFull: "SNAIL_POOL_QUEUE_FULL";
+    /** The request waited longer than `queueTimeout` and was dropped. */
+    readonly queueTimeout: "SNAIL_POOL_QUEUE_TIMEOUT";
+    /** The request was cancelled while it was still waiting for a slot. */
+    readonly aborted: "SNAIL_POOL_ABORTED";
+    /** The queue was cleared — usually because the plugin was uninstalled. */
+    readonly cleared: "SNAIL_POOL_CLEARED";
+};
+/** Any code {@link SnailPoolError} can carry. */
+export type PoolErrorCode = (typeof POOL_ERROR_CODES)[keyof typeof POOL_ERROR_CODES];
+/**
+ * Raised when the pool refuses or drops a request.
+ *
+ * A dedicated class rather than a reuse of `SnailRequestError`: a pool refusal
+ * means the request **never reached the network**, which is a materially different
+ * situation from a transport failure. Retrying is safe and usually correct, the
+ * payload is untouched, and no server state changed — a caller that cannot tell the
+ * two apart will either retry a request the server already processed, or give up on
+ * one that was merely queued behind a burst.
+ */
+export declare class SnailPoolError extends SnailError {
+    /** Which refusal this is. */
+    readonly code: PoolErrorCode;
+    constructor(message: string, code: PoolErrorCode, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=type.d.ts.map

package/dist/plugins/pool/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/plugins/pool/type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;IAC3B,0DAA0D;aAC1D,SAAS,EAAE,uBAAuB;IAClC,qEAAqE;aACrE,YAAY,EAAE,0BAA0B;IACxC,uEAAuE;aACvE,OAAO,EAAE,oBAAoB;IAC7B,0EAA0E;aAC1E,OAAO,EAAE,oBAAoB;CACrB,CAAC;AAEX,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAErF;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,UAAU;IAC5C,6BAA6B;IAC7B,SAAiB,IAAI,EAAE,aAAa,CAAC;IAErC,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,EAElF;CACF"}

package/dist/plugins/react/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * React adapter plugin.
+ *
+ * ```tsx
+ * import { ReactAdapter, useMethodState } from "@snail-js/api/plugins/react";
+ *
+ * Service.use(ReactAdapter());
+ *
+ * const { data, loading, error } = useMethodState(userApi.getUser("1"));
+ * ```
+ *
+ * This sits behind its own subpath rather than in `@snail-js/api/plugins`: that
+ * barrel must not statically import `react`, or an application using only `Cache`
+ * would fail to resolve React at all.
+ *
+ * @packageDocumentation
+ */
+export { ReactAdapter, useMethodState } from "./plugin.js";
+export type { ReactAdapterOptions, ReactMethodState } from "./type.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACxD,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC"}

package/dist/plugins/react/index.js

@@ -0,0 +1,145 @@
+import { n as createPlugin } from "../../chunks/plugin-D3RDffDG.js";
+import { t as SnailCancelledError } from "../../chunks/request-qeRhihEF.js";
+import { a as readKey, o as unwrapEnvelope } from "../../chunks/response-D-ubkAFl.js";
+import { t as reactStateAdapter } from "../../chunks/react-C1em-gxy.js";
+//#region src/plugins/react/plugin.ts
+/**
+* React adapter plugin.
+*
+* Mirrors every request's state onto `ctx.meta` as subscribable boxes and exposes
+* {@link useMethodState} to bind them during render.
+*
+* ## Why this is not just the Vue plugin with another adapter
+*
+* A Vue `ref` tracks reads by itself, so writing it is enough. A React box has no
+* idea a component rendered it: the component must subscribe during render
+* (`useSyncExternalStore`) or the new value is never painted. That subscription
+* lives in `useMethodState`, not in the plugin hooks.
+*
+* ## Why `initMeta` and not `beforeRequest`
+*
+* `initMeta` runs **once**, when the `SnailMethod` is built, while `beforeCreate`
+* runs per `send()`. Creating the boxes per send is the classic bug where a
+* component keeps rendering the first response forever, because the UI captured
+* box #1 while the second send wrote into box #2.
+*/
+/** Key of the `loading` handle. Fixed, and not part of the envelope. */
+var LOADING_KEY = "loading";
+/** Key of the `error` handle. Fixed, and not part of the envelope. */
+var ERROR_KEY = "error";
+/**
+* Stand-in bound when a handle is missing.
+*
+* `useMethodState` must call the same number of hooks in the same order on every
+* render; a missing handle therefore cannot mean "call one hook fewer".
+*/
+var MISSING_HANDLE = reactStateAdapter.create(void 0);
+/** `useSyncExternalStore` behind a non-optional name, so it can always be called. */
+var bindHandle = reactStateAdapter.useBind;
+/**
+* Create one box unless the caller already holds one for that key.
+*
+* The guard keeps a re-run of `initMeta` (a context built before the plugin was
+* installed) from replacing boxes the UI is already subscribed to.
+*/
+function ensureHandle(ctx, key, initial) {
+	if (reactStateAdapter.isState?.(ctx.meta[key])) return;
+	ctx.meta[key] = reactStateAdapter.create(initial);
+}
+/** Create the five boxes. Runs once per `SnailMethod`. */
+function createHandles(ctx) {
+	const { dataKey, codeKey, messageKey } = ctx.serverOptions;
+	ensureHandle(ctx, dataKey, void 0);
+	ensureHandle(ctx, codeKey, void 0);
+	ensureHandle(ctx, messageKey, void 0);
+	ensureHandle(ctx, LOADING_KEY, false);
+	ensureHandle(ctx, ERROR_KEY, void 0);
+}
+/** Write one box, ignoring a key this plugin never created. */
+function writeHandle(ctx, key, value) {
+	const handle = ctx.meta[key];
+	if (handle) reactStateAdapter.write(handle, value);
+}
+/** Copy the envelope of the current response into the caller's boxes. */
+function captureResponse(ctx) {
+	const response = ctx.getResponse();
+	if (!response) return;
+	const { dataKey, codeKey, messageKey } = ctx.serverOptions;
+	writeHandle(ctx, dataKey, unwrapEnvelope(response.data, dataKey));
+	writeHandle(ctx, codeKey, readKey(response.data, codeKey));
+	writeHandle(ctx, messageKey, readKey(response.data, messageKey));
+}
+/**
+* Read a request method's state inside a component, subscribing it to changes.
+*
+* ```tsx
+* function User({ id }: { id: string }) {
+*   const method = useMemo(() => userApi.getUser(id), [id]);
+*   const { data, loading, error } = useMethodState(method);
+*   useEffect(() => { void method.send(); }, [method]);
+*   if (loading) return <Spinner />;
+*   return <p>{error ? String(error) : data?.name}</p>;
+* }
+* ```
+*
+* The five handles are bound unconditionally and in a fixed order, because React
+* identifies hooks by call position: a conditional `useBind` throws
+* "rendered fewer hooks than expected" as soon as the second render takes a
+* different branch.
+*/
+function useMethodState(method) {
+	const meta = method.meta;
+	const { dataKey, codeKey, messageKey } = method.context.serverOptions;
+	const data = bindHandle(meta[dataKey] ?? MISSING_HANDLE);
+	const code = bindHandle(meta[codeKey] ?? MISSING_HANDLE);
+	const message = bindHandle(meta[messageKey] ?? MISSING_HANDLE);
+	const loading = bindHandle(meta[LOADING_KEY] ?? MISSING_HANDLE);
+	const error = bindHandle(meta[ERROR_KEY] ?? MISSING_HANDLE);
+	return {
+		data,
+		loading: Boolean(loading),
+		error,
+		code,
+		message
+	};
+}
+/**
+* Create the React adapter plugin.
+*
+* ```tsx
+* Service.use(ReactAdapter());
+*
+* const method = Service.createApi(UserApi).getUser("1");
+* const { data, loading } = useMethodState(method);
+* ```
+*/
+var ReactAdapter = createPlugin({
+	name: "react-adapter",
+	priority: 0,
+	setup() {
+		return {
+			initMeta(ctx) {
+				createHandles(ctx);
+			},
+			beforeCreate(ctx) {
+				writeHandle(ctx, LOADING_KEY, true);
+				writeHandle(ctx, ERROR_KEY, void 0);
+			},
+			afterResponse(ctx, next) {
+				captureResponse(ctx);
+				return next();
+			},
+			onError(ctx, error) {
+				if (error instanceof SnailCancelledError) return;
+				writeHandle(ctx, ERROR_KEY, error);
+			},
+			afterRequest(ctx) {
+				writeHandle(ctx, LOADING_KEY, false);
+			}
+		};
+	}
+});
+//#endregion
+export { ReactAdapter, useMethodState };
+
+//# sourceMappingURL=index.js.map

package/dist/plugins/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/plugins/react/plugin.ts"],"sourcesContent":["import { reactStateAdapter } from \"../../adapter/react\";\nimport { createPlugin } from \"../../core/plugin\";\nimport { readKey, unwrapEnvelope } from \"../../core/response\";\nimport { SnailCancelledError } from \"../../error/request\";\nimport type { SnailContext } from \"../../core/context\";\nimport type { SnailMethod } from \"../../core/method\";\nimport type { SnailStateRef } from \"../../typings/adapter\";\nimport type { ReactAdapterOptions, ReactMethodState } from \"./type\";\n\n/**\n * React adapter plugin.\n *\n * Mirrors every request's state onto `ctx.meta` as subscribable boxes and exposes\n * {@link useMethodState} to bind them during render.\n *\n * ## Why this is not just the Vue plugin with another adapter\n *\n * A Vue `ref` tracks reads by itself, so writing it is enough. A React box has no\n * idea a component rendered it: the component must subscribe during render\n * (`useSyncExternalStore`) or the new value is never painted. That subscription\n * lives in `useMethodState`, not in the plugin hooks.\n *\n * ## Why `initMeta` and not `beforeRequest`\n *\n * `initMeta` runs **once**, when the `SnailMethod` is built, while `beforeCreate`\n * runs per `send()`. Creating the boxes per send is the classic bug where a\n * component keeps rendering the first response forever, because the UI captured\n * box #1 while the second send wrote into box #2.\n */\n\n/** Key of the `loading` handle. Fixed, and not part of the envelope. */\nconst LOADING_KEY = \"loading\";\n\n/** Key of the `error` handle. Fixed, and not part of the envelope. */\nconst ERROR_KEY = \"error\";\n\n/**\n * Stand-in bound when a handle is missing.\n *\n * `useMethodState` must call the same number of hooks in the same order on every\n * render; a missing handle therefore cannot mean \"call one hook fewer\".\n */\nconst MISSING_HANDLE = reactStateAdapter.create<unknown>(undefined);\n\n/** `useSyncExternalStore` behind a non-optional name, so it can always be called. */\nconst bindHandle = reactStateAdapter.useBind as (ref: SnailStateRef) => unknown;\n\n/**\n * Create one box unless the caller already holds one for that key.\n *\n * The guard keeps a re-run of `initMeta` (a context built before the plugin was\n * installed) from replacing boxes the UI is already subscribed to.\n */\nfunction ensureHandle(ctx: SnailContext, key: string, initial: unknown): void {\n  if (reactStateAdapter.isState?.(ctx.meta[key])) return;\n  ctx.meta[key] = reactStateAdapter.create(initial);\n}\n\n/** Create the five boxes. Runs once per `SnailMethod`. */\nfunction createHandles(ctx: SnailContext): void {\n  const { dataKey, codeKey, messageKey } = ctx.serverOptions;\n  ensureHandle(ctx, dataKey, undefined);\n  ensureHandle(ctx, codeKey, undefined);\n  ensureHandle(ctx, messageKey, undefined);\n  ensureHandle(ctx, LOADING_KEY, false);\n  ensureHandle(ctx, ERROR_KEY, undefined);\n}\n\n/** Write one box, ignoring a key this plugin never created. */\nfunction writeHandle(ctx: SnailContext, key: string, value: unknown): void {\n  const handle = ctx.meta[key];\n  if (handle) reactStateAdapter.write(handle as SnailStateRef, value);\n}\n\n/** Copy the envelope of the current response into the caller's boxes. */\nfunction captureResponse(ctx: SnailContext): void {\n  const response = ctx.getResponse();\n  if (!response) return;\n\n  const { dataKey, codeKey, messageKey } = ctx.serverOptions;\n  writeHandle(ctx, dataKey, unwrapEnvelope(response.data, dataKey));\n  writeHandle(ctx, codeKey, readKey(response.data, codeKey));\n  writeHandle(ctx, messageKey, readKey(response.data, messageKey));\n}\n\n/**\n * Read a request method's state inside a component, subscribing it to changes.\n *\n * ```tsx\n * function User({ id }: { id: string }) {\n *   const method = useMemo(() => userApi.getUser(id), [id]);\n *   const { data, loading, error } = useMethodState(method);\n *   useEffect(() => { void method.send(); }, [method]);\n *   if (loading) return <Spinner />;\n *   return <p>{error ? String(error) : data?.name}</p>;\n * }\n * ```\n *\n * The five handles are bound unconditionally and in a fixed order, because React\n * identifies hooks by call position: a conditional `useBind` throws\n * \"rendered fewer hooks than expected\" as soon as the second render takes a\n * different branch.\n */\nexport function useMethodState<TData = unknown>(\n  method: SnailMethod<any, TData, any, any, any>\n): ReactMethodState<TData> {\n  const meta = method.meta;\n  const { dataKey, codeKey, messageKey } = method.context.serverOptions;\n\n  // Fixed order and fixed count — do not reorder, do not hoist into a loop.\n  const data = bindHandle((meta[dataKey] ?? MISSING_HANDLE) as SnailStateRef);\n  const code = bindHandle((meta[codeKey] ?? MISSING_HANDLE) as SnailStateRef);\n  const message = bindHandle((meta[messageKey] ?? MISSING_HANDLE) as SnailStateRef);\n  const loading = bindHandle((meta[LOADING_KEY] ?? MISSING_HANDLE) as SnailStateRef);\n  const error = bindHandle((meta[ERROR_KEY] ?? MISSING_HANDLE) as SnailStateRef);\n\n  return {\n    data: data as TData | undefined,\n    loading: Boolean(loading),\n    error,\n    code,\n    message\n  };\n}\n\n/**\n * Create the React adapter plugin.\n *\n * ```tsx\n * Service.use(ReactAdapter());\n *\n * const method = Service.createApi(UserApi).getUser(\"1\");\n * const { data, loading } = useMethodState(method);\n * ```\n */\nexport const ReactAdapter = createPlugin<ReactAdapterOptions>({\n  name: \"react-adapter\",\n  priority: 0,\n\n  setup() {\n    return {\n      initMeta(ctx) {\n        createHandles(ctx);\n      },\n\n      beforeCreate(ctx) {\n        writeHandle(ctx, LOADING_KEY, true);\n        // A new attempt clears the previous failure; a stale error would otherwise\n        // keep rendering next to data that has just loaded successfully.\n        writeHandle(ctx, ERROR_KEY, undefined);\n      },\n\n      afterResponse(ctx, next) {\n        captureResponse(ctx);\n        return next();\n      },\n\n      onError(ctx, error) {\n        // Cancellation is expected control flow, not a failure: writing it would\n        // flash an error state every time a component unmounts mid-request.\n        if (error instanceof SnailCancelledError) return;\n        writeHandle(ctx, ERROR_KEY, error);\n      },\n\n      afterRequest(ctx) {\n        writeHandle(ctx, LOADING_KEY, false);\n      }\n    };\n  }\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,IAAM,cAAc;;AAGpB,IAAM,YAAY;;;;;;;AAQlB,IAAM,iBAAiB,kBAAkB,OAAgB,KAAA,CAAS;;AAGlE,IAAM,aAAa,kBAAkB;;;;;;;AAQrC,SAAS,aAAa,KAAmB,KAAa,SAAwB;CAC5E,IAAI,kBAAkB,UAAU,IAAI,KAAK,IAAI,GAAG;CAChD,IAAI,KAAK,OAAO,kBAAkB,OAAO,OAAO;AAClD;;AAGA,SAAS,cAAc,KAAyB;CAC9C,MAAM,EAAE,SAAS,SAAS,eAAe,IAAI;CAC7C,aAAa,KAAK,SAAS,KAAA,CAAS;CACpC,aAAa,KAAK,SAAS,KAAA,CAAS;CACpC,aAAa,KAAK,YAAY,KAAA,CAAS;CACvC,aAAa,KAAK,aAAa,KAAK;CACpC,aAAa,KAAK,WAAW,KAAA,CAAS;AACxC;;AAGA,SAAS,YAAY,KAAmB,KAAa,OAAsB;CACzE,MAAM,SAAS,IAAI,KAAK;CACxB,IAAI,QAAQ,kBAAkB,MAAM,QAAyB,KAAK;AACpE;;AAGA,SAAS,gBAAgB,KAAyB;CAChD,MAAM,WAAW,IAAI,YAAY;CACjC,IAAI,CAAC,UAAU;CAEf,MAAM,EAAE,SAAS,SAAS,eAAe,IAAI;CAC7C,YAAY,KAAK,SAAS,eAAe,SAAS,MAAM,OAAO,CAAC;CAChE,YAAY,KAAK,SAAS,QAAQ,SAAS,MAAM,OAAO,CAAC;CACzD,YAAY,KAAK,YAAY,QAAQ,SAAS,MAAM,UAAU,CAAC;AACjE;;;;;;;;;;;;;;;;;;;AAoBA,SAAgB,eACd,QACyB;CACzB,MAAM,OAAO,OAAO;CACpB,MAAM,EAAE,SAAS,SAAS,eAAe,OAAO,QAAQ;CAGxD,MAAM,OAAO,WAAY,KAAK,YAAY,cAAgC;CAC1E,MAAM,OAAO,WAAY,KAAK,YAAY,cAAgC;CAC1E,MAAM,UAAU,WAAY,KAAK,eAAe,cAAgC;CAChF,MAAM,UAAU,WAAY,KAAK,gBAAgB,cAAgC;CACjF,MAAM,QAAQ,WAAY,KAAK,cAAc,cAAgC;CAE7E,OAAO;EACC;EACN,SAAS,QAAQ,OAAO;EACxB;EACA;EACA;CACF;AACF;;;;;;;;;;;AAYA,IAAa,eAAe,aAAkC;CAC5D,MAAM;CACN,UAAU;CAEV,QAAQ;EACN,OAAO;GACL,SAAS,KAAK;IACZ,cAAc,GAAG;GACnB;GAEA,aAAa,KAAK;IAChB,YAAY,KAAK,aAAa,IAAI;IAGlC,YAAY,KAAK,WAAW,KAAA,CAAS;GACvC;GAEA,cAAc,KAAK,MAAM;IACvB,gBAAgB,GAAG;IACnB,OAAO,KAAK;GACd;GAEA,QAAQ,KAAK,OAAO;IAGlB,IAAI,iBAAiB,qBAAqB;IAC1C,YAAY,KAAK,WAAW,KAAK;GACnC;GAEA,aAAa,KAAK;IAChB,YAAY,KAAK,aAAa,KAAK;GACrC;EACF;CACF;AACF,CAAC"}

package/dist/plugins/react/plugin.d.ts

@@ -0,0 +1,33 @@
+import type { SnailMethod } from "../../core/method.js";
+import type { ReactAdapterOptions, ReactMethodState } from "./type.js";
+/**
+ * Read a request method's state inside a component, subscribing it to changes.
+ *
+ * ```tsx
+ * function User({ id }: { id: string }) {
+ *   const method = useMemo(() => userApi.getUser(id), [id]);
+ *   const { data, loading, error } = useMethodState(method);
+ *   useEffect(() => { void method.send(); }, [method]);
+ *   if (loading) return <Spinner />;
+ *   return <p>{error ? String(error) : data?.name}</p>;
+ * }
+ * ```
+ *
+ * The five handles are bound unconditionally and in a fixed order, because React
+ * identifies hooks by call position: a conditional `useBind` throws
+ * "rendered fewer hooks than expected" as soon as the second render takes a
+ * different branch.
+ */
+export declare function useMethodState<TData = unknown>(method: SnailMethod<any, TData, any, any, any>): ReactMethodState<TData>;
+/**
+ * Create the React adapter plugin.
+ *
+ * ```tsx
+ * Service.use(ReactAdapter());
+ *
+ * const method = Service.createApi(UserApi).getUser("1");
+ * const { data, loading } = useMethodState(method);
+ * ```
+ */
+export declare const ReactAdapter: import("../../index.js").SnailPlugin<ReactAdapterOptions>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugins/react/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/react/plugin.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AA8EpE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAG,OAAO,EAC5C,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAC7C,gBAAgB,CAAC,KAAK,CAAC,CAkBzB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,kDAkCvB,CAAC"}

package/dist/plugins/react/type.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Options accepted by the React adapter plugin.
+ *
+ * Deliberately empty: the adapter mirrors the envelope keys the server already
+ * declares (`dataKey` / `codeKey` / `messageKey`) and adds the two fixed handles
+ * `loading` and `error`. A per-plugin key option was avoided on purpose — the
+ * companion `useMethodState` hook has to bind the same handles in a fixed order,
+ * and a configurable key would have to be threaded through the hook to stay in
+ * sync.
+ */
+export interface ReactAdapterOptions {
+}
+/**
+ * What {@link useMethodState} returns.
+ *
+ * Deliberately discriminated from a `SnailResult`: the values update over time and
+ * each one is read live from its own state box, so `data` can be `undefined`
+ * (nothing loaded yet) even though a successful send always has one.
+ */
+export interface ReactMethodState<TData = unknown> {
+    /** Unwrapped payload of the most recent response. */
+    data: TData | undefined;
+    /** `true` between `send()` and settlement. */
+    loading: boolean;
+    /** Failure of the most recent send, cleared at the start of the next one. */
+    error: unknown;
+    /** Business code of the most recent response. */
+    code: unknown;
+    /** Business message of the most recent response. */
+    message: unknown;
+}
+//# sourceMappingURL=type.d.ts.map

package/dist/plugins/react/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/plugins/react/type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;CAAG;AAEvC;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO;IAC/C,qDAAqD;IACrD,IAAI,EAAE,KAAK,GAAG,SAAS,CAAC;IAExB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IAEjB,6EAA6E;IAC7E,KAAK,EAAE,OAAO,CAAC;IAEf,iDAAiD;IACjD,IAAI,EAAE,OAAO,CAAC;IAEd,oDAAoD;IACpD,OAAO,EAAE,OAAO,CAAC;CAClB"}