silgi 0.52.2 → 0.53.1

package/dist/plugins/cache.mjs

@@ -4,86 +4,128 @@ import { defineCachedFunction, setStorage, useStorage } from "ocache";
 import { hash } from "ohash";
 //#region src/plugins/cache.ts
 /**
-* Cache plugin — production-grade response caching powered by ocache.
-*
-* All ocache features exposed:
-* - TTL + Stale-While-Revalidate (SWR)
-* - Request deduplication (concurrent calls share one in-flight promise)
-* - Automatic integrity (redeploy invalidates stale cache)
-* - shouldBypassCache / shouldInvalidateCache callbacks
-* - Entry validation and transformation
-* - Multi-tier storage (read cascade, write to all)
-* - Pluggable storage via `setCacheStorage()` (default: in-memory)
-* - unstorage adapter for Redis, Cloudflare KV, S3, etc.
-* - Mutation-triggered invalidation
+* Response cache plugin
+* -----------------------
+*
+* Caches resolver output using `ocache` underneath. Drop the wrap on
+* a query procedure and its return value is memoized, deduplicated,
+* and (by default) served stale-while-revalidate.
+*
+* The storage backend is pluggable. If the parent silgi instance has
+* a `'cache'` mount configured via `silgi({ storage })`, we wire ocache
+* to that mount the first time `cacheQuery()` runs. Otherwise ocache
+* falls back to its built-in in-memory map. Users who want a different
+* backend without the silgi storage mount can call `setCacheStorage()`
+* directly, or wrap an unstorage instance via `createUnstorageAdapter()`.
+*
+* Every ocache feature is exposed through the options:
+*
+*   TTL + stale-while-revalidate    — `maxAge`, `swr`, `staleMaxAge`
+*   Request deduplication           — built-in, concurrent calls share
+*                                     one in-flight promise
+*   Integrity                       — redeploy invalidates stale cache
+*                                     when the resolver's hash changes
+*   Per-request bypass / invalidate — `shouldBypassCache`,
+*                                     `shouldInvalidateCache`
+*   Entry validation / transform    — `validate`, `transform`
+*   Multi-tier storage              — read cascade, write to all
+*   Manual invalidation             — `invalidateQueryCache(name)`
+*
+* @example
+*   import { cacheQuery, setCacheStorage, createUnstorageAdapter } from 'silgi/cache'
+*   import { createStorage } from 'silgi/unstorage'
+*   import redisDriver from 'unstorage/drivers/redis'
+*
+*   const listUsers = k
+*     .$use(cacheQuery({ maxAge: 60 }))
+*     .$resolve(({ ctx }) => ctx.db.users.findMany())
+*
+*   const storage = createStorage({ driver: redisDriver({ url: 'redis://localhost' }) })
+*   setCacheStorage(createUnstorageAdapter(storage))
+*/
+/**
+* Build an ocache `StorageInterface` from anything that quacks like
+* an unstorage store. The plugin uses it twice — once internally to
+* bridge silgi's configured storage mount, and once as a public helper
+* for users who bring their own unstorage instance.
+*
+* Setting `value` to `null` / `undefined` intentionally triggers a
+* delete so ocache's "mark as stale" signalling survives every
+* backend uniformly.
+*/
+function adaptUnstorage(storage) {
+	return {
+		get: (key) => storage.getItem(key),
+		set: (key, value, opts) => {
+			if (value === null || value === void 0) return storage.removeItem(key);
+			return storage.setItem(key, value, opts);
+		}
+	};
+}
+/**
+* Public helper for users who already have an unstorage instance.
 *
 * @example
-* ```ts
-* import { cacheQuery, setCacheStorage } from 'silgi/cache'
-*
-* // Basic: cache for 60 seconds with SWR
-* const listUsers = k
-*   .$use(cacheQuery({ maxAge: 60 }))
-*   .$resolve(({ ctx }) => ctx.db.users.findMany())
-*
-* // With unstorage backend (Redis)
-* import { createUnstorageAdapter } from 'silgi/cache'
-* import { createStorage } from 'silgi/unstorage'
-* import redisDriver from 'unstorage/drivers/redis'
-*
-* const storage = createStorage({ driver: redisDriver({ url: 'redis://localhost' }) })
-* setCacheStorage(createUnstorageAdapter(storage))
-* ```
+*   const storage = createStorage({ driver: redisDriver({ ... }) })
+*   setCacheStorage(createUnstorageAdapter(storage))
 */
+function createUnstorageAdapter(storage) {
+	return adaptUnstorage(storage);
+}
 /**
-* Auto-connect ocache to silgi's storage.
-* Called lazily on first cacheQuery() use.
+* Connect ocache to the silgi instance's `'cache'` storage mount, if
+* one is configured. Idempotent — the first `cacheQuery()` call wins
+* and every subsequent one is a cheap boolean check.
+*
+* When silgi has no storage mount the call is a silent no-op: ocache
+* keeps its built-in in-memory backend, which is still correct (just
+* not shared across processes).
 */
-let _storageConnected = false;
+let storageConnected = false;
 function ensureStorageConnected() {
-	if (_storageConnected) return;
-	_storageConnected = true;
+	if (storageConnected) return;
+	storageConnected = true;
 	try {
-		const storage = useStorage$1("cache");
-		setStorage({
-			get: (key) => storage.getItem(key),
-			set: (key, value, opts) => {
-				if (value === null || value === void 0) {
-					storage.removeItem(key);
-					return;
-				}
-				storage.setItem(key, value, opts?.ttl ? { ttl: opts.ttl } : void 0);
-			}
-		});
+		setStorage(adaptUnstorage(useStorage$1("cache")));
 	} catch {}
 }
-/** Registry of cached function keys for invalidation */
+/**
+* Per-procedure set of cache keys, keyed by the procedure's cache name.
+* `invalidateQueryCache(name)` uses this to wipe every key that a given
+* procedure has written to backing storage.
+*
+* Module-global by design: different silgi instances in the same
+* process calling the same procedure name end up sharing the same
+* ocache backend anyway, so a unified registry is correct.
+*/
 const cacheKeyRegistry = /* @__PURE__ */ new Map();
 /**
-* Wrap middleware that caches query results.
+* Build the cache-key generator from user options. When the user
+* passes `getKey`, we use it verbatim. Otherwise we hash the input
+* with ohash, falling back to an empty string when there is no input
+* (shared-cache-for-parameterless-queries is almost always what
+* people want).
+*/
+function buildKeyFn(custom) {
+	if (custom) return custom;
+	return (input) => input !== void 0 && input !== null ? hash(input) : "";
+}
+/**
+* Wrap middleware that caches a query procedure's output.
 *
-* Uses ocache under the hood: TTL, SWR, dedup, integrity, bypass, invalidation.
-* Default: 60s TTL, SWR enabled.
+* Defaults: 60-second TTL, SWR on. Every other knob comes from
+* {@link CacheQueryOptions}.
 *
 * @example
-* ```ts
-* const listUsers = k
-*   .$use(cacheQuery({ maxAge: 60 }))
-*   .$resolve(({ ctx }) => ctx.db.users.findMany())
-*
-* // Advanced: bypass cache for admin, custom validation
-* const listPosts = k
-*   .$use(cacheQuery({
-*     maxAge: 300,
-*     swr: true,
-*     staleMaxAge: 600,
-*     shouldBypassCache: (input) => (input as any)?.noCache,
-*     shouldInvalidateCache: (input) => (input as any)?.refresh,
-*     validate: (entry) => Array.isArray(entry.value),
-*     onError: (err) => console.error('[cache]', err),
-*   }))
-*   .$resolve(({ ctx }) => ctx.db.posts.findMany())
-* ```
+*   const listPosts = k
+*     .$use(cacheQuery({
+*       maxAge: 300,
+*       staleMaxAge: 600,
+*       shouldBypassCache: (input) => (input as any)?.noCache,
+*       validate: (entry) => Array.isArray(entry.value),
+*       onError: (err) => console.error('[cache]', err),
+*     }))
+*     .$resolve(({ ctx }) => ctx.db.posts.findMany())
 */
 function cacheQuery(options = {}) {
 	const maxAge = options.maxAge ?? 60;
@@ -91,29 +133,32 @@ function cacheQuery(options = {}) {
 	const staleMaxAge = options.staleMaxAge ?? maxAge;
 	const customGetKey = options.getKey;
 	let cacheName = options.name;
-	const pendingNextMap = /* @__PURE__ */ new Map();
-	let requestCounter = 0;
 	let cachedFn = null;
-	let keyFn;
+	let keyFn = buildKeyFn(customGetKey);
+	/**
+	* Two concurrent requests can race through the same cache entry:
+	* ocache calls our inner `_resolve` for each one, and they must not
+	* share a closure-scoped `next`. We keep a per-request map keyed
+	* by a monotonic counter so each call resolves its *own* `next()`.
+	*/
+	const pendingNext = /* @__PURE__ */ new Map();
+	let requestCounter = 0;
 	return {
 		kind: "wrap",
 		fn: async (ctx, next) => {
 			ensureStorageConnected();
 			if (!cachedFn) {
-				if (!cacheName) cacheName = ctx.__procedurePath || `proc_${hash(next.toString()).slice(0, 8)}`;
+				cacheName ??= ctx.__procedurePath ?? `proc_${hash(next.toString()).slice(0, 8)}`;
 				const resolvedName = cacheName;
+				const resolvedBase = options.base ?? "/cache";
 				const keySet = /* @__PURE__ */ new Set();
 				cacheKeyRegistry.set(resolvedName, keySet);
-				keyFn = customGetKey ? (input) => customGetKey(input) : (input) => input !== void 0 && input !== null ? hash(input) : "";
-				const resolvedBase = options.base ?? "/cache";
 				cachedFn = defineCachedFunction(async (_input, requestId) => {
-					const mapKey = requestId ?? keyFn(_input);
-					const nextFn = pendingNextMap.get(mapKey);
-					if (nextFn) {
-						pendingNextMap.delete(mapKey);
-						return nextFn();
-					}
-					throw new Error("[silgi/cache] Missing next() for cache resolve");
+					const key = requestId ?? keyFn(_input);
+					const fn = pendingNext.get(key);
+					if (!fn) throw new Error("[silgi/cache] Missing next() for cache resolve");
+					pendingNext.delete(key);
+					return fn();
 				}, {
 					name: resolvedName,
 					group: "silgi",
@@ -125,8 +170,8 @@ function cacheQuery(options = {}) {
 					onError: options.onError,
 					validate: options.validate,
 					transform: options.transform,
-					shouldBypassCache: options.shouldBypassCache ? (input) => options.shouldBypassCache(input) : void 0,
-					shouldInvalidateCache: options.shouldInvalidateCache ? (input) => options.shouldInvalidateCache(input) : void 0,
+					shouldBypassCache: options.shouldBypassCache,
+					shouldInvalidateCache: options.shouldInvalidateCache,
 					getKey: (input) => {
 						const key = keyFn(input);
 						keySet.add(`${resolvedBase}:silgi:${resolvedName}:${key}.json`);
@@ -136,77 +181,44 @@ function cacheQuery(options = {}) {
 			}
 			const input = ctx[RAW_INPUT];
 			const requestId = `__req_${++requestCounter}`;
-			pendingNextMap.set(requestId, next);
+			pendingNext.set(requestId, next);
 			return cachedFn(input, requestId);
 		}
 	};
 }
 /**
-* Invalidate cached entries for a procedure by name.
+* Wipe every cached entry for a procedure by its cache name.
 *
-* Call this after mutations to clear related query caches.
+* Typically called after a mutation that makes related queries stale.
+* Names default to the procedure's auto-generated path, or whatever
+* was passed via `cacheQuery({ name })`.
 *
 * @example
-* ```ts
-* const createUser = k.$resolve(async ({ input, ctx }) => {
-*   const user = await ctx.db.users.create(input)
-*   await invalidateQueryCache('users_list')
-*   return user
-* })
-* ```
+*   const createUser = k.$resolve(async ({ input, ctx }) => {
+*     const user = await ctx.db.users.create(input)
+*     await invalidateQueryCache('users_list')
+*     return user
+*   })
 */
 async function invalidateQueryCache(name) {
 	const keys = cacheKeyRegistry.get(name);
-	if (keys) {
-		const storage = useStorage();
-		await Promise.all([...keys].map((key) => storage.set(key, null)));
-		keys.clear();
-	}
+	if (!keys) return;
+	const storage = useStorage();
+	await Promise.all([...keys].map((key) => storage.set(key, null)));
+	keys.clear();
 }
 /**
-* Set the cache storage backend.
-*
-* Default: in-memory Map with TTL.
-* For production, use `createUnstorageAdapter()` with Redis, Cloudflare KV, etc.
+* Replace ocache's storage backend. Default is an in-memory map with
+* TTL; production deployments usually want Redis or Cloudflare KV via
+* `createUnstorageAdapter()`.
 *
 * @example
-* ```ts
-* import { setCacheStorage, createUnstorageAdapter } from 'silgi/cache'
-* import { createStorage } from 'silgi/unstorage'
-* import redisDriver from 'unstorage/drivers/redis'
-*
-* setCacheStorage(createUnstorageAdapter(
-*   createStorage({ driver: redisDriver({ url: 'redis://localhost' }) })
-* ))
-* ```
+*   setCacheStorage(createUnstorageAdapter(
+*     createStorage({ driver: redisDriver({ url: 'redis://localhost' }) })
+*   ))
 */
 function setCacheStorage(storage) {
 	setStorage(storage);
 }
-/**
-* Create an ocache-compatible storage adapter from an unstorage instance.
-*
-* @example
-* ```ts
-* import { createStorage } from 'silgi/unstorage'
-* import redisDriver from 'unstorage/drivers/redis'
-*
-* const storage = createStorage({ driver: redisDriver({ url: 'redis://localhost' }) })
-* const adapter = createUnstorageAdapter(storage)
-* setCacheStorage(adapter)
-* ```
-*/
-function createUnstorageAdapter(storage) {
-	return {
-		get: (key) => storage.getItem(key),
-		set: (key, value, opts) => {
-			if (value === null || value === void 0) {
-				storage.removeItem(key);
-				return;
-			}
-			storage.setItem(key, value, opts);
-		}
-	};
-}
 //#endregion
 export { cacheQuery, createUnstorageAdapter, invalidateQueryCache, setCacheStorage };

package/dist/plugins/coerce.d.mts

@@ -13,8 +13,9 @@ import { WrapDef } from "../types.mjs";
  * - "" → undefined (empty strings become undefined)
  * - Everything else → kept as-is
  *
- * Implemented as a wrap (not a guard) so it runs after __rawInput is populated
- * by the pipeline compiler.
+ * Implemented as a wrap so it runs after the pipeline has populated the
+ * `RAW_INPUT` slot on ctx — see the caveat in the top-level docstring
+ * about ordering vs. input schema validation.
  */
 declare const coerceGuard: WrapDef<Record<string, unknown>>;
 declare function coerceValue(value: unknown): unknown;

package/dist/plugins/coerce.mjs

@@ -7,17 +7,33 @@ import { RAW_INPUT } from "../core/ctx-symbols.mjs";
 * query parameters. This wrap coerces common types automatically:
 * "123" → 123, "true" → true, "null" → null, etc.
 *
+* @remarks
+* **Ordering caveat.** The pipeline validates `$input` schemas *before*
+* running the wrap onion. That means a plain `z.number()` rejects "123"
+* before this wrap can see it. You have three options:
+*
+* 1. **Use Zod's own coercion** — `z.coerce.number()`, `z.coerce.boolean()`.
+*    Zero extra wrap, works for simple cases.
+* 2. **Skip the input schema and validate inside the resolver** — pairs
+*    naturally with `coerceGuard` because the wrap always runs first.
+* 3. **Use a string-accepting schema and coerce with `.transform()`** —
+*    e.g. `z.object({ id: z.string().transform(Number) })`. Again no
+*    wrap needed.
+*
+* `coerceGuard` itself is useful when you have NO input schema but still
+* want `"42"` / `"true"` / `"null"` normalised before your resolver runs.
+*
 * @example
 * ```ts
-* import { coerceGuard } from "silgi/plugins"
-*
+* // Works: no schema → wrap can reshape freely.
 * const getUser = k
 *   .$use(coerceGuard)
-*   .$input(z.object({ id: z.number(), active: z.boolean().optional() }))
-*   .$resolve(({ input }) => db.users.find(input.id))
+*   .$resolve(({ input }) => db.users.find((input as any).id))
 *
-* // GET /users/get?data={"id":"42","active":"true"}
-* // → input is coerced to { id: 42, active: true }
+* // Works: schema uses z.coerce.
+* const getUser2 = k
+*   .$input(z.object({ id: z.coerce.number() }))
+*   .$resolve(({ input }) => db.users.find(input.id))
 * ```
 */
 /**
@@ -32,8 +48,9 @@ import { RAW_INPUT } from "../core/ctx-symbols.mjs";
 * - "" → undefined (empty strings become undefined)
 * - Everything else → kept as-is
 *
-* Implemented as a wrap (not a guard) so it runs after __rawInput is populated
-* by the pipeline compiler.
+* Implemented as a wrap so it runs after the pipeline has populated the
+* `RAW_INPUT` slot on ctx — see the caveat in the top-level docstring
+* about ordering vs. input schema validation.
 */
 const coerceGuard = {
 	kind: "wrap",

package/dist/scalar.d.mts

@@ -9,42 +9,53 @@ interface ScalarOptions {
     url: string;
     description?: string;
   }[];
-  /** Security scheme (e.g. Bearer token) */
+  /** Security scheme (e.g. Bearer token, API key header). */
   security?: {
-    type: 'http' | 'apiKey';
-    scheme?: string;
-    bearerFormat?: string;
-    in?: 'header' | 'query';
+    type: 'http' | 'apiKey'; /** For `type: 'http'`, e.g. `'bearer'`. */
+    scheme?: string; /** For `type: 'http'` + bearer, e.g. `'JWT'`. */
+    bearerFormat?: string; /** For `type: 'apiKey'`, which side of the request carries the key. */
+    in?: 'header' | 'query'; /** For `type: 'apiKey'`, the header / query-param name. */
     name?: string;
     description?: string;
   };
-  /** Contact info */
   contact?: {
     name?: string;
     url?: string;
     email?: string;
   };
-  /** License */
   license?: {
     name: string;
     url?: string;
   };
-  /** External docs */
   externalDocs?: {
     url: string;
     description?: string;
   };
   /**
-   * Scalar UI script source.
+   * Where to load the Scalar UI script from.
    *
-   * - `'cdn'` (default) — loads from cdn.jsdelivr.net
-   * - `'unpkg'` — loads from unpkg.com
-   * - `'local'` — serves from node_modules (offline, requires `@scalar/api-reference` installed)
-   * - Custom URL string — self-hosted or local path (e.g. `'/assets/scalar.js'`)
+   *   `'cdn'`   — `cdn.jsdelivr.net` (default).
+   *   `'unpkg'` — `unpkg.com`.
+   *   `'local'` — serve from `node_modules` (offline; requires the
+   *               `@scalar/api-reference` package installed).
+   *   string    — any custom URL, e.g. a self-hosted asset path.
    */
   cdn?: 'cdn' | 'unpkg' | 'local' | (string & {});
 }
+/**
+ * Generate an OpenAPI 3.1.0 document for a `RouterDef`.
+ *
+ * The document is a plain object and can be re-serialized, cached,
+ * piped into any OpenAPI consumer (codegen, docs site, validators). We
+ * do not return a typed `OpenAPIV3_1.Document` because the typings in
+ * the ecosystem are noisy; downstream consumers usually only care
+ * about a handful of keys anyway.
+ */
 declare function generateOpenAPI(router: RouterDef, options?: ScalarOptions, basePath?: string, registry?: SchemaRegistry): Record<string, unknown>;
+/**
+ * Render the minimal HTML shell the Scalar UI needs. The UI itself is
+ * a single script that reads the `data-url` attribute to pull the spec.
+ */
 declare function scalarHTML(specUrl: string, options?: ScalarOptions): string;
 //#endregion
 export { ScalarOptions, generateOpenAPI, scalarHTML };