silgi 0.52.2 → 0.53.1

package/dist/integrations/better-auth/index.mjs

@@ -48,6 +48,14 @@ function runWithCtx(ctx, fn) {
 * Keyed on `Request` identity. GC-friendly: entry auto-released when the
 * `Request` is collected.
 *
+* @remarks
+* This is a documented exception to ARCHITECTURE §3 ("no WeakMap keyed on
+* Request identity"). Kept only because `setRequestContext` is a public
+* API consumed by user code outside silgi's control — removing it is a
+* breaking change reserved for the next major. New integrations must
+* use `silgi.runInContext(ctx, fn)` or the per-plugin closure pattern
+* (see `requestMetas` inside `tracing()` below).
+*
 * @internal
 */
 const _requestContextMap = /* @__PURE__ */ new WeakMap();
@@ -186,7 +194,6 @@ function extractUserData(returned) {
 	}
 	return result;
 }
-const requestMetas = /* @__PURE__ */ new WeakMap();
 /**
 * Creates a Better Auth plugin that auto-traces all auth operations
 * into silgi analytics spans.
@@ -197,6 +204,8 @@ const requestMetas = /* @__PURE__ */ new WeakMap();
 function tracing(config) {
 	const captureInput = config?.captureInput ?? true;
 	const captureOutput = config?.captureOutput ?? true;
+	const wrapMiddleware = config?.createAuthMiddleware ?? ((fn) => fn);
+	const requestMetas = /* @__PURE__ */ new WeakMap();
 	return {
 		id: "silgi-tracing",
 		onRequest: async (request, _ctx) => {
@@ -215,7 +224,7 @@ function tracing(config) {
 		},
 		hooks: { after: [{
 			matcher: () => true,
-			handler: (config?.createAuthMiddleware ?? ((fn) => fn))(async (ctx) => {
+			handler: wrapMiddleware(async (ctx) => {
 				try {
 					const request = ctx.request;
 					if (!request) return;

package/dist/lazy.mjs

@@ -62,6 +62,9 @@ async function resolveLazy(value) {
 			resolved.set(value, mod.default);
 			loading.delete(value);
 			return mod.default;
+		}, (err) => {
+			loading.delete(value);
+			throw err;
 		});
 		loading.set(value, pending);
 	}

package/dist/map-input.d.mts

@@ -4,13 +4,15 @@ import { WrapDef } from "./types.mjs";
 /**
  * Create a wrap that transforms the procedure input before execution.
  *
- * The mapper function receives the raw input and returns the transformed input.
- * The mapped input is set on the context as `__mappedInput` and picked up
- * by the pipeline.
+ * @remarks
+ * The mapper receives the raw input and returns the transformed input.
+ * Internally this wrap replaces the value in the pipeline's `RAW_INPUT`
+ * symbol slot on `ctx`; the resolver reads the same slot to get the
+ * rewritten input. Users never interact with the slot directly — it's
+ * framework-internal (see `src/core/ctx-symbols.ts`).
  *
- * Note: Since Silgi's pipeline receives input as a separate argument
- * (not on ctx), mapInput works as a wrap that intercepts and transforms
- * before calling next().
+ * Must run inside the wrap onion (not as a guard) so it can observe and
+ * mutate the already-parsed input after schema validation.
  */
 declare function mapInput<TIn = unknown, TOut = unknown>(mapper: (input: TIn) => TOut | Promise<TOut>): WrapDef;
 //#endregion

package/dist/map-input.mjs

@@ -25,13 +25,15 @@ import { RAW_INPUT } from "./core/ctx-symbols.mjs";
 /**
 * Create a wrap that transforms the procedure input before execution.
 *
-* The mapper function receives the raw input and returns the transformed input.
-* The mapped input is set on the context as `__mappedInput` and picked up
-* by the pipeline.
+* @remarks
+* The mapper receives the raw input and returns the transformed input.
+* Internally this wrap replaces the value in the pipeline's `RAW_INPUT`
+* symbol slot on `ctx`; the resolver reads the same slot to get the
+* rewritten input. Users never interact with the slot directly — it's
+* framework-internal (see `src/core/ctx-symbols.ts`).
 *
-* Note: Since Silgi's pipeline receives input as a separate argument
-* (not on ctx), mapInput works as a wrap that intercepts and transforms
-* before calling next().
+* Must run inside the wrap onion (not as a guard) so it can observe and
+* mutate the already-parsed input after schema validation.
 */
 function mapInput(mapper) {
 	return {

package/dist/plugins/analytics/routes.mjs

@@ -107,6 +107,22 @@ function parseAnalyticsDetailPath(pathname, prefix) {
 function jsonResponse(data, headers) {
 	return new Response(JSON.stringify(data), { headers });
 }
+/**
+* Parse a request body as JSON without throwing. Returns `null` on any
+* failure (empty body, malformed JSON, non-JSON content). Used by the
+* analytics hidden-paths endpoint so a bad request produces a 400 instead
+* of an uncaught exception that surfaces as a 500 to the client.
+*/
+async function parseJsonBody(request) {
+	try {
+		const text = await request.text();
+		if (!text) return null;
+		const parsed = JSON.parse(text);
+		return parsed && typeof parsed === "object" ? parsed : null;
+	} catch {
+		return null;
+	}
+}
 /** Serve analytics dashboard and API routes. */
 async function serveAnalyticsRoute(pathname, request, collector, dashboardHtml) {
 	const jsonCacheHeaders = {
@@ -122,24 +138,20 @@ async function serveAnalyticsRoute(pathname, request, collector, dashboardHtml)
 	if (pathname === "api/analytics/stats") return jsonResponse(collector.toJSON(), jsonCacheHeaders);
 	if (pathname === "api/analytics/hidden") {
 		if (request.method === "GET") return jsonResponse(collector.getHiddenPaths(), jsonCacheHeaders);
-		if (request.method === "POST") {
-			const body = await request.json();
-			if (typeof body.path !== "string") return new Response("{\"error\":\"path required\"}", {
-				status: 400,
-				headers: jsonCacheHeaders
-			});
-			collector.addHiddenPath(body.path);
-			return jsonResponse(collector.getHiddenPaths(), jsonCacheHeaders);
-		}
-		if (request.method === "DELETE") {
-			const body = await request.json();
-			if (typeof body.path !== "string") return new Response("{\"error\":\"path required\"}", {
+		if (request.method === "POST" || request.method === "DELETE") {
+			const body = await parseJsonBody(request);
+			if (!body || typeof body.path !== "string") return new Response("{\"error\":\"path required\"}", {
 				status: 400,
 				headers: jsonCacheHeaders
 			});
-			collector.removeHiddenPath(body.path);
+			if (request.method === "POST") collector.addHiddenPath(body.path);
+			else collector.removeHiddenPath(body.path);
 			return jsonResponse(collector.getHiddenPaths(), jsonCacheHeaders);
 		}
+		return new Response("{\"error\":\"method not allowed\"}", {
+			status: 405,
+			headers: jsonCacheHeaders
+		});
 	}
 	if (pathname === "api/analytics/errors") return jsonResponse(queryErrors((await collector.getErrors()).filter((e) => !collector.isHidden(e.procedure)), parseQueryParams(url.searchParams)), jsonCacheHeaders);
 	if (pathname === "api/analytics/requests") return jsonResponse(queryRequests((await collector.getRequests()).filter((r) => !collector.isHidden(r.path)), parseQueryParams(url.searchParams)), jsonCacheHeaders);

package/dist/plugins/cache.d.mts

@@ -2,169 +2,105 @@ import { WrapDef } from "../types.mjs";
 import { CacheEntry, CacheOptions, StorageInterface } from "ocache";
 
 //#region src/plugins/cache.d.ts
+/**
+ * Minimal interface matching an unstorage `Storage`. We describe it
+ * locally so the cache plugin does not take a hard dependency on the
+ * unstorage package — users bring their own.
+ */
+interface UnstorageCompatible {
+  getItem<T = unknown>(key: string): Promise<T | null> | T | null;
+  setItem(key: string, value: unknown, opts?: {
+    ttl?: number;
+  }): Promise<void> | void;
+  removeItem(key: string): Promise<void> | void;
+}
+/**
+ * Public helper for users who already have an unstorage instance.
+ *
+ * @example
+ *   const storage = createStorage({ driver: redisDriver({ ... }) })
+ *   setCacheStorage(createUnstorageAdapter(storage))
+ */
+declare function createUnstorageAdapter(storage: UnstorageCompatible): StorageInterface;
 interface CacheQueryOptions<T = unknown> {
-  /** Cache TTL in seconds (default: 60) */
+  /** Cache TTL in seconds. @default 60 */
   maxAge?: number;
-  /** Enable stale-while-revalidate (default: true) */
+  /** Enable stale-while-revalidate. @default true */
   swr?: boolean;
-  /** Max seconds to serve stale while revalidating (default: maxAge) */
+  /** Max seconds to serve stale while revalidating. @default maxAge */
   staleMaxAge?: number;
-  /** Custom cache key generator from input */
+  /** Custom cache-key generator from the request input. */
   getKey?: (input: unknown) => string;
-  /** Cache key name prefix (default: procedure path, set automatically) */
+  /** Human-readable cache name. Defaults to the procedure path. */
   name?: string;
   /**
-   * When returns `true`, skip cache entirely and call resolver directly.
-   * Useful for admin users or debug modes.
-   *
-   * @example
-   * ```ts
-   * cacheQuery({
-   *   shouldBypassCache: (input) => input?.noCache === true,
-   * })
-   * ```
+   * Return `true` to skip cache entirely and call the resolver
+   * directly. Useful for admin users or debug modes.
    */
   shouldBypassCache?: (input: unknown) => boolean | Promise<boolean>;
   /**
-   * When returns `true`, invalidate cache for this key and re-resolve.
+   * Return `true` to invalidate cache for this key and re-resolve.
    * The new result is cached normally.
-   *
-   * @example
-   * ```ts
-   * cacheQuery({
-   *   shouldInvalidateCache: (input) => input?.refresh === true,
-   * })
-   * ```
    */
   shouldInvalidateCache?: (input: unknown) => boolean | Promise<boolean>;
-  /**
-   * Validate a cache entry before returning it.
-   * Return `false` to treat as cache miss and re-resolve.
-   *
-   * @example
-   * ```ts
-   * cacheQuery({
-   *   validate: (entry) => entry.value !== null && entry.value !== undefined,
-   * })
-   * ```
-   */
+  /** Validate a cache entry before returning it. `false` = treat as miss. */
   validate?: (entry: CacheEntry<T>) => boolean;
-  /**
-   * Transform a cache entry before returning.
-   * Runs on both cache hits and fresh resolves.
-   *
-   * @example
-   * ```ts
-   * cacheQuery({
-   *   transform: (entry) => ({ ...entry.value, cachedAt: entry.mtime }),
-   * })
-   * ```
-   */
+  /** Transform a cache entry before returning. Runs on both hits and fresh resolves. */
   transform?: (entry: CacheEntry<T>) => T;
-  /**
-   * Storage base prefix for cache keys.
-   * Defaults to `'/cache'`.
-   *
-   * @example
-   * ```ts
-   * cacheQuery({
-   *   base: '/my-app-cache',
-   * })
-   * ```
-   */
+  /** Storage key prefix. @default '/cache' */
   base?: string;
   /**
-   * Custom integrity value. Auto-generated from the resolver + options by default.
-   * When integrity changes (e.g. after redeploy), stale cache is invalidated.
+   * Custom integrity value. Auto-generated from the resolver + options
+   * by default; when it changes (e.g. after a redeploy) stale cache is
+   * invalidated.
    */
   integrity?: string;
-  /** Error handler for cache read/write/SWR failures */
+  /** Error handler for cache read / write / SWR failures. */
   onError?: (error: unknown) => void;
 }
 /**
- * Wrap middleware that caches query results.
+ * 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())
  */
 declare function cacheQuery<T = unknown>(options?: CacheQueryOptions<T>): WrapDef;
 /**
- * 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
+ *   })
  */
 declare function invalidateQueryCache(name: string): Promise<void>;
 /**
- * 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' }) })
+ *   ))
  */
 declare function setCacheStorage(storage: StorageInterface): void;
-/**
- * Minimal interface matching unstorage's Storage.
- * Avoids hard dependency on unstorage — users bring their own.
- */
-interface UnstorageCompatible {
-  getItem<T = unknown>(key: string): Promise<T | null> | T | null;
-  setItem(key: string, value: unknown, opts?: {
-    ttl?: number;
-  }): Promise<void> | void;
-  removeItem(key: string): Promise<void> | void;
-}
-/**
- * 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)
- * ```
- */
-declare function createUnstorageAdapter(storage: UnstorageCompatible): StorageInterface;
 //#endregion
 export { type CacheEntry, type CacheOptions, CacheQueryOptions, type StorageInterface, UnstorageCompatible, cacheQuery, createUnstorageAdapter, invalidateQueryCache, setCacheStorage };