silgi 0.43.28 → 0.50.0

package/dist/plugins/otel.d.mts

@@ -0,0 +1,35 @@
+import { WrapDef } from "../types.mjs";
+
+//#region src/plugins/otel.d.ts
+interface Span {
+  setAttribute(key: string, value: string | number | boolean): void;
+  setStatus(status: {
+    code: number;
+    message?: string;
+  }): void;
+  addEvent(name: string, attributes?: Record<string, unknown>): void;
+  end(): void;
+}
+interface Tracer {
+  startSpan(name: string, options?: {
+    attributes?: Record<string, string | number | boolean>;
+  }): Span;
+}
+/**
+ * Create an OTel tracing wrap middleware.
+ *
+ * @example
+ * ```ts
+ * import { otelWrap } from "silgi/otel"
+ * import { trace } from "@opentelemetry/api"
+ *
+ * const tracing = otelWrap(trace.getTracer("my-service"))
+ *
+ * const proc = k
+ *   .$use(tracing)
+ *   .$resolve(({ ctx }) => ctx.db.find())
+ * ```
+ */
+declare function otelWrap(tracer: Tracer, spanName?: string): WrapDef;
+//#endregion
+export { Span, Tracer, otelWrap };

package/dist/plugins/otel.mjs

@@ -0,0 +1,40 @@
+//#region src/plugins/otel.ts
+/**
+* Create an OTel tracing wrap middleware.
+*
+* @example
+* ```ts
+* import { otelWrap } from "silgi/otel"
+* import { trace } from "@opentelemetry/api"
+*
+* const tracing = otelWrap(trace.getTracer("my-service"))
+*
+* const proc = k
+*   .$use(tracing)
+*   .$resolve(({ ctx }) => ctx.db.find())
+* ```
+*/
+function otelWrap(tracer, spanName = "rpc.call") {
+	return {
+		kind: "wrap",
+		fn: async (_ctx, next) => {
+			const span = tracer.startSpan(spanName, { attributes: { "rpc.system": "silgi" } });
+			try {
+				const result = await next();
+				span.setStatus({ code: 0 });
+				return result;
+			} catch (error) {
+				span.setStatus({
+					code: 2,
+					message: String(error)
+				});
+				span.addEvent("exception", { "exception.message": error instanceof Error ? error.message : String(error) });
+				throw error;
+			} finally {
+				span.end();
+			}
+		}
+	};
+}
+//#endregion
+export { otelWrap };

package/dist/plugins/pino.d.mts

@@ -0,0 +1,60 @@
+//#region src/plugins/pino.d.ts
+/**
+ * Pino logging plugin — v2 hook-based.
+ *
+ * Logs request lifecycle events via silgi hooks.
+ */
+interface Logger {
+  child(bindings: Record<string, unknown>): Logger;
+  info(obj: Record<string, unknown>, msg?: string): void;
+  error(obj: Record<string, unknown>, msg?: string): void;
+  warn(obj: Record<string, unknown>, msg?: string): void;
+  debug(obj: Record<string, unknown>, msg?: string): void;
+}
+interface LoggingOptions {
+  /** The root logger instance */
+  logger: Logger;
+  /** Log request received events (default: true) */
+  logRequests?: boolean;
+  /** Log response events (default: true) */
+  logResponses?: boolean;
+}
+/**
+ * Create logging hooks for silgi().
+ *
+ * @example
+ * ```ts
+ * import pino from "pino"
+ * import { loggingHooks } from "silgi/pino"
+ *
+ * const k = silgi({
+ *   context: (req) => ({}),
+ *   hooks: loggingHooks({ logger: pino() }),
+ * })
+ * ```
+ */
+declare function loggingHooks(options: LoggingOptions): {
+  error: ({
+    path,
+    error
+  }: {
+    path: string;
+    error: unknown;
+  }) => void;
+  response?: (({
+    path,
+    durationMs
+  }: {
+    path: string;
+    durationMs: number;
+  }) => void) | undefined;
+  request?: (({
+    path,
+    input
+  }: {
+    path: string;
+    input: unknown;
+  }) => void) | undefined;
+};
+//#endregion
+export { Logger, LoggingOptions, loggingHooks };

package/dist/plugins/pino.mjs

@@ -0,0 +1,42 @@
+//#region src/plugins/pino.ts
+/**
+* Create logging hooks for silgi().
+*
+* @example
+* ```ts
+* import pino from "pino"
+* import { loggingHooks } from "silgi/pino"
+*
+* const k = silgi({
+*   context: (req) => ({}),
+*   hooks: loggingHooks({ logger: pino() }),
+* })
+* ```
+*/
+function loggingHooks(options) {
+	const { logger } = options;
+	const logRequests = options.logRequests ?? true;
+	const logResponses = options.logResponses ?? true;
+	return {
+		...logRequests && { request: ({ path, input }) => {
+			logger.info({
+				path,
+				hasInput: input !== void 0
+			}, "request received");
+		} },
+		...logResponses && { response: ({ path, durationMs }) => {
+			logger.info({
+				path,
+				durationMs: Math.round(durationMs * 100) / 100
+			}, "response sent");
+		} },
+		error: ({ path, error }) => {
+			logger.error({
+				path,
+				error: error instanceof Error ? error.message : String(error)
+			}, "request error");
+		}
+	};
+}
+//#endregion
+export { loggingHooks };

package/dist/plugins/pubsub.d.mts

@@ -0,0 +1,50 @@
+//#region src/plugins/pubsub.d.ts
+/**
+ * Publisher/PubSub — event pub/sub with pluggable backends.
+ *
+ * Publish events from any procedure, subscribe from SSE/WebSocket.
+ * Built-in memory adapter. Redis/Upstash adapters plug in via interface.
+ *
+ * @example
+ * ```ts
+ * import { createPublisher, MemoryPubSub } from "silgi/plugins"
+ *
+ * const pubsub = createPublisher(new MemoryPubSub())
+ *
+ * // Publish from a mutation
+ * const createUser = k.$resolve(async ({ input, ctx }) => {
+ *   const user = await ctx.db.users.create(input)
+ *   await pubsub.publish("user:created", user)
+ *   return user
+ * })
+ *
+ * // Subscribe via SSE
+ * const onUserCreated = k.subscription(async function* () {
+ *   yield* pubsub.subscribe("user:created")
+ * })
+ * ```
+ */
+interface PubSubBackend {
+  publish(channel: string, data: unknown): Promise<void>;
+  subscribe(channel: string, callback: (data: unknown) => void): () => void;
+}
+declare class MemoryPubSub implements PubSubBackend {
+  #private;
+  publish(channel: string, data: unknown): Promise<void>;
+  subscribe(channel: string, callback: (data: unknown) => void): () => void;
+}
+interface Publisher {
+  /** Publish an event to a channel */
+  publish(channel: string, data: unknown): Promise<void>;
+  /** Subscribe to a channel — returns an async iterable for use in subscriptions */
+  subscribe<T = unknown>(channel: string): AsyncGenerator<T, void, unknown>;
+}
+/**
+ * Create a publisher from a PubSub backend.
+ *
+ * The publisher exposes `publish()` for mutations and `subscribe()`
+ * as an async generator for SSE/WebSocket subscriptions.
+ */
+declare function createPublisher(backend: PubSubBackend): Publisher;
+//#endregion
+export { MemoryPubSub, PubSubBackend, Publisher, createPublisher };

package/dist/plugins/pubsub.mjs

@@ -0,0 +1,53 @@
+//#region src/plugins/pubsub.ts
+var MemoryPubSub = class {
+	#listeners = /* @__PURE__ */ new Map();
+	async publish(channel, data) {
+		const listeners = this.#listeners.get(channel);
+		if (!listeners) return;
+		for (const cb of listeners) cb(data);
+	}
+	subscribe(channel, callback) {
+		let set = this.#listeners.get(channel);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.#listeners.set(channel, set);
+		}
+		set.add(callback);
+		return () => {
+			set.delete(callback);
+			if (set.size === 0) this.#listeners.delete(channel);
+		};
+	}
+};
+/**
+* Create a publisher from a PubSub backend.
+*
+* The publisher exposes `publish()` for mutations and `subscribe()`
+* as an async generator for SSE/WebSocket subscriptions.
+*/
+function createPublisher(backend) {
+	return {
+		publish: (channel, data) => backend.publish(channel, data),
+		async *subscribe(channel) {
+			const queue = [];
+			let resolve = null;
+			const unsubscribe = backend.subscribe(channel, (data) => {
+				queue.push(data);
+				if (resolve) {
+					resolve();
+					resolve = null;
+				}
+			});
+			try {
+				while (true) if (queue.length > 0) yield queue.shift();
+				else await new Promise((r) => {
+					resolve = r;
+				});
+			} finally {
+				unsubscribe();
+			}
+		}
+	};
+}
+//#endregion
+export { MemoryPubSub, createPublisher };

package/dist/plugins/ratelimit.d.mts

@@ -0,0 +1,53 @@
+import { GuardDef } from "../types.mjs";
+
+//#region src/plugins/ratelimit.d.ts
+interface RateLimitResult {
+  success: boolean;
+  limit: number;
+  remaining: number;
+  reset: number;
+}
+interface RateLimiter {
+  limit(key: string): Promise<RateLimitResult>;
+}
+interface MemoryRateLimiterOptions {
+  /** Maximum requests per window */
+  limit: number;
+  /** Window duration in milliseconds */
+  windowMs: number;
+}
+declare class MemoryRateLimiter implements RateLimiter {
+  #private;
+  constructor(options: MemoryRateLimiterOptions);
+  limit(key: string): Promise<RateLimitResult>;
+  /** Remove entries with no active timestamps to prevent unbounded Map growth */
+  evict(): void;
+}
+interface RateLimitGuardOptions {
+  /** The rate limiter instance */
+  limiter: RateLimiter;
+  /** Extract rate limit key from context */
+  keyFn: (ctx: Record<string, unknown>) => string | Promise<string>;
+  /** Custom error message */
+  message?: string;
+}
+/**
+ * Create a rate limiting guard.
+ *
+ * @example
+ * ```ts
+ * import { rateLimitGuard, MemoryRateLimiter } from "silgi/ratelimit"
+ *
+ * const rateLimit = rateLimitGuard({
+ *   limiter: new MemoryRateLimiter({ limit: 100, windowMs: 60_000 }),
+ *   keyFn: (ctx) => (ctx as any).ip ?? "anonymous",
+ * })
+ *
+ * const proc = k
+ *   .$use(rateLimit)
+ *   .$resolve(() => ({ ok: true }))
+ * ```
+ */
+declare function rateLimitGuard(options: RateLimitGuardOptions): GuardDef<any, any>;
+//#endregion
+export { MemoryRateLimiter, MemoryRateLimiterOptions, RateLimitGuardOptions, RateLimitResult, RateLimiter, rateLimitGuard };

package/dist/plugins/ratelimit.mjs

@@ -0,0 +1,92 @@
+import { SilgiError } from "../core/error.mjs";
+//#region src/plugins/ratelimit.ts
+/**
+* Rate limiting plugin — v2 guard middleware.
+*
+* Sliding window in-memory rate limiter.
+* Pluggable: swap MemoryRateLimiter for Redis/Upstash/etc.
+*/
+var MemoryRateLimiter = class {
+	#limit;
+	#windowMs;
+	#store = /* @__PURE__ */ new Map();
+	#evictTimer;
+	constructor(options) {
+		this.#limit = options.limit;
+		this.#windowMs = options.windowMs;
+		this.#evictTimer = setInterval(() => this.evict(), this.#windowMs * 2);
+		if (typeof this.#evictTimer === "object" && "unref" in this.#evictTimer) this.#evictTimer.unref();
+	}
+	async limit(key) {
+		const now = Date.now();
+		const windowStart = now - this.#windowMs;
+		let timestamps = this.#store.get(key);
+		if (!timestamps) {
+			timestamps = [];
+			this.#store.set(key, timestamps);
+		}
+		while (timestamps.length > 0 && timestamps[0] < windowStart) timestamps.shift();
+		const remaining = Math.max(0, this.#limit - timestamps.length);
+		const reset = timestamps.length > 0 ? timestamps[0] + this.#windowMs : now + this.#windowMs;
+		if (timestamps.length >= this.#limit) return {
+			success: false,
+			limit: this.#limit,
+			remaining: 0,
+			reset
+		};
+		timestamps.push(now);
+		return {
+			success: true,
+			limit: this.#limit,
+			remaining: remaining - 1,
+			reset
+		};
+	}
+	/** Remove entries with no active timestamps to prevent unbounded Map growth */
+	evict() {
+		const now = Date.now();
+		for (const [key, timestamps] of this.#store) {
+			while (timestamps.length > 0 && timestamps[0] < now - this.#windowMs) timestamps.shift();
+			if (timestamps.length === 0) this.#store.delete(key);
+		}
+	}
+};
+/**
+* Create a rate limiting guard.
+*
+* @example
+* ```ts
+* import { rateLimitGuard, MemoryRateLimiter } from "silgi/ratelimit"
+*
+* const rateLimit = rateLimitGuard({
+*   limiter: new MemoryRateLimiter({ limit: 100, windowMs: 60_000 }),
+*   keyFn: (ctx) => (ctx as any).ip ?? "anonymous",
+* })
+*
+* const proc = k
+*   .$use(rateLimit)
+*   .$resolve(() => ({ ok: true }))
+* ```
+*/
+function rateLimitGuard(options) {
+	return {
+		kind: "guard",
+		fn: async (ctx) => {
+			const key = await options.keyFn(ctx);
+			const result = await options.limiter.limit(key);
+			if (!result.success) throw new SilgiError("TOO_MANY_REQUESTS", {
+				status: 429,
+				message: options.message ?? "Rate limit exceeded",
+				data: {
+					limit: result.limit,
+					remaining: result.remaining,
+					reset: result.reset,
+					retryAfter: Math.ceil((result.reset - Date.now()) / 1e3)
+				}
+			});
+			return { rateLimit: result };
+		}
+	};
+}
+//#endregion
+export { MemoryRateLimiter, rateLimitGuard };

package/dist/plugins/signing.d.mts

@@ -0,0 +1,41 @@
+//#region src/plugins/signing.d.ts
+/**
+ * Signing & Encryption utilities — HMAC-SHA256 and AES-GCM.
+ *
+ * Uses the Web Crypto API (works in Node.js, Bun, Deno, Cloudflare Workers).
+ *
+ * @example
+ * ```ts
+ * import { sign, unsign, encrypt, decrypt } from "silgi/plugins"
+ *
+ * // Sign a value (tamper-proof)
+ * const signed = await sign("user:123", "my-secret")
+ * const value = await unsign(signed, "my-secret") // "user:123" or null
+ *
+ * // Encrypt a value (confidential)
+ * const encrypted = await encrypt("sensitive-data", "my-secret")
+ * const decrypted = await decrypt(encrypted, "my-secret") // "sensitive-data"
+ * ```
+ */
+/**
+ * Sign a string value with HMAC-SHA256.
+ * Returns `value.signature` — use `unsign()` to verify.
+ */
+declare function sign(value: string, secret: string): Promise<string>;
+/**
+ * Verify and extract a signed value.
+ * Returns the original value if valid, or `null` if tampered.
+ */
+declare function unsign(signed: string, secret: string): Promise<string | null>;
+/**
+ * Encrypt a string with AES-256-GCM (PBKDF2 key derivation).
+ * Returns a base64url-encoded string containing salt + iv + ciphertext.
+ */
+declare function encrypt(plaintext: string, secret: string): Promise<string>;
+/**
+ * Decrypt a string encrypted with `encrypt()`.
+ * Returns the original plaintext, or throws if the secret is wrong.
+ */
+declare function decrypt(encrypted: string, secret: string): Promise<string>;
+//#endregion
+export { decrypt, encrypt, sign, unsign };

package/dist/plugins/signing.mjs

@@ -0,0 +1,118 @@
+//#region src/plugins/signing.ts
+/**
+* Signing & Encryption utilities — HMAC-SHA256 and AES-GCM.
+*
+* Uses the Web Crypto API (works in Node.js, Bun, Deno, Cloudflare Workers).
+*
+* @example
+* ```ts
+* import { sign, unsign, encrypt, decrypt } from "silgi/plugins"
+*
+* // Sign a value (tamper-proof)
+* const signed = await sign("user:123", "my-secret")
+* const value = await unsign(signed, "my-secret") // "user:123" or null
+*
+* // Encrypt a value (confidential)
+* const encrypted = await encrypt("sensitive-data", "my-secret")
+* const decrypted = await decrypt(encrypted, "my-secret") // "sensitive-data"
+* ```
+*/
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+async function getSigningKey(secret) {
+	return crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign", "verify"]);
+}
+function toHex(buffer) {
+	return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function fromHex(hex) {
+	if (hex.length % 2 !== 0 || hex.length === 0) return null;
+	if (!/^[0-9a-f]+$/i.test(hex)) return null;
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < hex.length; i += 2) bytes[i / 2] = Number.parseInt(hex.slice(i, i + 2), 16);
+	return bytes;
+}
+/**
+* Sign a string value with HMAC-SHA256.
+* Returns `value.signature` — use `unsign()` to verify.
+*/
+async function sign(value, secret) {
+	const key = await getSigningKey(secret);
+	return `${value}.${toHex(await crypto.subtle.sign("HMAC", key, encoder.encode(value)))}`;
+}
+/**
+* Verify and extract a signed value.
+* Returns the original value if valid, or `null` if tampered.
+*/
+async function unsign(signed, secret) {
+	const dotIdx = signed.lastIndexOf(".");
+	if (dotIdx === -1) return null;
+	const value = signed.slice(0, dotIdx);
+	const expected = fromHex(signed.slice(dotIdx + 1));
+	if (!expected) return null;
+	const key = await getSigningKey(secret);
+	return await crypto.subtle.verify("HMAC", key, expected.buffer, encoder.encode(value)) ? value : null;
+}
+async function getEncryptionKey(secret, salt) {
+	const keyMaterial = await crypto.subtle.importKey("raw", encoder.encode(secret), "PBKDF2", false, ["deriveKey"]);
+	return crypto.subtle.deriveKey({
+		name: "PBKDF2",
+		salt: salt.buffer,
+		iterations: 1e5,
+		hash: "SHA-256"
+	}, keyMaterial, {
+		name: "AES-GCM",
+		length: 256
+	}, false, ["encrypt", "decrypt"]);
+}
+/**
+* Encrypt a string with AES-256-GCM (PBKDF2 key derivation).
+* Returns a base64url-encoded string containing salt + iv + ciphertext.
+*/
+async function encrypt(plaintext, secret) {
+	const salt = crypto.getRandomValues(new Uint8Array(16));
+	const iv = crypto.getRandomValues(new Uint8Array(12));
+	const key = await getEncryptionKey(secret, salt);
+	const ciphertext = await crypto.subtle.encrypt({
+		name: "AES-GCM",
+		iv
+	}, key, encoder.encode(plaintext));
+	const combined = new Uint8Array(salt.length + iv.length + ciphertext.byteLength);
+	combined.set(salt, 0);
+	combined.set(iv, salt.length);
+	combined.set(new Uint8Array(ciphertext), salt.length + iv.length);
+	return base64urlEncode(combined);
+}
+/**
+* Decrypt a string encrypted with `encrypt()`.
+* Returns the original plaintext, or throws if the secret is wrong.
+*/
+async function decrypt(encrypted, secret) {
+	const combined = base64urlDecode(encrypted);
+	const salt = combined.slice(0, 16);
+	const iv = combined.slice(16, 28);
+	const ciphertext = combined.slice(28);
+	const key = await getEncryptionKey(secret, salt);
+	const plaintext = await crypto.subtle.decrypt({
+		name: "AES-GCM",
+		iv
+	}, key, ciphertext);
+	return decoder.decode(plaintext);
+}
+function base64urlEncode(data) {
+	let binary = "";
+	const chunkSize = 8192;
+	for (let i = 0; i < data.length; i += chunkSize) binary += String.fromCharCode(...data.subarray(i, i + chunkSize));
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlDecode(str) {
+	const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+	const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+	const binary = atob(padded);
+	return Uint8Array.from(binary, (c) => c.charCodeAt(0));
+}
+//#endregion
+export { decrypt, encrypt, sign, unsign };

package/dist/plugins/strict-get.d.mts

@@ -0,0 +1,10 @@
+import { GuardDef } from "../types.mjs";
+
+//#region src/plugins/strict-get.d.ts
+/**
+ * Guard that rejects non-GET requests. Use on query procedures
+ * to enforce RESTful method semantics and prevent CSRF.
+ */
+declare const strictGetGuard: GuardDef<Record<string, unknown>>;
+//#endregion
+export { strictGetGuard };

package/dist/plugins/strict-get.mjs

@@ -0,0 +1,33 @@
+import { SilgiError } from "../core/error.mjs";
+//#region src/plugins/strict-get.ts
+/**
+* Strict GET method guard — enforce GET for query procedures.
+*
+* Rejects non-GET requests to query procedures with 405 Method Not Allowed.
+* Mutations must use POST. This prevents CSRF on read endpoints.
+*
+* @example
+* ```ts
+* import { strictGetGuard } from "silgi/plugins"
+*
+* const listUsers = k
+*   .$use(strictGetGuard)
+*   .$resolve(({ ctx }) => ctx.db.users.findMany())
+* ```
+*/
+/**
+* Guard that rejects non-GET requests. Use on query procedures
+* to enforce RESTful method semantics and prevent CSRF.
+*/
+const strictGetGuard = {
+	kind: "guard",
+	fn: (ctx) => {
+		const method = ctx.method;
+		if (method && method !== "GET" && method !== "HEAD") throw new SilgiError("METHOD_NOT_ALLOWED", {
+			status: 405,
+			message: `Expected GET, received ${method}`
+		});
+	}
+};
+//#endregion
+export { strictGetGuard };

package/dist/scalar.d.mts

@@ -0,0 +1,49 @@
+import { RouterDef } from "./types.mjs";
+//#region src/scalar.d.ts
+interface ScalarOptions {
+  title?: string;
+  version?: string;
+  description?: string;
+  servers?: {
+    url: string;
+    description?: string;
+  }[];
+  /** Security scheme (e.g. Bearer token) */
+  security?: {
+    type: 'http' | 'apiKey';
+    scheme?: string;
+    bearerFormat?: string;
+    in?: 'header' | 'query';
+    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.
+   *
+   * - `'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' | 'unpkg' | 'local' | (string & {});
+}
+declare function generateOpenAPI(router: RouterDef, options?: ScalarOptions): Record<string, unknown>;
+declare function scalarHTML(specUrl: string, options?: ScalarOptions): string;
+//#endregion
+export { ScalarOptions, generateOpenAPI, scalarHTML };