@tanstack/pacer 0.5.0 → 0.7.0

package/dist/cjs/async-rate-limiter.d.cts

@@ -15,7 +15,9 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
      */
     limit: number | ((rateLimiter: AsyncRateLimiter<TFn>) => number);
     /**
-     * Optional error handler for when the rate-limited function throws
+     * Optional error handler for when the rate-limited function throws.
+     * If provided, the handler will be called with the error and rate limiter instance.
+     * This can be used alongside throwOnError - the handler will be called before any error is thrown.
      */
     onError?: (error: unknown, rateLimiter: AsyncRateLimiter<TFn>) => void;
     /**
@@ -30,6 +32,12 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
      * Optional function to call when the rate-limited function is executed
      */
     onSuccess?: (result: ReturnType<TFn>, rateLimiter: AsyncRateLimiter<TFn>) => void;
+    /**
+     * Whether to throw errors when they occur.
+     * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+     * Can be explicitly set to override these defaults.
+     */
+    throwOnError?: boolean;
     /**
      * Time window in milliseconds within which the limit applies.
      * Can be a number or a function that returns a number.
@@ -67,11 +75,29 @@ export interface AsyncRateLimiterOptions<TFn extends AnyAsyncFunction> {
  * Rate limiting is best used for hard API limits or resource constraints. For UI updates or
  * smoothing out frequent events, throttling or debouncing usually provide better user experience.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and rate limiter instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncRateLimiter instance
+ * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler
+ *
  * @example
  * ```ts
  * const rateLimiter = new AsyncRateLimiter(
  *   async (id: string) => await api.getData(id),
- *   { limit: 5, window: 1000, windowType: 'sliding' } // 5 calls per second with sliding window
+ *   {
+ *     limit: 5,
+ *     window: 1000,
+ *     windowType: 'sliding',
+ *     onError: (error) => {
+ *       console.error('API call failed:', error);
+ *     },
+ *     onReject: (limiter) => {
+ *       console.log(`Rate limit exceeded. Try again in ${limiter.getMsUntilNextWindow()}ms`);
+ *     }
+ *   }
  * );
  *
  * // Will execute immediately until limit reached, then block
@@ -92,13 +118,12 @@ export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
     constructor(fn: TFn, initialOptions: AsyncRateLimiterOptions<TFn>);
     /**
      * Updates the rate limiter options
-     * Returns the new options state
      */
     setOptions(newOptions: Partial<AsyncRateLimiterOptions<TFn>>): void;
     /**
      * Returns the current rate limiter options
      */
-    getOptions(): Required<AsyncRateLimiterOptions<TFn>>;
+    getOptions(): AsyncRateLimiterOptions<TFn>;
     /**
      * Returns the current enabled state of the rate limiter
      */
@@ -116,6 +141,19 @@ export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
      * Will reject execution if the number of calls in the current window exceeds the limit.
      * If execution is allowed, waits for any previous execution to complete before proceeding.
      *
+     * Error Handling:
+     * - If the rate-limited function throws and no `onError` handler is configured,
+     *   the error will be thrown from this method.
+     * - If an `onError` handler is configured, errors will be caught and passed to the handler,
+     *   and this method will return undefined.
+     * - If the rate limit is exceeded, the execution will be rejected and the `onReject` handler
+     *   will be called if configured.
+     * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
+     * - Rate limit rejections can be tracked using `getRejectionCount()`.
+     *
+     * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
+     * @throws The error from the rate-limited function if no onError handler is configured
+     *
      * @example
      * ```ts
      * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
@@ -128,7 +166,7 @@ export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
      * ```
      */
     maybeExecute(...args: Parameters<TFn>): Promise<ReturnType<TFn> | undefined>;
-    private executeFunction;
+    private execute;
     private rejectFunction;
     private cleanupOldExecutions;
     /**
@@ -187,6 +225,14 @@ export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  * Consider using throttle() or debounce() if you need more intelligent execution control. Use rate limiting when you specifically
  * need to enforce a hard limit on the number of executions within a time period.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and rate limiter instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncRateLimiter instance
+ * - Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler
+ *
  * @example
  * ```ts
  * // Rate limit to 5 calls per minute with a sliding window
@@ -194,6 +240,9 @@ export declare class AsyncRateLimiter<TFn extends AnyAsyncFunction> {
  *   limit: 5,
  *   window: 60000,
  *   windowType: 'sliding',
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   },
  *   onReject: (rateLimiter) => {
  *     console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
  *   }

package/dist/cjs/async-throttler.cjs

@@ -4,12 +4,6 @@ const utils = require("./utils.cjs");
 const defaultOptions = {
   enabled: true,
   leading: true,
-  onError: () => {
-  },
-  onSettled: () => {
-  },
-  onSuccess: () => {
-  },
   trailing: true,
   wait: 0
 };
@@ -24,14 +18,15 @@ class AsyncThrottler {
     this._settleCount = 0;
     this._successCount = 0;
     this._timeoutId = null;
+    this._resolvePreviousPromise = null;
     this._options = {
       ...defaultOptions,
-      ...initialOptions
+      ...initialOptions,
+      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError
     };
   }
   /**
    * Updates the throttler options
-   * Returns the new options state
    */
   setOptions(newOptions) {
     this._options = { ...this._options, ...newOptions };
@@ -49,7 +44,7 @@ class AsyncThrottler {
    * Returns the current enabled state of the throttler
    */
   getEnabled() {
-    return utils.parseFunctionOrValue(this._options.enabled, this);
+    return !!utils.parseFunctionOrValue(this._options.enabled, this);
   }
   /**
    * Returns the current wait time in milliseconds
@@ -58,19 +53,31 @@ class AsyncThrottler {
     return utils.parseFunctionOrValue(this._options.wait, this);
   }
   /**
-   * Attempts to execute the throttled function
-   * If a call is already in progress, it may be blocked or queued depending on the `wait` option
+   * Attempts to execute the throttled function.
+   * If a call is already in progress, it may be blocked or queued depending on the `wait` option.
+   *
+   * Error Handling:
+   * - If the throttled function throws and no `onError` handler is configured,
+   *   the error will be thrown from this method.
+   * - If an `onError` handler is configured, errors will be caught and passed to the handler,
+   *   and this method will return undefined.
+   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
+   *
+   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
+   * @throws The error from the throttled function if no onError handler is configured
    */
   async maybeExecute(...args) {
     const now = Date.now();
     const timeSinceLastExecution = now - this._lastExecutionTime;
     const wait = this.getWait();
+    this.resolvePreviousPromise();
     if (this._options.leading && timeSinceLastExecution >= wait) {
-      await this.executeFunction(...args);
+      await this.execute(...args);
       return this._lastResult;
     } else {
       this._lastArgs = args;
       return new Promise((resolve) => {
+        this._resolvePreviousPromise = resolve;
         if (this._timeoutId) {
           clearTimeout(this._timeoutId);
         }
@@ -79,35 +86,48 @@ class AsyncThrottler {
           const timeoutDuration = wait - _timeSinceLastExecution;
           this._timeoutId = setTimeout(async () => {
             if (this._lastArgs !== void 0) {
-              await this.executeFunction(...this._lastArgs);
+              await this.execute(...this._lastArgs);
             }
+            this._resolvePreviousPromise = null;
             resolve(this._lastResult);
           }, timeoutDuration);
         }
       });
     }
   }
-  async executeFunction(...args) {
+  async execute(...args) {
+    var _a, _b, _c, _d, _e, _f;
     if (!this.getEnabled() || this._isExecuting) return void 0;
     this._abortController = new AbortController();
     try {
       this._isExecuting = true;
       this._lastResult = await this.fn(...args);
       this._successCount++;
-      this._options.onSuccess(this._lastResult, this);
+      (_b = (_a = this._options).onSuccess) == null ? void 0 : _b.call(_a, this._lastResult, this);
     } catch (error) {
       this._errorCount++;
-      this._options.onError(error, this);
+      (_d = (_c = this._options).onError) == null ? void 0 : _d.call(_c, error, this);
+      if (this._options.throwOnError) {
+        throw error;
+      } else {
+        console.error(error);
+      }
     } finally {
       this._isExecuting = false;
       this._settleCount++;
       this._abortController = null;
       this._lastExecutionTime = Date.now();
       this._nextExecutionTime = this._lastExecutionTime + this.getWait();
-      this._options.onSettled(this);
+      (_f = (_e = this._options).onSettled) == null ? void 0 : _f.call(_e, this);
     }
     return this._lastResult;
   }
+  resolvePreviousPromise() {
+    if (this._resolvePreviousPromise) {
+      this._resolvePreviousPromise(this._lastResult);
+      this._resolvePreviousPromise = null;
+    }
+  }
   /**
    * Cancels any pending execution or aborts any execution in progress
    */
@@ -120,6 +140,7 @@ class AsyncThrottler {
       this._abortController.abort();
       this._abortController = null;
     }
+    this.resolvePreviousPromise();
     this._lastArgs = void 0;
   }
   /**

package/dist/cjs/async-throttler.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"async-throttler.cjs","sources":["../../src/async-throttler.ts"],"sourcesContent":["import { parseFunctionOrValue } from './utils'\nimport type { AnyAsyncFunction } from './types'\n\n/**\n * Options for configuring an async throttled function\n */\nexport interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {\n  /**\n   * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Can be a boolean or a function that returns a boolean.\n   * Defaults to true.\n   */\n  enabled?: boolean | ((throttler: AsyncThrottler<TFn>) => boolean)\n  /**\n   * Whether to execute the function immediately when called\n   * Defaults to true\n   */\n  leading?: boolean\n  /**\n   * Optional error handler for when the throttled function throws\n   */\n  onError?: (error: unknown, asyncThrottler: AsyncThrottler<TFn>) => void\n  /**\n   * Optional function to call when the throttled function is executed\n   */\n  onSettled?: (asyncThrottler: AsyncThrottler<TFn>) => void\n  /**\n   * Optional function to call when the throttled function is executed\n   */\n  onSuccess?: (\n    result: ReturnType<TFn>,\n    asyncThrottler: AsyncThrottler<TFn>,\n  ) => void\n  /**\n   * Whether to execute the function on the trailing edge of the wait period\n   * Defaults to true\n   */\n  trailing?: boolean\n  /**\n   * Time window in milliseconds during which the function can only be executed once.\n   * Can be a number or a function that returns a number.\n   * Defaults to 0ms\n   */\n  wait: number | ((throttler: AsyncThrottler<TFn>) => number)\n}\n\nconst defaultOptions: Required<AsyncThrottlerOptions<any>> = {\n  enabled: true,\n  leading: true,\n  onError: () => {},\n  onSettled: () => {},\n  onSuccess: () => {},\n  trailing: true,\n  wait: 0,\n}\n\n/**\n * A class that creates an async throttled function.\n *\n * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.\n * Unlike debouncing which resets the delay timer on each call, throttling ensures the function executes at a\n * regular interval regardless of how often it's called.\n *\n * Unlike the non-async Throttler, this async version supports returning values from the throttled function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the throttled function.\n *\n * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to\n * ensure a maximum execution frequency.\n *\n * @example\n * ```ts\n * const throttler = new AsyncThrottler(async (value: string) => {\n *   const result = await saveToAPI(value);\n *   return result; // Return value is preserved\n * }, { wait: 1000 });\n *\n * // Will only execute once per second no matter how often called\n * // Returns the API response directly\n * const result = await throttler.maybeExecute(inputElement.value);\n * ```\n */\nexport class AsyncThrottler<TFn extends AnyAsyncFunction> {\n  private _options: Required<AsyncThrottlerOptions<TFn>>\n  private _abortController: AbortController | null = null\n  private _errorCount = 0\n  private _isExecuting = false\n  private _lastArgs: Parameters<TFn> | undefined\n  private _lastExecutionTime = 0\n  private _lastResult: ReturnType<TFn> | undefined\n  private _nextExecutionTime = 0\n  private _settleCount = 0\n  private _successCount = 0\n  private _timeoutId: NodeJS.Timeout | null = null\n\n  constructor(\n    private fn: TFn,\n    initialOptions: AsyncThrottlerOptions<TFn>,\n  ) {\n    this._options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the throttler options\n   * Returns the new options state\n   */\n  setOptions(newOptions: Partial<AsyncThrottlerOptions<TFn>>): void {\n    this._options = { ...this._options, ...newOptions }\n\n    // End the pending state if the debouncer is disabled\n    if (!this._options.enabled) {\n      this.cancel()\n    }\n  }\n\n  /**\n   * Returns the current options\n   */\n  getOptions(): Required<AsyncThrottlerOptions<TFn>> {\n    return this._options\n  }\n\n  /**\n   * Returns the current enabled state of the throttler\n   */\n  getEnabled(): boolean {\n    return parseFunctionOrValue(this._options.enabled, this)\n  }\n\n  /**\n   * Returns the current wait time in milliseconds\n   */\n  getWait(): number {\n    return parseFunctionOrValue(this._options.wait, this)\n  }\n\n  /**\n   * Attempts to execute the throttled function\n   * If a call is already in progress, it may be blocked or queued depending on the `wait` option\n   */\n  async maybeExecute(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    const now = Date.now()\n    const timeSinceLastExecution = now - this._lastExecutionTime\n    const wait = this.getWait()\n\n    // Handle leading execution\n    if (this._options.leading && timeSinceLastExecution >= wait) {\n      await this.executeFunction(...args)\n      return this._lastResult\n    } else {\n      // Store the most recent arguments for potential trailing execution\n      this._lastArgs = args\n\n      return new Promise((resolve) => {\n        // Clear any existing timeout to ensure we use the latest arguments\n        if (this._timeoutId) {\n          clearTimeout(this._timeoutId)\n        }\n\n        // Set up trailing execution if enabled\n        if (this._options.trailing) {\n          const _timeSinceLastExecution = this._lastExecutionTime\n            ? now - this._lastExecutionTime\n            : 0\n          const timeoutDuration = wait - _timeSinceLastExecution\n          this._timeoutId = setTimeout(async () => {\n            if (this._lastArgs !== undefined) {\n              await this.executeFunction(...this._lastArgs)\n            }\n            resolve(this._lastResult)\n          }, timeoutDuration)\n        }\n      })\n    }\n  }\n\n  private async executeFunction(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    if (!this.getEnabled() || this._isExecuting) return undefined\n    this._abortController = new AbortController()\n    try {\n      this._isExecuting = true\n      this._lastResult = await this.fn(...args) // EXECUTE!\n      this._successCount++\n      this._options.onSuccess(this._lastResult!, this)\n    } catch (error) {\n      this._errorCount++\n      this._options.onError(error, this)\n    } finally {\n      this._isExecuting = false\n      this._settleCount++\n      this._abortController = null\n      this._lastExecutionTime = Date.now()\n      this._nextExecutionTime = this._lastExecutionTime + this.getWait()\n      this._options.onSettled(this)\n    }\n    return this._lastResult\n  }\n\n  /**\n   * Cancels any pending execution or aborts any execution in progress\n   */\n  cancel(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = null\n    }\n    if (this._abortController) {\n      this._abortController.abort()\n      this._abortController = null\n    }\n    this._lastArgs = undefined\n  }\n\n  /**\n   * Returns the last execution time\n   */\n  getLastExecutionTime(): number {\n    return this._lastExecutionTime\n  }\n\n  /**\n   * Returns the next execution time\n   */\n  getNextExecutionTime(): number {\n    return this._nextExecutionTime\n  }\n\n  /**\n   * Returns the last result of the debounced function\n   */\n  getLastResult(): ReturnType<TFn> | undefined {\n    return this._lastResult\n  }\n\n  /**\n   * Returns the number of times the function has been executed successfully\n   */\n  getSuccessCount(): number {\n    return this._successCount\n  }\n\n  /**\n   * Returns the number of times the function has settled (completed or errored)\n   */\n  getSettleCount(): number {\n    return this._settleCount\n  }\n\n  /**\n   * Returns the number of times the function has errored\n   */\n  getErrorCount(): number {\n    return this._errorCount\n  }\n\n  /**\n   * Returns the current pending state\n   */\n  getIsPending(): boolean {\n    return this.getEnabled() && !!this._timeoutId\n  }\n\n  /**\n   * Returns the current executing state\n   */\n  getIsExecuting(): boolean {\n    return this._isExecuting\n  }\n}\n\n/**\n * Creates an async throttled function that limits how often the function can execute.\n * The throttled function will execute at most once per wait period, even if called multiple times.\n * If called while executing, it will wait until execution completes before scheduling the next call.\n *\n * Unlike the non-async Throttler, this async version supports returning values from the throttled function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the throttled function.\n *\n * @example\n * ```ts\n * const throttled = asyncThrottle(async (value: string) => {\n *   const result = await saveToAPI(value);\n *   return result; // Return value is preserved\n * }, { wait: 1000 });\n *\n * // This will execute at most once per second\n * // Returns the API response directly\n * const result = await throttled(inputElement.value);\n * ```\n */\nexport function asyncThrottle<TFn extends AnyAsyncFunction>(\n  fn: TFn,\n  initialOptions: AsyncThrottlerOptions<TFn>,\n) {\n  const asyncThrottler = new AsyncThrottler(fn, initialOptions)\n  return asyncThrottler.maybeExecute.bind(asyncThrottler)\n}\n"],"names":["parseFunctionOrValue"],"mappings":"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"}
+{"version":3,"file":"async-throttler.cjs","sources":["../../src/async-throttler.ts"],"sourcesContent":["import { parseFunctionOrValue } from './utils'\nimport type { AnyAsyncFunction, OptionalKeys } from './types'\n\n/**\n * Options for configuring an async throttled function\n */\nexport interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {\n  /**\n   * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Can be a boolean or a function that returns a boolean.\n   * Defaults to true.\n   */\n  enabled?: boolean | ((throttler: AsyncThrottler<TFn>) => boolean)\n  /**\n   * Whether to execute the function immediately when called\n   * Defaults to true\n   */\n  leading?: boolean\n  /**\n   * Optional error handler for when the throttled function throws.\n   * If provided, the handler will be called with the error and throttler instance.\n   * This can be used alongside throwOnError - the handler will be called before any error is thrown.\n   */\n  onError?: (error: unknown, asyncThrottler: AsyncThrottler<TFn>) => void\n  /**\n   * Optional function to call when the throttled function is executed\n   */\n  onSettled?: (asyncThrottler: AsyncThrottler<TFn>) => void\n  /**\n   * Optional function to call when the throttled function is executed\n   */\n  onSuccess?: (\n    result: ReturnType<TFn>,\n    asyncThrottler: AsyncThrottler<TFn>,\n  ) => void\n  /**\n   * Whether to throw errors when they occur.\n   * Defaults to true if no onError handler is provided, false if an onError handler is provided.\n   * Can be explicitly set to override these defaults.\n   */\n  throwOnError?: boolean\n  /**\n   * Whether to execute the function on the trailing edge of the wait period\n   * Defaults to true\n   */\n  trailing?: boolean\n  /**\n   * Time window in milliseconds during which the function can only be executed once.\n   * Can be a number or a function that returns a number.\n   * Defaults to 0ms\n   */\n  wait: number | ((throttler: AsyncThrottler<TFn>) => number)\n}\n\ntype AsyncThrottlerOptionsWithOptionalCallbacks = OptionalKeys<\n  AsyncThrottlerOptions<any>,\n  'onError' | 'onSettled' | 'onSuccess'\n>\n\nconst defaultOptions: AsyncThrottlerOptionsWithOptionalCallbacks = {\n  enabled: true,\n  leading: true,\n  trailing: true,\n  wait: 0,\n}\n\n/**\n * A class that creates an async throttled function.\n *\n * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.\n * Unlike debouncing which resets the delay timer on each call, throttling ensures the function executes at a\n * regular interval regardless of how often it's called.\n *\n * Unlike the non-async Throttler, this async version supports returning values from the throttled function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the throttled function.\n *\n * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to\n * ensure a maximum execution frequency.\n *\n * Error Handling:\n * - If an `onError` handler is provided, it will be called with the error and throttler instance\n * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown\n * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed\n * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown\n * - The error state can be checked using the underlying AsyncThrottler instance\n *\n * @example\n * ```ts\n * const throttler = new AsyncThrottler(async (value: string) => {\n *   const result = await saveToAPI(value);\n *   return result; // Return value is preserved\n * }, {\n *   wait: 1000,\n *   onError: (error) => {\n *     console.error('API call failed:', error);\n *   }\n * });\n *\n * // Will only execute once per second no matter how often called\n * // Returns the API response directly\n * const result = await throttler.maybeExecute(inputElement.value);\n * ```\n */\nexport class AsyncThrottler<TFn extends AnyAsyncFunction> {\n  private _options: AsyncThrottlerOptionsWithOptionalCallbacks\n  private _abortController: AbortController | null = null\n  private _errorCount = 0\n  private _isExecuting = false\n  private _lastArgs: Parameters<TFn> | undefined\n  private _lastExecutionTime = 0\n  private _lastResult: ReturnType<TFn> | undefined\n  private _nextExecutionTime = 0\n  private _settleCount = 0\n  private _successCount = 0\n  private _timeoutId: NodeJS.Timeout | null = null\n  private _resolvePreviousPromise:\n    | ((value?: ReturnType<TFn> | undefined) => void)\n    | null = null\n\n  constructor(\n    private fn: TFn,\n    initialOptions: AsyncThrottlerOptions<TFn>,\n  ) {\n    this._options = {\n      ...defaultOptions,\n      ...initialOptions,\n      throwOnError: initialOptions.throwOnError ?? !initialOptions.onError,\n    }\n  }\n\n  /**\n   * Updates the throttler options\n   */\n  setOptions(newOptions: Partial<AsyncThrottlerOptions<TFn>>): void {\n    this._options = { ...this._options, ...newOptions }\n\n    // End the pending state if the debouncer is disabled\n    if (!this._options.enabled) {\n      this.cancel()\n    }\n  }\n\n  /**\n   * Returns the current options\n   */\n  getOptions(): AsyncThrottlerOptions<TFn> {\n    return this._options\n  }\n\n  /**\n   * Returns the current enabled state of the throttler\n   */\n  getEnabled(): boolean {\n    return !!parseFunctionOrValue(this._options.enabled, this)\n  }\n\n  /**\n   * Returns the current wait time in milliseconds\n   */\n  getWait(): number {\n    return parseFunctionOrValue(this._options.wait, this)\n  }\n\n  /**\n   * Attempts to execute the throttled function.\n   * If a call is already in progress, it may be blocked or queued depending on the `wait` option.\n   *\n   * Error Handling:\n   * - If the throttled function throws and no `onError` handler is configured,\n   *   the error will be thrown from this method.\n   * - If an `onError` handler is configured, errors will be caught and passed to the handler,\n   *   and this method will return undefined.\n   * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.\n   *\n   * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError\n   * @throws The error from the throttled function if no onError handler is configured\n   */\n  async maybeExecute(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    const now = Date.now()\n    const timeSinceLastExecution = now - this._lastExecutionTime\n    const wait = this.getWait()\n\n    this.resolvePreviousPromise()\n\n    // Handle leading execution\n    if (this._options.leading && timeSinceLastExecution >= wait) {\n      await this.execute(...args)\n      return this._lastResult\n    } else {\n      // Store the most recent arguments for potential trailing execution\n      this._lastArgs = args\n\n      return new Promise((resolve) => {\n        this._resolvePreviousPromise = resolve\n        // Clear any existing timeout to ensure we use the latest arguments\n        if (this._timeoutId) {\n          clearTimeout(this._timeoutId)\n        }\n\n        // Set up trailing execution if enabled\n        if (this._options.trailing) {\n          const _timeSinceLastExecution = this._lastExecutionTime\n            ? now - this._lastExecutionTime\n            : 0\n          const timeoutDuration = wait - _timeSinceLastExecution\n          this._timeoutId = setTimeout(async () => {\n            if (this._lastArgs !== undefined) {\n              await this.execute(...this._lastArgs)\n            }\n            this._resolvePreviousPromise = null\n            resolve(this._lastResult)\n          }, timeoutDuration)\n        }\n      })\n    }\n  }\n\n  private async execute(\n    ...args: Parameters<TFn>\n  ): Promise<ReturnType<TFn> | undefined> {\n    if (!this.getEnabled() || this._isExecuting) return undefined\n    this._abortController = new AbortController()\n    try {\n      this._isExecuting = true\n      this._lastResult = await this.fn(...args) // EXECUTE!\n      this._successCount++\n      this._options.onSuccess?.(this._lastResult!, this)\n    } catch (error) {\n      this._errorCount++\n      this._options.onError?.(error, this)\n      if (this._options.throwOnError) {\n        throw error\n      } else {\n        console.error(error)\n      }\n    } finally {\n      this._isExecuting = false\n      this._settleCount++\n      this._abortController = null\n      this._lastExecutionTime = Date.now()\n      this._nextExecutionTime = this._lastExecutionTime + this.getWait()\n      this._options.onSettled?.(this)\n    }\n    return this._lastResult\n  }\n\n  private resolvePreviousPromise(): void {\n    if (this._resolvePreviousPromise) {\n      this._resolvePreviousPromise(this._lastResult)\n      this._resolvePreviousPromise = null\n    }\n  }\n\n  /**\n   * Cancels any pending execution or aborts any execution in progress\n   */\n  cancel(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = null\n    }\n    if (this._abortController) {\n      this._abortController.abort()\n      this._abortController = null\n    }\n    this.resolvePreviousPromise()\n    this._lastArgs = undefined\n  }\n\n  /**\n   * Returns the last execution time\n   */\n  getLastExecutionTime(): number {\n    return this._lastExecutionTime\n  }\n\n  /**\n   * Returns the next execution time\n   */\n  getNextExecutionTime(): number {\n    return this._nextExecutionTime\n  }\n\n  /**\n   * Returns the last result of the debounced function\n   */\n  getLastResult(): ReturnType<TFn> | undefined {\n    return this._lastResult\n  }\n\n  /**\n   * Returns the number of times the function has been executed successfully\n   */\n  getSuccessCount(): number {\n    return this._successCount\n  }\n\n  /**\n   * Returns the number of times the function has settled (completed or errored)\n   */\n  getSettleCount(): number {\n    return this._settleCount\n  }\n\n  /**\n   * Returns the number of times the function has errored\n   */\n  getErrorCount(): number {\n    return this._errorCount\n  }\n\n  /**\n   * Returns the current pending state\n   */\n  getIsPending(): boolean {\n    return this.getEnabled() && !!this._timeoutId\n  }\n\n  /**\n   * Returns the current executing state\n   */\n  getIsExecuting(): boolean {\n    return this._isExecuting\n  }\n}\n\n/**\n * Creates an async throttled function that limits how often the function can execute.\n * The throttled function will execute at most once per wait period, even if called multiple times.\n * If called while executing, it will wait until execution completes before scheduling the next call.\n *\n * Unlike the non-async Throttler, this async version supports returning values from the throttled function,\n * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call\n * instead of setting the result on a state variable from within the throttled function.\n *\n * Error Handling:\n * - If an `onError` handler is provided, it will be called with the error and throttler instance\n * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown\n * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed\n * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown\n * - The error state can be checked using the underlying AsyncThrottler instance\n *\n * @example\n * ```ts\n * const throttled = asyncThrottle(async (value: string) => {\n *   const result = await saveToAPI(value);\n *   return result; // Return value is preserved\n * }, {\n *   wait: 1000,\n *   onError: (error) => {\n *     console.error('API call failed:', error);\n *   }\n * });\n *\n * // This will execute at most once per second\n * // Returns the API response directly\n * const result = await throttled(inputElement.value);\n * ```\n */\nexport function asyncThrottle<TFn extends AnyAsyncFunction>(\n  fn: TFn,\n  initialOptions: AsyncThrottlerOptions<TFn>,\n) {\n  const asyncThrottler = new AsyncThrottler(fn, initialOptions)\n  return asyncThrottler.maybeExecute.bind(asyncThrottler)\n}\n"],"names":["parseFunctionOrValue"],"mappings":"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"}

package/dist/cjs/async-throttler.d.cts

@@ -15,7 +15,9 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
      */
     leading?: boolean;
     /**
-     * Optional error handler for when the throttled function throws
+     * Optional error handler for when the throttled function throws.
+     * If provided, the handler will be called with the error and throttler instance.
+     * This can be used alongside throwOnError - the handler will be called before any error is thrown.
      */
     onError?: (error: unknown, asyncThrottler: AsyncThrottler<TFn>) => void;
     /**
@@ -26,6 +28,12 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
      * Optional function to call when the throttled function is executed
      */
     onSuccess?: (result: ReturnType<TFn>, asyncThrottler: AsyncThrottler<TFn>) => void;
+    /**
+     * Whether to throw errors when they occur.
+     * Defaults to true if no onError handler is provided, false if an onError handler is provided.
+     * Can be explicitly set to override these defaults.
+     */
+    throwOnError?: boolean;
     /**
      * Whether to execute the function on the trailing edge of the wait period
      * Defaults to true
@@ -52,12 +60,24 @@ export interface AsyncThrottlerOptions<TFn extends AnyAsyncFunction> {
  * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to
  * ensure a maximum execution frequency.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
  * @example
  * ```ts
  * const throttler = new AsyncThrottler(async (value: string) => {
  *   const result = await saveToAPI(value);
  *   return result; // Return value is preserved
- * }, { wait: 1000 });
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   }
+ * });
  *
  * // Will only execute once per second no matter how often called
  * // Returns the API response directly
@@ -77,16 +97,16 @@ export declare class AsyncThrottler<TFn extends AnyAsyncFunction> {
     private _settleCount;
     private _successCount;
     private _timeoutId;
+    private _resolvePreviousPromise;
     constructor(fn: TFn, initialOptions: AsyncThrottlerOptions<TFn>);
     /**
      * Updates the throttler options
-     * Returns the new options state
      */
     setOptions(newOptions: Partial<AsyncThrottlerOptions<TFn>>): void;
     /**
      * Returns the current options
      */
-    getOptions(): Required<AsyncThrottlerOptions<TFn>>;
+    getOptions(): AsyncThrottlerOptions<TFn>;
     /**
      * Returns the current enabled state of the throttler
      */
@@ -96,11 +116,22 @@ export declare class AsyncThrottler<TFn extends AnyAsyncFunction> {
      */
     getWait(): number;
     /**
-     * Attempts to execute the throttled function
-     * If a call is already in progress, it may be blocked or queued depending on the `wait` option
+     * Attempts to execute the throttled function.
+     * If a call is already in progress, it may be blocked or queued depending on the `wait` option.
+     *
+     * Error Handling:
+     * - If the throttled function throws and no `onError` handler is configured,
+     *   the error will be thrown from this method.
+     * - If an `onError` handler is configured, errors will be caught and passed to the handler,
+     *   and this method will return undefined.
+     * - The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
+     *
+     * @returns A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
+     * @throws The error from the throttled function if no onError handler is configured
      */
     maybeExecute(...args: Parameters<TFn>): Promise<ReturnType<TFn> | undefined>;
-    private executeFunction;
+    private execute;
+    private resolvePreviousPromise;
     /**
      * Cancels any pending execution or aborts any execution in progress
      */
@@ -147,12 +178,24 @@ export declare class AsyncThrottler<TFn extends AnyAsyncFunction> {
  * making it ideal for API calls and other async operations where you want the result of the `maybeExecute` call
  * instead of setting the result on a state variable from within the throttled function.
  *
+ * Error Handling:
+ * - If an `onError` handler is provided, it will be called with the error and throttler instance
+ * - If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
+ * - If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
+ * - Both onError and throwOnError can be used together - the handler will be called before any error is thrown
+ * - The error state can be checked using the underlying AsyncThrottler instance
+ *
  * @example
  * ```ts
  * const throttled = asyncThrottle(async (value: string) => {
  *   const result = await saveToAPI(value);
  *   return result; // Return value is preserved
- * }, { wait: 1000 });
+ * }, {
+ *   wait: 1000,
+ *   onError: (error) => {
+ *     console.error('API call failed:', error);
+ *   }
+ * });
  *
  * // This will execute at most once per second
  * // Returns the API response directly

package/dist/cjs/batcher.cjs

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const defaultOptions = {
+  getShouldExecute: () => false,
+  maxSize: Infinity,
+  started: true,
+  wait: Infinity
+};
+class Batcher {
+  constructor(fn, initialOptions) {
+    this.fn = fn;
+    this._batchExecutionCount = 0;
+    this._itemExecutionCount = 0;
+    this._items = [];
+    this._timeoutId = null;
+    this._options = { ...defaultOptions, ...initialOptions };
+    this._running = this._options.started;
+  }
+  /**
+   * Updates the batcher options
+   */
+  setOptions(newOptions) {
+    this._options = { ...this._options, ...newOptions };
+  }
+  /**
+   * Returns the current batcher options
+   */
+  getOptions() {
+    return this._options;
+  }
+  /**
+   * Adds an item to the batcher
+   * If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed
+   */
+  addItem(item) {
+    var _a, _b;
+    this._items.push(item);
+    (_b = (_a = this._options).onItemsChange) == null ? void 0 : _b.call(_a, this);
+    const shouldProcess = this._items.length >= this._options.maxSize || this._options.getShouldExecute(this._items, this);
+    if (shouldProcess) {
+      this.execute();
+    } else if (this._running && !this._timeoutId && this._options.wait !== Infinity) {
+      this._timeoutId = setTimeout(() => this.execute(), this._options.wait);
+    }
+  }
+  /**
+   * Processes the current batch of items.
+   * This method will automatically be triggered if the batcher is running and any of these conditions are met:
+   * - The number of items reaches batchSize
+   * - The wait duration has elapsed
+   * - The getShouldExecute function returns true upon adding an item
+   *
+   * You can also call this method manually to process the current batch at any time.
+   */
+  execute() {
+    var _a, _b, _c, _d;
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId);
+      this._timeoutId = null;
+    }
+    if (this._items.length === 0) {
+      return;
+    }
+    const batch2 = this.getAllItems();
+    this._items = [];
+    (_b = (_a = this._options).onItemsChange) == null ? void 0 : _b.call(_a, this);
+    this.fn(batch2);
+    this._batchExecutionCount++;
+    this._itemExecutionCount += batch2.length;
+    (_d = (_c = this._options).onExecute) == null ? void 0 : _d.call(_c, this);
+  }
+  /**
+   * Stops the batcher from processing batches
+   */
+  stop() {
+    var _a, _b;
+    this._running = false;
+    (_b = (_a = this._options).onIsRunningChange) == null ? void 0 : _b.call(_a, this);
+    if (this._timeoutId) {
+      clearTimeout(this._timeoutId);
+      this._timeoutId = null;
+    }
+  }
+  /**
+   * Starts the batcher and processes any pending items
+   */
+  start() {
+    var _a, _b;
+    this._running = true;
+    (_b = (_a = this._options).onIsRunningChange) == null ? void 0 : _b.call(_a, this);
+    if (this._items.length > 0 && !this._timeoutId) {
+      this._timeoutId = setTimeout(() => this.execute(), this._options.wait);
+    }
+  }
+  /**
+   * Returns the current number of items in the batcher
+   */
+  getSize() {
+    return this._items.length;
+  }
+  /**
+   * Returns true if the batcher is empty
+   */
+  getIsEmpty() {
+    return this._items.length === 0;
+  }
+  /**
+   * Returns true if the batcher is running
+   */
+  getIsRunning() {
+    return this._running;
+  }
+  /**
+   * Returns a copy of all items currently in the batcher
+   */
+  getAllItems() {
+    return [...this._items];
+  }
+  /**
+   * Returns the number of times batches have been processed
+   */
+  getBatchExecutionCount() {
+    return this._batchExecutionCount;
+  }
+  /**
+   * Returns the total number of individual items that have been processed
+   */
+  getItemExecutionCount() {
+    return this._itemExecutionCount;
+  }
+}
+function batch(fn, options) {
+  const batcher = new Batcher(fn, options);
+  return batcher.addItem.bind(batcher);
+}
+exports.Batcher = Batcher;
+exports.batch = batch;
+//# sourceMappingURL=batcher.cjs.map

package/dist/cjs/batcher.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"batcher.cjs","sources":["../../src/batcher.ts"],"sourcesContent":["import type { OptionalKeys } from './types'\n\n/**\n * Options for configuring a Batcher instance\n */\nexport interface BatcherOptions<TValue> {\n  /**\n   * Custom function to determine if a batch should be processed\n   * Return true to process the batch immediately\n   */\n  getShouldExecute?: (items: Array<TValue>, batcher: Batcher<TValue>) => boolean\n  /**\n   * Maximum number of items in a batch\n   * @default Infinity\n   */\n  maxSize?: number\n  /**\n   * Callback fired after a batch is processed\n   */\n  onExecute?: (batcher: Batcher<TValue>) => void\n  /**\n   * Callback fired when the batcher's running state changes\n   */\n  onIsRunningChange?: (batcher: Batcher<TValue>) => void\n  /**\n   * Callback fired after items are added to the batcher\n   */\n  onItemsChange?: (batcher: Batcher<TValue>) => void\n  /**\n   * Whether the batcher should start processing immediately\n   * @default true\n   */\n  started?: boolean\n  /**\n   * Maximum time in milliseconds to wait before processing a batch.\n   * If the wait duration has elapsed, the batch will be processed.\n   * If not provided, the batch will not be triggered by a timeout.\n   * @default Infinity\n   */\n  wait?: number\n}\n\ntype BatcherOptionsWithOptionalCallbacks<TValue> = OptionalKeys<\n  Required<BatcherOptions<TValue>>,\n  'onExecute' | 'onItemsChange' | 'onIsRunningChange'\n>\n\nconst defaultOptions: BatcherOptionsWithOptionalCallbacks<any> = {\n  getShouldExecute: () => false,\n  maxSize: Infinity,\n  started: true,\n  wait: Infinity,\n}\n\n/**\n * A class that collects items and processes them in batches.\n *\n * Batching is a technique for grouping multiple operations together to be processed as a single unit.\n *\n * The Batcher provides a flexible way to implement batching with configurable:\n * - Maximum batch size (number of items per batch)\n * - Time-based batching (process after X milliseconds)\n * - Custom batch processing logic via getShouldExecute\n * - Event callbacks for monitoring batch operations\n *\n * @example\n * ```ts\n * const batcher = new Batcher<number>(\n *   (items) => console.log('Processing batch:', items),\n *   {\n *     maxSize: 5,\n *     wait: 2000,\n *     onExecuteBatch: (items) => console.log('Batch executed:', items)\n *   }\n * );\n *\n * batcher.addItem(1);\n * batcher.addItem(2);\n * // After 2 seconds or when 5 items are added, whichever comes first,\n * // the batch will be processed\n * // batcher.execute() // manually trigger a batch\n * ```\n */\nexport class Batcher<TValue> {\n  private _options: BatcherOptionsWithOptionalCallbacks<TValue>\n  private _batchExecutionCount = 0\n  private _itemExecutionCount = 0\n  private _items: Array<TValue> = []\n  private _running: boolean\n  private _timeoutId: NodeJS.Timeout | null = null\n\n  constructor(\n    private fn: (items: Array<TValue>) => void,\n    initialOptions: BatcherOptions<TValue>,\n  ) {\n    this._options = { ...defaultOptions, ...initialOptions }\n    this._running = this._options.started\n  }\n\n  /**\n   * Updates the batcher options\n   */\n  setOptions(newOptions: Partial<BatcherOptions<TValue>>): void {\n    this._options = { ...this._options, ...newOptions }\n  }\n\n  /**\n   * Returns the current batcher options\n   */\n  getOptions(): BatcherOptions<TValue> {\n    return this._options\n  }\n\n  /**\n   * Adds an item to the batcher\n   * If the batch size is reached, timeout occurs, or shouldProcess returns true, the batch will be processed\n   */\n  addItem(item: TValue): void {\n    this._items.push(item)\n    this._options.onItemsChange?.(this)\n\n    const shouldProcess =\n      this._items.length >= this._options.maxSize ||\n      this._options.getShouldExecute(this._items, this)\n\n    if (shouldProcess) {\n      this.execute()\n    } else if (\n      this._running &&\n      !this._timeoutId &&\n      this._options.wait !== Infinity\n    ) {\n      this._timeoutId = setTimeout(() => this.execute(), this._options.wait)\n    }\n  }\n\n  /**\n   * Processes the current batch of items.\n   * This method will automatically be triggered if the batcher is running and any of these conditions are met:\n   * - The number of items reaches batchSize\n   * - The wait duration has elapsed\n   * - The getShouldExecute function returns true upon adding an item\n   *\n   * You can also call this method manually to process the current batch at any time.\n   */\n  execute(): void {\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = null\n    }\n\n    if (this._items.length === 0) {\n      return\n    }\n\n    const batch = this.getAllItems() // copy of the items to be processed (to prevent race conditions)\n    this._items = [] // Clear items before processing to prevent race conditions\n    this._options.onItemsChange?.(this) // Call onItemsChange to notify listeners that the items have changed\n\n    this.fn(batch)\n    this._batchExecutionCount++\n    this._itemExecutionCount += batch.length\n    this._options.onExecute?.(this)\n  }\n\n  /**\n   * Stops the batcher from processing batches\n   */\n  stop(): void {\n    this._running = false\n    this._options.onIsRunningChange?.(this)\n    if (this._timeoutId) {\n      clearTimeout(this._timeoutId)\n      this._timeoutId = null\n    }\n  }\n\n  /**\n   * Starts the batcher and processes any pending items\n   */\n  start(): void {\n    this._running = true\n    this._options.onIsRunningChange?.(this)\n    if (this._items.length > 0 && !this._timeoutId) {\n      this._timeoutId = setTimeout(() => this.execute(), this._options.wait)\n    }\n  }\n\n  /**\n   * Returns the current number of items in the batcher\n   */\n  getSize(): number {\n    return this._items.length\n  }\n\n  /**\n   * Returns true if the batcher is empty\n   */\n  getIsEmpty(): boolean {\n    return this._items.length === 0\n  }\n\n  /**\n   * Returns true if the batcher is running\n   */\n  getIsRunning(): boolean {\n    return this._running\n  }\n\n  /**\n   * Returns a copy of all items currently in the batcher\n   */\n  getAllItems(): Array<TValue> {\n    return [...this._items]\n  }\n\n  /**\n   * Returns the number of times batches have been processed\n   */\n  getBatchExecutionCount(): number {\n    return this._batchExecutionCount\n  }\n\n  /**\n   * Returns the total number of individual items that have been processed\n   */\n  getItemExecutionCount(): number {\n    return this._itemExecutionCount\n  }\n}\n\n/**\n * Creates a batcher that processes items in batches\n *\n * @example\n * ```ts\n * const batchItems = batch<number>({\n *   batchSize: 3,\n *   processBatch: (items) => console.log('Processing:', items)\n * });\n *\n * batchItems(1);\n * batchItems(2);\n * batchItems(3); // Triggers batch processing\n * ```\n */\nexport function batch<TValue>(\n  fn: (items: Array<TValue>) => void,\n  options: BatcherOptions<TValue>,\n) {\n  const batcher = new Batcher<TValue>(fn, options)\n  return batcher.addItem.bind(batcher)\n}\n"],"names":["batch"],"mappings":";;AA+CA,MAAM,iBAA2D;AAAA,EAC/D,kBAAkB,MAAM;AAAA,EACxB,SAAS;AAAA,EACT,SAAS;AAAA,EACT,MAAM;AACR;AA+BO,MAAM,QAAgB;AAAA,EAQ3B,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AAPV,SAAQ,uBAAuB;AAC/B,SAAQ,sBAAsB;AAC9B,SAAQ,SAAwB,CAAC;AAEjC,SAAQ,aAAoC;AAM1C,SAAK,WAAW,EAAE,GAAG,gBAAgB,GAAG,eAAe;AAClD,SAAA,WAAW,KAAK,SAAS;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMhC,WAAW,YAAmD;AAC5D,SAAK,WAAW,EAAE,GAAG,KAAK,UAAU,GAAG,WAAW;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMpD,aAAqC;AACnC,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOd,QAAQ,MAAoB;;AACrB,SAAA,OAAO,KAAK,IAAI;AAChB,qBAAA,UAAS,kBAAT,4BAAyB;AAE9B,UAAM,gBACJ,KAAK,OAAO,UAAU,KAAK,SAAS,WACpC,KAAK,SAAS,iBAAiB,KAAK,QAAQ,IAAI;AAElD,QAAI,eAAe;AACjB,WAAK,QAAQ;AAAA,IAAA,WAEb,KAAK,YACL,CAAC,KAAK,cACN,KAAK,SAAS,SAAS,UACvB;AACK,WAAA,aAAa,WAAW,MAAM,KAAK,WAAW,KAAK,SAAS,IAAI;AAAA,IAAA;AAAA,EACvE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYF,UAAgB;;AACd,QAAI,KAAK,YAAY;AACnB,mBAAa,KAAK,UAAU;AAC5B,WAAK,aAAa;AAAA,IAAA;AAGhB,QAAA,KAAK,OAAO,WAAW,GAAG;AAC5B;AAAA,IAAA;AAGIA,UAAAA,SAAQ,KAAK,YAAY;AAC/B,SAAK,SAAS,CAAC;AACV,qBAAA,UAAS,kBAAT,4BAAyB;AAE9B,SAAK,GAAGA,MAAK;AACR,SAAA;AACL,SAAK,uBAAuBA,OAAM;AAC7B,qBAAA,UAAS,cAAT,4BAAqB;AAAA,EAAI;AAAA;AAAA;AAAA;AAAA,EAMhC,OAAa;;AACX,SAAK,WAAW;AACX,qBAAA,UAAS,sBAAT,4BAA6B;AAClC,QAAI,KAAK,YAAY;AACnB,mBAAa,KAAK,UAAU;AAC5B,WAAK,aAAa;AAAA,IAAA;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA,EAMF,QAAc;;AACZ,SAAK,WAAW;AACX,qBAAA,UAAS,sBAAT,4BAA6B;AAClC,QAAI,KAAK,OAAO,SAAS,KAAK,CAAC,KAAK,YAAY;AACzC,WAAA,aAAa,WAAW,MAAM,KAAK,WAAW,KAAK,SAAS,IAAI;AAAA,IAAA;AAAA,EACvE;AAAA;AAAA;AAAA;AAAA,EAMF,UAAkB;AAChB,WAAO,KAAK,OAAO;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMrB,aAAsB;AACb,WAAA,KAAK,OAAO,WAAW;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMhC,eAAwB;AACtB,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,cAA6B;AACpB,WAAA,CAAC,GAAG,KAAK,MAAM;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMxB,yBAAiC;AAC/B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,wBAAgC;AAC9B,WAAO,KAAK;AAAA,EAAA;AAEhB;AAiBgB,SAAA,MACd,IACA,SACA;AACA,QAAM,UAAU,IAAI,QAAgB,IAAI,OAAO;AACxC,SAAA,QAAQ,QAAQ,KAAK,OAAO;AACrC;;;"}