silgi 0.0.13 → 0.1.0-beta.1

package/dist/plugins/batch-server.mjs

@@ -0,0 +1,86 @@
+import { SilgiError, toSilgiError } from "../core/error.mjs";
+import { ValidationError } from "../core/schema.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) => {
+			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,16 @@
+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 the Content-Length header — zero overhead for GET requests.
+ */
+declare function bodyLimitGuard(options?: BodyLimitOptions): GuardDef<Record<string, unknown>>;
+//#endregion
+export { BodyLimitOptions, bodyLimitGuard };

package/dist/plugins/body-limit.mjs

@@ -0,0 +1,44 @@
+import { SilgiError } from "../core/error.mjs";
+//#region src/plugins/body-limit.ts
+/**
+* Body limit guard — reject oversized request bodies.
+*
+* Throws TOO_LARGE (413) when the Content-Length header exceeds the limit.
+*
+* @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 the Content-Length header — zero overhead for GET requests.
+*/
+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
+				}
+			});
+		}
+	};
+}
+//#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 };

package/dist/plugins/cache.mjs

@@ -0,0 +1,200 @@
+import { useStorage as useStorage$1 } from "../core/storage.mjs";
+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
+*
+* @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))
+* ```
+*/
+/**
+* Auto-connect ocache to silgi's storage.
+* Called lazily on first cacheQuery() use.
+*/
+let _storageConnected = false;
+function ensureStorageConnected() {
+	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);
+			}
+		});
+	} catch {}
+}
+/** Registry of cached function keys for invalidation */
+const cacheKeyRegistry = /* @__PURE__ */ new Map();
+/**
+* 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())
+* ```
+*/
+function cacheQuery(options = {}) {
+	const maxAge = options.maxAge ?? 60;
+	const swr = options.swr ?? true;
+	const staleMaxAge = options.staleMaxAge ?? maxAge;
+	const customGetKey = options.getKey;
+	let cacheName = options.name;
+	let currentNext = null;
+	let cachedFn = null;
+	return {
+		kind: "wrap",
+		fn: async (ctx, next) => {
+			ensureStorageConnected();
+			if (!cachedFn) {
+				if (!cacheName) cacheName = ctx.__procedurePath || `proc_${hash(next.toString()).slice(0, 8)}`;
+				const resolvedName = cacheName;
+				const keySet = /* @__PURE__ */ new Set();
+				cacheKeyRegistry.set(resolvedName, keySet);
+				const keyFn = customGetKey ? (input) => customGetKey(input) : (input) => input !== void 0 && input !== null ? hash(input) : "";
+				const resolvedBase = options.base ?? "/cache";
+				cachedFn = defineCachedFunction(async (_input) => currentNext(), {
+					name: resolvedName,
+					group: "silgi",
+					maxAge,
+					swr,
+					staleMaxAge,
+					base: resolvedBase,
+					integrity: options.integrity,
+					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,
+					getKey: (input) => {
+						const key = keyFn(input);
+						keySet.add(`${resolvedBase}:silgi:${resolvedName}:${key}.json`);
+						return key;
+					}
+				});
+			}
+			currentNext = next;
+			const input = ctx.__rawInput;
+			return cachedFn(input);
+		}
+	};
+}
+/**
+* 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
+* })
+* ```
+*/
+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();
+	}
+}
+/**
+* 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' }) })
+* ))
+* ```
+*/
+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

@@ -0,0 +1,21 @@
+import { GuardDef } from "../types.mjs";
+
+//#region src/plugins/coerce.d.ts
+/**
+ * Coerce string values in the input to their proper JavaScript types.
+ * Only processes top-level and one-level-deep object values.
+ *
+ * Rules:
+ * - "123", "-42", "3.14" → number
+ * - "true", "false" → boolean
+ * - "null" → null
+ * - "undefined" → undefined
+ * - "" → undefined (empty strings become undefined)
+ * - Everything else → kept as-is
+ */
+declare const coerceGuard: GuardDef<Record<string, unknown>>;
+declare function coerceValue(value: unknown): unknown;
+declare function coerceObject(obj: Record<string, unknown>): void;
+/** Standalone coercion function — use outside of guards */
+//#endregion
+export { coerceGuard, coerceObject, coerceValue };

package/dist/plugins/coerce.mjs

@@ -0,0 +1,46 @@
+//#region src/plugins/coerce.ts
+/**
+* Coerce string values in the input to their proper JavaScript types.
+* Only processes top-level and one-level-deep object values.
+*
+* Rules:
+* - "123", "-42", "3.14" → number
+* - "true", "false" → boolean
+* - "null" → null
+* - "undefined" → undefined
+* - "" → undefined (empty strings become undefined)
+* - Everything else → kept as-is
+*/
+const coerceGuard = {
+	kind: "guard",
+	fn: (ctx) => {
+		const input = ctx.__rawInput;
+		if (typeof input !== "object" || input === null) return;
+		coerceObject(input);
+	}
+};
+function coerceValue(value) {
+	if (typeof value !== "string") return value;
+	if (value === "") return void 0;
+	if (value === "null") return null;
+	if (value === "undefined") return void 0;
+	if (value === "true") return true;
+	if (value === "false") return false;
+	if (value.length > 0 && value.length <= 20) {
+		const num = Number(value);
+		if (!Number.isNaN(num) && String(num) === value) return num;
+	}
+	return value;
+}
+function coerceObject(obj) {
+	const keys = Object.keys(obj);
+	for (let i = 0; i < keys.length; i++) {
+		const key = keys[i];
+		const val = obj[key];
+		if (typeof val === "string") obj[key] = coerceValue(val);
+		else if (typeof val === "object" && val !== null && !Array.isArray(val)) coerceObject(val);
+		else if (Array.isArray(val)) for (let j = 0; j < val.length; j++) val[j] = coerceValue(val[j]);
+	}
+}
+//#endregion
+export { coerceGuard, coerceObject, coerceValue };

package/dist/plugins/compression.d.mts

@@ -0,0 +1,19 @@
+import { WrapDef } from "../types.mjs";
+
+//#region src/plugins/compression.d.ts
+interface CompressionOptions {
+  /** Minimum response size in bytes before compression kicks in. Default: 1024 */
+  threshold?: number;
+  /** Preferred encoding. Default: "gzip" */
+  encoding?: 'gzip' | 'deflate';
+}
+/**
+ * Create a compression wrap middleware.
+ *
+ * Note: Compression is most useful with handler() / custom servers.
+ * With serve(), Node.js handles compression at the HTTP level.
+ * This wrap operates on the procedure output before serialization.
+ */
+declare function compressionWrap(options?: CompressionOptions): WrapDef;
+//#endregion
+export { CompressionOptions, compressionWrap };

package/dist/plugins/compression.mjs

@@ -0,0 +1,23 @@
+//#region src/plugins/compression.ts
+/**
+* Create a compression wrap middleware.
+*
+* Note: Compression is most useful with handler() / custom servers.
+* With serve(), Node.js handles compression at the HTTP level.
+* This wrap operates on the procedure output before serialization.
+*/
+function compressionWrap(options = {}) {
+	const { threshold = 1024, encoding = "gzip" } = options;
+	return {
+		kind: "wrap",
+		fn: async (_ctx, next) => {
+			_ctx.__compression = {
+				threshold,
+				encoding
+			};
+			return next();
+		}
+	};
+}
+//#endregion
+export { compressionWrap };

package/dist/plugins/cookies.d.mts

@@ -0,0 +1,44 @@
+//#region src/plugins/cookies.d.ts
+/**
+ * Cookie helpers — parse, set, and delete cookies.
+ *
+ * Lightweight utilities for working with cookies in Silgi handlers.
+ * No dependencies. Works with both serve() and handler().
+ *
+ * @example
+ * ```ts
+ * import { getCookie, setCookie, deleteCookie } from "silgi/cookies"
+ *
+ * const auth = k.guard((ctx) => {
+ *   const token = getCookie(ctx.headers, "session")
+ *   if (!token) throw new SilgiError("UNAUTHORIZED")
+ *   return { sessionToken: token }
+ * })
+ * ```
+ */
+/** Parse a specific cookie from a headers object or cookie string. */
+declare function getCookie(headers: Record<string, string> | string, name: string): string | undefined;
+/** Parse all cookies from a headers object or cookie string. */
+declare function parseCookies(headers: Record<string, string> | string): Record<string, string>;
+interface CookieOptions {
+  /** Cookie expiry in seconds from now. */
+  maxAge?: number;
+  /** Absolute expiry date. */
+  expires?: Date;
+  /** Cookie path. Default: "/" */
+  path?: string;
+  /** Cookie domain. */
+  domain?: string;
+  /** HTTPS only. Default: true in production. */
+  secure?: boolean;
+  /** Prevent JavaScript access. Default: true */
+  httpOnly?: boolean;
+  /** SameSite policy. Default: "lax" */
+  sameSite?: 'strict' | 'lax' | 'none';
+}
+/** Serialize a Set-Cookie header value. */
+declare function setCookie(name: string, value: string, options?: CookieOptions): string;
+/** Create a Set-Cookie header that deletes a cookie. */
+declare function deleteCookie(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): string;
+//#endregion
+export { CookieOptions, deleteCookie, getCookie, parseCookies, setCookie };