silgi 0.43.28 → 0.50.0

package/dist/plugins/analytics/types.mjs

@@ -0,0 +1,40 @@
+//#region src/plugins/analytics/types.ts
+/**
+* Analytics type definitions and RingBuffer data structure.
+*/
+var RingBuffer = class {
+	#data;
+	#size;
+	#head = 0;
+	#count = 0;
+	constructor(size) {
+		this.#data = new Float64Array(size);
+		this.#size = size;
+	}
+	push(value) {
+		this.#data[this.#head] = value;
+		this.#head = (this.#head + 1) % this.#size;
+		if (this.#count < this.#size) this.#count++;
+	}
+	percentile(p) {
+		if (this.#count === 0) return 0;
+		const arr = new Float64Array(this.#count);
+		if (this.#count < this.#size) arr.set(this.#data.subarray(0, this.#count));
+		else arr.set(this.#data);
+		arr.sort();
+		const idx = Math.ceil(p / 100 * this.#count) - 1;
+		return arr[Math.max(0, idx)];
+	}
+	avg() {
+		if (this.#count === 0) return 0;
+		let sum = 0;
+		const n = this.#count;
+		for (let i = 0; i < n; i++) sum += this.#data[i];
+		return sum / n;
+	}
+	get count() {
+		return this.#count;
+	}
+};
+//#endregion
+export { RingBuffer };

package/dist/plugins/analytics/utils.d.mts

@@ -0,0 +1,4 @@
+//#region src/plugins/analytics/utils.d.ts
+declare function sanitizeHeaders(headers: Headers): Record<string, string>;
+//#endregion
+export { sanitizeHeaders };

package/dist/plugins/analytics/utils.mjs

@@ -0,0 +1,56 @@
+//#region src/plugins/analytics/utils.ts
+/**
+* Shared utilities for the analytics subsystem.
+*
+* Helpers: rounding, header redaction, path matching, JSON safety.
+*/
+const REDACTED = "[REDACTED]";
+const SENSITIVE_HEADER_KEYS = new Set([
+	"authorization",
+	"cookie",
+	"set-cookie",
+	"x-api-key",
+	"x-auth-token",
+	"proxy-authorization"
+]);
+function shouldRedactSensitiveData() {
+	return process.env.NODE_ENV === "production";
+}
+function redactHeaderValue(key, value) {
+	return shouldRedactSensitiveData() && SENSITIVE_HEADER_KEYS.has(key.toLowerCase()) ? REDACTED : value;
+}
+function round(n) {
+	return Math.round(n * 100) / 100;
+}
+function safeStringify(v) {
+	try {
+		return JSON.stringify(v, null, 2);
+	} catch {
+		return String(v);
+	}
+}
+function sanitizeHeaders(headers) {
+	const result = {};
+	headers.forEach((value, key) => {
+		result[key] = redactHeaderValue(key, value);
+	});
+	return result;
+}
+function matchesPathPrefix(pathname, prefixes) {
+	const normalized = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+	for (const prefix of prefixes) if (normalized === prefix || normalized.startsWith(prefix + "/")) return true;
+	return false;
+}
+function isTrackedRequestPath(pathname) {
+	const normalized = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+	return normalized === "api" || normalized.startsWith("api/") || normalized === "graphql" || normalized.startsWith("graphql/");
+}
+function isAnalyticsPath(pathname) {
+	return pathname === "api/analytics" || pathname.startsWith("api/analytics/");
+}
+/** Helper to safely cast unknown to Record. */
+function asRecord(value) {
+	return value && typeof value === "object" ? value : null;
+}
+//#endregion
+export { asRecord, isAnalyticsPath, isTrackedRequestPath, matchesPathPrefix, redactHeaderValue, round, safeStringify, sanitizeHeaders };

package/dist/plugins/analytics.d.mts

@@ -0,0 +1,18 @@
+import { AnalyticsOptions, AnalyticsSnapshot, ErrorEntry, ProcedureCall, ProcedureSnapshot, RequestEntry, SpanKind, TaskExecution, TaskSnapshot, TraceSpan } from "./analytics/types.mjs";
+import { AnalyticsCollector } from "./analytics/collector.mjs";
+import { RequestTrace, trace } from "./analytics/trace.mjs";
+import { analyticsAuthResponse, analyticsHTML, checkAnalyticsAuth, serveAnalyticsRoute } from "./analytics/routes.mjs";
+import { errorToMarkdown, requestToMarkdown } from "./analytics/export.mjs";
+import { sanitizeHeaders } from "./analytics/utils.mjs";
+import { RequestAccumulator } from "./analytics/accumulator.mjs";
+import { analyticsTraceMap } from "../core/trace-map.mjs";
+import { FetchHandler } from "../core/handler.mjs";
+
+//#region src/plugins/analytics.d.ts
+/**
+ * Wrap a fetch handler with analytics collection.
+ * Intercepts analytics dashboard routes and instruments every request.
+ */
+declare function wrapWithAnalytics(handler: FetchHandler, options?: AnalyticsOptions): FetchHandler;
+//#endregion
+export { AnalyticsCollector, type AnalyticsOptions, type AnalyticsSnapshot, type ErrorEntry, type ProcedureCall, type ProcedureSnapshot, RequestAccumulator, type RequestEntry, RequestTrace, type SpanKind, type TaskExecution, type TaskSnapshot, type TraceSpan, analyticsAuthResponse, analyticsHTML, analyticsTraceMap, checkAnalyticsAuth, errorToMarkdown, requestToMarkdown, sanitizeHeaders, serveAnalyticsRoute, trace, wrapWithAnalytics };

package/dist/plugins/analytics.mjs

@@ -0,0 +1,188 @@
+import { ValidationError } from "../core/schema.mjs";
+import { SilgiError, toSilgiError } from "../core/error.mjs";
+import { analyticsTraceMap } from "../core/trace-map.mjs";
+import { parseUrlPathname } from "../core/url.mjs";
+import { generateRequestId } from "./analytics/request-id.mjs";
+import { isAnalyticsPath, isTrackedRequestPath, round, sanitizeHeaders } from "./analytics/utils.mjs";
+import { RequestAccumulator } from "./analytics/accumulator.mjs";
+import { AnalyticsCollector } from "./analytics/collector.mjs";
+import { errorToMarkdown, requestToMarkdown } from "./analytics/export.mjs";
+import { analyticsAuthResponse, analyticsHTML, checkAnalyticsAuth, serveAnalyticsRoute } from "./analytics/routes.mjs";
+import { RequestTrace, trace } from "./analytics/trace.mjs";
+//#region src/plugins/analytics.ts
+/**
+* Built-in analytics plugin — zero-dependency monitoring with deep error tracing.
+*
+* This module is the public entry point. Implementation lives in ./analytics/.
+*
+* - Per-procedure metrics (count, errors, latency percentiles) via ring buffers
+* - Full error log with input, headers, stack trace, custom spans
+* - `trace()` helper for measuring DB queries, API calls, etc.
+* - HTTP-level request tracking with procedure grouping (batch support)
+* - Unique request IDs via `x-request-id` response header
+*
+* Dashboard at /api/analytics, JSON API at /api/analytics/stats, errors at /api/analytics/errors.
+*/
+async function captureResponseBody(response) {
+	const lowered = (response.headers.get("content-type") ?? "").toLowerCase();
+	if (!response.body || lowered.includes("text/event-stream") || lowered.includes("application/octet-stream")) return { output: null };
+	try {
+		const text = await response.clone().text();
+		if (!text) return { output: null };
+		let output = text;
+		if (lowered.includes("application/json") || lowered.includes("+json")) try {
+			output = JSON.parse(text);
+		} catch {
+			output = text;
+		}
+		if (response.status < 400) return { output };
+		if (output && typeof output === "object") {
+			const record = output;
+			const message = typeof record.message === "string" ? record.message : null;
+			const code = typeof record.code === "string" ? record.code : null;
+			if (message && code) return {
+				output,
+				error: `${code}: ${message}`
+			};
+			if (message) return {
+				output,
+				error: message
+			};
+		}
+		return {
+			output,
+			error: typeof output === "string" ? output : JSON.stringify(output)
+		};
+	} catch {
+		return { output: null };
+	}
+}
+function extractResponseError(output, status, fallback) {
+	if (output && typeof output === "object") {
+		const record = output;
+		const code = typeof record.code === "string" ? record.code : null;
+		const message = typeof record.message === "string" ? record.message : null;
+		if (code && message) return {
+			code,
+			message
+		};
+		if (message) return {
+			code: `HTTP_${status}`,
+			message
+		};
+	}
+	if (fallback) return {
+		code: `HTTP_${status}`,
+		message: fallback
+	};
+	return {
+		code: `HTTP_${status}`,
+		message: `Request failed with status ${status}`
+	};
+}
+/**
+* Wrap a fetch handler with analytics collection.
+* Intercepts analytics dashboard routes and instruments every request.
+*/
+function wrapWithAnalytics(handler, options = {}) {
+	const collector = new AnalyticsCollector(options);
+	const dashboardHtml = analyticsHTML();
+	const auth = options.auth;
+	import("../core/task.mjs").then(({ setTaskAnalytics }) => {
+		setTaskAnalytics((entry) => collector.recordTask({
+			...entry,
+			spans: entry.spans ?? []
+		}));
+	});
+	return async (request) => {
+		const pathname = parseUrlPathname(request.url);
+		if (isAnalyticsPath(pathname)) {
+			if (auth) {
+				const authResult = checkAnalyticsAuth(request, auth);
+				if (!(authResult instanceof Promise ? await authResult : authResult)) return analyticsAuthResponse(pathname);
+			}
+			return serveAnalyticsRoute(pathname, request, collector, dashboardHtml);
+		}
+		if (!isTrackedRequestPath(pathname) || collector.isIgnored(pathname)) return handler(request);
+		const incomingTraceId = request.headers.get("x-trace-id");
+		const parentRequestId = request.headers.get("x-parent-request-id");
+		const traceId = incomingTraceId || generateRequestId();
+		const acc = new RequestAccumulator(request, collector, traceId, parentRequestId ?? void 0);
+		const reqTrace = new RequestTrace();
+		const t0 = performance.now();
+		analyticsTraceMap.set(request, reqTrace);
+		let response;
+		try {
+			response = await handler(request);
+			const durationMs = round(performance.now() - t0);
+			const captured = await captureResponseBody(response);
+			const procedureInput = reqTrace.procedureInput ?? null;
+			const procedureOutput = reqTrace.procedureOutput ?? captured.output;
+			const procedureSpans = reqTrace.spans ?? [];
+			collector.record(pathname, durationMs);
+			acc.addProcedure({
+				procedure: pathname,
+				durationMs,
+				status: response.status,
+				input: procedureInput,
+				output: procedureOutput,
+				spans: procedureSpans,
+				error: captured.error
+			});
+			if (response.status >= 400) {
+				const { code, message } = extractResponseError(procedureOutput, response.status, captured.error);
+				collector.recordError(pathname, durationMs, message);
+				collector.recordDetailedError({
+					requestId: acc.requestId,
+					timestamp: Date.now(),
+					procedure: pathname,
+					error: message,
+					code,
+					status: response.status,
+					stack: "",
+					input: procedureInput,
+					headers: sanitizeHeaders(request.headers),
+					durationMs,
+					spans: procedureSpans
+				});
+			}
+		} catch (error) {
+			const durationMs = round(performance.now() - t0);
+			const errorMsg = error instanceof Error ? error.message : String(error);
+			const isValidation = error instanceof ValidationError;
+			const silgiErr = isValidation ? null : error instanceof SilgiError ? error : toSilgiError(error);
+			const errStatus = isValidation ? 400 : silgiErr?.status ?? 500;
+			collector.recordError(pathname, durationMs, errorMsg);
+			collector.recordDetailedError({
+				requestId: acc.requestId,
+				timestamp: Date.now(),
+				procedure: pathname,
+				error: errorMsg,
+				code: isValidation ? "BAD_REQUEST" : silgiErr?.code ?? "INTERNAL_SERVER_ERROR",
+				status: errStatus,
+				stack: error instanceof Error ? (error.stack ?? "").slice(0, 2048) : "",
+				input: null,
+				headers: sanitizeHeaders(request.headers),
+				durationMs,
+				spans: reqTrace.spans ?? []
+			});
+			throw error;
+		} finally {
+			analyticsTraceMap.delete(request);
+		}
+		const headers = new Headers(response.headers);
+		headers.set("x-request-id", acc.requestId);
+		headers.set("x-trace-id", traceId);
+		const cookie = acc.getSessionCookie();
+		if (cookie) headers.append("set-cookie", cookie);
+		const injected = new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers
+		});
+		acc.flushWithResponse(injected);
+		return injected;
+	};
+}
+//#endregion
+export { AnalyticsCollector, RequestAccumulator, RequestTrace, analyticsAuthResponse, analyticsHTML, analyticsTraceMap, checkAnalyticsAuth, errorToMarkdown, requestToMarkdown, sanitizeHeaders, serveAnalyticsRoute, trace, wrapWithAnalytics };

package/dist/plugins/batch-server.d.mts

@@ -0,0 +1,20 @@
+import { RouterDef } from "../types.mjs";
+
+//#region src/plugins/batch-server.d.ts
+interface BatchHandlerOptions<TCtx extends Record<string, unknown>> {
+  /** Context factory — called once per batch request */
+  context: (req: Request) => TCtx | Promise<TCtx>;
+  /** Maximum number of calls in a single batch. Default: 50 */
+  maxBatchSize?: number;
+}
+/**
+ * Create a Fetch API handler that processes batched RPC calls.
+ *
+ * Expects a POST with JSON body: `[{ path, input }, ...]`
+ * Returns: `[{ data } | { error }, ...]`
+ *
+ * All calls in a batch share the same context (computed once).
+ */
+declare function createBatchHandler<TCtx extends Record<string, unknown>>(router: RouterDef, options: BatchHandlerOptions<TCtx>): (request: Request) => Promise<Response>;
+//#endregion
+export { BatchHandlerOptions, createBatchHandler };

package/dist/plugins/batch-server.mjs

@@ -0,0 +1,91 @@
+import { ValidationError } from "../core/schema.mjs";
+import { SilgiError, toSilgiError } from "../core/error.mjs";
+import { compileRouter } from "../compile.mjs";
+//#region src/plugins/batch-server.ts
+/**
+* Server-side batch endpoint — handle multiple RPC calls in one HTTP request.
+*
+* Works with the client-side BatchLink to combine multiple calls into
+* a single HTTP round-trip.
+*
+* @example
+* ```ts
+* import { createBatchHandler } from "silgi/plugins"
+*
+* const batchHandler = createBatchHandler(appRouter, {
+*   context: (req) => ({ db: getDB() }),
+*   maxBatchSize: 20,
+* })
+*
+* // Mount at /batch endpoint alongside your normal handler
+* ```
+*/
+/**
+* Create a Fetch API handler that processes batched RPC calls.
+*
+* Expects a POST with JSON body: `[{ path, input }, ...]`
+* Returns: `[{ data } | { error }, ...]`
+*
+* All calls in a batch share the same context (computed once).
+*/
+function createBatchHandler(router, options) {
+	const flatRouter = compileRouter(router);
+	const { maxBatchSize = 50 } = options;
+	return async (request) => {
+		if (request.method !== "POST") return Response.json({
+			code: "METHOD_NOT_ALLOWED",
+			status: 405
+		}, { status: 405 });
+		let calls;
+		try {
+			calls = await request.json();
+		} catch {
+			return Response.json({
+				code: "BAD_REQUEST",
+				status: 400,
+				message: "Invalid JSON"
+			}, { status: 400 });
+		}
+		if (!Array.isArray(calls)) return Response.json({
+			code: "BAD_REQUEST",
+			status: 400,
+			message: "Expected array"
+		}, { status: 400 });
+		if (calls.length > maxBatchSize) return Response.json({
+			code: "BAD_REQUEST",
+			status: 400,
+			message: `Batch too large: ${calls.length} calls (max ${maxBatchSize})`
+		}, { status: 400 });
+		const baseCtx = await options.context(request);
+		const results = await Promise.all(calls.map(async (call) => {
+			if (typeof call.path !== "string" || call.path.length === 0 || call.path.length > 512 || call.path.includes("\0")) return { error: {
+				code: "BAD_REQUEST",
+				status: 400,
+				message: "Invalid procedure path"
+			} };
+			const route = flatRouter("POST", "/" + call.path)?.data;
+			if (!route) return { error: {
+				code: "NOT_FOUND",
+				status: 404,
+				message: "Procedure not found"
+			} };
+			try {
+				const ctx = Object.create(null);
+				const keys = Object.keys(baseCtx);
+				for (let i = 0; i < keys.length; i++) ctx[keys[i]] = baseCtx[keys[i]];
+				return { data: await route.handler(ctx, call.input, request.signal) };
+			} catch (error) {
+				if (error instanceof ValidationError) return { error: {
+					code: "BAD_REQUEST",
+					status: 400,
+					message: error.message,
+					data: { issues: error.issues }
+				} };
+				return { error: (error instanceof SilgiError ? error : toSilgiError(error)).toJSON() };
+			}
+		}));
+		return Response.json(results);
+	};
+}
+//#endregion
+export { createBatchHandler };

package/dist/plugins/body-limit.d.mts

@@ -0,0 +1,19 @@
+import { GuardDef } from "../types.mjs";
+
+//#region src/plugins/body-limit.d.ts
+interface BodyLimitOptions {
+  /** Maximum body size in bytes. Default: 1_048_576 (1 MB) */
+  maxBytes?: number;
+  /** Custom error message. */
+  message?: string;
+}
+/**
+ * Create a guard that rejects requests with bodies larger than `maxBytes`.
+ *
+ * Checks Content-Length header when present (zero overhead for GET requests).
+ * For chunked/streaming bodies without Content-Length, the limit is enforced
+ * at parse time by the handler's body parsing logic.
+ */
+declare function bodyLimitGuard(options?: BodyLimitOptions): GuardDef<Record<string, unknown>>;
+//#endregion
+export { BodyLimitOptions, bodyLimitGuard };

package/dist/plugins/body-limit.mjs

@@ -0,0 +1,49 @@
+import { SilgiError } from "../core/error.mjs";
+//#region src/plugins/body-limit.ts
+/**
+* Body limit guard — reject oversized request bodies.
+*
+* Checks Content-Length header first (fast path), then enforces
+* actual body size during stream consumption as a fallback.
+*
+* @example
+* ```ts
+* import { bodyLimitGuard } from "silgi/plugins"
+*
+* const upload = k
+*   .$use(bodyLimitGuard({ maxBytes: 5 * 1024 * 1024 })) // 5 MB
+*   .$resolve(({ input }) => processUpload(input))
+* ```
+*/
+/**
+* Create a guard that rejects requests with bodies larger than `maxBytes`.
+*
+* Checks Content-Length header when present (zero overhead for GET requests).
+* For chunked/streaming bodies without Content-Length, the limit is enforced
+* at parse time by the handler's body parsing logic.
+*/
+function bodyLimitGuard(options = {}) {
+	const { maxBytes = 1048576, message = "Request body too large" } = options;
+	return {
+		kind: "guard",
+		fn: (ctx) => {
+			const headers = ctx.headers;
+			if (!headers) return;
+			const cl = headers["content-length"];
+			if (!cl) return;
+			const size = Number.parseInt(cl, 10);
+			if (Number.isNaN(size)) return;
+			if (size > maxBytes) throw new SilgiError("PAYLOAD_TOO_LARGE", {
+				status: 413,
+				message,
+				data: {
+					maxBytes,
+					receivedBytes: size
+				}
+			});
+		},
+		maxBytes
+	};
+}
+//#endregion
+export { bodyLimitGuard };

package/dist/plugins/cache.d.mts

@@ -0,0 +1,170 @@
+import { WrapDef } from "../types.mjs";
+import { CacheEntry, CacheOptions, StorageInterface } from "ocache";
+
+//#region src/plugins/cache.d.ts
+interface CacheQueryOptions<T = unknown> {
+  /** Cache TTL in seconds (default: 60) */
+  maxAge?: number;
+  /** Enable stale-while-revalidate (default: true) */
+  swr?: boolean;
+  /** Max seconds to serve stale while revalidating (default: maxAge) */
+  staleMaxAge?: number;
+  /** Custom cache key generator from input */
+  getKey?: (input: unknown) => string;
+  /** Cache key name prefix (default: procedure path, set automatically) */
+  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,
+   * })
+   * ```
+   */
+  shouldBypassCache?: (input: unknown) => boolean | Promise<boolean>;
+  /**
+   * When returns `true`, 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?: (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?: (entry: CacheEntry<T>) => T;
+  /**
+   * Storage base prefix for cache keys.
+   * Defaults to `'/cache'`.
+   *
+   * @example
+   * ```ts
+   * cacheQuery({
+   *   base: '/my-app-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.
+   */
+  integrity?: string;
+  /** Error handler for cache read/write/SWR failures */
+  onError?: (error: unknown) => void;
+}
+/**
+ * Wrap middleware that caches query results.
+ *
+ * Uses ocache under the hood: TTL, SWR, dedup, integrity, bypass, invalidation.
+ * Default: 60s TTL, SWR enabled.
+ *
+ * @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())
+ * ```
+ */
+declare function cacheQuery<T = unknown>(options?: CacheQueryOptions<T>): WrapDef;
+/**
+ * Invalidate cached entries for a procedure by name.
+ *
+ * Call this after mutations to clear related query caches.
+ *
+ * @example
+ * ```ts
+ * 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.
+ *
+ * @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' }) })
+ * ))
+ * ```
+ */
+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 };