@procedures/client 0.0.0-stage → 0.2.0

package/src/events/types.ts

@@ -0,0 +1,263 @@
+/**
+ * Event Bus Types
+ *
+ * Central pub/sub system for streaming coordination.
+ * Enables procedures to subscribe to events and emit updates.
+ */
+
+// =============================================================================
+// Event Types
+// =============================================================================
+
+/**
+ * Event payload with channel and data.
+ */
+export interface Event<T = unknown> {
+  /** Channel the event was emitted on */
+  channel: string;
+  /** Event data */
+  data: T;
+  /** Timestamp when event was emitted */
+  timestamp: number;
+}
+
+/**
+ * Event handler function.
+ */
+export type EventHandler<T = unknown> = (data: T) => void | Promise<void>;
+
+/**
+ * Unsubscribe function returned from subscriptions.
+ */
+export type Unsubscribe = () => void;
+
+// =============================================================================
+// Event Bus Interface
+// =============================================================================
+
+/**
+ * Central event bus for pub/sub messaging.
+ *
+ * Features:
+ * - Type-safe channels (optional via generics)
+ * - Multiple subscribers per channel
+ * - Async iteration support via stream()
+ * - One-time subscriptions via once()
+ *
+ * @example
+ * ```typescript
+ * const bus = new EventBus();
+ *
+ * // Subscribe to events
+ * const unsubscribe = bus.on("user:updated", (user) => {
+ *   console.log("User updated:", user);
+ * });
+ *
+ * // Emit events
+ * bus.emit("user:updated", { id: "123", name: "John" });
+ *
+ * // Unsubscribe
+ * unsubscribe();
+ *
+ * // One-time subscription
+ * const user = await bus.once("user:created");
+ *
+ * // Streaming iteration
+ * for await (const update of bus.stream("updates")) {
+ *   console.log("Update:", update);
+ * }
+ * ```
+ */
+export interface EventBus {
+  /**
+   * Emit an event on a channel.
+   *
+   * @param channel - Channel to emit on
+   * @param data - Event data
+   */
+  emit<T>(channel: string, data: T): void;
+
+  /**
+   * Subscribe to events on a channel.
+   *
+   * @param channel - Channel to subscribe to
+   * @param handler - Handler function called for each event
+   * @returns Unsubscribe function
+   */
+  on<T>(channel: string, handler: EventHandler<T>): Unsubscribe;
+
+  /**
+   * Subscribe to a single event on a channel.
+   * Returns a promise that resolves with the first event.
+   *
+   * @param channel - Channel to wait for
+   * @param options - A signal: when it aborts first, the promise rejects with an `AbortError`
+   * @returns Promise resolving to the event data
+   */
+  once<T>(channel: string, options?: EventWaitOptions): Promise<T>;
+
+  /**
+   * Create an async iterable for a channel.
+   * Yields events as they arrive until the reader stops, the signal aborts, or `clear()`.
+   *
+   * @param channel - Channel to stream
+   * @param options - A signal: when it aborts, the stream ends
+   * @returns AsyncIterable of event data
+   */
+  stream<T>(channel: string, options?: EventWaitOptions): AsyncIterable<T>;
+
+  /**
+   * Get the number of subscribers on a channel.
+   *
+   * @param channel - Channel to check
+   * @returns Number of subscribers
+   */
+  subscriberCount(channel: string): number;
+
+  /**
+   * Check if a channel has any subscribers.
+   *
+   * @param channel - Channel to check
+   */
+  hasSubscribers(channel: string): boolean;
+
+  /**
+   * Get all active channel names.
+   */
+  channels(): string[];
+
+  /**
+   * Remove all subscribers from a channel.
+   *
+   * @param channel - Channel to clear
+   */
+  clear(channel: string): void;
+
+  /**
+   * Remove all subscribers from all channels.
+   */
+  clearAll(): void;
+}
+
+// =============================================================================
+// Typed Channel Maps
+// =============================================================================
+
+/**
+ * Channel type map for type-safe event buses.
+ * Define your channels and their data types here.
+ *
+ * @example
+ * ```typescript
+ * interface MyChannels {
+ *   "user:created": { id: string; name: string };
+ *   "user:updated": { id: string; changes: Partial<User> };
+ *   "order:placed": { orderId: string; total: number };
+ * }
+ *
+ * const bus = createTypedEventBus<MyChannels>();
+ *
+ * // Type-safe emissions and subscriptions
+ * bus.emit("user:created", { id: "123", name: "John" }); // ✓
+ * bus.emit("user:created", { invalid: true }); // Type error
+ *
+ * bus.on("order:placed", (order) => {
+ *   console.log(order.orderId); // ✓ typed as string
+ * });
+ * ```
+ */
+export interface ChannelMap {
+  [channel: string]: unknown;
+}
+
+/**
+ * Type-safe event bus with predefined channels.
+ */
+export interface TypedEventBus<TChannels extends ChannelMap> {
+  emit<K extends keyof TChannels & string>(channel: K, data: TChannels[K]): void;
+  on<K extends keyof TChannels & string>(
+    channel: K,
+    handler: EventHandler<TChannels[K]>
+  ): Unsubscribe;
+  once<K extends keyof TChannels & string>(channel: K, options?: EventWaitOptions): Promise<TChannels[K]>;
+  stream<K extends keyof TChannels & string>(channel: K, options?: EventWaitOptions): AsyncIterable<TChannels[K]>;
+  subscriberCount(channel: string): number;
+  hasSubscribers(channel: string): boolean;
+  channels(): string[];
+  clear(channel: string): void;
+  clearAll(): void;
+}
+
+// =============================================================================
+// Built-in Channel Types
+// =============================================================================
+
+/**
+ * Standard system channels.
+ */
+export interface SystemChannels {
+  /** Error events */
+  "system:error": { error: Error; context?: string };
+  /** Warning events */
+  "system:warning": { message: string; context?: string };
+  /** Debug events */
+  "system:debug": { message: string; data?: unknown };
+}
+
+/**
+ * Procedure-related channels.
+ */
+export interface ProcedureChannels {
+  /** Procedure execution started */
+  "procedure:start": { path: string[]; input: unknown };
+  /** Procedure execution completed */
+  "procedure:complete": { path: string[]; output: unknown; duration: number };
+  /** Procedure execution failed */
+  "procedure:error": { path: string[]; error: Error };
+  /** Procedure yielded (streaming) */
+  "procedure:yield": { path: string[]; value: unknown; index: number };
+}
+
+/**
+ * Default channel map combining system and procedure channels.
+ */
+export interface DefaultChannels extends SystemChannels, ProcedureChannels {
+  // Allow additional custom channels
+  [channel: string]: unknown;
+}
+
+// =============================================================================
+// Event Bus Options
+// =============================================================================
+
+/**
+ * Options for a wait on a channel: `once()` and `stream()`.
+ */
+export interface EventWaitOptions {
+  /** When this signal aborts, the wait ends */
+  signal?: AbortSignal | undefined;
+}
+
+/**
+ * Options for creating an event bus.
+ */
+export interface EventBusOptions {
+  /**
+   * Maximum number of events to buffer for late subscribers.
+   * Set to 0 to disable buffering.
+   * Default: 0 (no buffering)
+   */
+  bufferSize?: number;
+
+  /**
+   * Handler for uncaught errors in event handlers.
+   * Default: console.error
+   */
+  onError?: (error: Error, channel: string) => void;
+
+  /**
+   * Enable debug logging.
+   * Default: false
+   */
+  debug?: boolean;
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Universal Client Library
+ *
+ * Protocol-agnostic RPC client with middleware composition
+ * and transport adapters.
+ *
+ * This entry point is for Node. It exports the browser-safe entry point
+ * ("@procedures/client/browser") and the server transports, which use `http` and `ws`.
+ */
+
+export * from "./browser.js";
+
+// ============================================================================
+// Server Transports (Node only)
+// ============================================================================
+export {
+  HttpServerTransport,
+  defaultServerUrlStrategy,
+  rpcServerUrlStrategy,
+} from "./server/index.js";
+export type {
+  HttpServerTransportOptions,
+  HttpUrlStrategy,
+} from "./server/index.js";
+export { WebSocketServerTransport } from "./server/index.js";
+export { checkBrowserRequest, isLoopbackHost, isLoopbackAddress, hostNameOf } from "./server/browser-guard.js";
+export type { BrowserGuardOptions, GuardedRequest, GuardResult } from "./server/browser-guard.js";
+export type {
+  WebSocketServerTransportOptions,
+  WebSocketAuthHandler,
+  WebSocketConnectionHandler,
+  WebSocketMessage,
+} from "./server/index.js";

package/src/middleware/compose.ts

@@ -0,0 +1,159 @@
+/**
+ * Middleware Composition Utilities
+ *
+ * Provides type-safe composition of middleware chains with proper context tracking.
+ * Uses recursive type inference (`MiddlewaresContext`) to validate middleware compatibility
+ * for any chain length - no manual overloads needed!
+ */
+
+import type {
+  Middleware,
+  MiddlewareRunner,
+  MiddlewaresContext,
+  AsyncMiddleware,
+  SyncMiddleware,
+} from "./types.js";
+
+/**
+ * Wraps an async function with a series of middlewares and returns a new async function
+ * representing their combined execution.
+ *
+ * The middlewares list is ordered from outer to inner, such that when the combined async function
+ * is executed, the first middleware in the list is run first and then executes the "next" function
+ * which represents the inner function wrapped by subsequent middlewares.
+ *
+ * Type safety: The `MiddlewaresContext` recursive type validates that each middleware's
+ * requirements are satisfied by the accumulated context from previous middleware.
+ * If incompatible, the return type becomes `never` (compile error).
+ *
+ * @example
+ * ```typescript
+ * const runner = wrapWithAsyncMiddlewares(
+ *   [timeoutMiddleware, retryMiddleware, cacheMiddleware],
+ *   async (ctx: BaseContext) => fetchData(ctx)
+ * );
+ * await runner({ request: req }); // Type-safe!
+ * ```
+ */
+export function wrapWithAsyncMiddlewares<
+  TMiddlewares extends readonly AsyncMiddleware<any, any, any>[],
+  TBaseContext,
+  TReturn
+>(
+  middlewares: TMiddlewares,
+  fn: MiddlewareRunner<
+    MiddlewaresContext<TMiddlewares, TBaseContext>,
+    TReturn,
+    true
+  >
+): MiddlewareRunner<TBaseContext, TReturn, true> {
+  const combinedRunner = middlewares.reduceRight(
+    (currentRunner, currentMiddleware) => {
+      return currentMiddleware(currentRunner);
+    },
+    fn
+  ) as MiddlewareRunner<TBaseContext, TReturn, true>;
+
+  // Wrap in async to ensure synchronous throws become rejected promises
+  return async (context) => {
+    return combinedRunner(context);
+  };
+}
+
+/**
+ * Wraps a synchronous function with a series of middlewares.
+ * Same as async version but for synchronous execution.
+ *
+ * @example
+ * ```typescript
+ * const runner = wrapWithSyncMiddlewares(
+ *   [boundedMiddleware, eventedMiddleware],
+ *   (collection: Collection) => collection.size
+ * );
+ * const size = runner(baseCollection);
+ * ```
+ */
+export function wrapWithSyncMiddlewares<
+  TMiddlewares extends readonly SyncMiddleware<any, any, any>[],
+  TBaseContext,
+  TReturn
+>(
+  middlewares: TMiddlewares,
+  fn: MiddlewareRunner<
+    MiddlewaresContext<TMiddlewares, TBaseContext>,
+    TReturn,
+    false
+  >
+): MiddlewareRunner<TBaseContext, TReturn, false> {
+  return middlewares.reduceRight((currentRunner, currentMiddleware) => {
+    return currentMiddleware(currentRunner);
+  }, fn) as MiddlewareRunner<TBaseContext, TReturn, false>;
+}
+
+/**
+ * Composes multiple middleware with an initial runner.
+ * Automatically detects sync vs async based on middleware type.
+ *
+ * This is a convenience wrapper around `wrapWithAsyncMiddlewares`/`wrapWithSyncMiddlewares`
+ * that accepts middleware as individual arguments instead of an array.
+ *
+ * @example
+ * ```typescript
+ * // Async composition
+ * const runner = compose(m1, m2, m3, async (ctx) => fetch(ctx.url));
+ * await runner({ url: "..." });
+ *
+ * // Sync composition
+ * const runner = compose(m1, m2, (ctx) => ctx.value * 2);
+ * const result = runner({ value: 21 });
+ * ```
+ */
+export function compose<TAsync extends boolean = false>(
+  ...args: [...Middleware<any, any, any, TAsync>[], any]
+): MiddlewareRunner<any, any, TAsync> {
+  // Last argument is the initial runner/function
+  const fn = args[args.length - 1];
+  const middleware = args.slice(0, -1) as Middleware<any, any, any, TAsync>[];
+
+  // Compose middleware from right to left (onion model)
+  const combined = middleware.reduceRight(
+    (next, mw) => mw(next),
+    fn
+  ) as MiddlewareRunner<any, any, TAsync>;
+
+  return combined;
+}
+
+/**
+ * Bundles multiple middleware into a single composed middleware.
+ * This is useful for creating reusable middleware stacks.
+ *
+ * Unlike `compose`, `bundle` returns a middleware (not a runner), so it can be
+ * composed further or used with `.use()` on clients.
+ *
+ * @example
+ * ```typescript
+ * // Create a standard middleware bundle
+ * const standardStack = bundle(
+ *   timeoutMiddleware,
+ *   retryMiddleware,
+ *   cacheMiddleware
+ * );
+ *
+ * // Use it like any other middleware
+ * client.use(standardStack);
+ *
+ * // Or compose it further
+ * const enhanced = bundle(loggingMiddleware, standardStack);
+ * ```
+ */
+export function bundle<TAsync extends boolean = false>(
+  ...middleware: Middleware<any, any, any, TAsync>[]
+): Middleware<any, any, any, TAsync> {
+  return (next) =>
+    middleware.reduceRight((acc, mw) => mw(acc), next) as MiddlewareRunner<
+      any,
+      any,
+      TAsync
+    >;
+}

package/src/middleware/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Unified Middleware System
+ *
+ * Provides type-safe middleware composition for both sync and async operations.
+ * Used by both API middleware (async) and Collections middleware (sync).
+ *
+ * Uses recursive type inference (`MiddlewaresContext`) to validate middleware
+ * compatibility at compile time - no manual overloads needed!
+ */
+
+export type {
+  MiddlewareRunner,
+  Middleware,
+  AsyncMiddleware,
+  SyncMiddleware,
+  MiddlewaresContext,
+  MiddlewareReturn,
+  MiddlewareContextIn,
+  MiddlewareContextOut,
+  IsAsyncMiddleware,
+} from "./types.js";
+
+export {
+  compose,
+  bundle,
+  wrapWithAsyncMiddlewares,
+  wrapWithSyncMiddlewares,
+} from "./compose.js";

package/src/middleware/types.ts

@@ -0,0 +1,166 @@
+/**
+ * Unified Middleware Type System
+ *
+ * This module provides a sophisticated type-safe middleware system that supports
+ * both synchronous and asynchronous middleware with full context tracking.
+ *
+ * Key features:
+ * - Type-level context tracking through middleware chains
+ * - Compile-time validation of middleware compatibility
+ * - Support for both sync and async execution
+ * - Recursive type inference for composed middleware
+ */
+
+/**
+ * MiddlewareRunner is a function that can be wrapped in middleware.
+ * It takes a context object and returns either a value or a promise.
+ *
+ * @template TContext - The context object type
+ * @template TReturn - The return value type
+ * @template TAsync - Whether the runner is async (true) or sync (false)
+ */
+export type MiddlewareRunner<TContext, TReturn, TAsync extends boolean = false> =
+  TAsync extends true
+    ? (context: TContext) => Promise<TReturn>
+    : (context: TContext) => TReturn;
+
+/**
+ * Middleware represents a function that wraps another function, such that the inner
+ * function can be instrumented or provided with additional context.
+ *
+ * The middleware can:
+ * - Add new properties to the context (TContextOut)
+ * - Require existing properties from the context (TContextIn)
+ * - Transform the execution flow
+ * - Be composed with other middleware
+ *
+ * Type parameters express middleware capabilities and requirements:
+ * - TContextOut: What context fields this middleware provides/adds
+ * - TContextIn: What context fields this middleware requires
+ * - TReturn: The return type
+ * - TAsync: Whether execution is async (true) or sync (false)
+ *
+ * Example:
+ * ```typescript
+ * // Async middleware that adds retryCount to context
+ * type RetryMiddleware = Middleware<
+ *   { retryCount: number },  // Provides
+ *   {},                       // Requires nothing
+ *   Response,                 // Returns Response
+ *   true                      // Async
+ * >;
+ *
+ * // Middleware that requires retryCount
+ * type LogMiddleware = Middleware<
+ *   {},                       // Provides nothing
+ *   { retryCount: number },   // Requires retryCount
+ *   Response,                 // Returns Response
+ *   true                      // Async
+ * >;
+ * ```
+ */
+export interface Middleware<
+  TContextOut,
+  TContextIn,
+  TReturn,
+  TAsync extends boolean = false,
+> {
+  (
+    next: MiddlewareRunner<TContextIn & TContextOut, TReturn, TAsync>,
+  ): MiddlewareRunner<TContextIn, TReturn, TAsync>;
+}
+
+/**
+ * AsyncMiddleware is a specialized version for async execution.
+ * This is the most common form for API/network operations.
+ */
+export type AsyncMiddleware<TContextOut, TContextIn, TReturn> = Middleware<
+  TContextOut,
+  TContextIn,
+  TReturn,
+  true
+>;
+
+/**
+ * SyncMiddleware is a specialized version for synchronous execution.
+ * This is common for in-memory data structure operations.
+ */
+export type SyncMiddleware<TContextOut, TContextIn, TReturn> = Middleware<
+  TContextOut,
+  TContextIn,
+  TReturn,
+  false
+>;
+
+/**
+ * Extracts the combined context after applying a series of middlewares.
+ *
+ * This recursive type validates that each middleware's requirements are satisfied
+ * by the accumulated context. If any middleware expects a context field that is
+ * not provided by previous middleware or the initial context, the result is `never`.
+ *
+ * Example:
+ * ```typescript
+ * type Mw1 = Middleware<{ a: number }, {}, Response, true>;
+ * type Mw2 = Middleware<{ b: string }, { a: number }, Response, true>;
+ * type Mw3 = Middleware<{}, { a: number; b: string }, Response, true>;
+ *
+ * // Valid: each middleware gets what it needs
+ * type Ctx = MiddlewaresContext<[Mw1, Mw2, Mw3], {}>;
+ * // Result: { a: number; b: string }
+ *
+ * // Invalid: Mw2 requires { a: number } but Mw1 is missing
+ * type BadCtx = MiddlewaresContext<[Mw2], {}>;
+ * // Result: never (compile error)
+ * ```
+ */
+export type MiddlewaresContext<
+  TMiddlewares extends readonly Middleware<any, any, any, any>[],
+  TContextIn = {},
+> =
+  // Recursive case: process next middleware in chain
+  TMiddlewares extends readonly [
+    Middleware<infer TNextContextOut, infer TNextContextIn, any, any>,
+    ...infer TRest,
+  ]
+    ? // Check that the accumulated context satisfies next middleware's requirements
+      TContextIn extends TNextContextIn
+      ? // Check type constraint for recursion
+        TRest extends readonly Middleware<any, any, any, any>[]
+        ? // Recurse with accumulated context
+          MiddlewaresContext<TRest, TContextIn & TNextContextOut>
+        : never
+      : // Requirements not met - incompatible middleware
+        never
+    : // Base case: no more middleware, return accumulated context
+    TMiddlewares extends readonly []
+    ? TContextIn
+    : never;
+
+/**
+ * Helper type to extract the return type from a middleware
+ */
+export type MiddlewareReturn<T> = T extends Middleware<any, any, infer R, any>
+  ? R
+  : never;
+
+/**
+ * Helper type to extract the context input from a middleware
+ */
+export type MiddlewareContextIn<T> = T extends Middleware<any, infer Ctx, any, any>
+  ? Ctx
+  : never;
+
+/**
+ * Helper type to extract the context output from a middleware
+ */
+export type MiddlewareContextOut<T> = T extends Middleware<infer Ctx, any, any, any>
+  ? Ctx
+  : never;
+
+/**
+ * Helper type to check if a middleware is async
+ */
+export type IsAsyncMiddleware<T> = T extends Middleware<any, any, any, infer A>
+  ? A
+  : never;