@taukirsheikh/rate-limiter 1.1.0

package/dist/redis/lua-scripts.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * Lua scripts for atomic Redis operations
+ * These ensure race-condition-free distributed rate limiting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEARTBEAT = exports.CLEAR_STATE = exports.INIT_STATE = exports.INCREMENT_RESERVOIR = exports.UPDATE_RESERVOIR = exports.GET_STATE = exports.RELEASE_SLOT = exports.ACQUIRE_SLOT = void 0;
+/**
+ * Acquire a slot for job execution
+ * Returns: [allowed: 0|1, running: number, waitTime: number]
+ *
+ * KEYS[1]: limiter state key (hash)
+ * ARGV[1]: max concurrent
+ * ARGV[2]: min time (ms)
+ * ARGV[3]: max per interval
+ * ARGV[4]: interval (ms)
+ * ARGV[5]: current timestamp (ms)
+ * ARGV[6]: job weight
+ * ARGV[7]: job id
+ */
+exports.ACQUIRE_SLOT = `
+local stateKey = KEYS[1]
+local maxConcurrent = tonumber(ARGV[1])
+local minTime = tonumber(ARGV[2])
+local maxPerInterval = tonumber(ARGV[3])
+local interval = tonumber(ARGV[4])
+local now = tonumber(ARGV[5])
+local weight = tonumber(ARGV[6])
+local jobId = ARGV[7]
+
+-- Get current state
+local running = tonumber(redis.call('HGET', stateKey, 'running') or '0')
+local currentWeight = tonumber(redis.call('HGET', stateKey, 'currentWeight') or '0')
+local lastJobTime = tonumber(redis.call('HGET', stateKey, 'lastJobTime') or '0')
+local intervalStart = tonumber(redis.call('HGET', stateKey, 'intervalStart') or '0')
+local intervalCount = tonumber(redis.call('HGET', stateKey, 'intervalCount') or '0')
+local reservoir = redis.call('HGET', stateKey, 'reservoir')
+
+-- Check concurrency limit
+if currentWeight + weight > maxConcurrent then
+  return {0, running, 0, 'concurrency'}
+end
+
+-- Check reservoir
+if reservoir ~= false and tonumber(reservoir) <= 0 then
+  return {0, running, 0, 'reservoir'}
+end
+
+-- Check interval rate limit
+if now - intervalStart >= interval then
+  intervalStart = now
+  intervalCount = 0
+end
+
+if intervalCount >= maxPerInterval then
+  local waitTime = interval - (now - intervalStart)
+  return {0, running, waitTime, 'interval'}
+end
+
+-- Check min time between jobs
+local timeSinceLastJob = now - lastJobTime
+if timeSinceLastJob < minTime then
+  local waitTime = minTime - timeSinceLastJob
+  return {0, running, waitTime, 'minTime'}
+end
+
+-- All checks passed - acquire slot
+redis.call('HINCRBY', stateKey, 'running', 1)
+redis.call('HINCRBY', stateKey, 'currentWeight', weight)
+redis.call('HSET', stateKey, 'lastJobTime', now)
+redis.call('HSET', stateKey, 'intervalStart', intervalStart)
+redis.call('HINCRBY', stateKey, 'intervalCount', 1)
+
+-- Decrement reservoir if set
+if reservoir ~= false then
+  redis.call('HINCRBY', stateKey, 'reservoir', -1)
+end
+
+-- Track active job
+redis.call('HSET', stateKey .. ':jobs', jobId, weight)
+
+-- Set TTL on state (cleanup after inactivity)
+redis.call('EXPIRE', stateKey, 3600)
+redis.call('EXPIRE', stateKey .. ':jobs', 3600)
+
+return {1, running + 1, 0, 'ok'}
+`;
+/**
+ * Release a slot after job completion
+ * KEYS[1]: limiter state key
+ * ARGV[1]: job weight
+ * ARGV[2]: job id
+ * ARGV[3]: success (1) or failure (0)
+ */
+exports.RELEASE_SLOT = `
+local stateKey = KEYS[1]
+local weight = tonumber(ARGV[1])
+local jobId = ARGV[2]
+local success = tonumber(ARGV[3])
+
+-- Decrement running count
+local running = redis.call('HINCRBY', stateKey, 'running', -1)
+redis.call('HINCRBY', stateKey, 'currentWeight', -weight)
+
+-- Update stats
+if success == 1 then
+  redis.call('HINCRBY', stateKey, 'done', 1)
+else
+  redis.call('HINCRBY', stateKey, 'failed', 1)
+end
+
+-- Remove from active jobs
+redis.call('HDEL', stateKey .. ':jobs', jobId)
+
+return running
+`;
+/**
+ * Get current limiter state
+ * KEYS[1]: limiter state key
+ */
+exports.GET_STATE = `
+local stateKey = KEYS[1]
+
+local running = tonumber(redis.call('HGET', stateKey, 'running') or '0')
+local currentWeight = tonumber(redis.call('HGET', stateKey, 'currentWeight') or '0')
+local done = tonumber(redis.call('HGET', stateKey, 'done') or '0')
+local failed = tonumber(redis.call('HGET', stateKey, 'failed') or '0')
+local reservoir = redis.call('HGET', stateKey, 'reservoir')
+
+if reservoir == false then
+  reservoir = -1
+else
+  reservoir = tonumber(reservoir)
+end
+
+return {running, currentWeight, done, failed, reservoir}
+`;
+/**
+ * Update reservoir value
+ * KEYS[1]: limiter state key
+ * ARGV[1]: new reservoir value
+ */
+exports.UPDATE_RESERVOIR = `
+local stateKey = KEYS[1]
+local value = tonumber(ARGV[1])
+
+redis.call('HSET', stateKey, 'reservoir', value)
+redis.call('EXPIRE', stateKey, 3600)
+
+return value
+`;
+/**
+ * Increment reservoir value
+ * KEYS[1]: limiter state key
+ * ARGV[1]: amount to add
+ */
+exports.INCREMENT_RESERVOIR = `
+local stateKey = KEYS[1]
+local amount = tonumber(ARGV[1])
+
+local current = tonumber(redis.call('HGET', stateKey, 'reservoir') or '0')
+local newValue = current + amount
+
+redis.call('HSET', stateKey, 'reservoir', newValue)
+redis.call('EXPIRE', stateKey, 3600)
+
+return newValue
+`;
+/**
+ * Initialize limiter state
+ * KEYS[1]: limiter state key
+ * ARGV[1]: reservoir (or -1 for null)
+ */
+exports.INIT_STATE = `
+local stateKey = KEYS[1]
+local reservoir = tonumber(ARGV[1])
+
+-- Only initialize if not exists
+if redis.call('EXISTS', stateKey) == 0 then
+  redis.call('HSET', stateKey, 'running', 0)
+  redis.call('HSET', stateKey, 'currentWeight', 0)
+  redis.call('HSET', stateKey, 'lastJobTime', 0)
+  redis.call('HSET', stateKey, 'intervalStart', 0)
+  redis.call('HSET', stateKey, 'intervalCount', 0)
+  redis.call('HSET', stateKey, 'done', 0)
+  redis.call('HSET', stateKey, 'failed', 0)
+  
+  if reservoir >= 0 then
+    redis.call('HSET', stateKey, 'reservoir', reservoir)
+  end
+  
+  redis.call('EXPIRE', stateKey, 3600)
+end
+
+return 1
+`;
+/**
+ * Clear limiter state (for testing/reset)
+ * KEYS[1]: limiter state key
+ */
+exports.CLEAR_STATE = `
+local stateKey = KEYS[1]
+
+redis.call('DEL', stateKey)
+redis.call('DEL', stateKey .. ':jobs')
+redis.call('DEL', stateKey .. ':queue')
+
+return 1
+`;
+/**
+ * Heartbeat - extend TTL and clean up stale jobs
+ * KEYS[1]: limiter state key
+ * ARGV[1]: current timestamp
+ * ARGV[2]: job timeout (ms)
+ */
+exports.HEARTBEAT = `
+local stateKey = KEYS[1]
+local now = tonumber(ARGV[1])
+local timeout = tonumber(ARGV[2])
+
+-- Extend TTL
+redis.call('EXPIRE', stateKey, 3600)
+redis.call('EXPIRE', stateKey .. ':jobs', 3600)
+
+-- Could add stale job cleanup here if needed
+
+return redis.call('HGET', stateKey, 'running') or '0'
+`;
+//# sourceMappingURL=lua-scripts.js.map

package/dist/redis/lua-scripts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lua-scripts.js","sourceRoot":"","sources":["../../src/redis/lua-scripts.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;;;;;;;GAYG;AACU,QAAA,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkE3B,CAAC;AAEF;;;;;;GAMG;AACU,QAAA,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;CAqB3B,CAAC;AAEF;;;GAGG;AACU,QAAA,SAAS,GAAG;;;;;;;;;;;;;;;;CAgBxB,CAAC;AAEF;;;;GAIG;AACU,QAAA,gBAAgB,GAAG;;;;;;;;CAQ/B,CAAC;AAEF;;;;GAIG;AACU,QAAA,mBAAmB,GAAG;;;;;;;;;;;CAWlC,CAAC;AAEF;;;;GAIG;AACU,QAAA,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBzB,CAAC;AAEF;;;GAGG;AACU,QAAA,WAAW,GAAG;;;;;;;;CAQ1B,CAAC;AAEF;;;;;GAKG;AACU,QAAA,SAAS,GAAG;;;;;;;;;;;;CAYxB,CAAC"}

package/dist/redis/redis-storage.d.ts

@@ -0,0 +1,134 @@
+import type { Redis, RedisOptions, Cluster, ClusterOptions } from 'ioredis';
+/**
+ * Result of acquiring a slot
+ */
+export interface AcquireResult {
+    allowed: boolean;
+    running: number;
+    waitTime: number;
+    reason: 'ok' | 'concurrency' | 'reservoir' | 'interval' | 'minTime';
+}
+/**
+ * Distributed state from Redis
+ */
+export interface DistributedState {
+    running: number;
+    currentWeight: number;
+    done: number;
+    failed: number;
+    reservoir: number | null;
+}
+/**
+ * Redis connection options
+ */
+export interface RedisConnectionOptions {
+    /** Redis connection URL (redis://...) */
+    url?: string;
+    /** Redis host */
+    host?: string;
+    /** Redis port */
+    port?: number;
+    /** Redis password */
+    password?: string;
+    /** Redis database number */
+    db?: number;
+    /** Key prefix for this limiter */
+    keyPrefix?: string;
+    /** Use Redis Cluster */
+    cluster?: boolean;
+    /** Cluster nodes */
+    clusterNodes?: Array<{
+        host: string;
+        port: number;
+    }>;
+    /** Additional ioredis options */
+    redisOptions?: RedisOptions;
+    /** Cluster options */
+    clusterOptions?: ClusterOptions;
+    /** Existing Redis client to use */
+    client?: Redis | Cluster;
+}
+/**
+ * Redis storage adapter for distributed rate limiting
+ */
+export declare class RedisStorage {
+    private client;
+    private readonly keyPrefix;
+    private readonly ownClient;
+    private initialized;
+    private scripts;
+    constructor(options: RedisConnectionOptions);
+    private createClient;
+    /**
+     * Execute a Lua script with automatic fallback to EVAL if EVALSHA fails
+     */
+    private execScript;
+    /**
+     * Initialize storage and load Lua scripts
+     */
+    initialize(limiterId: string, reservoir: number | null): Promise<void>;
+    /**
+     * Get the Redis key for a limiter
+     */
+    private getKey;
+    /**
+     * Try to acquire a slot for job execution
+     */
+    acquireSlot(limiterId: string, options: {
+        maxConcurrent: number;
+        minTime: number;
+        maxPerInterval: number;
+        interval: number;
+        weight: number;
+        jobId: string;
+    }): Promise<AcquireResult>;
+    /**
+     * Release a slot after job completion
+     */
+    releaseSlot(limiterId: string, jobId: string, weight: number, success: boolean): Promise<number>;
+    /**
+     * Get current distributed state
+     */
+    getState(limiterId: string): Promise<DistributedState>;
+    /**
+     * Update reservoir value
+     */
+    updateReservoir(limiterId: string, value: number): Promise<number>;
+    /**
+     * Increment reservoir value
+     */
+    incrementReservoir(limiterId: string, amount: number): Promise<number>;
+    /**
+     * Clear all state for a limiter
+     */
+    clear(limiterId: string): Promise<void>;
+    /**
+     * Send heartbeat to keep state alive
+     */
+    heartbeat(limiterId: string, timeout: number): Promise<number>;
+    /**
+     * Subscribe to reservoir depletion events
+     */
+    subscribeToEvents(limiterId: string, callback: (event: string, data: unknown) => void): Promise<() => void>;
+    /**
+     * Publish an event
+     */
+    publishEvent(limiterId: string, event: string, data: unknown): Promise<void>;
+    /**
+     * Get the underlying Redis client
+     */
+    getClient(): Redis | Cluster;
+    /**
+     * Check if connected to Redis
+     */
+    isConnected(): boolean;
+    /**
+     * Wait for Redis connection
+     */
+    waitForConnection(timeout?: number): Promise<void>;
+    /**
+     * Close the Redis connection
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=redis-storage.d.ts.map

package/dist/redis/redis-storage.d.ts.map

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

package/dist/redis/redis-storage.js

@@ -0,0 +1,255 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisStorage = void 0;
+const lua_scripts_js_1 = require("./lua-scripts.js");
+/**
+ * Redis storage adapter for distributed rate limiting
+ */
+class RedisStorage {
+    client;
+    keyPrefix;
+    ownClient;
+    initialized = false;
+    // Scripts with their source and cached SHAs
+    scripts = new Map([
+        ['acquire', { source: lua_scripts_js_1.ACQUIRE_SLOT }],
+        ['release', { source: lua_scripts_js_1.RELEASE_SLOT }],
+        ['getState', { source: lua_scripts_js_1.GET_STATE }],
+        ['updateReservoir', { source: lua_scripts_js_1.UPDATE_RESERVOIR }],
+        ['incrementReservoir', { source: lua_scripts_js_1.INCREMENT_RESERVOIR }],
+        ['initState', { source: lua_scripts_js_1.INIT_STATE }],
+        ['clearState', { source: lua_scripts_js_1.CLEAR_STATE }],
+        ['heartbeat', { source: lua_scripts_js_1.HEARTBEAT }],
+    ]);
+    constructor(options) {
+        this.keyPrefix = options.keyPrefix ?? 'ratelimit';
+        this.ownClient = !options.client;
+        if (options.client) {
+            this.client = options.client;
+        }
+        else {
+            // Dynamically import ioredis
+            this.client = this.createClient(options);
+        }
+    }
+    createClient(options) {
+        // Dynamic import to make Redis optional
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const IORedis = require('ioredis');
+        if (options.cluster && options.clusterNodes) {
+            return new IORedis.Cluster(options.clusterNodes, {
+                redisOptions: {
+                    password: options.password,
+                    ...options.redisOptions,
+                },
+                ...options.clusterOptions,
+            });
+        }
+        if (options.url) {
+            return new IORedis.default(options.url, options.redisOptions);
+        }
+        return new IORedis.default({
+            host: options.host ?? 'localhost',
+            port: options.port ?? 6379,
+            password: options.password,
+            db: options.db ?? 0,
+            ...options.redisOptions,
+        });
+    }
+    /**
+     * Execute a Lua script with automatic fallback to EVAL if EVALSHA fails
+     */
+    async execScript(name, numKeys, ...args) {
+        const script = this.scripts.get(name);
+        if (!script) {
+            throw new Error(`Unknown script: ${name}`);
+        }
+        // Try EVALSHA first if we have a cached SHA
+        if (script.sha) {
+            try {
+                return await this.client.evalsha(script.sha, numKeys, ...args);
+            }
+            catch (error) {
+                // If NOSCRIPT error, fall through to EVAL
+                if (!(error instanceof Error) || !error.message.includes('NOSCRIPT')) {
+                    throw error;
+                }
+                // Clear the cached SHA
+                script.sha = undefined;
+            }
+        }
+        // Use EVAL and cache the SHA for next time
+        const result = await this.client.eval(script.source, numKeys, ...args);
+        // Cache SHA for future calls (load script)
+        try {
+            script.sha = await this.client.script('LOAD', script.source);
+        }
+        catch {
+            // Ignore errors loading script - we'll just use EVAL next time
+        }
+        return result;
+    }
+    /**
+     * Initialize storage and load Lua scripts
+     */
+    async initialize(limiterId, reservoir) {
+        if (this.initialized)
+            return;
+        // Pre-load all scripts
+        for (const [name, script] of this.scripts) {
+            try {
+                script.sha = await this.client.script('LOAD', script.source);
+            }
+            catch {
+                // Ignore - we'll use EVAL as fallback
+            }
+        }
+        // Initialize state
+        const key = this.getKey(limiterId);
+        await this.execScript('initState', 1, key, reservoir ?? -1);
+        this.initialized = true;
+    }
+    /**
+     * Get the Redis key for a limiter
+     */
+    getKey(limiterId) {
+        return `${this.keyPrefix}:${limiterId}`;
+    }
+    /**
+     * Try to acquire a slot for job execution
+     */
+    async acquireSlot(limiterId, options) {
+        const key = this.getKey(limiterId);
+        const now = Date.now();
+        const result = await this.execScript('acquire', 1, key, options.maxConcurrent, options.minTime, options.maxPerInterval, options.interval, now, options.weight, options.jobId);
+        return {
+            allowed: result[0] === 1,
+            running: result[1],
+            waitTime: result[2],
+            reason: result[3],
+        };
+    }
+    /**
+     * Release a slot after job completion
+     */
+    async releaseSlot(limiterId, jobId, weight, success) {
+        const key = this.getKey(limiterId);
+        return await this.execScript('release', 1, key, weight, jobId, success ? 1 : 0);
+    }
+    /**
+     * Get current distributed state
+     */
+    async getState(limiterId) {
+        const key = this.getKey(limiterId);
+        const result = await this.execScript('getState', 1, key);
+        return {
+            running: result[0],
+            currentWeight: result[1],
+            done: result[2],
+            failed: result[3],
+            reservoir: result[4] === -1 ? null : result[4],
+        };
+    }
+    /**
+     * Update reservoir value
+     */
+    async updateReservoir(limiterId, value) {
+        const key = this.getKey(limiterId);
+        return await this.execScript('updateReservoir', 1, key, value);
+    }
+    /**
+     * Increment reservoir value
+     */
+    async incrementReservoir(limiterId, amount) {
+        const key = this.getKey(limiterId);
+        return await this.execScript('incrementReservoir', 1, key, amount);
+    }
+    /**
+     * Clear all state for a limiter
+     */
+    async clear(limiterId) {
+        const key = this.getKey(limiterId);
+        await this.execScript('clearState', 1, key);
+    }
+    /**
+     * Send heartbeat to keep state alive
+     */
+    async heartbeat(limiterId, timeout) {
+        const key = this.getKey(limiterId);
+        const now = Date.now();
+        return await this.execScript('heartbeat', 1, key, now, timeout);
+    }
+    /**
+     * Subscribe to reservoir depletion events
+     */
+    async subscribeToEvents(limiterId, callback) {
+        const channel = `${this.keyPrefix}:${limiterId}:events`;
+        // Create a subscriber connection
+        const subscriber = this.client.duplicate();
+        await subscriber.subscribe(channel);
+        subscriber.on('message', (ch, message) => {
+            if (ch === channel) {
+                try {
+                    const { event, data } = JSON.parse(message);
+                    callback(event, data);
+                }
+                catch {
+                    // Ignore parse errors
+                }
+            }
+        });
+        return () => {
+            subscriber.unsubscribe(channel);
+            subscriber.quit();
+        };
+    }
+    /**
+     * Publish an event
+     */
+    async publishEvent(limiterId, event, data) {
+        const channel = `${this.keyPrefix}:${limiterId}:events`;
+        await this.client.publish(channel, JSON.stringify({ event, data }));
+    }
+    /**
+     * Get the underlying Redis client
+     */
+    getClient() {
+        return this.client;
+    }
+    /**
+     * Check if connected to Redis
+     */
+    isConnected() {
+        return this.client.status === 'ready';
+    }
+    /**
+     * Wait for Redis connection
+     */
+    async waitForConnection(timeout = 5000) {
+        if (this.isConnected())
+            return;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error('Redis connection timeout'));
+            }, timeout);
+            this.client.once('ready', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            this.client.once('error', (err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Close the Redis connection
+     */
+    async close() {
+        if (this.ownClient) {
+            await this.client.quit();
+        }
+    }
+}
+exports.RedisStorage = RedisStorage;
+//# sourceMappingURL=redis-storage.js.map

package/dist/redis/redis-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-storage.js","sourceRoot":"","sources":["../../src/redis/redis-storage.ts"],"names":[],"mappings":";;;AACA,qDAS0B;AA2D1B;;GAEG;AACH,MAAa,YAAY;IACf,MAAM,CAAkB;IACf,SAAS,CAAS;IAClB,SAAS,CAAU;IAC5B,WAAW,GAAG,KAAK,CAAC;IAE5B,4CAA4C;IACpC,OAAO,GAA2B,IAAI,GAAG,CAAC;QAChD,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,6BAAY,EAAE,CAAC;QACrC,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,6BAAY,EAAE,CAAC;QACrC,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,0BAAS,EAAE,CAAC;QACnC,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,iCAAgB,EAAE,CAAC;QACjD,CAAC,oBAAoB,EAAE,EAAE,MAAM,EAAE,oCAAmB,EAAE,CAAC;QACvD,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,2BAAU,EAAE,CAAC;QACrC,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,4BAAW,EAAE,CAAC;QACvC,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,0BAAS,EAAE,CAAC;KACrC,CAAC,CAAC;IAEH,YAAY,OAA+B;QACzC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,WAAW,CAAC;QAClD,IAAI,CAAC,SAAS,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC;QAEjC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC/B,CAAC;aAAM,CAAC;YACN,6BAA6B;YAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAEO,YAAY,CAAC,OAA+B;QAClD,wCAAwC;QACxC,8DAA8D;QAC9D,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QAEnC,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;YAC5C,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE;gBAC/C,YAAY,EAAE;oBACZ,QAAQ,EAAE,OAAO,CAAC,QAAQ;oBAC1B,GAAG,OAAO,CAAC,YAAY;iBACxB;gBACD,GAAG,OAAO,CAAC,cAAc;aAC1B,CAAC,CAAC;QACL,CAAC;QAED,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YAChB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;YACzB,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW;YACjC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC;YACnB,GAAG,OAAO,CAAC,YAAY;SACxB,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,UAAU,CACtB,IAAY,EACZ,OAAe,EACf,GAAG,IAAyB;QAE5B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC;QAED,4CAA4C;QAC5C,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC;YACf,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;YACjE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,0CAA0C;gBAC1C,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;oBACrE,MAAM,KAAK,CAAC;gBACd,CAAC;gBACD,uBAAuB;gBACvB,MAAM,CAAC,GAAG,GAAG,SAAS,CAAC;YACzB,CAAC;QACH,CAAC;QAED,2CAA2C;QAC3C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;QAEvE,2CAA2C;QAC3C,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAW,CAAC;QACzE,CAAC;QAAC,MAAM,CAAC;YACP,+DAA+D;QACjE,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,SAAiB,EAAE,SAAwB;QAC1D,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO;QAE7B,uBAAuB;QACvB,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC1C,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAW,CAAC;YACzE,CAAC;YAAC,MAAM,CAAC;gBACP,sCAAsC;YACxC,CAAC;QACH,CAAC;QAED,mBAAmB;QACnB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACnC,MAAM,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,IAAI,CAAC,CAAC,CAAC,CAAC;QAE5D,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,SAAiB;QAC9B,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,SAAS,EAAE,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CACf,SAAiB,EACjB,OAOC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAClC,SAAS,EACT,CAAC,EACD,GAAG,EACH,OAAO,CAAC,aAAa,EACrB,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,cAAc,EACtB,OAAO,CAAC,QAAQ,EAChB,GAAG,EACH,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,KAAK,CACsB,CAAC;QAEtC,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;YACxB,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;YAClB,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;YACnB,MAAM,EAAE,MAAM,CAAC,CAAC,CAA4B;SAC7C,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CACf,SAAiB,EACjB,KAAa,EACb,MAAc,EACd,OAAgB;QAEhB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAEnC,OAAO,MAAM,IAAI,CAAC,UAAU,CAC1B,SAAS,EACT,CAAC,EACD,GAAG,EACH,MAAM,EACN,KAAK,EACL,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACN,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ,CAAC,SAAiB;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAEnC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAClC,UAAU,EACV,CAAC,EACD,GAAG,CACwC,CAAC;QAE9C,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;YAClB,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;YACxB,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;YACf,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;YACjB,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;SAC/C,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,eAAe,CAAC,SAAiB,EAAE,KAAa;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAEnC,OAAO,MAAM,IAAI,CAAC,UAAU,CAC1B,iBAAiB,EACjB,CAAC,EACD,GAAG,EACH,KAAK,CACI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,kBAAkB,CAAC,SAAiB,EAAE,MAAc;QACxD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAEnC,OAAO,MAAM,IAAI,CAAC,UAAU,CAC1B,oBAAoB,EACpB,CAAC,EACD,GAAG,EACH,MAAM,CACG,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAEnC,MAAM,IAAI,CAAC,UAAU,CACnB,YAAY,EACZ,CAAC,EACD,GAAG,CACJ,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,SAAiB,EAAE,OAAe;QAChD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,OAAO,MAAM,IAAI,CAAC,UAAU,CAC1B,WAAW,EACX,CAAC,EACD,GAAG,EACH,GAAG,EACH,OAAO,CACE,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,iBAAiB,CACrB,SAAiB,EACjB,QAAgD;QAEhD,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,SAAS,SAAS,CAAC;QAExD,iCAAiC;QACjC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QAE3C,MAAM,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAEpC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE;YACvC,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;gBACnB,IAAI,CAAC;oBACH,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;oBAC5C,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;gBACxB,CAAC;gBAAC,MAAM,CAAC;oBACP,sBAAsB;gBACxB,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,EAAE;YACV,UAAU,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAChC,UAAU,CAAC,IAAI,EAAE,CAAC;QACpB,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,YAAY,CAAC,SAAiB,EAAE,KAAa,EAAE,IAAa;QAChE,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,SAAS,SAAS,CAAC;QACxD,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACtE,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,OAAO,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,iBAAiB,CAAC,OAAO,GAAG,IAAI;QACpC,IAAI,IAAI,CAAC,WAAW,EAAE;YAAE,OAAO;QAE/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,MAAM,CAAC,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC;YAChD,CAAC,EAAE,OAAO,CAAC,CAAC;YAEZ,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;gBAC7B,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBAChC,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,MAAM,CAAC,GAAG,CAAC,CAAC;YACd,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC3B,CAAC;IACH,CAAC;CACF;AA5VD,oCA4VC"}