silgi 0.53.0 → 0.53.1

package/dist/core/task.mjs

@@ -1,19 +1,104 @@
 import { validateSchema } from "./schema.mjs";
 //#region src/core/task.ts
 /**
-* Task API — type-safe background tasks built on the procedure builder.
+* Background tasks
+* ------------------
+*
+* A *task* is a procedure with two extra capabilities:
+*
+*   1. Programmatic `dispatch(input)` — call it directly, outside the
+*      HTTP pipeline. Used for async work (send-email, rebuild-index)
+*      and as the callback target for cron schedules.
+*   2. Optional `cron` spec — when set, the task is auto-registered
+*      with a `croner` job at `serve()` time.
+*
+* Tasks are built via the procedure builder:
 *
-* Tasks are procedures with dispatch + cron capabilities:
 *   s.$use(auth).$input(schema).$task({ name: 'send-email', resolve })
+*
+* Dispatch runs through the same root-wrap onion as the HTTP pipeline
+* so tenant scoping, trace propagation, and similar cross-cutting
+* concerns apply uniformly. When no root wraps are configured the
+* dispatch path reduces to a direct `await resolveFn(…)`.
 */
-let _onTaskComplete = null;
+/**
+* Module-global sink for task completion events. This is shared across
+* every silgi instance in the process — analytics is currently wired
+* through the process-default cron registry for the same reason.
+* Per-instance analytics is a future refactor; `setTaskAnalytics(null)`
+* detaches the sink.
+*/
+let onTaskComplete = null;
 function setTaskAnalytics(cb) {
-	_onTaskComplete = cb;
+	onTaskComplete = cb;
 }
+/** Round a millisecond duration to two decimal places — matches dashboard display. */
+const round2 = (ms) => Math.round(ms * 100) / 100;
+/**
+* Wrap `run` in the root-wrap onion. Root wraps are outermost-first, so
+* we fold from the end of the list: the last wrap wraps `run`, the one
+* before wraps that, and so on. When there are no wraps we just return
+* `run` unchanged — zero onion overhead.
+*
+* Same shape as `composeWraps` in `compile.ts`; kept here privately to
+* avoid a core → compile import cycle.
+*/
+function applyRootWraps(ctx, wraps, run) {
+	let chain = run;
+	for (let i = wraps.length - 1; i >= 0; i--) {
+		const wrap = wraps[i];
+		const next = chain;
+		chain = () => Promise.resolve(wrap.fn(ctx, next));
+	}
+	return chain();
+}
+/**
+* Lazy-loaded `RequestTrace` constructor. The analytics module is
+* optional — missing it must not break task dispatch — so we attempt
+* the import once and cache the outcome. `null` means "we've tried;
+* analytics is not available in this build".
+*/
+let requestTraceCtor;
+async function getRequestTrace() {
+	if (requestTraceCtor !== void 0) return requestTraceCtor;
+	try {
+		requestTraceCtor = (await import("../plugins/analytics.mjs")).RequestTrace;
+	} catch {
+		requestTraceCtor = null;
+	}
+	return requestTraceCtor;
+}
+/** Record this dispatch as a span on the parent request's trace, if one exists. */
+function recordParentSpan(parentTrace, name, spanStart, err) {
+	if (!parentTrace) return;
+	const span = {
+		name: `task:${name}`,
+		kind: "queue",
+		durationMs: round2(performance.now() - spanStart),
+		startOffsetMs: round2(spanStart - parentTrace.t0),
+		detail: `dispatch ${name}`
+	};
+	if (err !== void 0) span.error = err instanceof Error ? err.message : String(err);
+	parentTrace.spans.push(span);
+}
+/**
+* Build a `TaskDef` from the procedure builder's `.$task()` configuration.
+*
+* @param rootWrapsGetter A *live* getter so a task constructed before
+*   `s.router()` stamps wraps still picks them up at dispatch time. The
+*   silgi instance threads a closure over its own rootWraps reference.
+*   Pass `null` when no wraps are configured — dispatch then skips the
+*   onion entirely.
+*/
 function createTaskFromProcedure(config, resolveFn, inputSchema, use, contextFactory, rootWrapsGetter = null) {
 	const { name, cron = null, description } = config;
 	if (!name) throw new TypeError("Task name is required");
-	const taskResolve = async (opts) => {
+	/**
+	* Resolver called by the *HTTP* pipeline when the task is reachable
+	* through the router tree. `ctx` already carries everything the
+	* pipeline set up (base context, guards, trace), so we just forward.
+	*/
+	const pipelineResolve = async (opts) => {
 		return resolveFn({
 			input: opts.input,
 			ctx: opts.ctx,
@@ -21,72 +106,52 @@ function createTaskFromProcedure(config, resolveFn, inputSchema, use, contextFac
 			scheduledTime: void 0
 		});
 	};
+	/**
+	* Programmatic dispatch — the one users call from another procedure
+	* or a cron callback. Validates input, builds its own context, runs
+	* the root-wrap onion around the resolver, records analytics.
+	*/
 	const dispatch = async (rawInput, parentCtx) => {
 		const input = inputSchema ? await validateSchema(inputSchema, rawInput) : rawInput;
 		const ctx = contextFactory ? await contextFactory() : {};
 		const parentTrace = parentCtx?.trace;
 		const spanStart = parentTrace ? performance.now() : 0;
-		let reqTrace = null;
-		try {
-			const { RequestTrace } = await import("../plugins/analytics.mjs");
-			reqTrace = new RequestTrace();
-			ctx.trace = reqTrace;
-		} catch {}
-		const rootWraps = rootWrapsGetter ? rootWrapsGetter() : null;
-		const runResolver = () => resolveFn({
+		const RequestTrace = await getRequestTrace();
+		const selfTrace = RequestTrace ? new RequestTrace() : null;
+		if (selfTrace) ctx.trace = selfTrace;
+		const runResolver = () => Promise.resolve(resolveFn({
 			input,
 			ctx,
 			name,
 			scheduledTime: void 0
-		});
+		}));
+		const wraps = rootWrapsGetter?.() ?? null;
 		const t0 = performance.now();
 		try {
-			let output;
-			if (rootWraps && rootWraps.length > 0) {
-				let execute = () => Promise.resolve(runResolver());
-				for (let i = rootWraps.length - 1; i >= 0; i--) {
-					const wrapFn = rootWraps[i].fn;
-					const next = execute;
-					execute = () => wrapFn(ctx, next);
-				}
-				output = await execute();
-			} else output = await runResolver();
-			if (parentTrace) parentTrace.spans.push({
-				name: `task:${name}`,
-				kind: "queue",
-				durationMs: Math.round((performance.now() - spanStart) * 100) / 100,
-				startOffsetMs: Math.round((spanStart - parentTrace.t0) * 100) / 100,
-				detail: `dispatch ${name}`
-			});
-			if (_onTaskComplete) _onTaskComplete({
+			const output = wraps && wraps.length > 0 ? await applyRootWraps(ctx, wraps, runResolver) : await runResolver();
+			recordParentSpan(parentTrace, name, spanStart);
+			onTaskComplete?.({
 				taskName: name,
 				trigger: "dispatch",
 				timestamp: Date.now(),
-				durationMs: Math.round((performance.now() - t0) * 100) / 100,
+				durationMs: round2(performance.now() - t0),
 				status: "success",
 				input,
 				output,
-				spans: reqTrace?.spans
+				spans: selfTrace?.spans
 			});
 			return output;
 		} catch (err) {
-			if (parentTrace) parentTrace.spans.push({
-				name: `task:${name}`,
-				kind: "queue",
-				durationMs: Math.round((performance.now() - spanStart) * 100) / 100,
-				startOffsetMs: Math.round((spanStart - parentTrace.t0) * 100) / 100,
-				detail: `dispatch ${name}`,
-				error: err instanceof Error ? err.message : String(err)
-			});
-			if (_onTaskComplete) _onTaskComplete({
+			recordParentSpan(parentTrace, name, spanStart, err);
+			onTaskComplete?.({
 				taskName: name,
 				trigger: "dispatch",
 				timestamp: Date.now(),
-				durationMs: Math.round((performance.now() - t0) * 100) / 100,
+				durationMs: round2(performance.now() - t0),
 				status: "error",
 				error: err instanceof Error ? err.message : String(err),
 				input,
-				spans: reqTrace?.spans
+				spans: selfTrace?.spans
 			});
 			throw err;
 		}
@@ -99,7 +164,7 @@ function createTaskFromProcedure(config, resolveFn, inputSchema, use, contextFac
 		output: null,
 		errors: null,
 		use,
-		resolve: taskResolve,
+		resolve: pipelineResolve,
 		route: description ? {
 			summary: description,
 			tags: ["Tasks"]
@@ -109,33 +174,51 @@ function createTaskFromProcedure(config, resolveFn, inputSchema, use, contextFac
 		dispatch
 	};
 }
-const _running = /* @__PURE__ */ new Map();
+/**
+* In-flight dispatches keyed by task object.
+*
+* `runTask` coalesces concurrent calls so two callers asking for the
+* same task at once share a single execution. Useful for idempotent
+* background jobs that can be kicked off from multiple places.
+*/
+const running = /* @__PURE__ */ new Map();
 async function runTask(task, ...args) {
-	const existing = _running.get(task);
+	const existing = running.get(task);
 	if (existing) return existing;
 	const promise = task.dispatch(args[0]);
-	_running.set(task, promise);
+	running.set(task, promise);
 	try {
 		return await promise;
 	} finally {
-		_running.delete(task);
+		running.delete(task);
 	}
 }
+/**
+* Walk a router tree and collect every task that has a `cron` field set.
+* Nested namespaces are recursed into; we stop at any node already
+* tagged as a task so a task's internal structure is never inspected.
+*/
 function collectCronTasks(def) {
 	const result = [];
-	for (const value of Object.values(def)) if (value && typeof value === "object") {
-		if ("_tag" in value && value._tag === "task" && value.cron) result.push({
-			cron: value.cron,
-			task: value
-		});
-		else if (!("_tag" in value)) result.push(...collectCronTasks(value));
+	for (const value of Object.values(def)) {
+		if (!value || typeof value !== "object") continue;
+		if ("_tag" in value && value._tag === "task") {
+			const task = value;
+			if (task.cron) result.push({
+				cron: task.cron,
+				task
+			});
+		} else if (!("_tag" in value)) result.push(...collectCronTasks(value));
 	}
 	return result;
 }
 /**
-* Create an isolated cron registry. Each silgi instance owns one, so
-* `server.close()` on instance A never stops instance B's jobs and
-* `list()` never returns jobs from another instance.
+* Create an isolated cron registry.
+*
+* Each silgi instance owns one, so `server.close()` on instance A
+* never stops instance B's jobs and `list()` never returns jobs from
+* another instance. The module-default registry below keeps the
+* legacy top-level exports working.
 */
 function createCronRegistry() {
 	const entries = [];
@@ -165,37 +248,38 @@ function createCronRegistry() {
 			}
 		},
 		stop() {
-			for (const e of entries) e.job.stop();
+			for (const entry of entries) entry.job.stop();
 			entries.length = 0;
 		},
 		list() {
-			return entries.map((e) => ({
-				name: e.name,
-				cron: e.cron,
-				description: e.description,
-				nextRun: e.job.nextRun()?.getTime() ?? null,
-				lastRun: e.lastRun,
-				runs: e.runs,
-				errors: e.errors
+			return entries.map((entry) => ({
+				name: entry.name,
+				cron: entry.cron,
+				description: entry.description,
+				nextRun: entry.job.nextRun()?.getTime() ?? null,
+				lastRun: entry.lastRun,
+				runs: entry.runs,
+				errors: entry.errors
 			}));
 		}
 	};
 }
 /**
-* Process-default cron registry. Shared state — use {@link createCronRegistry}
-* when a silgi instance should own its own jobs.
+* Process-default cron registry.
 *
-* @deprecated Prefer per-instance registries. The module-default is
-* retained so existing imports of `startCronJobs` / `stopCronJobs` /
+* @deprecated
+* Shared state. Prefer {@link createCronRegistry} and give each silgi
+* instance its own. The module-default registry is retained so
+* existing imports of `startCronJobs` / `stopCronJobs` /
 * `getScheduledTasks` keep working; a future major will remove these
 * top-level re-exports.
 */
-const _defaultRegistry = createCronRegistry();
+const defaultRegistry = createCronRegistry();
 /** @deprecated Use {@link createCronRegistry} — each silgi instance owns its own. */
-const startCronJobs = _defaultRegistry.start;
+const startCronJobs = defaultRegistry.start;
 /** @deprecated Use {@link createCronRegistry} — each silgi instance owns its own. */
-const stopCronJobs = _defaultRegistry.stop;
+const stopCronJobs = defaultRegistry.stop;
 /** @deprecated Use {@link createCronRegistry} — each silgi instance owns its own. */
-const getScheduledTasks = _defaultRegistry.list;
+const getScheduledTasks = defaultRegistry.list;
 //#endregion
 export { collectCronTasks, createCronRegistry, createTaskFromProcedure, getScheduledTasks, runTask, setTaskAnalytics, startCronJobs, stopCronJobs };

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 };