@snail-js/api 0.1.27 → 1.0.0

package/dist/plugins/cache/adapters/web-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-storage.d.ts","sourceRoot":"","sources":["../../../../src/plugins/cache/adapters/web-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAS5C,0DAA0D;AAC1D,MAAM,WAAW,6BAA6B;IAC5C,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,sBAAuB,YAAW,YAAY;IACzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4B;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YACE,cAAc,EAAE,MAAM,OAAO,GAAG,SAAS,EACzC,OAAO,GAAE,6BAAkC,EAK5C;IAED,4EAA4E;IAC5E,IAAI,SAAS,IAAI,OAAO,CAEvB;IAEK,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAqB1D;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYxE;IAEK,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvC;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAO3B;IAEK,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAK9B;IAED,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,GAAG;IAIX,4DAA4D;IAC5D,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,KAAK;CAUd"}

package/dist/plugins/cache/decorators.d.ts

@@ -0,0 +1,62 @@
+import type { CacheableOptions } from "./type.js";
+type DualDecorator = ClassDecorator & MethodDecorator;
+/**
+ * Mark this method — or every method of this class — as cacheable.
+ *
+ * Passing the decorator is an explicit opt-in: it caches even a verb that
+ * `CacheOptions.cacheFor` does not list. Without it, `cacheFor` decides, and the
+ * reason is that "cache every POST of this class" is far too easy to write by
+ * accident when the intent was only to attach tags.
+ *
+ * ```ts
+ * @Api("/user")
+ * @Cacheable({ tags: ["users"] })
+ * class UserApi {
+ *   @Get("/") list(): Promise<User[]> { return null!; }
+ *
+ *   @Get("/stats")
+ *   @Cacheable({ ttl: 5 })
+ *   stats(): Promise<Stats> { return null!; }
+ * }
+ * ```
+ */
+export declare function Cacheable(options?: CacheableOptions): DualDecorator;
+/**
+ * Opt this method — or this entire class — out of caching.
+ *
+ * A method-level `@NoCache()` beats a class-level `@Cacheable()`, and a
+ * class-level `@NoCache()` beats the `cacheFor` default. Opting out is the one
+ * decision that may never be overridden by a broader rule, because the cost of
+ * being wrong is serving stale data.
+ */
+export declare function NoCache(): DualDecorator;
+/**
+ * Purge every cached entry carrying any of `tags` once this request succeeds.
+ *
+ * "Succeeds" means the HTTP round-trip did: the hook lives on the response path,
+ * so a failed or cancelled request invalidates nothing. A method may invalidate a
+ * tag it also stores under — the plugin purges before it stores, so the fresh
+ * entry survives its own invalidation.
+ */
+export declare function Invalidates(...tags: string[]): DualDecorator;
+/**
+ * Legacy-compatible alias of {@link Invalidates} for a single source name.
+ *
+ * The pre-rewrite decorator was named after the *source* of a change rather than
+ * the entries it purges; application code written against it keeps working, and
+ * new code should prefer `@Invalidates`.
+ */
+export declare function HitSource(name: string): DualDecorator;
+/**
+ * Read `@Cacheable(...)` from a method (when `methodName` is given) or a class.
+ *
+ * `undefined` means "not marked", which is different from `{}` ("marked, with no
+ * overrides") — the plugin treats the two differently.
+ */
+export declare function readCacheable(target: unknown, methodName?: string): CacheableOptions | undefined;
+/** `true` when `@NoCache()` was applied to this method or class. */
+export declare function readNoCache(target: unknown, methodName?: string): boolean;
+/** Tags listed by `@Invalidates(...)` / `@HitSource(...)`, in application order. */
+export declare function readInvalidates(target: unknown, methodName?: string): string[];
+export {};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/plugins/cache/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../../src/plugins/cache/decorators.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAuB/C,KAAK,aAAa,GAAG,cAAc,GAAG,eAAe,CAAC;AAgDtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,aAAa,CAUvE;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,IAAI,aAAa,CAEvC;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAkB5D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAErD;AAID;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAIhG;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAOzE;AAED,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAM9E"}

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

@@ -0,0 +1,41 @@
+/**
+ * Cache plugin.
+ *
+ * ```ts
+ * import { Cache, Cacheable, Invalidates, NoCache } from "@snail-js/api/plugins";
+ *
+ * Service.use(Cache({ ttl: 30, l2: "localStorage" }));
+ *
+ * @Api("/user")
+ * class UserApi {
+ *   @Get("/")
+ *   @Cacheable({ tags: ["users"] })
+ *   list(): Promise<User[]> { return null!; }
+ *
+ *   @Post("/")
+ *   @Invalidates("users")
+ *   create(@Data() body: NewUser): Promise<User> { return null!; }
+ * }
+ * ```
+ *
+ * `priority: -100` is the reserved cache band: last in forward order, so the key
+ * is hashed from the final url/params/body, and first in unwind order, so the raw
+ * envelope is stored before validation and transformation touch it.
+ *
+ * @packageDocumentation
+ */
+export { IndexedDBCacheAdapter } from "./adapters/indexeddb.js";
+export type { IndexedDBCacheAdapterOptions } from "./adapters/indexeddb.js";
+export { DEFAULT_L1_MAX_SIZE, MemoryCacheAdapter } from "./adapters/memory.js";
+export type { MemoryCacheAdapterOptions } from "./adapters/memory.js";
+export { WebStorageCacheAdapter } from "./adapters/web-storage.js";
+export type { WebStorageCacheAdapterOptions } from "./adapters/web-storage.js";
+export { Cacheable, HitSource, Invalidates, NoCache, readCacheable, readInvalidates, readNoCache } from "./decorators.js";
+export { buildCacheKey } from "./key.js";
+export type { CacheKeyInput } from "./key.js";
+export { CacheManager } from "./manager.js";
+export type { CacheManagerOptions, ResolvedCacheOptions } from "./manager.js";
+export { CACHE_PLUGIN_NAME, CACHE_PRIORITY, Cache, makeCachedResponse } from "./plugin.js";
+export type { CachePlugin } from "./plugin.js";
+export type { CacheableOptions, CacheAdapter, CacheLookup, CacheOptions } from "./type.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,YAAY,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,YAAY,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAC5E,OAAO,EACL,SAAS,EACT,SAAS,EACT,WAAW,EACX,OAAO,EACP,aAAa,EACb,eAAe,EACf,WAAW,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACxF,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,YAAY,EACb,MAAM,QAAQ,CAAC"}

package/dist/plugins/cache/key.d.ts

@@ -0,0 +1,48 @@
+import type { InternalAxiosRequestConfig } from "axios";
+import type { SnailMethodType } from "../../typings/api.js";
+/**
+ * Cache-key construction.
+ *
+ * ## Why the whole request identity is hashed
+ *
+ * A key has to answer one question: "would this request produce the same
+ * response as the one I already stored?". That depends on the verb, the final
+ * url, the query params and the body — and on nothing else. Headers are
+ * deliberately excluded: an `Authorization` header changes *who* asks, not what
+ * is asked, and including it would turn every token refresh into a cache flush.
+ *
+ * ## Why `stableStringify`
+ *
+ * `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` are the same query. Serialising them
+ * with `JSON.stringify` produces two different strings and therefore two cache
+ * entries for one logical request; `stableStringify` sorts object keys, so the
+ * hash — and the key — is order-independent.
+ *
+ * ## Why the url is final here
+ *
+ * The cache plugin runs at `priority: -100` — last in forward order — precisely
+ * so the interceptor plugin (`100`) and the argument decorators have already
+ * rewritten `ctx.request.url` and filled in `:placeholders`. Hashing an earlier
+ * stage of the url would key `/user/:id` and `/user/42` differently, or worse,
+ * identically.
+ */
+/** Everything needed to identify one cacheable request. */
+export interface CacheKeyInput {
+    /** Namespace, so two servers on one origin never share entries. */
+    prefix: string;
+    /** The live axios config — url, params and body must already be final. */
+    request: InternalAxiosRequestConfig;
+    /** Fallback verb when the config carries none. */
+    methodType: SnailMethodType;
+    /** `@Cacheable({ key })`: use this verbatim instead of the request identity. */
+    explicitKey?: string;
+}
+/**
+ * Build the key used for one request.
+ *
+ * The readable part (`prefix:VERB`) is kept outside the hash so a misbehaving
+ * cache can be diagnosed from a key alone; only the volatile signature is hashed,
+ * which keeps keys short enough for `localStorage`.
+ */
+export declare function buildCacheKey(input: CacheKeyInput): string;
+//# sourceMappingURL=key.d.ts.map

package/dist/plugins/cache/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../../src/plugins/cache/key.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,OAAO,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IAEf,0EAA0E;IAC1E,OAAO,EAAE,0BAA0B,CAAC;IAEpC,kDAAkD;IAClD,UAAU,EAAE,eAAe,CAAC;IAE5B,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAmB1D"}

package/dist/plugins/cache/manager.d.ts

@@ -0,0 +1,124 @@
+import type { SnailLogger } from "../../core/logger.js";
+import type { SnailMethodType } from "../../typings/api.js";
+import type { CacheAdapter, CacheLookup, CacheOptions } from "./type.js";
+export interface CacheManagerOptions extends CacheOptions {
+    /**
+     * Logger for L2 failures.
+     *
+     * The manager runs outside any request, so it has no `ctx.logger`; the plugin
+     * injects one built from `@Server({ logLevel })`. Defaults to silent, because a
+     * cache must not make an application noisy by itself.
+     */
+    logger?: SnailLogger;
+}
+/** `CacheOptions` with every default applied — the manager's public state. */
+export interface ResolvedCacheOptions {
+    ttl: number;
+    maxSize: number;
+    l1: boolean;
+    l2: CacheAdapter | undefined;
+    cacheFor: "all" | readonly SnailMethodType[];
+    prefix: string;
+    staleWhileRevalidate: boolean;
+    dedupe: boolean;
+}
+/**
+ * Storage engine behind the cache plugin.
+ *
+ * ## Layers
+ *
+ * - **L1** is a {@link MemoryCacheAdapter}: always present unless `l1: false`,
+ *   bounded by `maxSize`, and the only place an L2 hit is promoted into.
+ * - **L2** is any {@link CacheAdapter}, usually a persistent store.
+ *
+ * ## What the manager owns that the adapters do not
+ *
+ * TTL, LRU and tags are policy, not storage. Keeping them here means a custom L2
+ * adapter only has to answer "get/set/delete" and never has to know what a tag
+ * is — which is what makes the adapter interface small enough to implement over
+ * anything (IndexedDB, `localStorage`, an HTTP cache).
+ *
+ * ## Freshness vs. `staleWhileRevalidate`
+ *
+ * Freshness is always decided by this class, using the `expiresAt` it records on
+ * `set`. In stale-while-revalidate mode L1 is told "never expire" so the stale
+ * copy survives to be served while the plugin refreshes it; otherwise L1 is
+ * given the real TTL and sweeps the entry itself. L2 always receives the real TTL
+ * so a second tab (which has no shared in-memory index) never reads a stale one.
+ */
+export declare class CacheManager {
+    /** Fully resolved options, exposed so the plugin can apply the same policy. */
+    readonly options: ResolvedCacheOptions;
+    private readonly l1;
+    private readonly logger;
+    /** key → absolute expiry timestamp in ms; `0` means "never expires". */
+    private readonly expiry;
+    /** tag → every key carrying it. */
+    private readonly tagIndex;
+    /** key → every tag it carries, so a delete can unindex it in O(tags). */
+    private readonly keyTags;
+    /** Cache key → the promise of the request currently being sent for it. */
+    private readonly flight;
+    constructor(options?: CacheManagerOptions);
+    /** Number of live **L1** entries. L2 is not enumerated, by design. */
+    get size(): number;
+    /**
+     * Read a fresh value.
+     *
+     * A stale entry (kept alive only for stale-while-revalidate) is *not* returned:
+     * callers that must serve staleness ask {@link lookup} explicitly, so the
+     * common path cannot accidentally serve expired data.
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** `true` when a fresh value is stored under `key`. */
+    has(key: string): Promise<boolean>;
+    /**
+     * Read a value together with its freshness.
+     *
+     * `allowStale` is the plugin's `staleWhileRevalidate` switch: when the entry is
+     * past its TTL but still resident, it is returned with `stale: true` so the
+     * caller can serve it now and refresh afterwards.
+     */
+    lookup<T = unknown>(key: string, allowStale?: boolean): Promise<CacheLookup<T> | undefined>;
+    /**
+     * Store a value in L1 and L2.
+     *
+     * `ttlSeconds` defaults to the configured TTL and `tags` may be empty; a tag
+     * written here is what `@Invalidates("tag")` later purges.
+     */
+    set(key: string, value: unknown, ttlSeconds?: number, tags?: readonly string[]): Promise<void>;
+    /** Remove one entry from every layer. */
+    delete(key: string): Promise<void>;
+    /** Remove every entry this manager can see. */
+    clear(): Promise<void>;
+    /**
+     * Purge every entry carrying any of `tags`.
+     *
+     * Used by `@Invalidates(...)` / `@HitSource(...)` after a successful request.
+     * Keys are collected first because deleting mutates the tags they came from.
+     */
+    invalidateTags(tags: readonly string[]): Promise<void>;
+    /** Alias of {@link clear}, spelled the way `@Invalidates("*")`-style callers expect. */
+    invalidateAll(): Promise<void>;
+    /** The promise of the request currently being sent for `key`, if any. */
+    getInFlight(key: string): Promise<unknown> | undefined;
+    /**
+     * Publish the promise of the request being sent for `key`.
+     *
+     * The entry removes itself when the promise settles, so a rejected shared
+     * promise cannot be picked up by a later, unrelated request. The rejection is
+     * also marked as observed: a leader that fails with no follower waiting would
+     * otherwise surface as an unhandled rejection in Node.
+     */
+    setInFlight(key: string, promise: Promise<unknown>): void;
+    private readL1;
+    private readL2;
+    private writeL1;
+    private writeL2;
+    private markExpiry;
+    private isStale;
+    private rememberTags;
+    private forgetKey;
+    private warnL2;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/plugins/cache/manager.d.ts.map

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

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

@@ -0,0 +1,64 @@
+import type { AxiosResponse, InternalAxiosRequestConfig } from "axios";
+import type { SnailPluginObject } from "../../typings/plugin.js";
+import { CacheManager } from "./manager.js";
+import type { CacheOptions } from "./type.js";
+/**
+ * The cache plugin.
+ *
+ * ## Where it sits in the pipeline
+ *
+ * `priority: -100` is the reserved cache band, which buys two things the contract
+ * spells out in `docs/guide/plugin-lifecycle.md` §2.2:
+ *
+ * - **last in forward order** — the interceptor (`100`) and every argument
+ *   decorator have already run, so `ctx.request` holds the final url, params and
+ *   body when the key is built. Hashing an earlier shape would key two different
+ *   requests identically (or one request twice).
+ * - **first in unwind order** — the raw envelope is stored before the validation
+ *   and transformation plugins touch it, so a hit replays exactly what the server
+ *   sent rather than a processed derivative.
+ *
+ * ## Stores what the server sent
+ *
+ * The entry holds `ctx.response.data`, not the `SnailResult`. The result is a
+ * projection of the envelope onto the caller's envelope schema; caching it would
+ * freeze one server's key names into another's cache.
+ */
+/** Plugin name; also the identity used by `Service.use()` / `Service.remove()`. */
+export declare const CACHE_PLUGIN_NAME = "cache";
+/** The reserved cache priority band (see `docs/guide/plugin-lifecycle.md` §2.1). */
+export declare const CACHE_PRIORITY = -100;
+/** The plugin object plus the manager behind it. */
+export interface CachePlugin extends SnailPluginObject<CacheOptions> {
+    /**
+     * The storage engine, available once the plugin has been installed by
+     * `Service.use(...)` — `install` is where the server name (the default key
+     * prefix) and the resolved log level become known.
+     */
+    readonly manager: CacheManager | undefined;
+}
+/**
+ * Create the cache plugin.
+ *
+ * ```ts
+ * const cache = Cache({ ttl: 30, l2: "localStorage" });
+ * Service.use(cache);
+ * await cache.manager?.invalidateAll();
+ * ```
+ */
+export declare function Cache(options?: CacheOptions): CachePlugin;
+/**
+ * Wrap a cached body into the axios response a plugin must hand back.
+ *
+ * `headers` is empty on purpose: the stored entry is only the body, and inventing
+ * headers would make downstream plugins react to values the server never sent.
+ * `config` is the live request, so anything reading `response.config` sees the
+ * request that produced the hit.
+ *
+ * The body is **copied**. Without that, the object handed to the caller would be
+ * the very object the cache holds, so one `result.data.name = "x"` would silently
+ * rewrite the cache entry — and, worse, a response transformer that hydrates the
+ * payload in place would corrupt the stored value for every later hit.
+ */
+export declare function makeCachedResponse<T>(body: T, config: InternalAxiosRequestConfig): AxiosResponse<T>;
+//# sourceMappingURL=plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/cache/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,OAAO,CAAC;AAOvE,OAAO,KAAK,EAAa,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAIzE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,oFAAoF;AACpF,eAAO,MAAM,cAAc,OAAO,CAAC;AAoBnC,oDAAoD;AACpD,MAAM,WAAW,WAAY,SAAQ,iBAAiB,CAAC,YAAY,CAAC;IAClE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CA4CzD;AA4LD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,0BAA0B,GACjC,aAAa,CAAC,CAAC,CAAC,CAQlB"}

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

@@ -0,0 +1,116 @@
+import type { SnailMethodType } from "../../typings/api.js";
+/**
+ * Shared shapes of the cache plugin.
+ *
+ * The design splits into three layers, each with one job:
+ *
+ * - a **decorator** says what to do (`@Cacheable`, `@NoCache`, `@Invalidates`),
+ * - the **plugin** turns that metadata plus the cache options into a per-request
+ *   plan, and
+ * - a **`CacheManager`** owns storage: L1, optional L2, TTL, LRU and tag index.
+ */
+/**
+ * A persistent (or at least outliving) cache store — "L2".
+ *
+ * Every method is asynchronous on purpose. `localStorage` is synchronous and
+ * IndexedDB is not; forcing the synchronous one to pretend does not cost
+ * anything, while letting an async store pretend to be synchronous is impossible.
+ * IndexedDB therefore needs no special case anywhere in the plugin.
+ *
+ * An implementation must never throw for a missing environment — the built-in
+ * IndexedDB and Web Storage adapters degrade to no-ops — but the manager guards
+ * the calls anyway, because a quota error (`QuotaExceededError`) is a normal
+ * outcome that must not fail the request.
+ */
+export interface CacheAdapter {
+    /** Read a value. `undefined` means "not stored" or "expired". */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Store a value. `ttlSeconds <= 0` means "no expiry". */
+    set(key: string, value: unknown, ttlSeconds: number): Promise<void>;
+    /** Remove one key. Removing an absent key is not an error. */
+    delete(key: string): Promise<void>;
+    /** Remove everything this adapter owns. */
+    clear(): Promise<void>;
+    /**
+     * Every key currently stored, when the backend can enumerate them.
+     *
+     * Optional because a custom adapter may front a store that cannot list keys
+     * (an HTTP cache, for example). The plugin never requires it; it exists for
+     * maintenance tooling and for tests.
+     */
+    keys?(): Promise<string[]>;
+}
+/** Options accepted by `Cache(...)`. */
+export interface CacheOptions {
+    /**
+     * Entry lifetime in seconds. Default 60.
+     *
+     * Must be positive; a zero, negative or non-finite value falls back to the
+     * default rather than silently storing an entry that never expires.
+     */
+    ttl?: number;
+    /**
+     * L1 LRU capacity. Default 100.
+     *
+     * A non-positive value also means 100 — an unbounded in-memory cache is a leak
+     * with extra steps, so it is not reachable by accident.
+     */
+    maxSize?: number;
+    /** L1 on/off. Default true. */
+    l1?: boolean;
+    /**
+     * L2 store.
+     *
+     * A string selects a built-in adapter and resolves its global lazily; an
+     * object is used as-is. When the selected environment global is missing
+     * (Node has neither `localStorage` nor `indexedDB`), the plugin warns once and
+     * continues with L1 only instead of throwing.
+     */
+    l2?: "localStorage" | "sessionStorage" | "indexedDB" | CacheAdapter;
+    /** Which verbs are cacheable. Default `["GET"]`. Accepts `"all"`. */
+    cacheFor?: "all" | SnailMethodType | SnailMethodType[];
+    /** Key prefix, defaults to the server name. */
+    prefix?: string;
+    /** Serve a stale entry immediately and refresh in the background. Default false. */
+    staleWhileRevalidate?: boolean;
+    /** Collapse concurrent identical requests into one. Default true. */
+    dedupe?: boolean;
+}
+/**
+ * Options accepted by `@Cacheable(...)`.
+ *
+ * Passing this decorator is an explicit opt-in: a method (or every method of a
+ * class) marked with it is cached even for a verb that `cacheFor` does not list.
+ * Without it, `cacheFor` decides.
+ */
+export interface CacheableOptions {
+    /**
+     * Entry lifetime in seconds for this target, overriding `CacheOptions.ttl`.
+     *
+     * Per-target rather than per-call because the decorator is static metadata: a
+     * method that needs a different lifetime for different arguments wants two
+     * methods.
+     */
+    ttl?: number;
+    /**
+     * Tags attached to the stored entry, so `@Invalidates("tag")` can purge it
+     * without knowing its key.
+     */
+    tags?: readonly string[];
+    /**
+     * Explicit cache key, bypassing the method/url/params/body hash.
+     *
+     * Every call of that method then shares one entry. Reach for it when the
+     * request has volatile parts that must not take part in the identity — a
+     * nonce, a timestamp — and accept that those parts are ignored.
+     */
+    key?: string;
+}
+/** One cached value plus its freshness, as returned by `CacheManager.lookup`. */
+export interface CacheLookup<T = unknown> {
+    /** The stored body. */
+    value: T;
+    /** `true` when the entry is past its TTL but was kept for `staleWhileRevalidate`. */
+    stale: boolean;
+}
+//# sourceMappingURL=type.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../src/plugins/cache/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;;GASG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAEtD,0DAA0D;IAC1D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE,8DAA8D;IAC9D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC,2CAA2C;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5B;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,+BAA+B;IAC/B,EAAE,CAAC,EAAE,OAAO,CAAC;IAEb;;;;;;;OAOG;IACH,EAAE,CAAC,EAAE,cAAc,GAAG,gBAAgB,GAAG,WAAW,GAAG,YAAY,CAAC;IAEpE,qEAAqE;IACrE,QAAQ,CAAC,EAAE,KAAK,GAAG,eAAe,GAAG,eAAe,EAAE,CAAC;IAEvD,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,oFAAoF;IACpF,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,iFAAiF;AACjF,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,uBAAuB;IACvB,KAAK,EAAE,CAAC,CAAC;IAET,qFAAqF;IACrF,KAAK,EAAE,OAAO,CAAC;CAChB"}

package/dist/plugins/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `@snail-js/api/plugins` — the built-in optional plugins.
+ *
+ * ```ts
+ * import {
+ *   Cache,
+ *   Cacheable,
+ *   Invalidates,
+ *   Interceptor,
+ *   BeforeRequest,
+ *   Versioning,
+ *   Version,
+ *   Validate,
+ *   Transform
+ * } from "@snail-js/api/plugins";
+ *
+ * Service
+ *   .use(Interceptor())
+ *   .use(Versioning({ type: "header", defaultVersion: "1.0.0" }))
+ *   .use(Validate())
+ *   .use(Transform())
+ *   .use(Cache({ ttl: 60, l2: "localStorage" }));
+ * ```
+ *
+ * ## Why this is a separate entry point
+ *
+ * Nothing here is in the core. Keeping the plugins behind `@snail-js/api/plugins`
+ * means an application that imports only the root entry pays for none of it — no
+ * cache, no validation and no JSON→class hydration. Each plugin lives in its own
+ * directory with its own barrel, so a bundler can drop the ones a given app never
+ * calls.
+ *
+ * ## The framework adapters are *not* here
+ *
+ * `VueAdapter` and `ReactAdapter` live behind their own subpaths:
+ *
+ * ```ts
+ * import { VueAdapter } from "@snail-js/api/plugins/vue";
+ * import { ReactAdapter } from "@snail-js/api/plugins/react";
+ * ```
+ *
+ * They are kept out of this barrel deliberately. A re-export would make this
+ * module statically import both `vue` and `react`, so a React application that
+ * only wanted `Cache` would fail to resolve `vue` at all — and a framework-free
+ * one would pull both frameworks into its bundle. Separate subpaths keep the
+ * optional peers genuinely optional.
+ *
+ * ## Registration order does not matter
+ *
+ * Plugins are ordered by `priority`, not by the order `use()` was called in:
+ *
+ * | Priority | Plugin |
+ * | --- | --- |
+ * | `100` | interceptor |
+ * | `50` | versioning |
+ * | `0` | framework adapter, transform |
+ * | `-50` | validate |
+ * | `-100` | cache |
+ * | `-150` | request pool |
+ *
+ * Forward hooks run highest-priority first, so the interceptor sees the request
+ * before the cache hashes it and the pool — dead last — only ever gates requests
+ * the cache could not answer. Unwind hooks run in the opposite direction, so the
+ * cache stores the raw envelope before validation and transformation touch it.
+ * See `docs/guide/plugin-lifecycle.md` §2.1 for the reasoning.
+ *
+ * @packageDocumentation
+ */
+export * from "./cache/index.js";
+export * from "./interceptor/index.js";
+export * from "./pool/index.js";
+export * from "./transform/index.js";
+export * from "./validate/index.js";
+export * from "./version/index.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}