@procedures/client 0.0.0-stage → 0.2.0

package/dist/client/middleware/batching.js

@@ -0,0 +1,245 @@
+/**
+ * Batching Middleware
+ *
+ * Combines multiple requests into a single batch for efficiency.
+ * Reduces network overhead and improves throughput.
+ *
+ * Works with both client and server!
+ */
+/**
+ * Batch queue for collecting requests.
+ */
+class BatchQueue {
+    options;
+    processBatch;
+    requests = new Map();
+    timers = new Map();
+    stats = {
+        totalRequests: 0,
+        totalBatches: 0,
+    };
+    constructor(options, processBatch) {
+        this.options = options;
+        this.processBatch = processBatch;
+    }
+    /**
+     * Add request to batch queue.
+     */
+    add(key, request) {
+        this.stats.totalRequests++;
+        // Get or create batch for this key
+        let batch = this.requests.get(key);
+        if (!batch) {
+            batch = [];
+            this.requests.set(key, batch);
+        }
+        batch.push(request);
+        // Check if batch is full
+        if (batch.length >= this.options.maxBatchSize) {
+            this.flush(key);
+        }
+        else if (batch.length === 1) {
+            // First request in batch - start timer
+            this.startTimer(key);
+        }
+    }
+    /**
+     * Start timer for batch.
+     */
+    startTimer(key) {
+        const timer = setTimeout(() => {
+            this.flush(key);
+        }, this.options.maxWaitTime);
+        this.timers.set(key, timer);
+    }
+    /**
+     * Flush batch (send it).
+     */
+    flush(key) {
+        const batch = this.requests.get(key);
+        if (!batch || batch.length === 0) {
+            return;
+        }
+        // Clear timer
+        const timer = this.timers.get(key);
+        if (timer) {
+            clearTimeout(timer);
+            this.timers.delete(key);
+        }
+        // Remove from queue
+        this.requests.delete(key);
+        // Update stats
+        this.stats.totalBatches++;
+        // Notify callback
+        if (this.options.onBatchSent) {
+            this.options.onBatchSent(batch.length, key);
+        }
+        // Process batch
+        this.processBatch(key, batch);
+    }
+    /**
+     * Get statistics.
+     */
+    getStats() {
+        let pendingRequests = 0;
+        for (const batch of this.requests.values()) {
+            pendingRequests += batch.length;
+        }
+        const averageBatchSize = this.stats.totalBatches > 0
+            ? this.stats.totalRequests / this.stats.totalBatches
+            : 0;
+        return {
+            totalRequests: this.stats.totalRequests,
+            totalBatches: this.stats.totalBatches,
+            averageBatchSize,
+            pendingRequests,
+        };
+    }
+}
+/**
+ * Create batching middleware.
+ *
+ * Automatically combines multiple requests into batches for efficiency.
+ *
+ * @param options - Batching configuration
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * client.use(createBatchingMiddleware({
+ *   maxBatchSize: 10,      // Combine up to 10 requests
+ *   maxWaitTime: 10,       // Wait max 10ms before sending
+ *   sameServiceOnly: true  // Only batch requests to same service
+ * }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom batching by operation
+ * client.use(createBatchingMiddleware({
+ *   getBatchKey: (msg) => `${msg.method.service}:${msg.method.operation}`
+ * }));
+ * ```
+ */
+export function createBatchingMiddleware(options = {}) {
+    const sameServiceOnly = options.sameServiceOnly ?? true;
+    const opts = {
+        maxBatchSize: options.maxBatchSize ?? 10,
+        maxWaitTime: options.maxWaitTime ?? 10,
+        sameServiceOnly,
+        getBatchKey: options.getBatchKey ??
+            ((msg) => sameServiceOnly
+                ? msg.method.service
+                : "__all__"),
+        ...(options.onBatchSent !== undefined && { onBatchSent: options.onBatchSent }),
+    };
+    /**
+     * Process a batch of requests.
+     */
+    async function processBatch(_key, requests) {
+        // Note: This is a simplified implementation.
+        // In practice, you'd need transport-level support for batching.
+        // The transport would need to:
+        // 1. Accept multiple messages
+        // 2. Send them in a single network request
+        // 3. Return multiple responses
+        // 4. Match responses to requests by ID
+        // For now, we execute requests individually
+        // Real batching requires transport cooperation
+        for (const request of requests) {
+            try {
+                const response = request.next(request.context);
+                request.resolve(response);
+            }
+            catch (error) {
+                request.reject(error);
+            }
+        }
+    }
+    // Create shared batch queue
+    const queue = new BatchQueue(opts, processBatch);
+    return (next) => {
+        return async function* (context) {
+            // Get batch key for this request
+            const key = opts.getBatchKey(context.message);
+            // Create promise for batched response
+            const responsePromise = new Promise((resolve, reject) => {
+                queue.add(key, {
+                    context,
+                    next: next,
+                    resolve: resolve,
+                    reject,
+                });
+            });
+            // Wait for batch to complete and yield response
+            const response = await responsePromise;
+            yield* response;
+        };
+    };
+}
+/**
+ * Get batching statistics.
+ *
+ * Note: This is a placeholder - proper implementation would
+ * require exposing the queue through the middleware instance.
+ */
+export function getBatchingStats(_middleware) {
+    return null;
+}
+/**
+ * Create adaptive batching middleware.
+ *
+ * Automatically adjusts batch size based on request patterns.
+ *
+ * @example
+ * ```typescript
+ * client.use(createAdaptiveBatchingMiddleware({
+ *   minBatchSize: 2,
+ *   maxBatchSize: 50,
+ *   targetLatency: 20  // Target 20ms latency
+ * }));
+ * ```
+ */
+export function createAdaptiveBatchingMiddleware(options = {}) {
+    const { minBatchSize = 2, maxBatchSize = 50, targetLatency = 20, } = options;
+    let currentBatchSize = minBatchSize;
+    let recentLatencies = [];
+    /**
+     * Adjust batch size based on latency.
+     */
+    function adjustBatchSize() {
+        if (recentLatencies.length < 5) {
+            return;
+        }
+        const avgLatency = recentLatencies.reduce((sum, l) => sum + l, 0) / recentLatencies.length;
+        if (avgLatency > targetLatency && currentBatchSize > minBatchSize) {
+            // Too slow - reduce batch size
+            currentBatchSize = Math.max(minBatchSize, currentBatchSize - 1);
+        }
+        else if (avgLatency < targetLatency * 0.5 && currentBatchSize < maxBatchSize) {
+            // Too fast - increase batch size
+            currentBatchSize = Math.min(maxBatchSize, currentBatchSize + 1);
+        }
+        // Keep only recent latencies
+        recentLatencies = recentLatencies.slice(-10);
+    }
+    return (next) => {
+        const batchingMiddleware = createBatchingMiddleware({
+            maxBatchSize: currentBatchSize,
+            maxWaitTime: targetLatency,
+        });
+        return async function* (context) {
+            const start = Date.now();
+            try {
+                const batchedNext = batchingMiddleware(next);
+                yield* batchedNext(context);
+            }
+            finally {
+                const latency = Date.now() - start;
+                recentLatencies.push(latency);
+                adjustBatchSize();
+            }
+        };
+    };
+}
+//# sourceMappingURL=batching.js.map

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

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

package/dist/client/middleware/cache.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Universal Cache Middleware
+ *
+ * Protocol-agnostic caching with LRU eviction and TTL expiration.
+ * Works with any transport!
+ */
+import type { ResponseItem, Metadata, Method, TypedClientMiddleware } from "../types.js";
+import type { CacheContext } from "./contexts.js";
+/**
+ * Cache middleware options.
+ */
+export interface CacheOptions {
+    /**
+     * The methods whose responses the middleware caches: a list of `"service.operation"` names,
+     * or a predicate. Caching is opt-in for each method: before, the middleware cached every
+     * call, mutations too (deep dive TRN-5).
+     */
+    methods: readonly string[] | ((method: Method) => boolean);
+    /**
+     * Time-to-live for cache entries in milliseconds. A call can give its own: `cache: { ttl }`.
+     * @default 60000 (1 minute)
+     */
+    ttl?: number;
+    /**
+     * Maximum number of cache entries (LRU eviction when exceeded).
+     * @default 100
+     */
+    capacity?: number;
+    /**
+     * Optional callback for cache statistics.
+     * Called periodically with hit/miss/eviction metrics.
+     */
+    onStats?: (stats: CacheStats) => void;
+    /**
+     * Interval in milliseconds for emitting cache statistics.
+     * Only used if onStats is provided.
+     * @default 60000 (1 minute)
+     */
+    statsInterval?: number;
+    /**
+     * Custom cache key generator.
+     * Default: the method, the payload and the request metadata (see `defaultKeyGenerator`).
+     *
+     * @param method - Method being called
+     * @param payload - Request payload
+     * @param metadata - Request metadata (auth, pagination, custom fields)
+     * @returns Cache key string
+     */
+    keyGenerator?: (method: Method, payload: unknown, metadata: Metadata) => string;
+    /**
+     * Predicate to determine if a response should be cached.
+     * Default: Only cache successful responses
+     *
+     * @param item - Response item
+     * @returns true if response should be cached
+     */
+    shouldCache?: (item: ResponseItem<unknown>) => boolean;
+}
+/**
+ * Cache performance statistics.
+ */
+export interface CacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Current cache size */
+    size: number;
+    /** Number of entries evicted */
+    evictions: number;
+    /** Hit rate as a percentage (0-100) */
+    hitRate: number;
+}
+/**
+ * Deterministic stringify for cache keys: recursively sorts object keys at every depth, so
+ * payloads that are structurally equal (regardless of key order) map to the same key, and
+ * null / primitive / array payloads are handled without throwing.
+ *
+ * Replaces a prior `JSON.stringify(payload, Object.keys(payload).sort())` which misused the
+ * array-replacer form of JSON.stringify: that filters keys at *every* depth (so `{filter:{a:1}}`
+ * and `{filter:{b:2}}` collided to the same key and returned each other's cached response) and
+ * threw `TypeError` on null/primitive payloads. See documentation/BUGS-2026-07.md (C1).
+ */
+export declare function stableStringify(value: unknown): string;
+/**
+ * Default cache key generator: the method, the payload and the metadata that can change the
+ * response. Before, the key ignored the metadata: with `withContext({ auth })`, one user got
+ * the cached response of another user, and a pagination cursor in the metadata returned the
+ * first page forever (deep dive TRN-5).
+ */
+export declare function defaultKeyGenerator(method: Method, payload: unknown, metadata?: Metadata): string;
+/**
+ * Create cache middleware with LRU eviction and TTL expiration.
+ *
+ * Memory management:
+ * - LRU eviction when capacity is reached (bounded memory, a small map of the core)
+ * - Each entry has its own expiry time, so a call can give its own TTL
+ *
+ * Each call can give overrides in its context (`route()` overrides, or `withContext`):
+ * `cache: { ttl }` for the entry that it stores, `cache: { bypass: true }` to skip the cache, and
+ * `cache: { refresh: true }` to fetch and replace the stored response. After the call, the
+ * context has `cache.hit` (CacheContext).
+ *
+ * Features:
+ * - Protocol-agnostic: Works with HTTP, gRPC, WebSocket, local
+ * - Automatic eviction: LRU + TTL composition
+ * - Observable: Optional stats callback
+ * - Customizable: Custom key generation and cache predicates
+ *
+ * @param options - Cache configuration options
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * client.use(createCacheMiddleware({
+ *   methods: ["users.get", "users.list"], // only these calls are cached
+ *   capacity: 100,
+ *   ttl: 60000, // 1 minute
+ *   onStats: (stats) => console.log(`Hit rate: ${stats.hitRate}%`)
+ * }));
+ * ```
+ */
+export declare function createCacheMiddleware(options: CacheOptions): TypedClientMiddleware<CacheContext, {}>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/client/middleware/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/client/middleware/cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAA+B,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACtH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;IAE3D;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAEtC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK,MAAM,CAAC;IAEhF;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC;CACxD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAetD;AAkBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAOjG;AAmCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,qBAAqB,CAAC,YAAY,EAAE,EAAE,CAAC,CA6GpG"}

package/dist/client/middleware/cache.js

@@ -0,0 +1,208 @@
+/**
+ * Universal Cache Middleware
+ *
+ * Protocol-agnostic caching with LRU eviction and TTL expiration.
+ * Works with any transport!
+ */
+import { LruMap } from "./lru.js";
+/**
+ * Deterministic stringify for cache keys: recursively sorts object keys at every depth, so
+ * payloads that are structurally equal (regardless of key order) map to the same key, and
+ * null / primitive / array payloads are handled without throwing.
+ *
+ * Replaces a prior `JSON.stringify(payload, Object.keys(payload).sort())` which misused the
+ * array-replacer form of JSON.stringify: that filters keys at *every* depth (so `{filter:{a:1}}`
+ * and `{filter:{b:2}}` collided to the same key and returned each other's cached response) and
+ * threw `TypeError` on null/primitive payloads. See documentation/BUGS-2026-07.md (C1).
+ */
+export function stableStringify(value) {
+    if (typeof value === "bigint")
+        return `${value}n`;
+    if (value === null || typeof value !== "object") {
+        // Primitives — and undefined/function/symbol (JSON.stringify → undefined): never throw.
+        return JSON.stringify(value) ?? String(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    const obj = value;
+    const body = Object.keys(obj)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`)
+        .join(",");
+    return `{${body}}`;
+}
+/**
+ * The metadata keys that do not change a response: middleware state and tracing. The other
+ * keys (auth, pagination, custom fields) are part of the cache key.
+ */
+const VOLATILE_METADATA = new Set(["retry", "timeout", "tracing", "cache", "circuitBreaker", "rateLimit"]);
+/** The part of the metadata that can change a response. */
+function keyMetadata(metadata) {
+    const out = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (VOLATILE_METADATA.has(key) || key.startsWith("__") || value === undefined)
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Default cache key generator: the method, the payload and the metadata that can change the
+ * response. Before, the key ignored the metadata: with `withContext({ auth })`, one user got
+ * the cached response of another user, and a pagination cursor in the metadata returned the
+ * first page forever (deep dive TRN-5).
+ */
+export function defaultKeyGenerator(method, payload, metadata) {
+    const methodKey = method.version
+        ? `${method.version}:${method.service}.${method.operation}`
+        : `${method.service}.${method.operation}`;
+    const base = `${methodKey}:${stableStringify(payload)}`;
+    return metadata ? `${base}|${stableStringify(keyMetadata(metadata))}` : base;
+}
+/** A deep copy of a cache entry, or undefined when the payload cannot be copied. */
+function copyItem(item) {
+    try {
+        return structuredClone(item);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The overrides of one call: `cache: { ttl, bypass, refresh }` in its context. */
+function cacheOverrides(value) {
+    if (typeof value !== "object" || value === null)
+        return {};
+    const { ttl, bypass, refresh } = value;
+    return {
+        ...(typeof ttl === "number" && ttl >= 0 ? { ttl } : {}),
+        ...(bypass === true ? { bypass: true } : {}),
+        ...(refresh === true ? { refresh: true } : {}),
+    };
+}
+/**
+ * Default should cache predicate - only cache successful responses.
+ */
+function defaultShouldCache(item) {
+    return item.status.type === "success";
+}
+/**
+ * Create cache middleware with LRU eviction and TTL expiration.
+ *
+ * Memory management:
+ * - LRU eviction when capacity is reached (bounded memory, a small map of the core)
+ * - Each entry has its own expiry time, so a call can give its own TTL
+ *
+ * Each call can give overrides in its context (`route()` overrides, or `withContext`):
+ * `cache: { ttl }` for the entry that it stores, `cache: { bypass: true }` to skip the cache, and
+ * `cache: { refresh: true }` to fetch and replace the stored response. After the call, the
+ * context has `cache.hit` (CacheContext).
+ *
+ * Features:
+ * - Protocol-agnostic: Works with HTTP, gRPC, WebSocket, local
+ * - Automatic eviction: LRU + TTL composition
+ * - Observable: Optional stats callback
+ * - Customizable: Custom key generation and cache predicates
+ *
+ * @param options - Cache configuration options
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * client.use(createCacheMiddleware({
+ *   methods: ["users.get", "users.list"], // only these calls are cached
+ *   capacity: 100,
+ *   ttl: 60000, // 1 minute
+ *   onStats: (stats) => console.log(`Hit rate: ${stats.hitRate}%`)
+ * }));
+ * ```
+ */
+export function createCacheMiddleware(options) {
+    const { methods, ttl = 60000, capacity = 100, onStats, statsInterval = 60000, keyGenerator = defaultKeyGenerator, shouldCache = defaultShouldCache, } = options;
+    // An LRU map bounds the memory. Each entry keeps its own expiry time, so a call can give its
+    // own TTL: before, one TTL map expired every entry after the TTL of the middleware.
+    const cache = new LruMap(capacity, () => {
+        stats.evictions++;
+    });
+    // Track cache statistics
+    const stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+    };
+    // Emit stats periodically if callback provided
+    if (onStats) {
+        const statsTimer = setInterval(() => {
+            const total = stats.hits + stats.misses;
+            const hitRate = total > 0 ? (stats.hits / total) * 100 : 0;
+            onStats({
+                hits: stats.hits,
+                misses: stats.misses,
+                size: cache.size,
+                evictions: stats.evictions,
+                hitRate: Math.round(hitRate * 100) / 100, // Round to 2 decimal places
+            });
+        }, statsInterval);
+        // Unref so the stats timer never keeps the process alive on its own (its lifecycle is tied
+        // to the client, not the event loop). See documentation/BUGS-2026-07.md (M4).
+        statsTimer.unref?.();
+    }
+    const cacheable = typeof methods === "function"
+        ? methods
+        : ((names) => (method) => names.has(`${method.service}.${method.operation}`))(new Set(methods));
+    return (next) => {
+        return async function* (context) {
+            if (!cacheable(context.message.method)) {
+                yield* next(context);
+                return;
+            }
+            const metadata = context.message.metadata;
+            const overrides = cacheOverrides(metadata["cache"]);
+            // The state for the outer middlewares (CacheContext). The key is not written: it holds the
+            // payload, and the metadata of a retry travels in a header.
+            const setState = (hit) => {
+                metadata["cache"] = { ...overrides, hit };
+            };
+            if (overrides.bypass) {
+                yield* next(context);
+                setState(false);
+                return;
+            }
+            // Generate cache key
+            const cacheKey = keyGenerator(context.message.method, context.message.payload, metadata);
+            // Check cache - use has() to avoid throwing "Key not found" error. A refresh skips the read.
+            if (!overrides.refresh && cache.has(cacheKey)) {
+                const cached = cache.get(cacheKey);
+                if (cached && cached.expiresAt > Date.now()) {
+                    // Cache hit - yield a copy: a caller that changes its result does not change the cache
+                    stats.hits++;
+                    setState(true);
+                    for (const item of cached.items) {
+                        yield (copyItem(item) ?? item);
+                    }
+                    return;
+                }
+                // Expired
+                cache.delete(cacheKey);
+            }
+            // Cache miss - fetch and store. Only a response of one item is cached: a stream is never
+            // collected or cached (before, the middleware kept every item of a stream in memory).
+            stats.misses++;
+            let first;
+            let count = 0;
+            for await (const item of next(context)) {
+                count++;
+                if (count === 1)
+                    first = item;
+                yield item;
+            }
+            setState(false);
+            if (count === 1 && first && shouldCache(first)) {
+                const copy = copyItem(first);
+                if (copy)
+                    cache.set(cacheKey, { items: [copy], expiresAt: Date.now() + (overrides.ttl ?? ttl) });
+            }
+        };
+    };
+}
+//# sourceMappingURL=cache.js.map

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

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