@procedures/client 0.0.0-stage → 0.1.0

package/dist/client/validation/middleware.js

@@ -0,0 +1,138 @@
+/**
+ * Schema Validation Middleware for transport calls
+ *
+ * Validates the request and response payloads of calls that go to a transport (a remote
+ * service), by method key. Schemas can be registered per-route (`Client.schema()`) or
+ * overridden per-call.
+ *
+ * A procedure of the registry does not need this middleware: `invokeProcedure` validates its
+ * input and output with its own schemas. Both use `validateSchema()` of the core, so any
+ * Standard Schema (zod 4, valibot, arktype) works here too, also an asynchronous one.
+ */
+import { methodToKey, ValidationError } from "./types.js";
+import { validateSchema } from "../../procedures/schema.js";
+// =============================================================================
+// Schema Registry Holder
+// =============================================================================
+/**
+ * Symbol for accessing the schema registry from middleware.
+ */
+export const SCHEMA_REGISTRY = Symbol.for("zod-middleware-schema-registry");
+// =============================================================================
+// Middleware Implementation
+// =============================================================================
+/**
+ * Create Zod validation middleware.
+ *
+ * This middleware validates request payloads before sending and
+ * response payloads after receiving, using registered schemas.
+ *
+ * Schemas are registered via `Client.schema()` or passed per-call
+ * in the options.
+ *
+ * @param options - Middleware configuration
+ * @returns Middleware with attached schema registry
+ *
+ * @example
+ * ```typescript
+ * const client = new Client({ transport })
+ *   .use(createZodMiddleware())
+ *   .schema({ service: "users", operation: "get" }, {
+ *     input: z.object({ id: z.string() }),
+ *     output: UserSchema,
+ *   });
+ *
+ * // Validation happens automatically
+ * const user = await client.call(
+ *   { service: "users", operation: "get" },
+ *   { id: "123" }
+ * );
+ * ```
+ */
+export function createZodMiddleware(options = {}) {
+    const { mode = "strict", transformOutput = false, onValidationError } = options;
+    // Schema registry (populated via Client.schema())
+    const schemaRegistry = new Map();
+    const middleware = (next) => {
+        return async function* (context) {
+            const methodKey = methodToKey(context.message.method);
+            // Get schema: per-call override > registry
+            const schema = getSchemaForContext(context, schemaRegistry, methodKey);
+            // Validate input
+            let validatedPayload = context.message.payload;
+            let inputValidated = false;
+            if (schema?.input) {
+                const result = await validatePayload(context.message.payload, schema.input, "input", context.message.method, { mode, onValidationError: onValidationError ?? undefined });
+                inputValidated = true;
+                if (result.success && transformOutput) {
+                    validatedPayload = result.data;
+                    context.message.payload = validatedPayload;
+                }
+            }
+            // Store validation context in metadata
+            context.message.metadata.__validation = {
+                inputValidated,
+                outputValidated: !!schema?.output,
+                methodKey,
+            };
+            // Execute downstream middleware
+            const responseStream = next(context);
+            // Validate each response item
+            for await (const item of responseStream) {
+                // Only validate successful responses with output schema
+                if (schema?.output && item.status.type === "success") {
+                    const result = await validatePayload(item.payload, schema.output, "output", context.message.method, { mode, onValidationError: onValidationError ?? undefined });
+                    if (result.success && transformOutput) {
+                        yield { ...item, payload: result.data };
+                        continue;
+                    }
+                }
+                yield item;
+            }
+        };
+    };
+    // Attach registry for Client.schema() access
+    middleware[SCHEMA_REGISTRY] = schemaRegistry;
+    return middleware;
+}
+// =============================================================================
+// Internal Helpers
+// =============================================================================
+/**
+ * Get schema for a request, checking per-call override first.
+ */
+function getSchemaForContext(context, registry, methodKey) {
+    // Check per-call override (from CallOptions.schema via metadata.__schema)
+    const perCallSchema = context.message.metadata?.__schema;
+    if (perCallSchema) {
+        return perCallSchema;
+    }
+    // Fall back to registry
+    return registry.get(methodKey);
+}
+/**
+ * Validate a payload against a schema.
+ */
+async function validatePayload(payload, schema, phase, method, options) {
+    // The one validation path of the core: any Standard Schema, also an asynchronous one
+    const result = await validateSchema(schema, payload);
+    if (!result.ok) {
+        const error = new ValidationError(`${phase} validation failed for ${method.service}.${method.operation}`, phase, { message: result.message, issues: result.issues.map((issue) => ({ message: issue.message, path: (issue.path ?? []).map((part) => (typeof part === "object" ? part.key : part)) })) }, method);
+        // Call custom error handler
+        options.onValidationError?.(error);
+        // Handle based on mode
+        switch (options.mode) {
+            case "strict":
+                throw error;
+            case "warn":
+                console.warn(`[Zod Validation] ${error.details}`);
+                break;
+            case "silent":
+                // No action
+                break;
+        }
+        return { success: false };
+    }
+    return { success: true, data: result.value };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/client/validation/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../../src/client/validation/middleware.ts"],"names":[],"mappings":"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"}

package/dist/client/validation/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Zod Validation Types
+ *
+ * Type definitions for schema validation middleware.
+ * Works with Zod as an optional peer dependency.
+ */
+import type { Method } from "../types.js";
+import type { InferSchema, ProcedureSchema } from "../../procedures/schema.js";
+/**
+ * Generic schema interface compatible with Zod.
+ * Allows the validation system to work without direct Zod dependency.
+ */
+export interface ZodLike<T = unknown> {
+    parse(data: unknown): T;
+    safeParse(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: ZodErrorLike;
+    };
+}
+/**
+ * Generic Zod error interface. Zod 4 gives `issues` (zod 3 gave `errors` too), so both are
+ * optional: a reader uses `message`, or `validateSchema()` of the core.
+ */
+export interface ZodErrorLike {
+    message: string;
+    errors?: ReadonlyArray<{
+        path?: ReadonlyArray<PropertyKey>;
+        message: string;
+    }> | undefined;
+    issues?: ReadonlyArray<{
+        path?: ReadonlyArray<PropertyKey>;
+        message: string;
+    }> | undefined;
+}
+/**
+ * Schema definition for a method (input and/or output validation).
+ */
+export interface SchemaDefinition<TInput extends ProcedureSchema = ProcedureSchema, TOutput extends ProcedureSchema = ProcedureSchema> {
+    /** Input/request payload schema */
+    input?: TInput;
+    /** Output/response payload schema */
+    output?: TOutput;
+}
+/**
+ * Infer the input type from a schema definition.
+ */
+export type InferInput<T> = T extends SchemaDefinition<infer TInput, any> ? InferSchema<TInput> : unknown;
+/**
+ * Infer the output type from a schema definition.
+ */
+export type InferOutput<T> = T extends SchemaDefinition<any, infer TOutput> ? InferSchema<TOutput> : unknown;
+/**
+ * Method key for schema registry lookup.
+ * Format: "service.operation" or "service.operation.version"
+ */
+export type MethodKey = `${string}.${string}` | `${string}.${string}.${string}`;
+/**
+ * Convert a Method object to a registry key string.
+ */
+export declare function methodToKey(method: Method): MethodKey;
+/**
+ * Parse a method key back to a Method object.
+ */
+export declare function keyToMethod(key: MethodKey): Method;
+/**
+ * Schema registry mapping method keys to schema definitions.
+ */
+export type SchemaRegistry = Map<MethodKey, SchemaDefinition>;
+/**
+ * Type-level schema registry for compile-time type inference.
+ */
+export interface TypedSchemaRegistry {
+    [methodKey: string]: SchemaDefinition;
+}
+/**
+ * Validation phase indicator.
+ */
+export type ValidationPhase = "input" | "output";
+/**
+ * Error thrown when validation fails.
+ */
+export declare class ValidationError extends Error {
+    /** Which phase of validation failed */
+    readonly phase: ValidationPhase;
+    /** The underlying Zod error */
+    readonly zodError: ZodErrorLike;
+    /** The method being called */
+    readonly method: Method;
+    readonly name = "ValidationError";
+    constructor(message: string, 
+    /** Which phase of validation failed */
+    phase: ValidationPhase, 
+    /** The underlying Zod error */
+    zodError: ZodErrorLike, 
+    /** The method being called */
+    method: Method);
+    /**
+     * Get formatted validation error details.
+     */
+    get details(): string;
+}
+/**
+ * Context provided by Zod validation middleware.
+ */
+export interface ZodValidationContext {
+    validation: {
+        /** Whether input was validated */
+        inputValidated: boolean;
+        /** Whether output was validated */
+        outputValidated: boolean;
+        /** The method key used for schema lookup */
+        methodKey: MethodKey;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/validation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/client/validation/types.ts"],"names":[],"mappings":"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"}

package/dist/client/validation/types.js

@@ -0,0 +1,59 @@
+/**
+ * Zod Validation Types
+ *
+ * Type definitions for schema validation middleware.
+ * Works with Zod as an optional peer dependency.
+ */
+/**
+ * Convert a Method object to a registry key string.
+ */
+export function methodToKey(method) {
+    return method.version
+        ? `${method.service}.${method.operation}.${method.version}`
+        : `${method.service}.${method.operation}`;
+}
+/**
+ * Parse a method key back to a Method object.
+ */
+export function keyToMethod(key) {
+    const parts = key.split(".");
+    if (parts.length === 3 && parts[2]) {
+        return { service: parts[0], operation: parts[1], version: parts[2] };
+    }
+    return { service: parts[0], operation: parts[1] };
+}
+/**
+ * Error thrown when validation fails.
+ */
+export class ValidationError extends Error {
+    phase;
+    zodError;
+    method;
+    name = "ValidationError";
+    constructor(message, 
+    /** Which phase of validation failed */
+    phase, 
+    /** The underlying Zod error */
+    zodError, 
+    /** The method being called */
+    method) {
+        super(message);
+        this.phase = phase;
+        this.zodError = zodError;
+        this.method = method;
+        // Maintain proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ValidationError);
+        }
+    }
+    /**
+     * Get formatted validation error details.
+     */
+    get details() {
+        const errors = (this.zodError.issues ?? this.zodError.errors ?? [])
+            .map((e) => `  - ${(e.path ?? []).map(String).join(".")}: ${e.message}`)
+            .join("\n");
+        return `${this.phase} validation failed for ${this.method.service}.${this.method.operation}:\n${errors}`;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/client/validation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/client/validation/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6DH;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,MAAM,CAAC,OAAO;QACnB,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,OAAO,EAAE;QAC3D,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAc;IACxC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC;AACtD,CAAC;AA2BD;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAMtB,KAAK;IAEL,QAAQ;IAER,MAAM;IATN,IAAI,GAAG,iBAAiB,CAAC;IAE3C,YACE,OAAe;IACf,uCAAuC;IACvB,KAAsB;IACtC,+BAA+B;IACf,QAAsB;IACtC,8BAA8B;IACd,MAAc;QAE9B,KAAK,CAAC,OAAO,CAAC,CAAC;qBANC,KAAK;wBAEL,QAAQ;sBAER,MAAM;QAItB,iDAAiD;QACjD,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,OAAO;QACT,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;aAChE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACvE,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,OAAO,GAAG,IAAI,CAAC,KAAK,0BAA0B,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,MAAM,MAAM,EAAE,CAAC;IAC3G,CAAC;CACF"}

package/dist/collections/async/async-queue.d.ts

@@ -0,0 +1,144 @@
+/**
+ * AsyncQueue - An async iterable queue with backpressure support.
+ *
+ * Designed for producer-consumer patterns where producers can wait when
+ * the queue is full and consumers can wait when the queue is empty.
+ * Implements AsyncIterable for use with for-await-of loops.
+ *
+ * @example
+ * const queue = asyncQueue<number>({ capacity: 10 })
+ *
+ * // Producer
+ * await queue.put(42) // Waits if queue is full
+ *
+ * // Consumer
+ * const value = await queue.take() // Waits if queue is empty
+ *
+ * // Async iteration
+ * for await (const value of queue) {
+ *   console.log(value)
+ * }
+ */
+import type { AsyncQueue as IAsyncQueue } from "../interfaces/queue.js";
+/**
+ * Options for creating an AsyncQueue.
+ */
+export interface AsyncQueueOptions {
+    /**
+     * Maximum capacity. Infinity for unbounded queue.
+     * @default Infinity
+     */
+    capacity?: number;
+    /**
+     * Timeout for put/take operations in milliseconds.
+     * @default undefined (no timeout)
+     */
+    timeout?: number;
+}
+/**
+ * AsyncQueue<T> - Thread-safe async queue with backpressure.
+ *
+ * Features:
+ * - Blocking put() when full (backpressure)
+ * - Blocking take() when empty
+ * - AsyncIterable support
+ * - Graceful closing
+ * - Timeouts
+ *
+ * Perfect for:
+ * - Producer-consumer patterns
+ * - Rate limiting
+ * - Task queues
+ * - Stream processing
+ */
+export declare class AsyncQueue<T> implements IAsyncQueue<T> {
+    private buffer;
+    private putters;
+    private takers;
+    private _isClosed;
+    private readonly capacity;
+    private readonly defaultTimeout?;
+    constructor(options?: AsyncQueueOptions);
+    get size(): number;
+    get isEmpty(): boolean;
+    get isFull(): boolean;
+    get isClosed(): boolean;
+    get remainingCapacity(): number;
+    /**
+     * Adds an element to the queue.
+     * If the queue is full, waits until space is available.
+     *
+     * @throws Error if queue is closed
+     * @throws Error if timeout expires
+     */
+    put(element: T, timeout?: number): Promise<void>;
+    /**
+     * Removes and returns an element from the queue.
+     * If the queue is empty, waits until an element is available.
+     *
+     * @throws Error if queue is closed and empty
+     * @throws Error if timeout expires
+     */
+    take(timeout?: number): Promise<T>;
+    /**
+     * Attempts to add an element without waiting.
+     * Returns false if queue is full.
+     */
+    tryPut(element: T): boolean;
+    /**
+     * Attempts to remove an element without waiting.
+     * Returns undefined if queue is empty.
+     */
+    tryTake(): T | undefined;
+    /**
+     * Returns the next element without removing it.
+     * Waits if queue is empty.
+     */
+    peek(): Promise<T>;
+    /**
+     * Returns the next element without waiting.
+     * Returns undefined if queue is empty.
+     */
+    tryPeek(): T | undefined;
+    /**
+     * Closes the queue. No more elements can be added.
+     * Existing elements can still be consumed.
+     */
+    close(): void;
+    /**
+     * Drains all elements into an array.
+     * Returns immediately with current elements.
+     */
+    drain(): T[];
+    /**
+     * Async iterator that yields elements as they become available.
+     * Stops when queue is closed and empty.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    private fulfillPutter;
+    private clearTimeout;
+    /**
+     * Returns statistics about the queue.
+     */
+    getStats(): {
+        size: number;
+        capacity: number;
+        isEmpty: boolean;
+        isFull: boolean;
+        isClosed: boolean;
+        waitingPutters: number;
+        waitingTakers: number;
+        remainingCapacity: number;
+    };
+    toString(): string;
+}
+/**
+ * Factory function to create an AsyncQueue.
+ *
+ * @example
+ * const queue = asyncQueue<number>({ capacity: 100 })
+ * await queue.put(42)
+ * const value = await queue.take()
+ */
+export declare function asyncQueue<T>(options?: AsyncQueueOptions): AsyncQueue<T>;
+//# sourceMappingURL=async-queue.d.ts.map

package/dist/collections/async/async-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-queue.d.ts","sourceRoot":"","sources":["../../../src/collections/async/async-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,IAAI,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAWD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU,CAAC,CAAC,CAAE,YAAW,WAAW,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAS;gBAE7B,OAAO,GAAE,iBAAsB;IAW3C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAMD;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqDtD;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAqDxC;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO;IAiB3B;;;OAGG;IACH,OAAO,IAAI,CAAC,GAAG,SAAS;IAcxB;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC;IAexB;;;OAGG;IACH,OAAO,IAAI,CAAC,GAAG,SAAS;IAQxB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAoBb;;;OAGG;IACH,KAAK,IAAI,CAAC,EAAE;IAgBZ;;;OAGG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;IAsBjD,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,YAAY;IAUpB;;OAEG;IACH,QAAQ,IAAK;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,OAAO,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;KAC3B;IAaD,QAAQ,IAAI,MAAM;CAGnB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAAC,CAAC,CAAC,CAExE"}