silgi 0.0.13 → 0.1.0-beta.1

package/dist/plugins/cookies.mjs

@@ -0,0 +1,67 @@
+//#region src/plugins/cookies.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. */
+function getCookie(headers, name) {
+	const cookieStr = typeof headers === "string" ? headers : headers.cookie ?? headers.Cookie ?? "";
+	if (!cookieStr) return void 0;
+	const prefix = `${name}=`;
+	const cookies = cookieStr.split(";");
+	for (let i = 0; i < cookies.length; i++) {
+		const c = cookies[i].trim();
+		if (c.startsWith(prefix)) return decodeURIComponent(c.slice(prefix.length));
+	}
+}
+/** Parse all cookies from a headers object or cookie string. */
+function parseCookies(headers) {
+	const cookieStr = typeof headers === "string" ? headers : headers.cookie ?? headers.Cookie ?? "";
+	if (!cookieStr) return {};
+	const result = {};
+	const cookies = cookieStr.split(";");
+	for (let i = 0; i < cookies.length; i++) {
+		const c = cookies[i].trim();
+		const eq = c.indexOf("=");
+		if (eq === -1) continue;
+		const key = c.slice(0, eq);
+		const value = c.slice(eq + 1);
+		result[key] = decodeURIComponent(value);
+	}
+	return result;
+}
+/** Serialize a Set-Cookie header value. */
+function setCookie(name, value, options = {}) {
+	const { path = "/", httpOnly = true, secure, sameSite = "lax", maxAge, expires, domain } = options;
+	let cookie = `${name}=${encodeURIComponent(value)}`;
+	if (path) cookie += `; Path=${path}`;
+	if (domain) cookie += `; Domain=${domain}`;
+	if (maxAge !== void 0) cookie += `; Max-Age=${maxAge}`;
+	if (expires) cookie += `; Expires=${expires.toUTCString()}`;
+	if (httpOnly) cookie += "; HttpOnly";
+	if (secure ?? (sameSite === "none" || typeof globalThis.process !== "undefined" && globalThis.process.env?.NODE_ENV === "production")) cookie += "; Secure";
+	cookie += `; SameSite=${sameSite.charAt(0).toUpperCase() + sameSite.slice(1)}`;
+	return cookie;
+}
+/** Create a Set-Cookie header that deletes a cookie. */
+function deleteCookie(name, options = {}) {
+	return setCookie(name, "", {
+		...options,
+		maxAge: 0
+	});
+}
+//#endregion
+export { deleteCookie, getCookie, parseCookies, setCookie };

package/dist/plugins/cors.d.mts

@@ -0,0 +1,39 @@
+//#region src/plugins/cors.d.ts
+/**
+ * CORS plugin — v2 hook-based.
+ *
+ * Adds CORS headers to every response via lifecycle hooks.
+ * Handles preflight OPTIONS requests automatically.
+ */
+interface CORSOptions {
+  origin?: string | string[] | ((origin: string) => boolean);
+  methods?: string[];
+  allowedHeaders?: string[];
+  exposedHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+}
+/**
+ * Create CORS hooks for silgi().
+ *
+ * @example
+ * ```ts
+ * import { cors } from "silgi/cors"
+ *
+ * const k = silgi({
+ *   context: (req) => ({}),
+ *   hooks: cors({ origin: "https://app.example.com", credentials: true }),
+ * })
+ * ```
+ */
+declare function cors(options?: CORSOptions): {
+  headers: Record<string, string>;
+  options: CORSOptions;
+};
+/**
+ * CORS header map — use in custom serve() or middleware.
+ * Returns headers object to merge into responses.
+ */
+declare function corsHeaders(options?: CORSOptions, requestOrigin?: string): Record<string, string>;
+//#endregion
+export { CORSOptions, cors, corsHeaders };

package/dist/plugins/cors.mjs

@@ -0,0 +1,56 @@
+//#region src/plugins/cors.ts
+/**
+* Create CORS hooks for silgi().
+*
+* @example
+* ```ts
+* import { cors } from "silgi/cors"
+*
+* const k = silgi({
+*   context: (req) => ({}),
+*   hooks: cors({ origin: "https://app.example.com", credentials: true }),
+* })
+* ```
+*/
+function cors(options = {}) {
+	const origin = options.origin ?? "*";
+	if (options.credentials && typeof origin === "string" && origin === "*") throw new Error("[silgi/cors] Cannot use credentials: true with origin: \"*\". Set an explicit origin.");
+	return {
+		headers: corsHeaders(options),
+		options
+	};
+}
+/**
+* CORS header map — use in custom serve() or middleware.
+* Returns headers object to merge into responses.
+*/
+function corsHeaders(options = {}, requestOrigin) {
+	const origin = options.origin ?? "*";
+	const methods = options.methods ?? [
+		"GET",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE",
+		"OPTIONS"
+	];
+	const allowedHeaders = options.allowedHeaders ?? ["Content-Type", "Authorization"];
+	const headers = {
+		"access-control-allow-methods": methods.join(", "),
+		"access-control-allow-headers": allowedHeaders.join(", ")
+	};
+	if (typeof origin === "string") headers["access-control-allow-origin"] = origin;
+	else if (Array.isArray(origin)) {
+		headers["access-control-allow-origin"] = requestOrigin && origin.includes(requestOrigin) ? requestOrigin : "";
+		headers["vary"] = "Origin";
+	} else if (typeof origin === "function" && requestOrigin) {
+		headers["access-control-allow-origin"] = origin(requestOrigin) ? requestOrigin : "";
+		headers["vary"] = "Origin";
+	}
+	if (options.credentials) headers["access-control-allow-credentials"] = "true";
+	if (options.maxAge !== void 0) headers["access-control-max-age"] = String(options.maxAge);
+	if (options.exposedHeaders) headers["access-control-expose-headers"] = options.exposedHeaders.join(", ");
+	return headers;
+}
+//#endregion
+export { cors, corsHeaders };

package/dist/plugins/custom-serializer.d.mts

@@ -0,0 +1,57 @@
+//#region src/plugins/custom-serializer.d.ts
+/**
+ * Custom JSON serializers — extend serialization for custom types.
+ *
+ * Register custom type handlers that run during JSON stringify/parse.
+ * Works with both serve() responses and client deserialization.
+ *
+ * @example
+ * ```ts
+ * import { createSerializer } from "silgi/plugins"
+ *
+ * const serializer = createSerializer()
+ *   .register("Date", {
+ *     test: (v) => v instanceof Date,
+ *     serialize: (v) => v.toISOString(),
+ *     deserialize: (v) => new Date(v),
+ *   })
+ *   .register("BigInt", {
+ *     test: (v) => typeof v === "bigint",
+ *     serialize: (v) => v.toString(),
+ *     deserialize: (v) => BigInt(v),
+ *   })
+ *
+ * // Use as JSON replacer/reviver
+ * JSON.stringify(data, serializer.replacer)
+ * JSON.parse(text, serializer.reviver)
+ * ```
+ */
+interface TypeHandler<T = unknown> {
+  /** Test if a value is this type */
+  test: (value: unknown) => boolean;
+  /** Convert to JSON-safe value */
+  serialize: (value: T) => unknown;
+  /** Convert back from JSON-safe value */
+  deserialize: (value: unknown) => T;
+}
+interface Serializer {
+  /** Register a custom type handler. Returns self for chaining. */
+  register<T>(tag: string, handler: TypeHandler<T>): Serializer;
+  /** JSON.stringify replacer function */
+  replacer: (key: string, value: unknown) => unknown;
+  /** JSON.parse reviver function */
+  reviver: (key: string, value: unknown) => unknown;
+  /** Stringify with custom types */
+  stringify: (value: unknown) => string;
+  /** Parse with custom types */
+  parse: (text: string) => unknown;
+}
+/**
+ * Create a custom serializer with support for non-JSON types.
+ *
+ * Values are wrapped as `{ __$type: "Tag", __$value: serialized }`
+ * during stringify and unwrapped during parse.
+ */
+declare function createSerializer(): Serializer;
+//#endregion
+export { Serializer, TypeHandler, createSerializer };

package/dist/plugins/custom-serializer.mjs

@@ -0,0 +1,40 @@
+//#region src/plugins/custom-serializer.ts
+const TYPE_TAG = "__$type";
+const VALUE_TAG = "__$value";
+/**
+* Create a custom serializer with support for non-JSON types.
+*
+* Values are wrapped as `{ __$type: "Tag", __$value: serialized }`
+* during stringify and unwrapped during parse.
+*/
+function createSerializer() {
+	const handlers = /* @__PURE__ */ new Map();
+	const replacer = (_key, value) => {
+		for (const [tag, handler] of handlers) if (handler.test(value)) return {
+			[TYPE_TAG]: tag,
+			[VALUE_TAG]: handler.serialize(value)
+		};
+		return value;
+	};
+	const reviver = (_key, value) => {
+		if (typeof value === "object" && value !== null && TYPE_TAG in value && VALUE_TAG in value) {
+			const tag = value[TYPE_TAG];
+			const handler = handlers.get(tag);
+			if (handler) return handler.deserialize(value[VALUE_TAG]);
+		}
+		return value;
+	};
+	const serializer = {
+		register(tag, handler) {
+			handlers.set(tag, handler);
+			return serializer;
+		},
+		replacer,
+		reviver,
+		stringify: (value) => JSON.stringify(value, replacer),
+		parse: (text) => JSON.parse(text, reviver)
+	};
+	return serializer;
+}
+//#endregion
+export { createSerializer };

package/dist/plugins/file-upload.d.mts

@@ -0,0 +1,38 @@
+import { GuardDef } from "../types.mjs";
+
+//#region src/plugins/file-upload.d.ts
+interface FileGuardOptions {
+  /** Maximum file size in bytes. Default: 10MB */
+  maxFileSize?: number;
+  /** Allowed MIME types (supports wildcards like "image/*"). Default: all */
+  allowedTypes?: string[];
+  /** Maximum number of files. Default: 1 */
+  maxFiles?: number;
+  /** Form field name for the file. Default: "file" */
+  fieldName?: string;
+}
+interface UploadedFile {
+  name: string;
+  size: number;
+  type: string;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  text(): Promise<string>;
+  stream(): ReadableStream<Uint8Array>;
+}
+/**
+ * Guard that parses multipart file uploads from the request.
+ *
+ * Adds `ctx.file` (single) or `ctx.files` (multiple) to the context.
+ * Validates file size and MIME type before the procedure runs.
+ */
+declare function fileGuard(options?: FileGuardOptions): GuardDef<Record<string, unknown>>;
+/**
+ * Parse multipart form data from a Request.
+ * Returns files and fields separately.
+ */
+declare function parseMultipart(request: Request): Promise<{
+  files: UploadedFile[];
+  fields: Record<string, string>;
+}>;
+//#endregion
+export { FileGuardOptions, UploadedFile, fileGuard, parseMultipart };

package/dist/plugins/file-upload.mjs

@@ -0,0 +1,100 @@
+import { SilgiError } from "../core/error.mjs";
+//#region src/plugins/file-upload.ts
+/**
+* File upload/download — type-safe File/Blob handling.
+*
+* Parse multipart/form-data requests and pass File objects
+* to procedure handlers. Works with serve() and handler().
+*
+* @example
+* ```ts
+* import { fileInput, fileGuard } from "silgi/plugins"
+*
+* const uploadAvatar = k
+*   .$use(fileGuard({ maxFileSize: 5 * 1024 * 1024, allowedTypes: ["image/*"] }))
+*   .$resolve(async ({ ctx }) => {
+*     const file = ctx.file
+*     const buffer = await file.arrayBuffer()
+*     return { name: file.name, size: file.size, type: file.type }
+*   })
+* ```
+*/
+/**
+* Guard that parses multipart file uploads from the request.
+*
+* Adds `ctx.file` (single) or `ctx.files` (multiple) to the context.
+* Validates file size and MIME type before the procedure runs.
+*/
+function fileGuard(options = {}) {
+	const { maxFileSize = 10 * 1024 * 1024, allowedTypes, maxFiles = 1, fieldName: _fieldName = "file" } = options;
+	return {
+		kind: "guard",
+		fn: (ctx) => {
+			const files = ctx.__files;
+			if (!files || files.length === 0) throw new SilgiError("BAD_REQUEST", {
+				status: 400,
+				message: "No file uploaded"
+			});
+			if (files.length > maxFiles) throw new SilgiError("BAD_REQUEST", {
+				status: 400,
+				message: `Too many files: ${files.length} (max ${maxFiles})`
+			});
+			for (const file of files) {
+				if (file.size > maxFileSize) throw new SilgiError("PAYLOAD_TOO_LARGE", {
+					status: 413,
+					message: `File too large: ${file.size} bytes (max ${maxFileSize})`,
+					data: {
+						maxFileSize,
+						actualSize: file.size,
+						fileName: file.name
+					}
+				});
+				if (allowedTypes && !matchesMimeType(file.type, allowedTypes)) throw new SilgiError("BAD_REQUEST", {
+					status: 400,
+					message: `File type not allowed: ${file.type}`,
+					data: {
+						allowedTypes,
+						actualType: file.type,
+						fileName: file.name
+					}
+				});
+			}
+			return maxFiles === 1 ? { file: files[0] } : { files };
+		}
+	};
+}
+/**
+* Parse multipart form data from a Request.
+* Returns files and fields separately.
+*/
+async function parseMultipart(request) {
+	const formData = await request.formData();
+	const files = [];
+	const fields = {};
+	for (const [key, value] of formData.entries()) if (value instanceof File) files.push({
+		name: value.name,
+		size: value.size,
+		type: value.type,
+		arrayBuffer: () => value.arrayBuffer(),
+		text: () => value.text(),
+		stream: () => value.stream()
+	});
+	else fields[key] = value;
+	return {
+		files,
+		fields
+	};
+}
+function matchesMimeType(actual, patterns) {
+	for (const pattern of patterns) {
+		if (pattern === "*" || pattern === "*/*") return true;
+		if (pattern === actual) return true;
+		if (pattern.endsWith("/*")) {
+			const prefix = pattern.slice(0, -2);
+			if (actual.startsWith(prefix + "/")) return true;
+		}
+	}
+	return false;
+}
+//#endregion
+export { fileGuard, parseMultipart };

package/dist/plugins/index.d.mts

@@ -0,0 +1,16 @@
+import { AnalyticsCollector, AnalyticsOptions, AnalyticsSnapshot, ErrorEntry, ProcedureSnapshot, RequestTrace, TraceSpan, analyticsHTML, errorToMarkdown, trace } from "./analytics.mjs";
+import { CookieOptions, deleteCookie, getCookie, parseCookies, setCookie } from "./cookies.mjs";
+import { CORSOptions, cors, corsHeaders } from "./cors.mjs";
+import { Span, Tracer, otelWrap } from "./otel.mjs";
+import { Logger, LoggingOptions, loggingHooks } from "./pino.mjs";
+import { MemoryRateLimiter, MemoryRateLimiterOptions, RateLimitGuardOptions, RateLimitResult, RateLimiter, rateLimitGuard } from "./ratelimit.mjs";
+import { CompressionOptions, compressionWrap } from "./compression.mjs";
+import { BodyLimitOptions, bodyLimitGuard } from "./body-limit.mjs";
+import { strictGetGuard } from "./strict-get.mjs";
+import { decrypt, encrypt, sign, unsign } from "./signing.mjs";
+import { coerceGuard, coerceObject, coerceValue } from "./coerce.mjs";
+import { BatchHandlerOptions, createBatchHandler } from "./batch-server.mjs";
+import { MemoryPubSub, PubSubBackend, Publisher, createPublisher } from "./pubsub.mjs";
+import { Serializer, TypeHandler, createSerializer } from "./custom-serializer.mjs";
+import { FileGuardOptions, UploadedFile, fileGuard, parseMultipart } from "./file-upload.mjs";
+export { AnalyticsCollector, type AnalyticsOptions, type AnalyticsSnapshot, type BatchHandlerOptions, type BodyLimitOptions, type CORSOptions, type CompressionOptions, type CookieOptions, type ErrorEntry, type FileGuardOptions, type Logger, type LoggingOptions, MemoryPubSub, MemoryRateLimiter, type MemoryRateLimiterOptions, type ProcedureSnapshot, type PubSubBackend, type Publisher, type RateLimitGuardOptions, type RateLimitResult, type RateLimiter, RequestTrace, type Serializer, type Span, type TraceSpan, type Tracer, type TypeHandler, type UploadedFile, analyticsHTML, bodyLimitGuard, coerceGuard, coerceObject, coerceValue, compressionWrap, cors, corsHeaders, createBatchHandler, createPublisher, createSerializer, decrypt, deleteCookie, encrypt, errorToMarkdown, fileGuard, getCookie, loggingHooks, otelWrap, parseCookies, parseMultipart, rateLimitGuard, setCookie, sign, strictGetGuard, trace, unsign };

package/dist/plugins/index.mjs

@@ -0,0 +1,16 @@
+import { AnalyticsCollector, RequestTrace, analyticsHTML, errorToMarkdown, trace } from "./analytics.mjs";
+import { cors, corsHeaders } from "./cors.mjs";
+import { otelWrap } from "./otel.mjs";
+import { loggingHooks } from "./pino.mjs";
+import { MemoryRateLimiter, rateLimitGuard } from "./ratelimit.mjs";
+import { compressionWrap } from "./compression.mjs";
+import { bodyLimitGuard } from "./body-limit.mjs";
+import { strictGetGuard } from "./strict-get.mjs";
+import { deleteCookie, getCookie, parseCookies, setCookie } from "./cookies.mjs";
+import { decrypt, encrypt, sign, unsign } from "./signing.mjs";
+import { coerceGuard, coerceObject, coerceValue } from "./coerce.mjs";
+import { createBatchHandler } from "./batch-server.mjs";
+import { MemoryPubSub, createPublisher } from "./pubsub.mjs";
+import { createSerializer } from "./custom-serializer.mjs";
+import { fileGuard, parseMultipart } from "./file-upload.mjs";
+export { AnalyticsCollector, MemoryPubSub, MemoryRateLimiter, RequestTrace, analyticsHTML, bodyLimitGuard, coerceGuard, coerceObject, coerceValue, compressionWrap, cors, corsHeaders, createBatchHandler, createPublisher, createSerializer, decrypt, deleteCookie, encrypt, errorToMarkdown, fileGuard, getCookie, loggingHooks, otelWrap, parseCookies, parseMultipart, rateLimitGuard, setCookie, sign, strictGetGuard, trace, unsign };

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