@snail-js/api 0.1.28 → 1.0.0

package/dist/core/http-stream.d.ts

@@ -0,0 +1,28 @@
+import type { SnailHttpStreamConnection, SnailHttpStreamOptions } from "../typings/stream.js";
+import type { SnailLogger } from "./logger.js";
+/** Everything the HTTP streaming transport needs. */
+export interface HttpStreamInit {
+    /** Fully qualified url. */
+    url: string;
+    /** Options from `@HttpStream(path, options)` with its request method. */
+    options: SnailHttpStreamOptions & {
+        method?: string;
+    };
+    /** Request payload. */
+    body: unknown;
+    /** Name used in log lines. */
+    name: string;
+    /** Extra headers (server-level, auth, …). */
+    headers?: Record<string, string>;
+    /** Logger. */
+    logger: SnailLogger;
+}
+/**
+ * Streaming HTTP response.
+ *
+ * Uses `fetch` so the response body arrives as a `ReadableStream`, which works
+ * in browsers, Node 18+ and workers alike. The connection object is itself
+ * async-iterable, so callers write `for await (const chunk of stream)`.
+ */
+export declare function createHttpStream(init: HttpStreamInit): SnailHttpStreamConnection;
+//# sourceMappingURL=http-stream.d.ts.map

package/dist/core/http-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-stream.d.ts","sourceRoot":"","sources":["../../src/core/http-stream.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,yBAAyB,EACzB,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,OAAO,EAAE,sBAAsB,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,uBAAuB;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,cAAc;IACd,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,yBAAyB,CAwJhF"}

package/dist/core/logger.d.ts

@@ -0,0 +1,22 @@
+import type { SnailLogLevel } from "../typings/server.js";
+/**
+ * Level-gated logger.
+ *
+ * The pre-rewrite code called bare `console.log` from the middle of the request
+ * pipeline, which made a request library noisy by default and impossible to
+ * silence. Every diagnostic now goes through a logger whose level comes from
+ * `@Server({ logLevel })`, and the default level is `"silent"`.
+ */
+export interface SnailLogger {
+    /** Active level. */
+    readonly level: SnailLogLevel;
+    /** `true` when a message at `level` would be printed. */
+    enabled(level: Exclude<SnailLogLevel, "silent">): boolean;
+    error(message: string, ...rest: unknown[]): void;
+    warn(message: string, ...rest: unknown[]): void;
+    info(message: string, ...rest: unknown[]): void;
+    debug(message: string, ...rest: unknown[]): void;
+}
+/** Create a logger honouring `@Server({ logLevel })`. */
+export declare function createLogger(level?: SnailLogLevel): SnailLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,yDAAyD;IACzD,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,aAAa,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC;IAC1D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,KAAK,GAAE,aAAwB,GAAG,WAAW,CAqBzE"}

package/dist/core/metadata.d.ts

@@ -0,0 +1,92 @@
+/**
+ * A dependency-free replacement for `reflect-metadata`.
+ *
+ * ## Why not `reflect-metadata`?
+ *
+ * TypeScript 7 dropped the ability to emit `design:*` metadata: enabling
+ * `emitDecoratorMetadata` is accepted but silently emits nothing (verified
+ * against `tsc` 7.0.2 — the `__metadata` helper is emitted, the calls are not).
+ * That removes the only capability `reflect-metadata` ever provided to this
+ * library: we have never needed inferred constructor parameter types, only the
+ * metadata our *own* decorators write.
+ *
+ * Dropping it buys three things:
+ *   1. no runtime polyfill to install or import at the app entry point;
+ *   2. one fewer entry in `dependencies` — axios stays the only one;
+ *   3. deterministic behaviour on every runtime (browser, Node, worker, edge)
+ *      because the polyfill's `Reflect.defineMetadata` is not involved at all.
+ *
+ * Legacy decorators (`experimentalDecorators: true`) and parameter decorators
+ * remain fully supported by TypeScript 7.
+ *
+ * ## Storage model
+ *
+ * ```text
+ * WeakMap<owner, Map<slot, Map<key, value>>>
+ *                 │       └── the decorator's symbol key
+ *                 └── CLASS_SLOT for class metadata, else the method name
+ * ```
+ *
+ * `owner` is always a *class* (constructor function). A decorator applied to a
+ * method or parameter receives the prototype, so {@link resolveOwner} maps it
+ * back to the class.
+ *
+ * ## Decorator application order (important)
+ *
+ * For `@Api("/u") class U { @Get() list(@Query("a") a: string) {} }` the
+ * runtime order is:
+ *
+ * ```text
+ *   1. parameter decorators   (reverse index order)
+ *   2. method decorators
+ *   3. class decorators
+ * ```
+ *
+ * Every writer below therefore *merges*; none of them may clobber an existing
+ * value. Array-shaped metadata is appended, never replaced.
+ */
+/**
+ * Normalise whatever a decorator receives into the class that owns the metadata.
+ *
+ * - class decorator → the constructor itself
+ * - method / parameter decorator → `prototype.constructor`
+ * - a bare prototype passed by hand → `prototype.constructor`
+ */
+export declare function resolveOwner(target: unknown): object;
+/**
+ * Write metadata, replacing any value previously written for the same
+ * (owner, slot, key) triple.
+ */
+export declare function defineMetadata(key: symbol, value: unknown, target: unknown, propertyKey?: PropertyKey): void;
+/** Read metadata from exactly this owner, ignoring the prototype chain. */
+export declare function getOwnMetadata<T = unknown>(key: symbol, target: unknown, propertyKey?: PropertyKey): T | undefined;
+/**
+ * Read metadata, walking the class prototype chain so a base api class or a base
+ * server class can supply defaults to its subclasses.
+ */
+export declare function getMetadata<T = unknown>(key: symbol, target: unknown, propertyKey?: PropertyKey): T | undefined;
+/** `true` when {@link getMetadata} would find something. */
+export declare function hasMetadata(key: symbol, target: unknown, propertyKey?: PropertyKey): boolean;
+/**
+ * Append to array-shaped metadata, always creating a fresh array.
+ *
+ * Copy-on-write matters: several decorators legitimately contribute to one key
+ * (four `@Query()` parameters, a class-level `@Header()` plus a method-level
+ * one) and the array must never be shared with a base class.
+ */
+export declare function appendMetadata<T>(key: symbol, value: T, target: unknown, propertyKey?: PropertyKey): void;
+/** Merge a record into record-shaped metadata (class-level `@Header` and friends). */
+export declare function mergeMetadata<T extends object>(key: symbol, value: T, target: unknown, propertyKey?: PropertyKey): void;
+/** Delete metadata from exactly this owner. Returns whether anything was removed. */
+export declare function deleteMetadata(key: symbol, target: unknown, propertyKey?: PropertyKey): boolean;
+/**
+ * Collect every method name that carries metadata for `key`, walking the class
+ * prototype chain from base to derived so subclasses may override.
+ */
+export declare function collectMethodKeys(key: symbol, target: unknown): string[];
+/**
+ * Test-only escape hatch: swap the registry for a fresh `WeakMap`. Existing
+ * owners become unreachable and are garbage collected.
+ */
+export declare function clearMetadataRegistry(): void;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/core/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/core/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AASH;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CASpD;AAwBD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,EACf,WAAW,CAAC,EAAE,WAAW,GACxB,IAAI,CAEN;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EACxC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,EACf,WAAW,CAAC,EAAE,WAAW,GACxB,CAAC,GAAG,SAAS,CAEf;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EACrC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,EACf,WAAW,CAAC,EAAE,WAAW,GACxB,CAAC,GAAG,SAAS,CAUf;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,EACf,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,OAAO,EACf,WAAW,CAAC,EAAE,WAAW,GACxB,IAAI,CAGN;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAC5C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,OAAO,EACf,WAAW,CAAC,EAAE,WAAW,GACxB,IAAI,CAGN;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,EACf,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAsBxE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/core/metadata.keys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Metadata keys used by every `@snail-js/api` decorator.
+ *
+ * `Symbol.for` is used instead of plain `Symbol()` on purpose: a monorepo can
+ * easily end up with two copies of this package (one hoisted for the app, one
+ * nested under a dependency). Global symbol registration keeps both copies
+ * reading and writing the *same* metadata slots.
+ */
+/** `@Server(...)` options, stored on the server class. */
+export declare const SNAIL_SERVER_OPTIONS: unique symbol;
+/** `@Api(...)` options, stored on the api class. */
+export declare const SNAIL_API_OPTIONS: unique symbol;
+/** `@Get(...)` / `@Post(...)` / … options, stored per method. */
+export declare const SNAIL_REQUEST_METHOD: unique symbol;
+/** `@Params()` / `@Query()` / `@Data()` parameter descriptors, stored per method. */
+export declare const SNAIL_PARAMS: unique symbol;
+/** `@Header(...)` records, stored on the api class and per method. */
+export declare const SNAIL_HEADERS: unique symbol;
+/** `@UploadProgress(...)` callback, stored per method. */
+export declare const SNAIL_UPLOAD_PROGRESS: unique symbol;
+/** `@DownloadProgress(...)` callback, stored per method. */
+export declare const SNAIL_DOWNLOAD_PROGRESS: unique symbol;
+/** `@Sse(...)` options, stored on the stream class. */
+export declare const SNAIL_SSE_OPTIONS: unique symbol;
+/** `@SseEvent(...)` / `@OnSseOpen()` / `@OnSseError()` handlers, stored on the stream class. */
+export declare const SNAIL_SSE_HANDLERS: unique symbol;
+/** `@WebSocket(...)` options, stored on the stream class. */
+export declare const SNAIL_WS_OPTIONS: unique symbol;
+/** `@OnWsOpen()` / `@OnWsMessage()` / … handlers, stored on the stream class. */
+export declare const SNAIL_WS_HANDLERS: unique symbol;
+/** `@HttpStream(...)` options, stored per method. */
+export declare const SNAIL_HTTP_STREAM: unique symbol;
+/**
+ * Prefix reserved for third-party decorators built with
+ * {@link createParamDecorator} and friends.
+ *
+ * Plugin authors should namespace their key, e.g.
+ * `Symbol.for("@acme/snail-plugin:tenant")`, so two plugins can never collide.
+ */
+export declare const SNAIL_CUSTOM_KEY_PREFIX = "@snail-js/api:custom:";
+//# sourceMappingURL=metadata.keys.d.ts.map

package/dist/core/metadata.keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.keys.d.ts","sourceRoot":"","sources":["../../src/core/metadata.keys.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,eAA6C,CAAC;AAE/E,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,eAA0C,CAAC;AAEzE,iEAAiE;AACjE,eAAO,MAAM,oBAAoB,eAA6C,CAAC;AAE/E,qFAAqF;AACrF,eAAO,MAAM,YAAY,eAAqC,CAAC;AAE/D,sEAAsE;AACtE,eAAO,MAAM,aAAa,eAAsC,CAAC;AAEjE,0DAA0D;AAC1D,eAAO,MAAM,qBAAqB,eAA8C,CAAC;AAEjF,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,eAAgD,CAAC;AAErF,uDAAuD;AACvD,eAAO,MAAM,iBAAiB,eAA0C,CAAC;AAEzE,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,eAA2C,CAAC;AAE3E,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,eAAyC,CAAC;AAEvE,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,eAA0C,CAAC;AAEzE,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,eAA0C,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,0BAA0B,CAAC"}

package/dist/core/method.d.ts

@@ -0,0 +1,177 @@
+import { AxiosHeaders } from "axios";
+import type { AxiosInstance, InternalAxiosRequestConfig } from "axios";
+import type { SnailApiOptions, SnailMethodOptions, SnailMethodType } from "../typings/api.js";
+import type { SnailParamDescriptor } from "../typings/args.js";
+import type { SnailMeta } from "../typings/meta.js";
+import type { SnailResult } from "../typings/response.js";
+import type { ResolvedServerOptions } from "../typings/server.js";
+import { SnailContext } from "./context.js";
+import type { SnailLogger } from "./logger.js";
+import type { PluginManager } from "./plugin-manager.js";
+import type { SnailServer } from "./server.js";
+/** Payload of the `codeError` event. */
+export interface SnailCodeErrorEvent {
+    /** Business status code the backend returned. */
+    code: number | string | undefined;
+    /** Full parsed envelope. */
+    payload: unknown;
+    /** The `SnailResponseError` that will be thrown. */
+    error: unknown;
+}
+/** Events emitted by a {@link SnailMethod}. */
+export interface SnailMethodEventMap<S, T, D extends string, C extends string, M extends string> {
+    success: SnailResult<S, T, D, C, M>;
+    error: unknown;
+    codeError: SnailCodeErrorEvent;
+    finish: undefined;
+    cache: undefined;
+}
+/** Everything `SnailMethod` needs, assembled by the proxy in `SnailServer`. */
+export interface SnailMethodInit {
+    server: SnailServer<any, any, any, any>;
+    pluginManager: PluginManager;
+    axios: AxiosInstance;
+    apiClass: new () => unknown;
+    api: unknown;
+    apiName: string;
+    apiOptions: Required<SnailApiOptions>;
+    serverOptions: ResolvedServerOptions;
+    methodName: string;
+    methodType: SnailMethodType;
+    route: string;
+    methodOptions: SnailMethodOptions & {
+        url: string;
+    };
+    descriptors: readonly SnailParamDescriptor[];
+    headers: AxiosHeaders;
+    logger: SnailLogger;
+    /**
+     * Builds a fresh axios config for this method.
+     *
+     * A factory rather than a value: every `send()` must start from a clean config
+     * so mutations a plugin made during the previous send do not leak forward.
+     */
+    requestConfig: () => InternalAxiosRequestConfig;
+}
+/**
+ * One pending request.
+ *
+ * Created by calling a proxied api method — `userApi.getUser("1")` — and sent by
+ * calling {@link SnailMethod.send}. Nothing hits the network until `send()`.
+ *
+ * ## Why the context is built once and reset
+ *
+ * Framework adapters create the caller's reactive handles in their `initMeta`
+ * hook. Those handles must survive every re-send, so the context is constructed
+ * once and {@link SnailContext.reset} clears only the per-request fields. Calling
+ * `userApi.getUser()` twice would produce two independent sets of refs, which is
+ * exactly the bug the old `request()`-returns-fresh-state design had.
+ */
+export declare class SnailMethod<S = unknown, T = unknown, D extends string = "data", C extends string = "code", M extends string = "message"> {
+    /** `server.api.method`. */
+    readonly name: string;
+    /** Decorated method name. */
+    readonly methodName: string;
+    /** Request verb. */
+    readonly methodType: SnailMethodType;
+    /** Url template before `:placeholder` substitution. */
+    readonly route: string;
+    /** Arguments this instance was created with. `send(...args)` may override them. */
+    readonly args: readonly unknown[];
+    /**
+     * Caller-visible reactive values created by framework adapters.
+     *
+     * A live view of `context.meta`, so the handles an adapter created in
+     * `initMeta` stay stable across every re-send. Empty when no adapter plugin is
+     * installed.
+     *
+     * `loading` and `error` are typed by the {@link SnailMeta} interface; the
+     * envelope handles are named after the server's configured keys, so augment
+     * `SnailMeta` to type them.
+     */
+    get meta(): SnailMeta & Record<string, unknown>;
+    /** The live request context. */
+    readonly context: SnailContext;
+    private readonly init;
+    private readonly emitter;
+    private controller;
+    private inFlight;
+    constructor(init: SnailMethodInit, args?: readonly unknown[]);
+    /** `true` while a request is in flight. */
+    get pending(): boolean;
+    /** Result of the most recent successful request. */
+    get result(): SnailResult<S, T, D, C, M> | undefined;
+    /** Error from the most recent failed request. */
+    get error(): unknown;
+    /** The final axios config of the most recent request. */
+    get request(): InternalAxiosRequestConfig;
+    /**
+     * Send the request.
+     *
+     * Any arguments given here replace the ones captured when the method was
+     * proxied, which is what lets a strategy own one instance and vary the
+     * arguments per call.
+     *
+     * ## One request in flight at a time
+     *
+     * A `SnailMethod` owns exactly one context, and that context is what holds the
+     * caller's reactive handles. Two overlapping `send()` calls would therefore
+     * race over the same `ctx.response`, and the slower response could land in the
+     * state the faster one already reported.
+     *
+     * Starting a second send therefore **aborts the first**, so the previous call
+     * rejects with a `SnailCancelledError` and "latest wins" holds. Callers that
+     * genuinely want two parallel requests should create two instances —
+     * `userApi.getUser("1")` and `userApi.getUser("2")` — which is also what makes
+     * the argument types line up.
+     */
+    send(...args: unknown[]): Promise<SnailResult<S, T, D, C, M>>;
+    /**
+     * Cancel the in-flight request.
+     *
+     * `send()` rejects with a {@link SnailCancelledError}, which strategies treat
+     * as expected control flow rather than a failure.
+     */
+    abort(reason?: unknown): void;
+    /** Subscribe to a successful request. Returns an unsubscribe function. */
+    onSuccess(listener: (result: SnailResult<S, T, D, C, M>) => void): () => void;
+    /** Subscribe to a failed request. */
+    onError(listener: (error: unknown) => void): () => void;
+    /**
+     * Subscribe to a rejected business code.
+     *
+     * Observation only: the request still rejects with a `SnailResponseError`, so
+     * this is the right place to raise a toast, not to recover.
+     */
+    onCodeError(listener: (event: SnailCodeErrorEvent) => void): () => void;
+    /** Subscribe to settlement, successful or not. */
+    onFinish(listener: () => void): () => void;
+    /** Subscribe to a response served from a cache. */
+    onHitCache(listener: () => void): () => void;
+    /** Reset the context for a fresh send, superseding any request already in flight. */
+    private begin;
+    /**
+     * The transport step.
+     *
+     * Runs only when every `beforeRequest` hook called `next()`, i.e. only when the
+     * response has to come from the network. The `afterResponse` chain is *not* here
+     * — see {@link SnailMethod.send} for why it has to run on a cache hit too.
+     */
+    private dispatch;
+    /** Validate the envelope and assemble the caller-facing result. */
+    private finalize;
+    /** Report a failure through the plugin hooks and the events, then rethrow it. */
+    private fail;
+    /**
+     * Turn axios' error vocabulary into ours.
+     *
+     * The rule is: **if the server answered, hand back axios' error unchanged** —
+     * it carries `response.status` and `response.data`, which applications and the
+     * auth strategies both branch on. Only when no response exists at all (DNS
+     * failure, offline, CORS rejection) is there nothing useful to preserve, so
+     * that case becomes a typed {@link SnailHttpError} with the axios error as its
+     * `cause`.
+     */
+    private normalizeTransportError;
+}
+//# sourceMappingURL=method.d.ts.map

package/dist/core/method.d.ts.map

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

package/dist/core/plugin-manager.d.ts

@@ -0,0 +1,106 @@
+import type { SnailPluginObject } from "../typings/plugin.js";
+import type { ResolvedServerOptions } from "../typings/server.js";
+import { type BoundHook } from "./plugin.js";
+/** A plugin registered on one server. */
+export interface RegisteredPlugin {
+    /** Plugin name. */
+    readonly name: string;
+    /** Chain ordering weight; higher runs first in the forward phase. */
+    readonly priority: number;
+    /** Registration sequence, used as a stable tie-breaker. */
+    readonly index: number;
+    /** The plugin object itself. */
+    readonly instance: SnailPluginObject<any>;
+}
+/**
+ * Per-server plugin registry.
+ *
+ * ## Why this is not a singleton
+ *
+ * The pre-rewrite implementation kept one global manager plus a mutable
+ * `_server` pointer that every caller had to set with `switchServer()` before
+ * `getHooks()`. Any two servers in flight — or simply two interleaved `await`s —
+ * silently read the *wrong* server's plugins. Each `SnailServer` now owns its
+ * own manager and passes its name in the constructor, so that class of bug is
+ * unrepresentable.
+ *
+ * ## Ordering
+ *
+ * Plugins sort by `priority` descending, ties broken by registration order.
+ *
+ * - **Forward hooks** run highest-priority first, so an interceptor (`100`)
+ *   installs before the cache (`-100`).
+ * - **Unwind hooks** run in the opposite direction, closing the onion: the
+ *   plugin closest to the network reacts to the response first.
+ *
+ * ## Sync registration, async install
+ *
+ * `register()` is synchronous and returns immediately, so `Service.use(A).use(B)`
+ * chains naturally while a `dependsOn` mistake still throws on the spot. The
+ * `install` hooks themselves may be async; {@link PluginManager.ready} is awaited
+ * once per request, before any plugin hook runs.
+ */
+export declare class PluginManager {
+    private readonly serverName;
+    private readonly serverOptions;
+    private readonly registry;
+    private readonly order;
+    private readonly installTasks;
+    private sequence;
+    constructor(serverName: string, serverOptions: ResolvedServerOptions);
+    /** Number of registered plugins. */
+    get size(): number;
+    /** Resolves once every `install` hook has settled. */
+    get ready(): Promise<void>;
+    /** `true` when a plugin with this name is registered. */
+    has(name: string): boolean;
+    /** Read one registered plugin. */
+    get(name: string): RegisteredPlugin | undefined;
+    /** Registered plugin names in chain order (forward phase). */
+    names(): string[];
+    /** All registered plugins in chain order (forward phase). */
+    list(): RegisteredPlugin[];
+    /**
+     * Validate and register a plugin. Synchronous by design.
+     *
+     * Throws {@link SnailPluginError} for a nameless plugin, a duplicate name or
+     * an unsatisfied `dependsOn` — all before anything is mutated.
+     */
+    register(plugin: SnailPluginObject<any>): void;
+    /** Unregister a plugin, running its `uninstall` hook first. */
+    remove(name: string): Promise<void>;
+    /** Remove every plugin, unwinding in reverse registration order. */
+    clear(): Promise<void>;
+    /**
+     * Sorted plugin list.
+     *
+     * `"forward"` → priority descending (highest first).
+     * `"unwind"` → priority ascending (highest last).
+     */
+    sorted(direction: "forward" | "unwind"): RegisteredPlugin[];
+    /** Hooks of one name, in the direction that hook traverses. */
+    hooks(hookName: string): BoundHook[];
+    /** `true` when at least one plugin implements `hookName`. */
+    hasHook(hookName: string): boolean;
+    /**
+     * Run a chain hook over every plugin, then `downstream`.
+     *
+     * A plugin that never calls `next()` stops the chain: `downstream` (for
+     * `beforeRequest`, the HTTP request itself) never runs. That is the mechanism
+     * behind a cache hit.
+     */
+    runChain(hookName: string, ctx: unknown, downstream?: () => Promise<void> | void): Promise<void>;
+    /** Run a non-chain hook over every plugin, sequentially and awaited. */
+    runEffects(hookName: string, ...args: unknown[]): Promise<void>;
+    /** Run a non-chain hook synchronously — for constructor-time hooks. */
+    runEffectsSync(hookName: string, ...args: unknown[]): void;
+    /**
+     * Fold a value through every plugin's hook.
+     *
+     * Used by `requestInterceptor` / `responseInterceptor`, where each plugin may
+     * return a replacement for the value it received. Returning `undefined` keeps
+     * the previous value.
+     */
+    reduce<T>(hookName: string, initial: T, ...args: unknown[]): T;
+}
+//# sourceMappingURL=plugin-manager.d.ts.map

package/dist/core/plugin-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-manager.d.ts","sourceRoot":"","sources":["../../src/core/plugin-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA6B,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAqBxD,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAPhC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA4B;IACzD,OAAO,CAAC,QAAQ,CAAK;IAErB,YACmB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,qBAAqB,EACnD;IAEJ,oCAAoC;IACpC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,sDAAsD;IACtD,IAAI,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAEzB;IAED,yDAAyD;IACzD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzB;IAED,kCAAkC;IAClC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE9C;IAED,8DAA8D;IAC9D,KAAK,IAAI,MAAM,EAAE,CAEhB;IAED,6DAA6D;IAC7D,IAAI,IAAI,gBAAgB,EAAE,CAEzB;IAED;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,CAAC,GAAG,IAAI,CAuE7C;IAED,+DAA+D;IACzD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBxC;IAED,oEAAoE;IAC9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAI3B;IAED;;;;;OAKG;IACH,MAAM,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,GAAG,gBAAgB,EAAE,CAU1D;IAED,+DAA+D;IAC/D,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAgBnC;IAED,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQjC;IAED;;;;;;OAMG;IACG,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,OAAO,EACZ,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GACtC,OAAO,CAAC,IAAI,CAAC,CAOf;IAED,wEAAwE;IAClE,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpE;IAED,uEAAuE;IACvE,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAIzD;IAED;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAO7D;CACF"}

package/dist/core/plugin.d.ts

@@ -0,0 +1,113 @@
+import type { SnailMessages } from "../locale/types.js";
+import type { SnailParamResolver } from "../typings/args.js";
+import type { SnailPlugin, SnailPluginObject } from "../typings/plugin.js";
+import type { ResolvedServerOptions } from "../typings/server.js";
+/**
+ * Plugin machinery.
+ *
+ * ## Everything is a plugin
+ *
+ * The core ships *no* optional behaviour: caching, versioning, interceptors,
+ * validation, transformation and framework adapters are all plugins. Core owns
+ * exactly three things — the metadata written by decorators, the request
+ * pipeline, and this plugin lifecycle.
+ *
+ * ## Two kinds of hook
+ *
+ * - **Chain hooks** (`beforeRequest`, `afterResponse`) are Koa-style middleware:
+ *   a hook receives `next`, may `await` it, and may decline to call it to stop
+ *   the request. This is what makes cross-cutting concerns composable.
+ * - **Effect hooks** (`initMeta`, `beforeCreate`, `onError`, `afterRequest`) run
+ *   sequentially and cannot influence control flow.
+ */
+/** Identity helper that preserves the option type of a plugin factory. */
+export declare function definePlugin<O = unknown>(factory: SnailPlugin<O>): SnailPlugin<O>;
+/** Building blocks handed to a plugin's `setup` function. */
+export interface PluginSetupApi {
+    /** Name of the server this plugin was installed on. */
+    readonly serverName: string;
+    /** Fully resolved server options. */
+    readonly serverOptions: ResolvedServerOptions;
+    /** Names of the plugins registered before this one. */
+    readonly installedPlugins: readonly string[];
+    /**
+     * Register a custom parameter source usable as `@Source("key")`.
+     *
+     * @example
+     * ```ts
+     * api.defineParamSource("tenant", ({ ctx, value }) => {
+     *   ctx.request.headers.set("x-tenant", String(value));
+     * });
+     * ```
+     */
+    defineParamSource(source: string, resolver: SnailParamResolver): void;
+    /** Contribute translated messages for this plugin's own error output. */
+    addMessages(messages: SnailMessages): void;
+    /** Register cleanup to run when the plugin is uninstalled. */
+    onDispose(dispose: () => void | Promise<void>): void;
+}
+/** Declarative description accepted by {@link createPlugin}. */
+export interface PluginDefinition<O, Hooks extends object> {
+    /** Unique plugin name. */
+    readonly name: string;
+    /** Execution order inside a chain; higher runs first. Defaults to `0`. */
+    readonly priority?: number;
+    /** Plugin names that must be registered first. */
+    readonly dependsOn?: readonly string[];
+    /**
+     * Runs once per server, at install time.
+     *
+     * Use it to register parameter sources, add messages, seed state or capture
+     * options in a closure. Return the lifecycle hooks.
+     */
+    readonly setup?: (options: O, api: PluginSetupApi) => Hooks | void;
+}
+/** The lifecycle hooks a plugin may return, excluding registration plumbing. */
+export type PluginHooks = Omit<SnailPluginObject, "name" | "priority" | "dependsOn" | "install" | "uninstall">;
+/**
+ * Create a third-party plugin.
+ *
+ * This is the supported entry point for plugin authors. It validates the name,
+ * wires `install`/`uninstall`, exposes a scoped {@link PluginSetupApi} and keeps
+ * the hook object fully typed.
+ *
+ * @example
+ * ```ts
+ * interface TraceOptions { header?: string }
+ *
+ * export const Trace = createPlugin<TraceOptions, { onSend?: (url: string) => void }>({
+ *   name: "trace",
+ *   priority: 20,
+ *   setup(options, api) {
+ *     const header = options?.header ?? "x-trace-id";
+ *     api.addMessages({ "trace.missing": "trace header %s is missing" });
+ *     return {
+ *       beforeRequest(ctx) {
+ *         ctx.request.headers.set(header, crypto.randomUUID());
+ *       }
+ *     };
+ *   }
+ * });
+ *
+ * Service.use(Trace({ header: "x-trace-id" }));
+ * ```
+ */
+export declare function createPlugin<O = void, Hooks extends object = PluginHooks>(definition: PluginDefinition<O, Hooks>): SnailPlugin<O>;
+/** One hook bound to the plugin that owns it. */
+export interface BoundHook {
+    readonly pluginName: string;
+    readonly hook: (...args: any[]) => any;
+}
+/**
+ * Compose chain hooks into a single Koa-style function.
+ *
+ * The returned function runs `entries[0]` first (they are pre-sorted by the
+ * manager), handing each hook a `next` that advances the chain. When the chain
+ * is exhausted, `downstream` runs — that is where the manager splices in the
+ * actual HTTP request between `beforeRequest` and `afterResponse`.
+ *
+ * Calling `next()` twice from one hook throws {@link SnailHookError}; without
+ * that guard the second call silently re-runs the rest of the chain.
+ */
+export declare function composeChain(hookName: string, entries: readonly BoundHook[]): (ctx: unknown, downstream?: () => Promise<void> | void) => Promise<void>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/core/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/core/plugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAEV,WAAW,EAEX,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAK/D;;;;;;;;;;;;;;;;;GAiBG;AAEH,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAEjF;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,qCAAqC;IACrC,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAC;IAE9C,uDAAuD;IACvD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C;;;;;;;;;OASG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAEtE,yEAAyE;IACzE,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAE3C,8DAA8D;IAC9D,SAAS,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACtD;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB,CAAC,CAAC,EAAE,KAAK,SAAS,MAAM;IACvD,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEvC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,cAAc,KAAK,KAAK,GAAG,IAAI,CAAC;CACpE;AAED,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,CAAC,CAAC;AAE/G;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,SAAS,MAAM,GAAG,WAAW,EACvE,UAAU,EAAE,gBAAgB,CAAC,CAAC,EAAE,KAAK,CAAC,GACrC,WAAW,CAAC,CAAC,CAAC,CA6ChB;AAED,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;CACxC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,SAAS,SAAS,EAAE,GAC5B,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAqC1E"}

package/dist/core/reconnect.d.ts

@@ -0,0 +1,22 @@
+import type { SnailReconnectPolicy } from "../typings/stream.js";
+/** A reconnect policy with every default applied. */
+export type ResolvedReconnectPolicy = Required<SnailReconnectPolicy>;
+/** Defaults used when a transport enables reconnecting without a policy. */
+export declare const DEFAULT_RECONNECT_POLICY: ResolvedReconnectPolicy;
+/**
+ * Normalise the `reconnect` option.
+ *
+ * Returns `undefined` when reconnecting is switched off, so callers can branch on
+ * a single falsy check instead of handling `false | undefined | policy`.
+ */
+export declare function resolveReconnectPolicy(policy: false | SnailReconnectPolicy | undefined): ResolvedReconnectPolicy | undefined;
+/**
+ * Exponential backoff with optional full jitter.
+ *
+ * `attempt` is 1-based: `attempt: 1` returns the first delay. The result is
+ * always capped by `maxDelayMs`, so a long outage cannot push a retry hours out.
+ */
+export declare function backoffDelay(attempt: number, policy: ResolvedReconnectPolicy): number;
+/** `true` when another attempt is allowed. */
+export declare function canRetry(attempt: number, policy: ResolvedReconnectPolicy): boolean;
+//# sourceMappingURL=reconnect.d.ts.map

package/dist/core/reconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.d.ts","sourceRoot":"","sources":["../../src/core/reconnect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,qDAAqD;AACrD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAErE,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,EAAE,uBAMtC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,KAAK,GAAG,oBAAoB,GAAG,SAAS,GAC/C,uBAAuB,GAAG,SAAS,CAIrC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,uBAAuB,GAC9B,MAAM,CAOR;AAED,8CAA8C;AAC9C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAElF"}