@per_moeller/asterisk-ari 1.0.2 → 1.0.4

package/dist/pool.d.ts

@@ -1,10 +1,50 @@
 /**
  * Connection pool for high-throughput scenarios
+ *
+ * This module provides a connection pool that maintains multiple ARI connections
+ * for distributing load in high-volume call processing scenarios.
+ *
+ * @packageDocumentation
  */
 import { AriClient } from './client.js';
 import type { PoolOptions } from './types/options.js';
 /**
- * Connection pool for distributing load across multiple ARI connections
+ * Connection pool for distributing load across multiple ARI connections.
+ *
+ * In high-throughput scenarios, a single ARI connection may become a bottleneck.
+ * The connection pool maintains multiple connections and distributes requests
+ * across them using round-robin selection.
+ *
+ * @remarks
+ * All connections in the pool connect to the same Asterisk server and share
+ * the same application name. Events will be received on all connections,
+ * so you typically only need to set up event listeners on one client.
+ *
+ * @example
+ * ```typescript
+ * import { createPool } from '@per_moeller/asterisk-ari';
+ *
+ * // Create a pool with 5 connections
+ * const pool = await createPool({
+ *   url: 'http://localhost:8088',
+ *   username: 'asterisk',
+ *   password: 'secret',
+ *   app: 'my-app',
+ *   poolSize: 5
+ * });
+ *
+ * // Get a connection for making requests
+ * const client = pool.getConnection();
+ * const channels = await client.channels.list();
+ *
+ * // Use withConnection for automatic selection
+ * const result = await pool.withConnection(async (client) => {
+ *   return client.channels.originate({ ... });
+ * });
+ *
+ * // Clean up
+ * await pool.stop();
+ * ```
  */
 export declare class ConnectionPool {
     private connections;
@@ -12,46 +52,147 @@ export declare class ConnectionPool {
     private readonly options;
     private readonly poolSize;
     private initialized;
+    /**
+     * Create a new connection pool.
+     *
+     * @param options - Pool options including connection settings and pool size
+     *
+     * @remarks
+     * The pool is not immediately connected. Call {@link initialize} or use
+     * the {@link createPool} helper function to create an initialized pool.
+     */
     constructor(options: PoolOptions);
     /**
-     * Initialize the connection pool
+     * Initialize the connection pool by creating all connections.
+     *
+     * Creates `poolSize` number of connections in parallel and waits for
+     * all of them to be established.
+     *
+     * @returns Promise that resolves when all connections are established
+     * @throws {AriHttpError} If any connection fails
+     *
+     * @example
+     * ```typescript
+     * const pool = new ConnectionPool(options);
+     * await pool.initialize();
+     * ```
      */
     initialize(): Promise<void>;
     /**
-     * Get a connection from the pool (round-robin)
+     * Get a connection from the pool using round-robin selection.
+     *
+     * Each call returns the next connection in the pool, cycling back
+     * to the first after reaching the last.
+     *
+     * @returns An ARI client from the pool
+     * @throws {Error} If the pool is not initialized
+     *
+     * @example
+     * ```typescript
+     * const client = pool.getConnection();
+     * await client.channels.list();
+     * ```
      */
     getConnection(): AriClient;
     /**
-     * Get a connection that is currently connected
+     * Get a connection that is currently connected.
+     *
+     * Searches through the pool using round-robin to find a connected client.
+     * Returns undefined if no connections are available.
+     *
+     * @returns A connected ARI client, or undefined if none are connected
+     *
+     * @example
+     * ```typescript
+     * const client = pool.getConnectedConnection();
+     * if (client) {
+     *   await client.channels.list();
+     * } else {
+     *   console.log('No connections available');
+     * }
+     * ```
      */
     getConnectedConnection(): AriClient | undefined;
     /**
-     * Get all connections in the pool
+     * Get all connections in the pool.
+     *
+     * @returns Read-only array of all ARI clients in the pool
      */
     getConnections(): readonly AriClient[];
     /**
-     * Get the number of connections in the pool
+     * Get the total number of connections in the pool.
      */
     get size(): number;
     /**
-     * Get the number of connected clients
+     * Get the number of currently connected clients.
      */
     get connectedCount(): number;
     /**
-     * Stop all connections in the pool
+     * Stop all connections in the pool.
+     *
+     * Disconnects all clients and resets the pool state. The pool can be
+     * re-initialized after calling stop.
+     *
+     * @returns Promise that resolves when all connections are stopped
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown
+     * await pool.stop();
+     * ```
      */
     stop(): Promise<void>;
     /**
-     * Check if the pool is initialized
+     * Check if the pool is initialized.
+     *
+     * @returns `true` if initialize() has been called successfully
      */
     isInitialized(): boolean;
     /**
-     * Execute a function with a pooled connection
+     * Execute a function with a pooled connection.
+     *
+     * Automatically selects a connection from the pool and passes it to
+     * the provided function. Useful for one-off operations.
+     *
+     * @typeParam T - Return type of the function
+     * @param fn - Function to execute with the connection
+     * @returns Promise resolving to the function's return value
+     *
+     * @example
+     * ```typescript
+     * const channels = await pool.withConnection(async (client) => {
+     *   return client.channels.list();
+     * });
+     *
+     * const bridge = await pool.withConnection(async (client) => {
+     *   return client.bridges.create({ type: 'mixing' });
+     * });
+     * ```
      */
     withConnection<T>(fn: (client: AriClient) => Promise<T>): Promise<T>;
 }
 /**
- * Create and initialize a connection pool
+ * Create and initialize a connection pool.
+ *
+ * This is a convenience function that creates a pool and initializes it
+ * in one step.
+ *
+ * @param options - Pool options including connection settings and pool size
+ * @returns Promise resolving to an initialized connection pool
+ * @throws {AriHttpError} If any connection fails
+ *
+ * @example
+ * ```typescript
+ * const pool = await createPool({
+ *   url: 'http://localhost:8088',
+ *   username: 'asterisk',
+ *   password: 'secret',
+ *   app: 'my-app',
+ *   poolSize: 10
+ * });
+ *
+ * console.log(`Pool has ${pool.size} connections`);
+ * ```
  */
 export declare function createPool(options: PoolOptions): Promise<ConnectionPool>;
 //# sourceMappingURL=pool.d.ts.map

package/dist/pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAW,SAAS,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,EAAE,WAAW;IAKhC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC;;OAEG;IACH,aAAa,IAAI,SAAS;IAU1B;;OAEG;IACH,sBAAsB,IAAI,SAAS,GAAG,SAAS;IAmB/C;;OAEG;IACH,cAAc,IAAI,SAAS,SAAS,EAAE;IAItC;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACG,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAI3E;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAI9E"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAW,SAAS,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,WAAW,CAAS;IAE5B;;;;;;;;OAQG;gBACS,OAAO,EAAE,WAAW;IAKhC;;;;;;;;;;;;;;OAcG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC;;;;;;;;;;;;;;OAcG;IACH,aAAa,IAAI,SAAS;IAU1B;;;;;;;;;;;;;;;;;OAiBG;IACH,sBAAsB,IAAI,SAAS,GAAG,SAAS;IAmB/C;;;;OAIG;IACH,cAAc,IAAI,SAAS,SAAS,EAAE;IAItC;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED;;;;;;;;;;;;;OAaG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;;;OAIG;IACH,aAAa,IAAI,OAAO;IAIxB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAI3E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAI9E"}

package/dist/pool.js

@@ -1,9 +1,49 @@
 /**
  * Connection pool for high-throughput scenarios
+ *
+ * This module provides a connection pool that maintains multiple ARI connections
+ * for distributing load in high-volume call processing scenarios.
+ *
+ * @packageDocumentation
  */
 import { connect } from './client.js';
 /**
- * Connection pool for distributing load across multiple ARI connections
+ * Connection pool for distributing load across multiple ARI connections.
+ *
+ * In high-throughput scenarios, a single ARI connection may become a bottleneck.
+ * The connection pool maintains multiple connections and distributes requests
+ * across them using round-robin selection.
+ *
+ * @remarks
+ * All connections in the pool connect to the same Asterisk server and share
+ * the same application name. Events will be received on all connections,
+ * so you typically only need to set up event listeners on one client.
+ *
+ * @example
+ * ```typescript
+ * import { createPool } from '@per_moeller/asterisk-ari';
+ *
+ * // Create a pool with 5 connections
+ * const pool = await createPool({
+ *   url: 'http://localhost:8088',
+ *   username: 'asterisk',
+ *   password: 'secret',
+ *   app: 'my-app',
+ *   poolSize: 5
+ * });
+ *
+ * // Get a connection for making requests
+ * const client = pool.getConnection();
+ * const channels = await client.channels.list();
+ *
+ * // Use withConnection for automatic selection
+ * const result = await pool.withConnection(async (client) => {
+ *   return client.channels.originate({ ... });
+ * });
+ *
+ * // Clean up
+ * await pool.stop();
+ * ```
  */
 export class ConnectionPool {
     connections = [];
@@ -11,12 +51,33 @@ export class ConnectionPool {
     options;
     poolSize;
     initialized = false;
+    /**
+     * Create a new connection pool.
+     *
+     * @param options - Pool options including connection settings and pool size
+     *
+     * @remarks
+     * The pool is not immediately connected. Call {@link initialize} or use
+     * the {@link createPool} helper function to create an initialized pool.
+     */
     constructor(options) {
         this.options = options;
         this.poolSize = options.poolSize ?? 5;
     }
     /**
-     * Initialize the connection pool
+     * Initialize the connection pool by creating all connections.
+     *
+     * Creates `poolSize` number of connections in parallel and waits for
+     * all of them to be established.
+     *
+     * @returns Promise that resolves when all connections are established
+     * @throws {AriHttpError} If any connection fails
+     *
+     * @example
+     * ```typescript
+     * const pool = new ConnectionPool(options);
+     * await pool.initialize();
+     * ```
      */
     async initialize() {
         if (this.initialized) {
@@ -30,7 +91,19 @@ export class ConnectionPool {
         this.initialized = true;
     }
     /**
-     * Get a connection from the pool (round-robin)
+     * Get a connection from the pool using round-robin selection.
+     *
+     * Each call returns the next connection in the pool, cycling back
+     * to the first after reaching the last.
+     *
+     * @returns An ARI client from the pool
+     * @throws {Error} If the pool is not initialized
+     *
+     * @example
+     * ```typescript
+     * const client = pool.getConnection();
+     * await client.channels.list();
+     * ```
      */
     getConnection() {
         if (!this.initialized || this.connections.length === 0) {
@@ -41,7 +114,22 @@ export class ConnectionPool {
         return client;
     }
     /**
-     * Get a connection that is currently connected
+     * Get a connection that is currently connected.
+     *
+     * Searches through the pool using round-robin to find a connected client.
+     * Returns undefined if no connections are available.
+     *
+     * @returns A connected ARI client, or undefined if none are connected
+     *
+     * @example
+     * ```typescript
+     * const client = pool.getConnectedConnection();
+     * if (client) {
+     *   await client.channels.list();
+     * } else {
+     *   console.log('No connections available');
+     * }
+     * ```
      */
     getConnectedConnection() {
         if (!this.initialized) {
@@ -59,25 +147,38 @@ export class ConnectionPool {
         return undefined;
     }
     /**
-     * Get all connections in the pool
+     * Get all connections in the pool.
+     *
+     * @returns Read-only array of all ARI clients in the pool
      */
     getConnections() {
         return this.connections;
     }
     /**
-     * Get the number of connections in the pool
+     * Get the total number of connections in the pool.
      */
     get size() {
         return this.connections.length;
     }
     /**
-     * Get the number of connected clients
+     * Get the number of currently connected clients.
      */
     get connectedCount() {
         return this.connections.filter(c => c.isConnected()).length;
     }
     /**
-     * Stop all connections in the pool
+     * Stop all connections in the pool.
+     *
+     * Disconnects all clients and resets the pool state. The pool can be
+     * re-initialized after calling stop.
+     *
+     * @returns Promise that resolves when all connections are stopped
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown
+     * await pool.stop();
+     * ```
      */
     async stop() {
         const stopPromises = this.connections.map(c => c.stop());
@@ -87,13 +188,33 @@ export class ConnectionPool {
         this.initialized = false;
     }
     /**
-     * Check if the pool is initialized
+     * Check if the pool is initialized.
+     *
+     * @returns `true` if initialize() has been called successfully
      */
     isInitialized() {
         return this.initialized;
     }
     /**
-     * Execute a function with a pooled connection
+     * Execute a function with a pooled connection.
+     *
+     * Automatically selects a connection from the pool and passes it to
+     * the provided function. Useful for one-off operations.
+     *
+     * @typeParam T - Return type of the function
+     * @param fn - Function to execute with the connection
+     * @returns Promise resolving to the function's return value
+     *
+     * @example
+     * ```typescript
+     * const channels = await pool.withConnection(async (client) => {
+     *   return client.channels.list();
+     * });
+     *
+     * const bridge = await pool.withConnection(async (client) => {
+     *   return client.bridges.create({ type: 'mixing' });
+     * });
+     * ```
      */
     async withConnection(fn) {
         const client = this.getConnection();
@@ -101,7 +222,27 @@ export class ConnectionPool {
     }
 }
 /**
- * Create and initialize a connection pool
+ * Create and initialize a connection pool.
+ *
+ * This is a convenience function that creates a pool and initializes it
+ * in one step.
+ *
+ * @param options - Pool options including connection settings and pool size
+ * @returns Promise resolving to an initialized connection pool
+ * @throws {AriHttpError} If any connection fails
+ *
+ * @example
+ * ```typescript
+ * const pool = await createPool({
+ *   url: 'http://localhost:8088',
+ *   username: 'asterisk',
+ *   password: 'secret',
+ *   app: 'my-app',
+ *   poolSize: 10
+ * });
+ *
+ * console.log(`Pool has ${pool.size} connections`);
+ * ```
  */
 export async function createPool(options) {
     const pool = new ConnectionPool(options);

package/dist/pool.js.map

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

package/dist/queue.d.ts

@@ -1,16 +1,80 @@
 /**
  * Request queue with retry and circuit breaker
+ *
+ * This module provides a request queue that handles automatic retries
+ * and implements the circuit breaker pattern for fault tolerance.
+ *
+ * @packageDocumentation
  */
 import type { QueueOptions } from './types/options.js';
+/**
+ * Circuit breaker state.
+ *
+ * - `closed` - Normal operation, requests are processed
+ * - `open` - Too many failures, requests are rejected immediately
+ * - `half-open` - Testing if the system has recovered
+ */
 type CircuitState = 'closed' | 'open' | 'half-open';
 /**
- * Error thrown when circuit breaker is open
+ * Error thrown when the circuit breaker is open.
+ *
+ * This error is thrown immediately when attempting to enqueue a request
+ * while the circuit breaker is in the open state, without attempting
+ * the actual request.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await queue.enqueue(() => client.channels.list());
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerOpenError) {
+ *     console.log('Service temporarily unavailable');
+ *   }
+ * }
+ * ```
  */
 export declare class CircuitBreakerOpenError extends Error {
     constructor();
 }
 /**
- * Request queue with automatic retry and circuit breaker pattern
+ * Request queue with automatic retry and circuit breaker pattern.
+ *
+ * Provides controlled request execution with:
+ * - Concurrent request limiting
+ * - Automatic retry with exponential backoff
+ * - Circuit breaker to prevent cascading failures
+ *
+ * @remarks
+ * The circuit breaker pattern helps prevent overwhelming a failing service.
+ * After a threshold of failures, the circuit "opens" and rejects requests
+ * immediately. After a timeout, it enters "half-open" state to test if the
+ * service has recovered.
+ *
+ * @example
+ * ```typescript
+ * import { RequestQueue } from '@per_moeller/asterisk-ari';
+ *
+ * const queue = new RequestQueue({
+ *   maxConcurrent: 10,
+ *   maxRetries: 3,
+ *   retryDelay: 1000,
+ *   circuitBreakerThreshold: 5,
+ *   circuitBreakerTimeout: 30000
+ * });
+ *
+ * // Enqueue requests
+ * const result = await queue.enqueue(async () => {
+ *   return fetch('https://api.example.com/data');
+ * });
+ *
+ * // Check circuit breaker state
+ * if (queue.state === 'open') {
+ *   console.log('Circuit breaker is open, requests will fail fast');
+ * }
+ *
+ * // Reset if needed
+ * queue.reset();
+ * ```
  */
 export declare class RequestQueue {
     private queue;
@@ -23,61 +87,111 @@ export declare class RequestQueue {
     private readonly retryDelay;
     private readonly circuitBreakerThreshold;
     private readonly circuitBreakerTimeout;
+    /**
+     * Create a new request queue.
+     *
+     * @param options - Queue configuration options
+     */
     constructor(options?: QueueOptions);
     /**
-     * Enqueue a request
+     * Enqueue a request for execution.
+     *
+     * The request will be executed when a slot is available (based on
+     * maxConcurrent). If the request fails, it will be automatically
+     * retried up to maxRetries times with exponential backoff.
+     *
+     * @typeParam T - Return type of the request
+     * @param request - Async function that performs the request
+     * @returns Promise resolving to the request result
+     * @throws {CircuitBreakerOpenError} If the circuit breaker is open
+     * @throws {Error} If the request fails after all retries
+     *
+     * @example
+     * ```typescript
+     * const channels = await queue.enqueue(async () => {
+     *   return client.channels.list();
+     * });
+     * ```
      */
     enqueue<T>(request: () => Promise<T>): Promise<T>;
     /**
-     * Process the queue
+     * Process the queue by executing pending requests.
+     * @internal
      */
     private processQueue;
     /**
-     * Execute a single request with retry logic
+     * Execute a single request with retry logic.
+     * @internal
      */
     private executeRequest;
     /**
-     * Check if an error is retryable
+     * Check if an error is retryable.
+     * @internal
      */
     private isRetryable;
     /**
-     * Called on successful request
+     * Called on successful request to reset failure count.
+     * @internal
      */
     private onSuccess;
     /**
-     * Called on failed request
+     * Called on failed request to track failures.
+     * @internal
      */
     private onFailure;
     /**
-     * Update circuit breaker state based on timeout
+     * Update circuit breaker state based on timeout.
+     * @internal
      */
     private updateCircuitState;
     /**
-     * Delay helper
+     * Delay helper for retry backoff.
+     * @internal
      */
     private delay;
     /**
-     * Get current queue length
+     * Get the current queue length (pending requests).
      */
     get length(): number;
     /**
-     * Get current active request count
+     * Get the current number of active (executing) requests.
      */
     get active(): number;
     /**
-     * Get current circuit breaker state
+     * Get the current circuit breaker state.
+     *
+     * @returns Current state: 'closed', 'open', or 'half-open'
      */
     get state(): CircuitState;
     /**
-     * Get failure count
+     * Get the current consecutive failure count.
      */
     get failures(): number;
     /**
-     * Reset the circuit breaker
+     * Reset the circuit breaker to closed state.
+     *
+     * This clears the failure count and allows requests to proceed normally.
+     * Use this after fixing the underlying issue that caused failures.
+     *
+     * @example
+     * ```typescript
+     * // After fixing the issue
+     * queue.reset();
+     * console.log(queue.state); // 'closed'
+     * ```
      */
     reset(): void;
     /**
-     * Clear the queue (reject all pending requests)
+     * Clear the queue and reject all pending requests.
+     *
+     * Active requests will continue to execute, but pending requests
+     * in the queue will be rejected with an error.
+     *
+     * @example
+     * ```typescript
+     * // Cancel all pending requests
+     * queue.clear();
+     * ```
      */
     clear(): void;
 }

package/dist/queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AASvD,KAAK,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAEpD;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;;CAKjD;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,eAAe,CAAK;IAE5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACjD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;gBAEnC,OAAO,GAAE,YAAiB;IAQtC;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBvD;;OAEG;YACW,YAAY;IAuB1B;;OAEG;YACW,cAAc;IA0B5B;;OAEG;IACH,OAAO,CAAC,WAAW;IAyBnB;;OAEG;IACH,OAAO,CAAC,SAAS;IAOjB;;OAEG;IACH,OAAO,CAAC,SAAS;IAQjB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,YAAY,CAGxB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,KAAK,IAAI,IAAI;CAMd"}
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AASvD;;;;;;GAMG;AACH,KAAK,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAEpD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;;CAKjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,eAAe,CAAK;IAE5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACjD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAE/C;;;;OAIG;gBACS,OAAO,GAAE,YAAiB;IAQtC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBvD;;;OAGG;YACW,YAAY;IAuB1B;;;OAGG;YACW,cAAc;IA0B5B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAyBnB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAOjB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAQjB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;OAGG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;OAIG;IACH,IAAI,KAAK,IAAI,YAAY,CAGxB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,IAAI,IAAI;IAMb;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,IAAI;CAMd"}