@procedures/client 0.0.0-stage → 0.2.0

package/dist/client/middleware/circuit-breaker.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Circuit Breaker Middleware
+ *
+ * Prevents cascading failures by failing fast when a service is unhealthy.
+ * Implements the circuit breaker pattern with three states:
+ * - CLOSED: Normal operation (requests pass through)
+ * - OPEN: Service unhealthy (requests fail immediately)
+ * - HALF_OPEN: Testing if service recovered (limited requests)
+ *
+ * Works with both client and server!
+ */
+import type { ClientMiddleware, TypedClientMiddleware } from "../types.js";
+import type { CircuitBreakerContext } from "./contexts.js";
+/**
+ * Circuit breaker state.
+ */
+export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/**
+ * Circuit breaker options.
+ */
+export interface CircuitBreakerOptions {
+    /**
+     * Number of failures before opening circuit.
+     * @default 5
+     */
+    failureThreshold?: number;
+    /**
+     * Time window for counting failures (in milliseconds).
+     * @default 10000 (10 seconds)
+     */
+    failureWindow?: number;
+    /**
+     * Time to wait before attempting to close circuit (in milliseconds).
+     * @default 30000 (30 seconds)
+     */
+    resetTimeout?: number;
+    /**
+     * Number of successful requests required to close circuit from HALF_OPEN.
+     * @default 2
+     */
+    successThreshold?: number;
+    /**
+     * Number of probe requests that run at the same time in HALF_OPEN. The other requests fail
+     * fast with a CircuitBreakerError until a probe ends.
+     * @default successThreshold
+     */
+    halfOpenMaxRequests?: number;
+    /**
+     * Custom error predicate.
+     * Return true if error should count as failure.
+     * @default All errors count as failures
+     */
+    isFailure?: (error: Error) => boolean;
+    /**
+     * Callback when circuit state changes.
+     */
+    onStateChange?: (oldState: CircuitState, newState: CircuitState) => void;
+}
+/**
+ * Circuit breaker statistics.
+ */
+export interface CircuitBreakerStats {
+    state: CircuitState;
+    failures: number;
+    successes: number;
+    totalRequests: number;
+    lastFailureTime: number | null;
+    lastStateChange: number;
+}
+/**
+ * Circuit breaker error thrown when circuit is open.
+ */
+export declare class CircuitBreakerError extends Error {
+    readonly state: CircuitState;
+    readonly lastError: Error | null;
+    constructor(state: CircuitState, lastError: Error | null);
+}
+/**
+ * Create circuit breaker middleware.
+ *
+ * Automatically opens circuit when failure threshold is reached,
+ * preventing requests from reaching unhealthy services.
+ *
+ * @param options - Circuit breaker configuration
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * client.use(createCircuitBreakerMiddleware({
+ *   failureThreshold: 5,      // Open after 5 failures
+ *   failureWindow: 10000,      // Within 10 seconds
+ *   resetTimeout: 30000,       // Try again after 30 seconds
+ *   successThreshold: 2        // Close after 2 successes
+ * }));
+ * ```
+ */
+export declare function createCircuitBreakerMiddleware(options?: CircuitBreakerOptions): TypedClientMiddleware<CircuitBreakerContext, {}>;
+/**
+ * Get circuit breaker statistics.
+ *
+ * Note: This requires storing the middleware instance to access stats.
+ *
+ * @example
+ * ```typescript
+ * const breaker = createCircuitBreakerMiddleware();
+ * client.use(breaker);
+ *
+ * // Later...
+ * const stats = getCircuitBreakerStats(breaker);
+ * ```
+ */
+export declare function getCircuitBreakerStats(middleware: ClientMiddleware | TypedClientMiddleware<CircuitBreakerContext, {}>): CircuitBreakerStats | null;
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/client/middleware/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/client/middleware/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAA+B,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IAEtC;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;CAC1E;AAUD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,KAAK,EAAE,YAAY;aACnB,SAAS,EAAE,KAAK,GAAG,IAAI;IAFzC,YACkB,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,KAAK,GAAG,IAAI,EAMxC;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,qBAA0B,GAClC,qBAAqB,CAAC,qBAAqB,EAAE,EAAE,CAAC,CA8LlD;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,gBAAgB,GAAG,qBAAqB,CAAC,qBAAqB,EAAE,EAAE,CAAC,GAC9E,mBAAmB,GAAG,IAAI,CAG5B"}

package/dist/client/middleware/circuit-breaker.js

@@ -0,0 +1,236 @@
+/**
+ * Circuit Breaker Middleware
+ *
+ * Prevents cascading failures by failing fast when a service is unhealthy.
+ * Implements the circuit breaker pattern with three states:
+ * - CLOSED: Normal operation (requests pass through)
+ * - OPEN: Service unhealthy (requests fail immediately)
+ * - HALF_OPEN: Testing if service recovered (limited requests)
+ *
+ * Works with both client and server!
+ */
+/**
+ * Circuit breaker error thrown when circuit is open.
+ */
+export class CircuitBreakerError extends Error {
+    state;
+    lastError;
+    constructor(state, lastError) {
+        super(`Circuit breaker is ${state}${lastError ? `: ${lastError.message}` : ""}`);
+        this.state = state;
+        this.lastError = lastError;
+        this.name = "CircuitBreakerError";
+    }
+}
+/**
+ * Create circuit breaker middleware.
+ *
+ * Automatically opens circuit when failure threshold is reached,
+ * preventing requests from reaching unhealthy services.
+ *
+ * @param options - Circuit breaker configuration
+ * @returns Middleware function
+ *
+ * @example
+ * ```typescript
+ * client.use(createCircuitBreakerMiddleware({
+ *   failureThreshold: 5,      // Open after 5 failures
+ *   failureWindow: 10000,      // Within 10 seconds
+ *   resetTimeout: 30000,       // Try again after 30 seconds
+ *   successThreshold: 2        // Close after 2 successes
+ * }));
+ * ```
+ */
+export function createCircuitBreakerMiddleware(options = {}) {
+    const { failureThreshold = 5, failureWindow = 10000, resetTimeout = 30000, successThreshold = 2, isFailure = () => true, onStateChange, } = options;
+    const halfOpenMaxRequests = options.halfOpenMaxRequests ?? successThreshold;
+    let state = "CLOSED";
+    let failures = [];
+    let successes = 0;
+    let totalRequests = 0;
+    let probesInFlight = 0;
+    let lastStateChange = Date.now();
+    let resetTimer = null;
+    /**
+     * Change circuit state.
+     */
+    function setState(newState) {
+        const oldState = state;
+        state = newState;
+        if (oldState !== newState)
+            lastStateChange = Date.now();
+        if (oldState !== newState && onStateChange) {
+            onStateChange(oldState, newState);
+        }
+        // Clear reset timer when moving to CLOSED
+        if (newState === "CLOSED" && resetTimer) {
+            clearTimeout(resetTimer);
+            resetTimer = null;
+        }
+    }
+    /**
+     * Record a failure.
+     */
+    function recordFailure(error) {
+        const now = Date.now();
+        // Add failure
+        failures.push({ timestamp: now, error });
+        // Remove old failures outside window
+        failures = failures.filter((f) => now - f.timestamp < failureWindow);
+        if (state === "HALF_OPEN") {
+            // Any failure while testing reopens the circuit immediately — don't wait for the full
+            // failureThreshold. See documentation/BUGS-2026-07.md (H11).
+            setState("OPEN");
+            successes = 0;
+            scheduleReset();
+        }
+        else if (state === "CLOSED" && failures.length >= failureThreshold) {
+            setState("OPEN");
+            scheduleReset();
+        }
+    }
+    /**
+     * Record a success.
+     */
+    function recordSuccess() {
+        if (state === "HALF_OPEN") {
+            successes++;
+            if (successes >= successThreshold) {
+                // Enough successes - close circuit
+                setState("CLOSED");
+                failures = [];
+                successes = 0;
+            }
+        }
+        else if (state === "CLOSED") {
+            // Clear old failures on success
+            const now = Date.now();
+            failures = failures.filter((f) => now - f.timestamp < failureWindow);
+        }
+    }
+    /**
+     * Schedule circuit reset attempt.
+     */
+    function scheduleReset() {
+        if (resetTimer) {
+            clearTimeout(resetTimer);
+        }
+        resetTimer = setTimeout(() => {
+            if (state === "OPEN") {
+                setState("HALF_OPEN");
+                successes = 0;
+            }
+        }, resetTimeout);
+        // Don't keep the event loop alive just for the reset timer. See BUGS-2026-07.md (M4).
+        resetTimer.unref?.();
+    }
+    /**
+     * Check if request should be allowed. In HALF_OPEN, only `halfOpenMaxRequests` probes run at
+     * the same time: the other requests fail fast until a probe ends (deep dive TRN-4: before,
+     * HALF_OPEN let all traffic through).
+     */
+    function shouldAllowRequest() {
+        if (state === "CLOSED") {
+            return true;
+        }
+        if (state === "OPEN") {
+            return false;
+        }
+        return probesInFlight < halfOpenMaxRequests;
+    }
+    function getStats() {
+        const now = Date.now();
+        return {
+            state,
+            failures: failures.filter((f) => now - f.timestamp < failureWindow).length,
+            successes,
+            totalRequests,
+            lastFailureTime: failures.length > 0 ? failures[failures.length - 1].timestamp : null,
+            lastStateChange,
+        };
+    }
+    const middleware = (next) => {
+        return async function* (context) {
+            totalRequests++;
+            // The state for the other middlewares (CircuitBreakerContext)
+            const writeState = () => {
+                const now = Date.now();
+                context.message.metadata["circuitBreaker"] = {
+                    state,
+                    failures: failures.filter((f) => now - f.timestamp < failureWindow).length,
+                    successes,
+                };
+            };
+            writeState();
+            // Check if circuit allows request
+            if (!shouldAllowRequest()) {
+                const lastFailure = failures.length > 0 ? failures[failures.length - 1] : null;
+                const lastError = lastFailure != null ? lastFailure.error : null;
+                throw new CircuitBreakerError(state, lastError);
+            }
+            const probe = state === "HALF_OPEN";
+            if (probe)
+                probesInFlight++;
+            // The outcome is recorded once, as soon as it is known. Transports report failures as
+            // error items (BUGS-2026-07 H11), and a Client with throwOnError stops reading at the
+            // error item: the generator then gets return() at the yield, and code after the loop
+            // never runs. So the failure is recorded before the error item goes out (deep dive TRN-4).
+            let recorded = false;
+            const fail = (error) => {
+                if (recorded)
+                    return;
+                recorded = true;
+                if (isFailure(error))
+                    recordFailure(error);
+            };
+            try {
+                for await (const item of next(context)) {
+                    if (item.status.type === "error") {
+                        const err = new Error(item.status.message);
+                        err.code = item.status.code;
+                        fail(err);
+                    }
+                    yield item;
+                }
+            }
+            catch (error) {
+                // A thrown error (transport-level, not an error-status item) also counts as a failure.
+                fail(error);
+                throw error;
+            }
+            finally {
+                if (probe)
+                    probesInFlight--;
+                // The stream ended, or the reader stopped early, with no error: a success
+                if (!recorded) {
+                    recorded = true;
+                    recordSuccess();
+                }
+                writeState();
+            }
+        };
+    };
+    statsOf.set(middleware, getStats);
+    return middleware;
+}
+/** The stats function of each circuit breaker middleware */
+const statsOf = new WeakMap();
+/**
+ * Get circuit breaker statistics.
+ *
+ * Note: This requires storing the middleware instance to access stats.
+ *
+ * @example
+ * ```typescript
+ * const breaker = createCircuitBreakerMiddleware();
+ * client.use(breaker);
+ *
+ * // Later...
+ * const stats = getCircuitBreakerStats(breaker);
+ * ```
+ */
+export function getCircuitBreakerStats(middleware) {
+    // Before, this function always returned null (deep dive TRN-4)
+    return statsOf.get(middleware)?.() ?? null;
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/client/middleware/circuit-breaker.js.map

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

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

@@ -0,0 +1,199 @@
+/**
+ * Middleware Context Types
+ *
+ * Each middleware declares what context it provides and requires through
+ * these type definitions. This enables compile-time validation of middleware
+ * chains and type-safe context accumulation.
+ *
+ * @example
+ * ```typescript
+ * // Middleware composition with type accumulation
+ * const client = new Client(transport)
+ *   .use(createRetryMiddleware())     // Client<BaseContext & RetryContext>
+ *   .use(createCacheMiddleware({ methods: ["users.get"] }))     // Client<... & CacheContext>
+ *   .use(createAuthMiddleware(...))   // Client<... & AuthContext>
+ * ```
+ */
+/**
+ * Context provided by retry middleware.
+ * Tracks retry state for observability and dependent middleware.
+ */
+export interface RetryContext {
+    retry: {
+        /** Current attempt number (0-indexed). The middleware writes it: a call does not give it. */
+        attempt?: number;
+        /** Maximum number of attempts: an override of a call, then the value that the middleware uses */
+        maxAttempts?: number;
+        /** An override of the base delay, in milliseconds */
+        delay?: number;
+        /** An override of the factor of the delay from one attempt to the next */
+        backoffMultiplier?: number;
+        /** An override of the longest delay, in milliseconds */
+        maxDelay?: number;
+    };
+}
+/**
+ * Context of the cache middleware: the overrides of a call, and the state after it.
+ *
+ * The cache key is not in the context: it holds the payload, and the metadata of a retry
+ * travels in a header of limited size. (Before, the type named a `key` that the middleware
+ * never wrote.)
+ */
+export interface CacheContext {
+    cache: {
+        /** The time-to-live of the entry that this call stores, in milliseconds */
+        ttl?: number;
+        /** True: the call skips the cache (no read, no write) */
+        bypass?: boolean;
+        /** True: the call fetches and replaces the stored response */
+        refresh?: boolean;
+        /** After the call: whether the response came from the cache */
+        hit?: boolean;
+    };
+}
+/**
+ * Context provided by timeout middleware.
+ * Tracks timeout configuration.
+ */
+export interface TimeoutContext {
+    timeout: {
+        /** Overall timeout in milliseconds (if configured) */
+        overall?: number;
+        /** Per-attempt timeout in milliseconds (if configured) */
+        perAttempt?: number;
+    };
+}
+/**
+ * Context provided by auth middleware.
+ * Contains authentication credentials added to requests.
+ */
+export interface AuthContext {
+    auth: {
+        /** Bearer token (if provided) */
+        token?: string;
+        /** API key (if provided) */
+        apiKey?: string;
+        /** User ID (if provided) */
+        userId?: string;
+        /** Additional custom auth fields */
+        [key: string]: unknown;
+    };
+}
+/**
+ * Context provided by tracing middleware.
+ * Contains distributed tracing identifiers.
+ */
+export interface TracingContext {
+    tracing: {
+        /** Trace ID for the entire distributed trace */
+        traceId: string;
+        /** Span ID for this specific operation */
+        spanId: string;
+        /** Parent span ID (if continuing existing trace) */
+        parentSpanId?: string;
+    };
+}
+/**
+ * Circuit breaker state values.
+ */
+export type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/**
+ * Context provided by circuit breaker middleware: the middleware writes the state when it
+ * admits a call, and again when the call ends.
+ */
+export interface CircuitBreakerContext {
+    circuitBreaker: {
+        /** Current circuit state */
+        state: CircuitState;
+        /** Number of recent failures */
+        failures: number;
+        /** Number of successes in HALF_OPEN state */
+        successes: number;
+    };
+}
+/**
+ * Context provided by rate limit middleware: the middleware writes the state when a call gets
+ * its token.
+ */
+export interface RateLimitContext {
+    rateLimit: {
+        /** Tokens currently available */
+        tokensAvailable: number;
+        /** Maximum tokens */
+        maxTokens: number;
+        /** Requests currently queued */
+        queueSize: number;
+    };
+}
+/**
+ * Context provided by pagination middleware: the normalized page (or offset) and limit, as one
+ * object. The middleware writes the single keys (`page`, `limit`, `offset`) too.
+ */
+export interface PaginationContext {
+    pagination: {
+        /** Current page (for page-based pagination) */
+        page?: number;
+        /** Current offset (for offset-based pagination) */
+        offset?: number;
+        /** Page size limit */
+        limit: number;
+    };
+}
+/**
+ * Context provided by Zod validation middleware.
+ * Re-exported from validation module for consistency.
+ */
+export type { ZodValidationContext } from "../validation/types.js";
+/**
+ * Base context that all clients start with.
+ * Contains the minimum required context for any request.
+ */
+export interface BaseClientContext {
+    /** The request message being processed */
+    message: {
+        id: string;
+        method: {
+            service: string;
+            operation: string;
+            version?: string;
+        };
+        payload: unknown;
+        metadata: Record<string, unknown>;
+        signal?: AbortSignal;
+    };
+}
+/**
+ * Union of all middleware contexts.
+ * Useful for type guards and runtime checks.
+ */
+export type AnyMiddlewareContext = RetryContext | CacheContext | TimeoutContext | AuthContext | TracingContext | CircuitBreakerContext | RateLimitContext | PaginationContext;
+/**
+ * All middleware contexts combined.
+ * Represents a fully-configured client with all middleware.
+ */
+export type FullContext = BaseClientContext & RetryContext & CacheContext & TimeoutContext & AuthContext & TracingContext & CircuitBreakerContext & RateLimitContext & PaginationContext;
+/**
+ * Check if context has retry information.
+ */
+export declare function hasRetryContext(ctx: unknown): ctx is RetryContext;
+/**
+ * Check if context has cache information.
+ */
+export declare function hasCacheContext(ctx: unknown): ctx is CacheContext;
+/**
+ * Check if context has auth information.
+ */
+export declare function hasAuthContext(ctx: unknown): ctx is AuthContext;
+/**
+ * Check if context has tracing information.
+ */
+export declare function hasTracingContext(ctx: unknown): ctx is TracingContext;
+/**
+ * Check if context has circuit breaker information.
+ */
+export declare function hasCircuitBreakerContext(ctx: unknown): ctx is CircuitBreakerContext;
+/**
+ * Check if context has rate limit information.
+ */
+export declare function hasRateLimitContext(ctx: unknown): ctx is RateLimitContext;
+//# sourceMappingURL=contexts.d.ts.map

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

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

package/dist/client/middleware/contexts.js

@@ -0,0 +1,74 @@
+/**
+ * Middleware Context Types
+ *
+ * Each middleware declares what context it provides and requires through
+ * these type definitions. This enables compile-time validation of middleware
+ * chains and type-safe context accumulation.
+ *
+ * @example
+ * ```typescript
+ * // Middleware composition with type accumulation
+ * const client = new Client(transport)
+ *   .use(createRetryMiddleware())     // Client<BaseContext & RetryContext>
+ *   .use(createCacheMiddleware({ methods: ["users.get"] }))     // Client<... & CacheContext>
+ *   .use(createAuthMiddleware(...))   // Client<... & AuthContext>
+ * ```
+ */
+// =============================================================================
+// Context Type Guards
+// =============================================================================
+/**
+ * Check if context has retry information.
+ */
+export function hasRetryContext(ctx) {
+    return (typeof ctx === "object" &&
+        ctx !== null &&
+        "retry" in ctx &&
+        typeof ctx.retry === "object");
+}
+/**
+ * Check if context has cache information.
+ */
+export function hasCacheContext(ctx) {
+    return (typeof ctx === "object" &&
+        ctx !== null &&
+        "cache" in ctx &&
+        typeof ctx.cache === "object");
+}
+/**
+ * Check if context has auth information.
+ */
+export function hasAuthContext(ctx) {
+    return (typeof ctx === "object" &&
+        ctx !== null &&
+        "auth" in ctx &&
+        typeof ctx.auth === "object");
+}
+/**
+ * Check if context has tracing information.
+ */
+export function hasTracingContext(ctx) {
+    return (typeof ctx === "object" &&
+        ctx !== null &&
+        "tracing" in ctx &&
+        typeof ctx.tracing === "object");
+}
+/**
+ * Check if context has circuit breaker information.
+ */
+export function hasCircuitBreakerContext(ctx) {
+    return (typeof ctx === "object" &&
+        ctx !== null &&
+        "circuitBreaker" in ctx &&
+        typeof ctx.circuitBreaker === "object");
+}
+/**
+ * Check if context has rate limit information.
+ */
+export function hasRateLimitContext(ctx) {
+    return (typeof ctx === "object" &&
+        ctx !== null &&
+        "rateLimit" in ctx &&
+        typeof ctx.rateLimit === "object");
+}
+//# sourceMappingURL=contexts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contexts.js","sourceRoot":"","sources":["../../../src/client/middleware/contexts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAqOH,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,OAAO,IAAI,GAAG;QACd,OAAQ,GAAoB,CAAC,KAAK,KAAK,QAAQ,CAChD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,OAAO,IAAI,GAAG;QACd,OAAQ,GAAoB,CAAC,KAAK,KAAK,QAAQ,CAChD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,IAAI,GAAG;QACb,OAAQ,GAAmB,CAAC,IAAI,KAAK,QAAQ,CAC9C,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,SAAS,IAAI,GAAG;QAChB,OAAQ,GAAsB,CAAC,OAAO,KAAK,QAAQ,CACpD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAY;IACnD,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,gBAAgB,IAAI,GAAG;QACvB,OAAQ,GAA6B,CAAC,cAAc,KAAK,QAAQ,CAClE,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,WAAW,IAAI,GAAG;QAClB,OAAQ,GAAwB,CAAC,SAAS,KAAK,QAAQ,CACxD,CAAC;AACJ,CAAC"}