@igoforth/ws-rpc 1.0.0

package/src/schema.ts

@@ -0,0 +1,167 @@
+/**
+ * Schema Definition Utilities
+ *
+ * Provides helpers to define RPC methods and events with Zod schemas,
+ * enabling TypeScript type inference for the entire RPC contract.
+ */
+
+import type { LiteralUnion } from "type-fest";
+import type * as z from "zod";
+
+export type StringKeys<T> = keyof T extends string ? keyof T : never;
+export type LiteralString = "" | (string & Record<never, never>);
+export type LiteralStringUnion<T> = LiteralUnion<T, string>;
+
+/**
+ * Method definition with input and output schemas
+ */
+export interface MethodDef<
+	TInput extends z.ZodType = z.ZodType,
+	TOutput extends z.ZodType = z.ZodType,
+> {
+	_type: "method";
+	input: TInput;
+	output: TOutput;
+}
+
+/**
+ * Event definition with data schema
+ */
+export interface EventDef<TData extends z.ZodType = z.ZodType> {
+	_type: "event";
+	data: TData;
+}
+
+/**
+ * Define an RPC method with input/output schemas
+ *
+ * @param def - Object containing input and output Zod schemas
+ * @returns MethodDef with preserved type information
+ *
+ * @example
+ * ```ts
+ * const getUser = method({
+ *   input: z.object({ id: z.string() }),
+ *   output: z.object({ name: z.string(), email: z.string() }),
+ * });
+ * ```
+ */
+export function method<
+	TInput extends z.ZodType,
+	TOutput extends z.ZodType,
+>(def: { input: TInput; output: TOutput }): MethodDef<TInput, TOutput> {
+	return { _type: "method", ...def };
+}
+
+/**
+ * Define a fire-and-forget event with data schema
+ *
+ * @param def - Object containing data Zod schema
+ * @returns EventDef with preserved type information
+ *
+ * @example
+ * ```ts
+ * const userCreated = event({
+ *   data: z.object({ id: z.string(), name: z.string() }),
+ * });
+ * ```
+ */
+export function event<TData extends z.ZodType>(def: {
+	data: TData;
+}): EventDef<TData> {
+	return { _type: "event", ...def };
+}
+
+/**
+ * Schema definition containing methods and events
+ */
+export interface RpcSchema {
+	methods?: Record<string, MethodDef>;
+	events?: Record<string, EventDef>;
+}
+
+/**
+ * Infer the input type from a method definition
+ *
+ * @typeParam T - A MethodDef type to extract the input from
+ */
+export type InferInput<T> =
+	T extends MethodDef<infer TInput, z.ZodType> ? z.infer<TInput> : never;
+
+/**
+ * Infer the output type from a method definition
+ *
+ * @typeParam T - A MethodDef type to extract the output from
+ */
+export type InferOutput<T> =
+	T extends MethodDef<z.ZodType, infer TOutput> ? z.infer<TOutput> : never;
+
+/**
+ * Infer the data type from an event definition
+ *
+ * @typeParam T - An EventDef type to extract the data type from
+ */
+export type InferEventData<T> =
+	T extends EventDef<infer TData> ? z.infer<TData> : never;
+
+/**
+ * Infer method signatures from a schema's methods
+ */
+export type InferMethods<T extends RpcSchema> =
+	T["methods"] extends Record<string, MethodDef>
+		? {
+				[K in StringKeys<T["methods"]>]: (
+					input: InferInput<T["methods"][K]>,
+				) => Promise<InferOutput<T["methods"][K]>>;
+			}
+		: object;
+
+/**
+ * Infer event emitter signatures from a schema's events
+ */
+export type InferEvents<T extends RpcSchema> =
+	T["events"] extends Record<string, EventDef>
+		? {
+				[K in StringKeys<T["events"]>]: InferEventData<T["events"][K]>;
+			}
+		: object;
+
+/**
+ * Provider type - implements the local methods defined in a schema
+ */
+export type Provider<T extends RpcSchema> = InferMethods<T>;
+
+/**
+ * Driver type - proxy to call remote methods defined in a schema
+ */
+export type Driver<T extends RpcSchema> = InferMethods<T>;
+
+/**
+ * Event handler type - handles incoming events
+ */
+export type EventHandler<T extends RpcSchema, ExtraArgs extends any[] = []> = <
+	K extends StringKeys<T["events"]>,
+>(
+	...args: [
+		...ExtraArgs,
+		event: K,
+		data: T["events"] extends Record<string, EventDef>
+			? InferEventData<T["events"][K]>
+			: never,
+	]
+) => void;
+
+/**
+ * Event emitter type - emits outgoing events
+ */
+export type EventEmitter<T extends RpcSchema, ExtraArgs extends any[] = []> = <
+	K extends StringKeys<T["events"]>,
+>(
+	...args: [
+		event: K,
+		data: T["events"] extends Record<string, EventDef>
+			? InferEventData<T["events"][K]>
+			: never,
+		...ExtraArgs,
+	]
+) => void;

package/src/storage/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Storage Module Exports
+ */
+
+export {
+	type AsyncPendingCallStorage,
+	type MaybePromise,
+	type PendingCall,
+	type PendingCallStorage,
+	type StorageMode,
+	type SyncPendingCallStorage,
+} from "./interface.js";
+export {
+	MemoryPendingCallStorage,
+	type MemoryPendingCallStorageOptions,
+} from "./memory.js";
+export {
+	SqlPendingCallStorage,
+	type SqlPendingCallStorageOptions,
+} from "./sql.js";

package/src/storage/interface.ts

@@ -0,0 +1,146 @@
+/**
+ * Pending Call Storage Interface
+ *
+ * Abstraction for persisting RPC calls that need to survive hibernation.
+ * Supports both sync (DO SQL/KV) and async (file, external KV) backends.
+ */
+
+import type { RpcSchema } from "../schema";
+
+/**
+ * A pending RPC call awaiting a response
+ */
+export interface PendingCall {
+	/** Unique request ID */
+	id: string;
+	/** Remote method name */
+	method: string;
+	/** Serialized parameters */
+	params: unknown;
+	/** Method name on actor to call with response */
+	callback: string;
+	/** When the call was sent (Unix ms) */
+	sentAt: number;
+	/** When the call should timeout (Unix ms) */
+	timeoutAt: number;
+}
+
+/**
+ * Storage mode discriminant
+ */
+export type StorageMode = "sync" | "async";
+
+/**
+ * Conditional return type based on storage mode
+ */
+export type MaybePromise<T, TMode extends StorageMode> = TMode extends "sync"
+	? T
+	: Promise<T>;
+
+/**
+ * Pending call storage interface
+ *
+ * Generic over sync/async mode to preserve type information about
+ * whether operations block or return promises.
+ *
+ * @typeParam TMode - 'sync' for synchronous storage (DO SQL/KV), 'async' for file/external
+ */
+export interface PendingCallStorage<TMode extends StorageMode = "async"> {
+	/** Storage mode discriminant for runtime checks */
+	readonly mode: TMode;
+
+	/**
+	 * Save a pending call
+	 */
+	save(call: PendingCall): MaybePromise<void, TMode>;
+
+	/**
+	 * Get a pending call by ID
+	 */
+	get(id: string): MaybePromise<PendingCall | null, TMode>;
+
+	/**
+	 * Delete a pending call by ID
+	 */
+	delete(id: string): MaybePromise<boolean, TMode>;
+
+	/**
+	 * List all calls that have exceeded their timeout
+	 */
+	listExpired(before: number): MaybePromise<PendingCall[], TMode>;
+
+	/**
+	 * List all pending calls (for debugging/recovery)
+	 */
+	listAll(): MaybePromise<PendingCall[], TMode>;
+
+	/**
+	 * Delete all pending calls (for cleanup)
+	 */
+	clear(): MaybePromise<void, TMode>;
+}
+
+/**
+ * Convenience alias for synchronous storage (DO SQL/KV)
+ */
+export type SyncPendingCallStorage = PendingCallStorage<"sync">;
+
+/**
+ * Convenience alias for asynchronous storage (file, external KV)
+ */
+export type AsyncPendingCallStorage = PendingCallStorage<"async">;
+
+export interface IContinuationHandler<TRemoteSchema extends RpcSchema> {
+	/**
+	 * Make a hibernation-safe RPC call using continuation-passing style
+	 *
+	 * Instead of returning a Promise, the result will be passed to the
+	 * named callback method on the actor. This survives DO hibernation.
+	 *
+	 * @param method - Remote method to call
+	 * @param params - Parameters for the method
+	 * @param callback - Name of method on actor to call with result
+	 * @param timeout - Optional timeout override (ms)
+	 *
+	 * @example
+	 * ```ts
+	 * // Make the call
+	 * peer.callWithCallback('executeOrder', { market, side }, 'onOrderExecuted');
+	 *
+	 * // Define the callback on your actor
+	 * onOrderExecuted(result: OrderResult, context: CallContext) {
+	 *   console.log('Order executed:', result);
+	 *   console.log('Latency:', context.latencyMs, 'ms');
+	 * }
+	 * ```
+	 */
+	callWithCallback<K extends keyof TRemoteSchema["methods"] & string>(
+		method: K,
+		params: unknown,
+		callback: keyof this & string,
+		timeout?: number,
+	): void;
+
+	/**
+	 * Get all pending durable calls (for debugging/monitoring)
+	 */
+	getPendingCalls(): PendingCall[];
+
+	/**
+	 * Get expired calls that have exceeded their timeout
+	 */
+	getExpiredCalls(): PendingCall[];
+
+	/**
+	 * Clean up expired calls
+	 *
+	 * Call this periodically (e.g., on alarm) to remove stale calls.
+	 * Returns the expired calls for optional error handling.
+	 */
+	cleanupExpired(): PendingCall[];
+
+	/**
+	 * Clear all pending durable calls
+	 */
+	clearPendingCalls(): void;
+}

package/src/storage/memory.ts

@@ -0,0 +1,84 @@
+/**
+ * Memory Pending Call Storage
+ *
+ * In-memory storage implementation for testing purposes.
+ * Synchronous mode for compatibility with DurableRpcPeer tests.
+ */
+
+import { type StringCodec } from "../codecs/index.js";
+import type { PendingCall, SyncPendingCallStorage } from "./interface.js";
+
+/**
+ * Options for memory pending call storage
+ */
+export interface MemoryPendingCallStorageOptions {
+	/**
+	 * Codec for serializing/deserializing params
+	 *
+	 * While memory storage doesn't strictly need serialization,
+	 * using a codec ensures consistency with SQL storage and
+	 * validates that params can be round-tripped.
+	 */
+	paramsCodec?: StringCodec;
+}
+
+/**
+ * In-memory pending call storage for testing
+ *
+ * Optionally round-trips params through a codec for consistency testing.
+ */
+export class MemoryPendingCallStorage implements SyncPendingCallStorage {
+	readonly mode = "sync" as const;
+	private readonly calls = new Map<string, PendingCall>();
+	private readonly paramsCodec: StringCodec | null;
+
+	constructor(options?: MemoryPendingCallStorageOptions) {
+		// Only use codec if explicitly provided (for testing codec behavior)
+		this.paramsCodec = options?.paramsCodec ?? null;
+	}
+
+	save(call: PendingCall): void {
+		// Optionally round-trip params through codec
+		const params = this.paramsCodec
+			? this.paramsCodec.decode(this.paramsCodec.encode(call.params))
+			: call.params;
+
+		this.calls.set(call.id, { ...call, params });
+	}
+
+	get(id: string): PendingCall | null {
+		const call = this.calls.get(id);
+		return call ? { ...call } : null;
+	}
+
+	delete(id: string): boolean {
+		return this.calls.delete(id);
+	}
+
+	listExpired(before: number): PendingCall[] {
+		const expired: PendingCall[] = [];
+		for (const call of this.calls.values()) {
+			if (call.timeoutAt <= before) {
+				expired.push({ ...call });
+			}
+		}
+		return expired.sort((a, b) => a.timeoutAt - b.timeoutAt);
+	}
+
+	listAll(): PendingCall[] {
+		return [...this.calls.values()]
+			.map((c) => ({ ...c }))
+			.sort((a, b) => a.sentAt - b.sentAt);
+	}
+
+	clear(): void {
+		this.calls.clear();
+	}
+
+	/**
+	 * Get the number of stored calls (for testing)
+	 */
+	get size(): number {
+		return this.calls.size;
+	}
+}

package/src/storage/sql.ts

@@ -0,0 +1,266 @@
+/**
+ * SQL Pending Call Storage
+ *
+ * Synchronous storage implementation using Durable Object SQL storage.
+ * Calls are persisted to SQLite and survive hibernation.
+ */
+
+import * as z from "zod";
+import { createJsonCodec, type StringCodec } from "../codecs/index.js";
+import type { PendingCall, SyncPendingCallStorage } from "./interface.js";
+
+/**
+ * SQL storage value types (matches Cloudflare SqlStorageValue)
+ */
+type SqlStorageValue = ArrayBuffer | string | number | null;
+
+/**
+ * Cursor returned by SqlStorage.exec()
+ *
+ * Compatible with Cloudflare's SqlStorageCursor.
+ */
+export interface SqlStorageCursor<T extends Record<string, SqlStorageValue>>
+	extends Iterable<T> {
+	next(): { done?: false; value: T } | { done: true; value?: never };
+	toArray(): T[];
+	one(): T;
+	readonly rowsRead: number;
+	readonly rowsWritten: number;
+}
+
+/**
+ * Minimal SqlStorage interface for Durable Object SQL
+ *
+ * Compatible with `DurableObjectState.storage.sql` in Cloudflare Workers.
+ */
+export interface SqlStorage {
+	exec<T extends Record<string, SqlStorageValue>>(
+		query: string,
+		...bindings: unknown[]
+	): SqlStorageCursor<T>;
+}
+
+/**
+ * Row shape from the pending calls table
+ */
+interface PendingCallRow extends Record<string, SqlStorageValue> {
+	id: string;
+	method: string;
+	params: string;
+	callback: string;
+	sent_at: number;
+	timeout_at: number;
+}
+
+/**
+ * Table name for pending calls
+ */
+const TABLE_NAME = "_rpc_pending_calls";
+
+/**
+ * Default codec for params serialization (JSON)
+ */
+const defaultParamsCodec = createJsonCodec(z.unknown());
+
+/**
+ * Options for SQL pending call storage
+ */
+export interface SqlPendingCallStorageOptions {
+	/**
+	 * Codec for serializing/deserializing params
+	 *
+	 * Use a custom codec to support additional JavaScript types like
+	 * Date, Map, Set, BigInt, etc.
+	 *
+	 * @example
+	 * ```ts
+	 * import superjson from "superjson";
+	 * import { createStringCodecFactory } from "@igoforth/ws-rpc/codecs";
+	 *
+	 * const superJsonCodec = createStringCodecFactory(
+	 *   superjson.stringify,
+	 *   superjson.parse,
+	 *   "superjson"
+	 * );
+	 *
+	 * const storage = new SqlPendingCallStorage(sql, {
+	 *   paramsCodec: superJsonCodec(z.unknown()),
+	 * });
+	 * ```
+	 */
+	paramsCodec?: StringCodec;
+}
+
+/**
+ * SQL-backed pending call storage for Durable Objects
+ *
+ * Uses synchronous SQLite operations available in DO context.
+ */
+export class SqlPendingCallStorage implements SyncPendingCallStorage {
+	readonly mode = "sync" as const;
+	private readonly sql: SqlStorage;
+	private readonly paramsCodec: StringCodec;
+	private initialized = false;
+
+	/**
+	 * Create a SQL-backed pending call storage
+	 *
+	 * @param sql - Durable Object SQL storage instance
+	 * @param options - Optional configuration including custom params codec
+	 */
+	constructor(sql: SqlStorage, options?: SqlPendingCallStorageOptions) {
+		this.sql = sql;
+		this.paramsCodec = options?.paramsCodec ?? defaultParamsCodec;
+	}
+
+	/**
+	 * Ensure table exists (lazy initialization)
+	 */
+	private ensureTable(): void {
+		if (this.initialized) return;
+
+		this.sql.exec(`
+			CREATE TABLE IF NOT EXISTS ${TABLE_NAME} (
+				id TEXT PRIMARY KEY NOT NULL,
+				method TEXT NOT NULL,
+				params TEXT NOT NULL,
+				callback TEXT NOT NULL,
+				sent_at INTEGER NOT NULL,
+				timeout_at INTEGER NOT NULL
+			)
+		`);
+
+		// Index for timeout queries
+		this.sql.exec(`
+			CREATE INDEX IF NOT EXISTS idx_${TABLE_NAME}_timeout
+			ON ${TABLE_NAME}(timeout_at)
+		`);
+
+		this.initialized = true;
+	}
+
+	/**
+	 * Save a pending call to storage
+	 *
+	 * @param call - The pending call to persist
+	 */
+	save(call: PendingCall): void {
+		this.ensureTable();
+
+		const encodedParams = this.paramsCodec.encode(call.params);
+
+		this.sql.exec(
+			`INSERT OR REPLACE INTO ${TABLE_NAME}
+			 (id, method, params, callback, sent_at, timeout_at)
+			 VALUES (?, ?, ?, ?, ?, ?)`,
+			call.id,
+			call.method,
+			encodedParams,
+			call.callback,
+			call.sentAt,
+			call.timeoutAt,
+		);
+	}
+
+	/**
+	 * Get a pending call by ID
+	 *
+	 * @param id - The unique request ID
+	 * @returns The pending call or null if not found
+	 */
+	get(id: string): PendingCall | null {
+		this.ensureTable();
+
+		const results = [
+			...this.sql.exec<PendingCallRow>(
+				`SELECT * FROM ${TABLE_NAME} WHERE id = ?`,
+				id,
+			),
+		];
+
+		const row = results[0];
+		if (!row) return null;
+
+		return this.rowToCall(row);
+	}
+
+	/**
+	 * Delete a pending call by ID
+	 *
+	 * @param id - The unique request ID
+	 * @returns true if the call existed and was deleted
+	 */
+	delete(id: string): boolean {
+		this.ensureTable();
+
+		// SQLite doesn't return affected rows easily, so check existence first
+		const exists = this.get(id) !== null;
+		if (exists) {
+			this.sql.exec(`DELETE FROM ${TABLE_NAME} WHERE id = ?`, id);
+		}
+		return exists;
+	}
+
+	/**
+	 * List all calls that have exceeded their timeout
+	 *
+	 * @param before - Unix timestamp (ms); returns calls with timeoutAt <= before
+	 * @returns Array of expired pending calls ordered by timeout
+	 */
+	listExpired(before: number): PendingCall[] {
+		this.ensureTable();
+
+		const results = [
+			...this.sql.exec<PendingCallRow>(
+				`SELECT * FROM ${TABLE_NAME} WHERE timeout_at <= ? ORDER BY timeout_at ASC`,
+				before,
+			),
+		];
+
+		return results.map((row) => this.rowToCall(row));
+	}
+
+	/**
+	 * List all pending calls
+	 *
+	 * @returns Array of all pending calls ordered by sent time
+	 */
+	listAll(): PendingCall[] {
+		this.ensureTable();
+
+		const results = [
+			...this.sql.exec<PendingCallRow>(
+				`SELECT * FROM ${TABLE_NAME} ORDER BY sent_at ASC`,
+			),
+		];
+
+		return results.map((row) => this.rowToCall(row));
+	}
+
+	/**
+	 * Delete all pending calls
+	 */
+	clear(): void {
+		this.ensureTable();
+		this.sql.exec(`DELETE FROM ${TABLE_NAME}`);
+	}
+
+	/**
+	 * Convert a database row to a PendingCall
+	 *
+	 * @param row - Database row with call data
+	 * @returns Deserialized pending call
+	 */
+	private rowToCall(row: PendingCallRow): PendingCall {
+		const params = this.paramsCodec.decode(row.params);
+
+		return {
+			id: row.id,
+			method: row.method,
+			params,
+			callback: row.callback,
+			sentAt: row.sent_at,
+			timeoutAt: row.timeout_at,
+		};
+	}
+}