@snail-js/api 0.1.27 → 1.0.0

package/dist/strategies/use-retriable-request.d.ts

@@ -0,0 +1,46 @@
+import type { SnailStateRef } from "../typings/adapter.js";
+import type { StrategyMethod } from "./shared/method.js";
+import type { RetryOptions, RetryPredicate } from "./shared/retry.js";
+import type { StrategyState } from "./shared/state.js";
+import type { UseRequestOptions } from "./use-request.js";
+/** Options accepted by {@link useRetriableRequest}. */
+export interface UseRetriableRequestOptions<TData> extends UseRequestOptions<TData>, RetryOptions {
+    /**
+     * Decide whether one failed attempt deserves another.
+     *
+     * Receives the attempted number of the *next* try (1-based), so a caller can
+     * cap retries by reason as well as by count. The default retries everything
+     * except a cancellation, which is never retried: the caller asked for the
+     * request to stop, and a retry would ignore that instruction.
+     */
+    retryOn?: RetryPredicate;
+}
+/** What {@link useRetriableRequest} returns. */
+export interface UseRetriableRequestResult<TData, TArgs extends readonly unknown[] = readonly unknown[]> extends StrategyState<TData> {
+    send(...args: TArgs): Promise<TData>;
+    /** Attempts made by the most recent `send()`. Starts at `0`. */
+    readonly attempts: SnailStateRef<number>;
+}
+/**
+ * A request that heals itself.
+ *
+ * ```ts
+ * const save = useRetriableRequest(api.save, { retries: 3, delayMs: 200 });
+ * await save.send(payload);      // may hit the network up to 4 times
+ * save.attempts.value;           // how many tries it actually took
+ * ```
+ *
+ * ## Cancellation is the hard part
+ *
+ * The hook keeps its own `AbortController` for the backoff *between* attempts,
+ * because at that moment there is no in-flight request to cancel. `abort()` trips
+ * both, so a `abort()` during a 30 second delay rejects immediately instead of
+ * leaving the caller's promise pending until the timer fires. A cancellation is
+ * never counted as a failed attempt and never written to `error`.
+ *
+ * `attempts` is exposed because it is genuinely useful for telemetry ("this call
+ * needed three tries") and because it makes the retry loop testable without
+ * counting requests.
+ */
+export declare function useRetriableRequest<TArgs extends readonly unknown[], TData>(method: StrategyMethod<TArgs, TData>, options?: UseRetriableRequestOptions<TData>): UseRetriableRequestResult<TData, TArgs>;
+//# sourceMappingURL=use-retriable-request.d.ts.map

package/dist/strategies/use-retriable-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-retriable-request.d.ts","sourceRoot":"","sources":["../../src/strategies/use-retriable-request.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAMtD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,uDAAuD;AACvD,MAAM,WAAW,0BAA0B,CAAC,KAAK,CAC/C,SAAQ,iBAAiB,CAAC,KAAK,CAAC,EAC9B,YAAY;IACd;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,gDAAgD;AAChD,MAAM,WAAW,yBAAyB,CACxC,KAAK,EACL,KAAK,SAAS,SAAS,OAAO,EAAE,GAAG,SAAS,OAAO,EAAE,CACrD,SAAQ,aAAa,CAAC,KAAK,CAAC;IAC5B,IAAI,CAAC,GAAG,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAErC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,SAAS,OAAO,EAAE,EAAE,KAAK,EACzE,MAAM,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,EACpC,OAAO,GAAE,0BAA0B,CAAC,KAAK,CAAM,GAC9C,yBAAyB,CAAC,KAAK,EAAE,KAAK,CAAC,CA2EzC"}

package/dist/strategies/use-sse.d.ts

@@ -0,0 +1,103 @@
+import type { SnailStateAdapter, SnailStateRef } from "../typings/adapter.js";
+import type { SnailSseEndpoint, SnailSseMessage } from "../typings/stream.js";
+/**
+ * A connection that can report the events it parsed.
+ *
+ * `SnailConnection` deliberately exposes only `close`/`connected`/`opened`/
+ * `closed`, because a connection whose messages are delivered to `@SseEvent()`
+ * handlers on the endpoint class needs no other surface. `useSSE` has no such
+ * class, so it looks for this extension on the connection and, failing that, on
+ * the endpoint. Without either, `connected` still tracks the transport but
+ * `messages` stays empty — see the note on {@link useSSE}.
+ */
+export interface SseConnectionTap {
+    /** Register a message listener. Returns an unsubscribe function. */
+    onMessage?(listener: (message: SnailSseMessage) => void): () => void;
+}
+/** A `SnailSseEndpoint` that can also hand out messages directly. */
+export interface SseEndpoint extends SnailSseEndpoint {
+    /**
+     * Register a message listener for the connections this endpoint opens.
+     *
+     * Preferred over {@link SseConnectionTap} because it can be called once, before
+     * `open()`, which is the only way to be sure no message between the connect and
+     * the subscription is lost.
+     */
+    subscribe?(listener: (message: SnailSseMessage) => void): () => void;
+}
+/** Options accepted by {@link useSSE}. */
+export interface UseSseOptions {
+    /** State adapter. Defaults to the globally registered one. */
+    adapter?: SnailStateAdapter;
+    /**
+     * Open the connection as soon as the hook is created. Defaults to `false`,
+     * matching `SnailSseEndpoint`'s "nothing connects until `open()`" contract.
+     */
+    immediate?: boolean;
+    /**
+     * Maximum buffered messages. Defaults to `100`, dropping the oldest first.
+     *
+     * Bounded on purpose: an SSE feed that runs for hours with an unbounded array
+     * is a memory leak that ends in a frozen tab, and no view can render a hundred
+     * thousand rows anyway.
+     */
+    maxMessages?: number;
+    /** Keep only the messages this returns `true` for. */
+    filter?: (message: SnailSseMessage) => boolean;
+    /** Called for every accepted message, after the buffer was updated. */
+    onMessage?: (message: SnailSseMessage) => void;
+}
+/** What {@link useSSE} returns. */
+export interface UseSseResult {
+    /** Buffered messages, oldest first. */
+    readonly messages: SnailStateRef<SnailSseMessage[]>;
+    /** The most recent accepted message. */
+    readonly lastMessage: SnailStateRef<SnailSseMessage | undefined>;
+    /** `true` between a successful connect and the next close. */
+    readonly connected: SnailStateRef<boolean>;
+    /** Why the connection failed, or why a filter/handler threw. */
+    readonly error: SnailStateRef<unknown>;
+    /** Connect. A no-op while an open connection is already live. */
+    open(): void;
+    /** Disconnect, stop the reconnect loop and detach the listener. */
+    close(): void;
+    /** Empty the message buffer. Leaves the connection alone. */
+    clear(): void;
+    /** Resolved values, subscribing the current component when the adapter supports it. */
+    bind(): {
+        messages: SnailSseMessage[];
+        lastMessage: SnailSseMessage | undefined;
+        connected: boolean;
+        error: unknown;
+    };
+}
+/**
+ * Consume a Server-Sent Events endpoint as reactive state.
+ *
+ * ```ts
+ * const events = Service.createSse(Events);
+ * const feed = useSSE(events, { maxMessages: 50 });
+ * feed.open();
+ * feed.messages.value;   // SnailSseMessage[]
+ * feed.close();
+ * ```
+ *
+ * ## The message tap
+ *
+ * `Service.createSse()` returns an object whose only member is `open()`, and the
+ * messages it parses are dispatched to the decorated class's methods
+ * (`@SseEvent()`), not to the caller. `useSSE` therefore accepts an endpoint that
+ * additionally implements `subscribe(listener)`, or a connection that implements
+ * `onMessage(listener)`. Both extend the core contract without changing it; an
+ * endpoint that implements neither still reports `connected`/`error` faithfully,
+ * it just never fills `messages`.
+ *
+ * ## Never an unhandled rejection
+ *
+ * A rejected `opened` promise is exactly how a failed SSE connect is reported, and
+ * nothing else in the application will ever await it. Both `opened` and `closed`
+ * are handled here, so a dead server cannot take the process down with an
+ * unhandled rejection.
+ */
+export declare function useSSE(endpoint: SseEndpoint, options?: UseSseOptions): UseSseResult;
+//# sourceMappingURL=use-sse.d.ts.map

package/dist/strategies/use-sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-sse.d.ts","sourceRoot":"","sources":["../../src/strategies/use-sse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAA8B,MAAM,oBAAoB,CAAC;AACvG,OAAO,KAAK,EAAmB,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAI5F;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,SAAS,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACtE;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAY,SAAQ,gBAAgB;IACnD;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACtE;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAE5B;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,sDAAsD;IACtD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC;IAE/C,uEAAuE;IACvE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;CAChD;AAED,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,eAAe,EAAE,CAAC,CAAC;IAEpD,wCAAwC;IACxC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,eAAe,GAAG,SAAS,CAAC,CAAC;IAEjE,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAE3C,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAEvC,iEAAiE;IACjE,IAAI,IAAI,IAAI,CAAC;IAEb,mEAAmE;IACnE,KAAK,IAAI,IAAI,CAAC;IAEd,6DAA6D;IAC7D,KAAK,IAAI,IAAI,CAAC;IAEd,uFAAuF;IACvF,IAAI,IAAI;QACN,QAAQ,EAAE,eAAe,EAAE,CAAC;QAC5B,WAAW,EAAE,eAAe,GAAG,SAAS,CAAC;QACzC,SAAS,EAAE,OAAO,CAAC;QACnB,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;CACH;AAsBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CAyHvF"}

package/dist/strategies/use-token-auth.d.ts

@@ -0,0 +1,88 @@
+import type { SnailPluginObject } from "../typings/plugin.js";
+/** Options accepted by {@link useTokenAuth}. */
+export interface TokenAuthOptions {
+    /**
+     * Current token, from wherever the application keeps it.
+     *
+     * May be async (a secure store, a cookie API). Returning `null`/`undefined` is
+     * normal — it means "not logged in", and the header is simply not injected.
+     */
+    token: () => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * Obtain a fresh token.
+     *
+     * Called **at most once** per wave of 401s; see the class documentation on
+     * {@link useTokenAuth}. It must resolve with the new token; rejecting aborts the
+     * whole queue.
+     */
+    refresh: () => Promise<string>;
+    /** Header to write. Defaults to `"authorization"`. */
+    header?: string;
+    /** Prefix before the token. Defaults to `"Bearer"`; pass `""` for a raw token. */
+    scheme?: string;
+    /** Called when a 401 could not be recovered — the refresh failed, or the replay 401'd again. */
+    onUnauthorized?: (error: unknown) => void;
+}
+/** What {@link useTokenAuth} hands back. */
+export interface TokenAuthHandle {
+    /** Install with `Service.use(auth.plugin)`. */
+    readonly plugin: SnailPluginObject<TokenAuthOptions>;
+    /** Replace the cached token, e.g. after a successful login. */
+    setToken(token: string | null | undefined): void;
+    /** The cached token. Synchronous: an async `token()` cannot be awaited here. */
+    getToken(): string | undefined;
+    /** Forget the cached token so `token()` is consulted again on the next request. */
+    clearToken(): void;
+}
+/**
+ * Bearer-token authentication with single-flight refresh, as a plugin.
+ *
+ * ```ts
+ * const auth = useTokenAuth({
+ *   token: () => localStorage.getItem("token"),
+ *   refresh: async () => (await api.refresh().send()).token,
+ *   onUnauthorized: () => router.push("/login")
+ * });
+ *
+ * Service.use(auth.plugin);
+ * auth.setToken("...");
+ * ```
+ *
+ * ## Why a plugin and not a hook
+ *
+ * A token is global: every request of the service has to carry it, and a 401 on
+ * any one of them has to invalidate the token for all of them. A per-method hook
+ * could not see the other requests, so refresh coordination would be impossible.
+ *
+ * ## Exactly one refresh per wave of 401s
+ *
+ * Three parallel requests, one expired token, three 401s. Refreshing per request
+ * would fire three refreshes and, with a rotating refresh token, two of them would
+ * fail and log the user out. Two mechanisms prevent that:
+ *
+ * 1. a request that 401s while a refresh is already in flight **joins** it instead
+ *    of starting a second one;
+ * 2. a request whose 401 was produced by a token that has since been replaced
+ *    replays directly, without refreshing again.
+ *
+ * The token each request was sent with is remembered in `ctx.state` (which the core
+ * clears per send), and that is what makes rule 2 decidable without keeping
+ * timers around.
+ *
+ * ## Replaying
+ *
+ * `onError` cannot recover a failure — the core rethrows after every `onError`
+ * hook — so the recovery lives in `beforeRequest`, around `await next()`. The
+ * replay re-runs the `requestInterceptor` reduce, the transport and the
+ * `afterResponse` chain, so headers a plugin signs are recomputed for the retried
+ * call. `beforeRequest` hooks are deliberately *not* re-entered: the refresh
+ * decision has already been made, and re-entering could loop.
+ *
+ * ## What this cannot recover
+ *
+ * Only a **transport** 401 (HTTP 401). A backend that reports `{ code: 401 }` with
+ * HTTP 200 fails in `finalize`, after the chain, where no hook can intervene; that
+ * response reaches the caller as a `SnailResponseError`.
+ */
+export declare function useTokenAuth(options: TokenAuthOptions): TokenAuthHandle;
+//# sourceMappingURL=use-token-auth.d.ts.map

package/dist/strategies/use-token-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-token-auth.d.ts","sourceRoot":"","sources":["../../src/strategies/use-token-auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtE,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,KAAK,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAE5E;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/B,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,gGAAgG;IAChG,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;IAErD,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;IAEjD,gFAAgF;IAChF,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAC;IAE/B,mFAAmF;IACnF,UAAU,IAAI,IAAI,CAAC;CACpB;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAoKvE"}

package/dist/strategies/use-uploader.d.ts

@@ -0,0 +1,88 @@
+import type { SnailStateRef, SnailStrategyCommonOptions } from "../typings/adapter.js";
+import type { StrategyMethod } from "./shared/method.js";
+import type { StrategyState } from "./shared/state.js";
+/** Lifecycle of one queued file. */
+export type UploadFileStatus = "pending" | "uploading" | "success" | "error";
+/** Everything the hook tracks about one file. */
+export interface UploadFileState {
+    /** Stable id, used by `retry(id)`. */
+    readonly id: string;
+    /** The file itself. */
+    readonly file: File;
+    readonly status: UploadFileStatus;
+    /** `0`–`1`, from the transport when it reports progress, otherwise completed-or-not. */
+    readonly progress: number;
+    /** Failure of this file. Untouched for a cancellation. */
+    readonly error: unknown;
+    /** Unwrapped payload of this file's successful response. */
+    readonly response: unknown;
+}
+/** Snapshot handed to `onProgress`. */
+export interface UploaderProgress {
+    /** Average progress across every queued file, `0`–`1`. */
+    progress: number;
+    files: readonly UploadFileState[];
+}
+/** Options accepted by {@link useUploader}. */
+export interface UseUploaderOptions<TData> extends SnailStrategyCommonOptions {
+    /** Files in flight at once. Defaults to `3`. */
+    concurrency?: number;
+    /**
+     * Accept more than one file per `upload()` call.
+     *
+     * Defaults to `true`. When `false`, only the first entry of a `FileList` is
+     * queued and the rest are dropped — a single-file avatar input should not
+     * silently upload 40 holiday photos because a user multi-selected.
+     */
+    multiple?: boolean;
+    /** Called whenever aggregate or per-file progress changes. */
+    onProgress?: (state: UploaderProgress) => void;
+    /** FormData field the file is written to. Defaults to `"file"`. */
+    fieldName?: string;
+}
+/** What {@link useUploader} returns. */
+export interface UseUploaderResult<TData> extends StrategyState<TData> {
+    /**
+     * Queue files and resolve once the queue drains.
+     *
+     * Never rejects: per-file failures live on `files[i].error`, and one bad file
+     * must not abort the batch — that is the difference between "3 of 5 uploaded"
+     * and "nothing happened".
+     */
+    upload(files: File | File[] | FileList | null | undefined): Promise<void>;
+    /** Every queued file, in queue order. */
+    readonly files: SnailStateRef<UploadFileState[]>;
+    /** Aggregate progress, `0`–`1`. Reaches `1` when every file succeeded. */
+    readonly progress: SnailStateRef<number>;
+    /** Re-queue one failed file. */
+    retry(id: string): void;
+}
+/**
+ * Upload files with a bounded number of parallel requests.
+ *
+ * ```ts
+ * const uploader = useUploader(api.upload, { concurrency: 2 });
+ * await uploader.upload(input.files);
+ * uploader.files.value;      // per-file status, progress, error, response
+ * uploader.retry(id);        // re-queue one failure
+ * ```
+ *
+ * ## Progress
+ *
+ * Per-file progress comes from the transport via axios' `onUploadProgress`, which
+ * the hook attaches to the **live** request config of each file (see
+ * `shared/method.ts` for why that has to happen right after `send()` starts). The
+ * aggregate is the mean of the per-file values, and a finished file counts as `1`
+ * regardless of what the transport reported — a mocked or `fetch`-based adapter
+ * reports nothing at all, and without that rule the bar would stop at `0`.
+ *
+ * ## `data` and `code`
+ *
+ * The state handles are shared by the whole batch, so `data` holds the payload of
+ * the most recently finished file. Use `files[i].response` for anything
+ * per-file. `error` mirrors the file list: it holds the first failed file's error
+ * while any file is in the `error` state, and clears itself once the last failure
+ * has been retried successfully.
+ */
+export declare function useUploader<TData>(method: StrategyMethod<[FormData], TData>, options?: UseUploaderOptions<TData>): UseUploaderResult<TData>;
+//# sourceMappingURL=use-uploader.d.ts.map

package/dist/strategies/use-uploader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-uploader.d.ts","sourceRoot":"","sources":["../../src/strategies/use-uploader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAGpF,OAAO,KAAK,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,oCAAoC;AACpC,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAE7E,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,uBAAuB;IACvB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAEpB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAExB,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CACnC;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB,CAAC,KAAK,CAAE,SAAQ,0BAA0B;IAC3E,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAE/C,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAiB,CAAC,KAAK,CAAE,SAAQ,aAAa,CAAC,KAAK,CAAC;IACpE;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,EAAE,GAAG,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1E,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,eAAe,EAAE,CAAC,CAAC;IAEjD,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAEzC,gCAAgC;IAChC,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAC/B,MAAM,EAAE,cAAc,CAAC,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,EACzC,OAAO,GAAE,kBAAkB,CAAC,KAAK,CAAM,GACtC,iBAAiB,CAAC,KAAK,CAAC,CAkJ1B"}

package/dist/strategies/use-watcher.d.ts

@@ -0,0 +1,69 @@
+import type { SnailStateRef } from "../typings/adapter.js";
+import type { StrategyMethod } from "./shared/method.js";
+import type { UseRequestOptions, UseRequestResult } from "./use-request.js";
+/** Options accepted by {@link useWatcher}. */
+export interface UseWatcherOptions<TData> extends UseRequestOptions<TData> {
+    /**
+     * Values that trigger a re-send when they change.
+     *
+     * Must be a function returning **plain values** — `() => [page.value]`. State
+     * handles are unwrapped too when the adapter can identify them (see
+     * `shared/watcher.ts`), but the handle form is a heuristic: only a `{ value }`
+     * object is recognised, so a genuine data object with a lone `value` key is
+     * indistinguishable from a handle.
+     */
+    watching: () => readonly unknown[];
+    /**
+     * Wait for this many milliseconds of quiet, then send once.
+     *
+     * Takes precedence over `throttle` when both are set: the two express opposite
+     * intents ("wait until it settles" vs "send immediately, then at most once per
+     * window"), and silently honouring one of them is better than a hybrid whose
+     * behaviour depends on the call order.
+     */
+    debounce?: number;
+    /** Send on the leading edge, then at most once per window. */
+    throttle?: number;
+}
+/** What {@link useWatcher} returns. */
+export interface UseWatcherResult<TData, TArgs extends readonly unknown[] = readonly unknown[]> extends UseRequestResult<TData, TArgs> {
+    /**
+     * Whether `send()` collapses unchanged watched values.
+     *
+     * `true` (default) is the watching behaviour. Setting it to `false` turns every
+     * `send()` into an unconditional request, which is the escape hatch for a manual
+     * "refresh" button while the same hook keeps watching fields.
+     */
+    readonly watching: SnailStateRef<boolean>;
+}
+/**
+ * Re-send a request when watched values move.
+ *
+ * ```ts
+ * const keyword = createState("");
+ * const search = useWatcher(searchApi.find, {
+ *   watching: () => [keyword.value],
+ *   debounce: 200
+ * });
+ *
+ * keyword.value = "a"; await search.send();   // sends
+ * await search.send();                        // same values → no request
+ * keyword.value = "ab"; await search.send();  // sends again
+ * ```
+ *
+ * ## Why `send()` is the evaluation trigger
+ *
+ * `SnailStateAdapter` exposes `create`/`read`/`write` and an optional
+ * `subscribe`; it has no `watch` or `effect`, and the core deliberately keeps
+ * framework reactivity out of the strategy layer. So there is nothing to fire at
+ * the *moment* a value changes. The hook therefore evaluates `watching()` when
+ * `send()` is called and treats an unchanged snapshot as a no-op, which keeps the
+ * behaviour deterministic and framework-free: a Vue/React integration can call
+ * `send()` from its own reactive effect, and a script calls it directly.
+ *
+ * `debounce`/`throttle` then collapse the *bursts* of `send()` calls a reactive
+ * effect produces. Every collapsed caller's promise settles with the single
+ * request's outcome, so no `await` is ever left hanging.
+ */
+export declare function useWatcher<TArgs extends readonly unknown[], TData>(method: StrategyMethod<TArgs, TData>, options: UseWatcherOptions<TData>): UseWatcherResult<TData, TArgs>;
+//# sourceMappingURL=use-watcher.d.ts.map

package/dist/strategies/use-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-watcher.d.ts","sourceRoot":"","sources":["../../src/strategies/use-watcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAItD,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEzE,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB,CAAC,KAAK,CAAE,SAAQ,iBAAiB,CAAC,KAAK,CAAC;IACxE;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,SAAS,OAAO,EAAE,CAAC;IAEnC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB,CAC/B,KAAK,EACL,KAAK,SAAS,SAAS,OAAO,EAAE,GAAG,SAAS,OAAO,EAAE,CACrD,SAAQ,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,KAAK,SAAS,SAAS,OAAO,EAAE,EAAE,KAAK,EAChE,MAAM,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,EACpC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAChC,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CA4GhC"}

package/dist/typings/adapter.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Framework state abstraction used by the request strategies.
+ *
+ * A strategy needs to hand the caller values that update as the request
+ * progresses. "Updates" means something different in every framework, so the
+ * strategies never touch `ref()` or `useState()` directly — they go through a
+ * {@link SnailStateAdapter}.
+ *
+ * A state handle is intentionally minimal: anything with a mutable `value`
+ * property qualifies, which is exactly what a Vue `Ref<T>` is.
+ */
+/** A tracked value. Vue's `Ref<T>` structurally satisfies this. */
+export interface SnailStateRef<T = unknown> {
+    value: T;
+}
+/** Bridge between the strategies and one UI framework's reactivity system. */
+export interface SnailStateAdapter {
+    /** Identifier used in error messages, e.g. `"vue"`. */
+    readonly name: string;
+    /** Create a tracked value with an initial value. */
+    create<T>(initial: T): SnailStateRef<T>;
+    /** Read the current value. */
+    read<T>(ref: SnailStateRef<T>): T;
+    /** Write a new value. */
+    write<T>(ref: SnailStateRef<T>, value: T): void;
+    /**
+     * Subscribe to changes.
+     *
+     * Required by frameworks that re-render on subscription (React). Vue's
+     * `ref()` is tracked by the render effect itself, so its adapter omits this.
+     */
+    subscribe?<T>(ref: SnailStateRef<T>, listener: (value: T) => void): () => void;
+    /**
+     * Read a state during render, subscribing the current component.
+     *
+     * React's `useSyncExternalStore` lives here; Vue needs nothing.
+     */
+    useBind?<T>(ref: SnailStateRef<T>): T;
+    /** `true` when a value already is a state handle of this framework. */
+    isState?(value: unknown): boolean;
+    /** Release whatever the adapter allocated for this state. */
+    dispose?<T>(ref: SnailStateRef<T>): void;
+}
+/** Options shared by every request strategy. */
+export interface SnailStrategyCommonOptions {
+    /** Run the request as soon as the strategy is created. Defaults to `false`. */
+    immediate?: boolean;
+    /**
+     * State adapter to use.
+     *
+     * Defaults to the globally registered adapter (Vue in the default entry).
+     */
+    adapter?: SnailStateAdapter;
+    /** Called after a successful request. */
+    onSuccess?: (data: unknown) => void;
+    /** Called after a failed request. */
+    onError?: (error: unknown) => void;
+    /** Called once the request settles, successfully or not. */
+    onFinish?: () => void;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/typings/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/typings/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mEAAmE;AACnE,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,KAAK,EAAE,CAAC,CAAC;CACV;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,oDAAoD;IACpD,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IAExC,8BAA8B;IAC9B,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAElC,yBAAyB;IACzB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAEhD;;;;;OAKG;IACH,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAE/E;;;;OAIG;IACH,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAEtC,uEAAuE;IACvE,OAAO,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;IAElC,6DAA6D;IAC7D,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CAC1C;AAED,gDAAgD;AAChD,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAE5B,yCAAyC;IACzC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAEpC,qCAAqC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAEnC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB"}

package/dist/typings/api.d.ts

@@ -0,0 +1,122 @@
+import type { AxiosRequestConfig, Method } from "axios";
+import type { SnailEnvelopeSchema, SnailResult } from "./response.js";
+/** Every request verb this library can decorate. */
+export type SnailMethodType = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+/** `SnailMethodType` in the lowercase form axios expects. */
+export type SnailMethodTypeLower = Lowercase<SnailMethodType>;
+/** Options accepted by `@Api(...)`. */
+export interface SnailApiOptions {
+    /**
+     * Path prefix shared by every method of the class.
+     *
+     * Joined with the server `baseURL` and the method path, in that order.
+     */
+    url?: string;
+    /**
+     * Unique identifier of this api class.
+     *
+     * Defaults to the class name. Used for logging, cache namespacing and
+     * `@HitSource` resolution.
+     */
+    name?: string;
+    /** Per-api timeout, overriding the server timeout. */
+    timeout?: number;
+    /** Per-api adapter, overriding the server adapter. */
+    adapter?: AxiosRequestConfig["adapter"];
+    /** Per-api `responseType`, overriding the server value. */
+    responseType?: AxiosRequestConfig["responseType"];
+    /** Per-api `withCredentials`, overriding the server value. */
+    withCredentials?: boolean;
+}
+/**
+ * Options accepted by the request-method decorators.
+ *
+ * Extends `AxiosRequestConfig` so any axios knob can be set per method, minus
+ * the fields the library owns (`url` and `method`).
+ */
+export interface SnailMethodOptions extends Omit<AxiosRequestConfig, "url" | "method" | "params" | "data"> {
+    /** Extra query params baked into the request. */
+    params?: Record<string, any>;
+    /** Static body baked into the request (mutually exclusive with `@Data()`). */
+    data?: unknown;
+}
+/** What `@Get("/x", { ... })` receives as its second argument. */
+export type SnailMethodDecoratorOptions = SnailMethodOptions;
+/** A `Method` value axios understands. */
+export type SnailAxiosMethod = Method;
+/**
+ * The payload type of a decorated method, inferred from its declared return type.
+ *
+ * ```ts
+ * @Get("/:id")
+ * getUser(@Params("id") id: string): Promise<User> { return null!; }
+ * //                                          ^^^^^^^^^^^^^^ → User
+ * ```
+ *
+ * A method that declares nothing (implicitly `void`) yields `unknown`, which the
+ * caller can still override with an explicit generic:
+ * `userApi.getUser<MyShape>("1")`.
+ */
+export type SnailPayloadOf<R> = Awaited<R> extends void ? unknown : Awaited<R> extends undefined ? unknown : Awaited<R>;
+/**
+ * The proxy returned by `Service.createApi(UserApi)`.
+ *
+ * Every method carrying a request-method decorator becomes a function that
+ * builds a `SnailMethod` instead of running the original body — the decorated
+ * method exists only to declare the request's argument and return types:
+ *
+ * ```ts
+ * @Api("/user")
+ * class UserApi {
+ *   @Get("/:id")
+ *   getUser(@Params("id") id: string): Promise<User> { return null!; }
+ * }
+ *
+ * const userApi = Service.createApi(UserApi);
+ * const method = userApi.getUser("1");   // no request yet
+ * const { data } = await method.send();  // `data` is `User`
+ * ```
+ *
+ * Methods without a request-method decorator are passed through untouched, so an
+ * api class may keep helpers next to its endpoints.
+ */
+export type SnailApiProxy<TClass, S = SnailEnvelopeSchema, D extends string = "data", C extends string = "code", M extends string = "message"> = {
+    [K in keyof TClass]: TClass[K] extends (...args: infer A) => infer R ? <TData = SnailPayloadOf<R>>(...args: A) => import("../core/method.js").SnailMethod<S, TData, D, C, M> : TClass[K];
+};
+/** Static description of one decorated method, extracted from its decorators. */
+export interface SnailMethodMeta {
+    /** Server name. */
+    serverName: string;
+    /** Api class name. */
+    apiName: string;
+    /** Method name on the api class. */
+    methodName: string;
+    /** Fully qualified name: `server.api.method`. */
+    fullName: string;
+    /** Request verb. */
+    method: SnailMethodType;
+    /** Api prefix joined with the method path. */
+    url: string;
+}
+/**
+ * Per-call overrides.
+ *
+ * Mostly a convenience: prefer passing arguments to the proxied method. Kept for
+ * the cases where a strategy needs to inject a value the signature does not
+ * carry.
+ */
+export interface SnailSendOptions<TData = unknown> {
+    /** Override the body for this single call. */
+    data?: TData;
+    /** Override query params for this single call. */
+    query?: Record<string, any>;
+    /** Override path params for this single call. */
+    pathParams?: Record<string, any>;
+    /** Override headers for this single call. */
+    headers?: Record<string, any>;
+    /** Abort signal for this single call. */
+    signal?: AbortSignal;
+}
+/** Re-exported for convenience. */
+export type { SnailResult };
+//# sourceMappingURL=api.d.ts.map

package/dist/typings/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/typings/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnE,oDAAoD;AACpD,MAAM,MAAM,eAAe,GACvB,KAAK,GACL,MAAM,GACN,KAAK,GACL,QAAQ,GACR,OAAO,GACP,MAAM,GACN,SAAS,CAAC;AAEd,6DAA6D;AAC7D,MAAM,MAAM,oBAAoB,GAAG,SAAS,CAAC,eAAe,CAAC,CAAC;AAE9D,uCAAuC;AACvC,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,sDAAsD;IACtD,OAAO,CAAC,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAExC,2DAA2D;IAC3D,YAAY,CAAC,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAC;IAElD,8DAA8D;IAC9D,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBACf,SAAQ,IAAI,CAAC,kBAAkB,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtE,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE7B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,MAAM,2BAA2B,GAAG,kBAAkB,CAAC;AAE7D,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,SAAS,IAAI,GACnD,OAAO,GACP,OAAO,CAAC,CAAC,CAAC,SAAS,SAAS,GAC1B,OAAO,GACP,OAAO,CAAC,CAAC,CAAC,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,aAAa,CACvB,MAAM,EACN,CAAC,GAAG,mBAAmB,EACvB,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,CAAC,SAAS,MAAM,GAAG,MAAM,EACzB,CAAC,SAAS,MAAM,GAAG,SAAS,IAC1B;KACD,CAAC,IAAI,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,GAChE,CAAC,KAAK,GAAG,cAAc,CAAC,CAAC,CAAC,EACxB,GAAG,IAAI,EAAE,CAAC,KACP,OAAO,gBAAgB,EAAE,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAC5D,MAAM,CAAC,CAAC,CAAC;CACd,CAAC;AAEF,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,MAAM,EAAE,eAAe,CAAC;IACxB,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO;IAC/C,8CAA8C;IAC9C,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,yCAAyC;IACzC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,mCAAmC;AACnC,YAAY,EAAE,WAAW,EAAE,CAAC"}