@autonomaai/service-utils 1.0.0

package/dist/resilience/circuit-breaker.js

@@ -0,0 +1,267 @@
+/**
+ * Circuit Breaker Pattern
+ *
+ * Prevents cascading failures by failing fast when a service is down.
+ * After a threshold of failures, the circuit opens and rejects requests
+ * for a recovery period before allowing test requests through.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests flow through
+ * - OPEN: Service is down, fail immediately
+ * - HALF_OPEN: Testing if service recovered
+ *
+ * @example
+ * ```typescript
+ * const breaker = new CircuitBreaker({
+ *   name: 'exchange-api',
+ *   failureThreshold: 5,
+ *   recoveryTimeout: 30000,
+ *   halfOpenMaxCalls: 3
+ * });
+ *
+ * try {
+ *   const result = await breaker.execute(() => fetchData());
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerOpenError) {
+ *     // Use fallback
+ *     return getCachedData();
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+import { CircuitState, CircuitBreakerOpenError } from './types.js';
+const DEFAULT_CONFIG = {
+    failureThreshold: 5,
+    recoveryTimeout: 30000,
+    halfOpenMaxCalls: 3,
+    failureRateThreshold: 0.5,
+    excludedErrors: []
+};
+/**
+ * Circuit Breaker implementation
+ */
+export class CircuitBreaker {
+    static instances = new Map();
+    config;
+    state = CircuitState.CLOSED;
+    failureCount = 0;
+    successCount = 0;
+    lastFailureTime;
+    halfOpenCalls = 0;
+    stats = {
+        totalCalls: 0,
+        successfulCalls: 0,
+        failedCalls: 0,
+        rejectedCalls: 0,
+        state: CircuitState.CLOSED
+    };
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        CircuitBreaker.instances.set(this.config.name, this);
+    }
+    /**
+     * Get current circuit state
+     */
+    getState() {
+        if (this.state === CircuitState.OPEN) {
+            if (this.shouldAttemptRecovery()) {
+                this.transitionTo(CircuitState.HALF_OPEN);
+                this.halfOpenCalls = 0;
+            }
+        }
+        return this.state;
+    }
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats() {
+        return {
+            ...this.stats,
+            state: this.getState()
+        };
+    }
+    /**
+     * Execute a function through the circuit breaker
+     */
+    async execute(fn) {
+        // Wait for any concurrent state transition
+        const release = await this.acquireLock();
+        try {
+            const currentState = this.getState();
+            this.stats.totalCalls++;
+            if (currentState === CircuitState.OPEN) {
+                this.stats.rejectedCalls++;
+                const retryAfter = this.config.recoveryTimeout -
+                    (Date.now() - (this.lastFailureTime || 0));
+                throw new CircuitBreakerOpenError(this.config.name, Math.max(0, retryAfter));
+            }
+            if (currentState === CircuitState.HALF_OPEN) {
+                if (this.halfOpenCalls >= this.config.halfOpenMaxCalls) {
+                    this.stats.rejectedCalls++;
+                    throw new CircuitBreakerOpenError(this.config.name, this.config.recoveryTimeout);
+                }
+                this.halfOpenCalls++;
+            }
+        }
+        finally {
+            release();
+        }
+        try {
+            const result = await fn();
+            await this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            // Check if error should be excluded
+            if (this.isExcludedError(error)) {
+                throw error;
+            }
+            await this.onFailure();
+            throw error;
+        }
+    }
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset() {
+        this.transitionTo(CircuitState.CLOSED);
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.halfOpenCalls = 0;
+        this.lastFailureTime = undefined;
+        console.log(`Circuit breaker '${this.config.name}' manually reset`);
+    }
+    /**
+     * Check if recovery should be attempted
+     */
+    shouldAttemptRecovery() {
+        if (!this.lastFailureTime)
+            return true;
+        return Date.now() - this.lastFailureTime >= this.config.recoveryTimeout;
+    }
+    /**
+     * Handle successful execution
+     */
+    async onSuccess() {
+        const release = await this.acquireLock();
+        try {
+            this.successCount++;
+            this.stats.successfulCalls++;
+            this.stats.lastSuccessTime = Date.now();
+            if (this.state === CircuitState.HALF_OPEN) {
+                // Recovered - close the circuit
+                this.transitionTo(CircuitState.CLOSED);
+                this.failureCount = 0;
+                console.log(`Circuit breaker '${this.config.name}' recovered -> CLOSED`);
+            }
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Handle failed execution
+     */
+    async onFailure() {
+        const release = await this.acquireLock();
+        try {
+            this.failureCount++;
+            this.stats.failedCalls++;
+            this.stats.lastFailureTime = Date.now();
+            this.lastFailureTime = Date.now();
+            if (this.state === CircuitState.HALF_OPEN) {
+                // Failed during recovery - open again
+                this.transitionTo(CircuitState.OPEN);
+                console.warn(`Circuit breaker '${this.config.name}' failed during recovery -> OPEN`);
+            }
+            else if (this.state === CircuitState.CLOSED) {
+                if (this.failureCount >= this.config.failureThreshold) {
+                    this.transitionTo(CircuitState.OPEN);
+                    console.warn(`Circuit breaker '${this.config.name}' threshold reached -> OPEN`);
+                }
+            }
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Transition to a new state
+     */
+    transitionTo(newState) {
+        const oldState = this.state;
+        this.state = newState;
+        this.stats.state = newState;
+        // Call callbacks
+        switch (newState) {
+            case CircuitState.OPEN:
+                this.config.onOpen?.();
+                break;
+            case CircuitState.CLOSED:
+                this.config.onClose?.();
+                break;
+            case CircuitState.HALF_OPEN:
+                this.config.onHalfOpen?.();
+                break;
+        }
+    }
+    /**
+     * Check if error should be excluded from failure count
+     */
+    isExcludedError(error) {
+        if (!this.config.excludedErrors?.length)
+            return false;
+        return this.config.excludedErrors.some(ErrorClass => error instanceof ErrorClass);
+    }
+    /**
+     * Lock mechanism using a promise-based queue for atomic operations
+     */
+    lockQueue = Promise.resolve();
+    async acquireLock() {
+        let release = () => { };
+        const previousLock = this.lockQueue;
+        this.lockQueue = new Promise(resolve => {
+            release = resolve;
+        });
+        await previousLock;
+        return release;
+    }
+    /**
+     * Get stats for all circuit breakers (for monitoring)
+     */
+    static getAllStats() {
+        const stats = new Map();
+        for (const [name, breaker] of this.instances) {
+            stats.set(name, breaker.getStats());
+        }
+        return stats;
+    }
+    /**
+     * Get a circuit breaker by name
+     */
+    static get(name) {
+        return this.instances.get(name);
+    }
+}
+/**
+ * Decorator to apply circuit breaker to a method
+ */
+export function withCircuitBreaker(config) {
+    const breaker = new CircuitBreaker(config);
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            return breaker.execute(() => originalMethod.apply(this, args));
+        };
+        return descriptor;
+    };
+}
+/**
+ * Create a circuit breaker wrapper function
+ */
+export function createCircuitBreaker(config) {
+    const breaker = new CircuitBreaker(config);
+    return (fn) => breaker.execute(fn);
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/resilience/circuit-breaker.js.map

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

package/dist/resilience/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Resilience Patterns for TypeScript Services
+ *
+ * Provides circuit breaker, retry, bulkhead, rate limiting, and timeout patterns
+ * for building resilient microservices.
+ *
+ * @module @autonoma/service-utils/resilience
+ */
+export * from './circuit-breaker.js';
+export * from './retry.js';
+export * from './bulkhead.js';
+export * from './rate-limiter.js';
+export * from './timeout.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/resilience/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/resilience/index.js

@@ -0,0 +1,15 @@
+/**
+ * Resilience Patterns for TypeScript Services
+ *
+ * Provides circuit breaker, retry, bulkhead, rate limiting, and timeout patterns
+ * for building resilient microservices.
+ *
+ * @module @autonoma/service-utils/resilience
+ */
+export * from './circuit-breaker.js';
+export * from './retry.js';
+export * from './bulkhead.js';
+export * from './rate-limiter.js';
+export * from './timeout.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/resilience/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resilience/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/resilience/rate-limiter.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Rate Limiter Pattern
+ *
+ * Controls the rate of requests to prevent overload.
+ * Uses a sliding window algorithm for accurate rate limiting.
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter({
+ *   name: 'trading-api',
+ *   windowMs: 1000,
+ *   maxRequests: 10
+ * });
+ *
+ * try {
+ *   await limiter.acquire();
+ *   const result = await executeTrade();
+ * } catch (error) {
+ *   if (error instanceof RateLimitExceededError) {
+ *     // Wait and retry
+ *   }
+ * }
+ * ```
+ */
+import { RateLimiterConfig } from './types.js';
+/**
+ * Rate Limiter using token bucket algorithm
+ */
+export declare class RateLimiter {
+    private static instances;
+    private readonly config;
+    private buckets;
+    private stats;
+    constructor(config: Partial<RateLimiterConfig> & {
+        name: string;
+    });
+    /**
+     * Acquire a token (throws if rate limit exceeded)
+     */
+    acquire(context?: any): Promise<void>;
+    /**
+     * Try to acquire a token (returns false if rate limit exceeded)
+     */
+    tryAcquire(context?: any): boolean;
+    /**
+     * Execute a function with rate limiting
+     */
+    execute<T>(fn: () => Promise<T>, context?: any): Promise<T>;
+    /**
+     * Get remaining tokens for a key
+     */
+    getRemainingTokens(context?: any): number;
+    /**
+     * Get rate limiter statistics
+     */
+    getStats(): {
+        totalRequests: number;
+        allowedRequests: number;
+        rejectedRequests: number;
+    };
+    /**
+     * Reset rate limiter
+     */
+    reset(context?: any): void;
+    /**
+     * Get or create bucket for a key
+     */
+    private getOrCreateBucket;
+    /**
+     * Refill bucket based on elapsed time
+     */
+    private refillBucket;
+    /**
+     * Calculate when next token will be available
+     */
+    private calculateRetryAfter;
+    /**
+     * Get key for rate limiting
+     */
+    private getKey;
+    /**
+     * Get stats for all rate limiters
+     */
+    static getAllStats(): Map<string, ReturnType<RateLimiter['getStats']>>;
+    /**
+     * Get a rate limiter by name
+     */
+    static get(name: string): RateLimiter | undefined;
+}
+/**
+ * Decorator to apply rate limiting to a method
+ */
+export declare function withRateLimit(config: Partial<RateLimiterConfig> & {
+    name: string;
+}): <T extends (...args: any[]) => Promise<any>>(target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
+/**
+ * Create a rate limiter wrapper function
+ */
+export declare function createRateLimiter(config: Partial<RateLimiterConfig> & {
+    name: string;
+}): <T>(fn: () => Promise<T>, context?: any) => Promise<T>;
+/**
+ * Rate limiter presets for common use cases
+ */
+export declare const rateLimiterPresets: {
+    /** Standard API rate limiting */
+    standard: Partial<RateLimiterConfig>;
+    /** Strict rate limiting for trading operations */
+    trading: Partial<RateLimiterConfig>;
+    /** Relaxed rate limiting for read operations */
+    relaxed: Partial<RateLimiterConfig>;
+    /** Per-user rate limiting */
+    perUser: Partial<RateLimiterConfig>;
+};
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/resilience/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/resilience/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,iBAAiB,EAA0B,MAAM,YAAY,CAAC;AAcvE;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,SAAS,CAAuC;IAE/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAC9D,OAAO,CAAC,OAAO,CAAuC;IAEtD,OAAO,CAAC,KAAK,CAIX;gBAEU,MAAM,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE;IAKjE;;OAEG;IACG,OAAO,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB3C;;OAEG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO;IAkBlC;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC;IAWjE;;OAEG;IACH,kBAAkB,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG,MAAM;IASzC;;OAEG;IACH,QAAQ;;;;;IAIR;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI;IAS1B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;OAEG;IACH,OAAO,CAAC,YAAY;IAWpB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAO3B;;OAEG;IACH,OAAO,CAAC,MAAM;IA2Bd;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC;IAQtE;;OAEG;IACH,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;CAGlD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,IAGhE,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EACzD,QAAQ,GAAG,EACX,aAAa,MAAM,EACnB,YAAY,uBAAuB,CAAC,CAAC,CAAC,gCAUzC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GACpD,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,CAGxD;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB;IAC7B,iCAAiC;cAI5B,OAAO,CAAC,iBAAiB,CAAC;IAE/B,kDAAkD;aAI7C,OAAO,CAAC,iBAAiB,CAAC;IAE/B,gDAAgD;aAI3C,OAAO,CAAC,iBAAiB,CAAC;IAE/B,6BAA6B;aAKxB,OAAO,CAAC,iBAAiB,CAAC;CAChC,CAAC"}

package/dist/resilience/rate-limiter.js

@@ -0,0 +1,257 @@
+/**
+ * Rate Limiter Pattern
+ *
+ * Controls the rate of requests to prevent overload.
+ * Uses a sliding window algorithm for accurate rate limiting.
+ *
+ * @example
+ * ```typescript
+ * const limiter = new RateLimiter({
+ *   name: 'trading-api',
+ *   windowMs: 1000,
+ *   maxRequests: 10
+ * });
+ *
+ * try {
+ *   await limiter.acquire();
+ *   const result = await executeTrade();
+ * } catch (error) {
+ *   if (error instanceof RateLimitExceededError) {
+ *     // Wait and retry
+ *   }
+ * }
+ * ```
+ */
+import { RateLimitExceededError } from './types.js';
+const DEFAULT_CONFIG = {
+    windowMs: 60000,
+    maxRequests: 100,
+    skipSuccessfulRequests: false,
+    skipFailedRequests: false
+};
+/**
+ * Rate Limiter using token bucket algorithm
+ */
+export class RateLimiter {
+    static instances = new Map();
+    config;
+    buckets = new Map();
+    stats = {
+        totalRequests: 0,
+        allowedRequests: 0,
+        rejectedRequests: 0
+    };
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        RateLimiter.instances.set(this.config.name, this);
+    }
+    /**
+     * Acquire a token (throws if rate limit exceeded)
+     */
+    async acquire(context) {
+        const key = this.getKey(context);
+        this.stats.totalRequests++;
+        const bucket = this.getOrCreateBucket(key);
+        this.refillBucket(bucket);
+        if (bucket.tokens < 1) {
+            this.stats.rejectedRequests++;
+            this.config.onLimitReached?.(key);
+            // Calculate retry after
+            const retryAfter = this.calculateRetryAfter(bucket);
+            throw new RateLimitExceededError(key, retryAfter);
+        }
+        bucket.tokens -= 1;
+        this.stats.allowedRequests++;
+    }
+    /**
+     * Try to acquire a token (returns false if rate limit exceeded)
+     */
+    tryAcquire(context) {
+        try {
+            const key = this.getKey(context);
+            const bucket = this.getOrCreateBucket(key);
+            this.refillBucket(bucket);
+            if (bucket.tokens < 1) {
+                return false;
+            }
+            bucket.tokens -= 1;
+            this.stats.allowedRequests++;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Execute a function with rate limiting
+     */
+    async execute(fn, context) {
+        await this.acquire(context);
+        try {
+            const result = await fn();
+            return result;
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+     * Get remaining tokens for a key
+     */
+    getRemainingTokens(context) {
+        const key = this.getKey(context);
+        const bucket = this.buckets.get(key);
+        if (!bucket)
+            return this.config.maxRequests;
+        this.refillBucket(bucket);
+        return Math.floor(bucket.tokens);
+    }
+    /**
+     * Get rate limiter statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Reset rate limiter
+     */
+    reset(context) {
+        if (context) {
+            const key = this.getKey(context);
+            this.buckets.delete(key);
+        }
+        else {
+            this.buckets.clear();
+        }
+    }
+    /**
+     * Get or create bucket for a key
+     */
+    getOrCreateBucket(key) {
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = {
+                tokens: this.config.maxRequests,
+                lastRefill: Date.now()
+            };
+            this.buckets.set(key, bucket);
+        }
+        return bucket;
+    }
+    /**
+     * Refill bucket based on elapsed time
+     */
+    refillBucket(bucket) {
+        const now = Date.now();
+        const elapsed = now - bucket.lastRefill;
+        // Calculate tokens to add based on elapsed time
+        const tokensToAdd = (elapsed / this.config.windowMs) * this.config.maxRequests;
+        bucket.tokens = Math.min(this.config.maxRequests, bucket.tokens + tokensToAdd);
+        bucket.lastRefill = now;
+    }
+    /**
+     * Calculate when next token will be available
+     */
+    calculateRetryAfter(bucket) {
+        // Time until one token is refilled
+        const tokenRefillTime = this.config.windowMs / this.config.maxRequests;
+        const tokenDeficit = 1 - bucket.tokens;
+        return Math.ceil(tokenDeficit * tokenRefillTime);
+    }
+    /**
+     * Get key for rate limiting
+     */
+    getKey(context) {
+        if (!context)
+            return 'default';
+        if (this.config.keyGenerator) {
+            return this.config.keyGenerator(context);
+        }
+        if (typeof context === 'string')
+            return context;
+        if (typeof context === 'number')
+            return String(context);
+        // For objects, try to extract common identifiers
+        if (typeof context === 'object' && context !== null) {
+            // Try common identifier properties
+            if (context.id)
+                return String(context.id);
+            if (context.userId)
+                return String(context.userId);
+            if (context.key)
+                return String(context.key);
+            // Safely stringify, handling circular references
+            try {
+                return JSON.stringify(context);
+            }
+            catch {
+                // Fallback to object hash if stringify fails
+                return `object_${Object.keys(context).sort().join('_')}`;
+            }
+        }
+        return 'default';
+    }
+    /**
+     * Get stats for all rate limiters
+     */
+    static getAllStats() {
+        const stats = new Map();
+        for (const [name, limiter] of this.instances) {
+            stats.set(name, limiter.getStats());
+        }
+        return stats;
+    }
+    /**
+     * Get a rate limiter by name
+     */
+    static get(name) {
+        return this.instances.get(name);
+    }
+}
+/**
+ * Decorator to apply rate limiting to a method
+ */
+export function withRateLimit(config) {
+    const limiter = new RateLimiter(config);
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            return limiter.execute(() => originalMethod.apply(this, args));
+        };
+        return descriptor;
+    };
+}
+/**
+ * Create a rate limiter wrapper function
+ */
+export function createRateLimiter(config) {
+    const limiter = new RateLimiter(config);
+    return (fn, context) => limiter.execute(fn, context);
+}
+/**
+ * Rate limiter presets for common use cases
+ */
+export const rateLimiterPresets = {
+    /** Standard API rate limiting */
+    standard: {
+        windowMs: 60000,
+        maxRequests: 100
+    },
+    /** Strict rate limiting for trading operations */
+    trading: {
+        windowMs: 1000,
+        maxRequests: 10
+    },
+    /** Relaxed rate limiting for read operations */
+    relaxed: {
+        windowMs: 60000,
+        maxRequests: 1000
+    },
+    /** Per-user rate limiting */
+    perUser: {
+        windowMs: 60000,
+        maxRequests: 60,
+        keyGenerator: (context) => context.userId || 'anonymous'
+    }
+};
+//# sourceMappingURL=rate-limiter.js.map