@tanstack/pacer 0.1.0

package/dist/esm/async-throttler.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Options for configuring an async throttled function
+ */
+export interface AsyncThrottlerOptions {
+    /**
+     * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
+     * Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * Time window in milliseconds during which the function can only be executed once
+     * Defaults to 0ms
+     */
+    wait: number;
+    /**
+     * Optional error handler for when the throttled function throws
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * A class that creates an async throttled function.
+ *
+ * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.
+ * Unlike debouncing which resets the delay timer on each call, throttling ensures the function executes at a
+ * regular interval regardless of how often it's called.
+ *
+ * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to
+ * ensure a maximum execution frequency.
+ *
+ * @example
+ * ```ts
+ * const throttler = new AsyncThrottler(async (value: string) => {
+ *   await saveToAPI(value);
+ * }, { wait: 1000 });
+ *
+ * // Will only execute once per second no matter how often called
+ * inputElement.addEventListener('input', () => {
+ *   throttler.maybeExecute(inputElement.value);
+ * });
+ * ```
+ */
+export declare class AsyncThrottler<TFn extends (...args: Array<any>) => Promise<any>, TArgs extends Parameters<TFn>> {
+    private fn;
+    private abortController;
+    private executionCount;
+    private isExecuting;
+    private isScheduled;
+    private lastArgs;
+    private nextExecutionTime;
+    private options;
+    constructor(fn: TFn, initialOptions: AsyncThrottlerOptions);
+    /**
+     * Updates the throttler options
+     * Returns the new options state
+     */
+    setOptions(newOptions: Partial<AsyncThrottlerOptions>): Required<AsyncThrottlerOptions>;
+    /**
+     * Returns the number of times the function has been executed
+     */
+    getExecutionCount(): number;
+    /**
+     * Returns the next execution time
+     */
+    getNextExecutionTime(): number;
+    /**
+     * Cancels any pending execution
+     */
+    cancel(): void;
+    /**
+     * Attempts to execute the throttled function
+     * If a call is already in progress, it may be blocked or queued depending on the `wait` option
+     */
+    maybeExecute(...args: TArgs): Promise<void>;
+    private delay;
+    private executeFunction;
+}
+/**
+ * Creates an async throttled function that limits how often the function can execute.
+ * The throttled function will execute at most once per wait period, even if called multiple times.
+ * If called while executing, it will wait until execution completes before scheduling the next call.
+ *
+ * @example
+ * ```ts
+ * const throttled = asyncThrottle(async () => {
+ *   await someAsyncOperation();
+ * }, { wait: 1000 });
+ *
+ * // This will execute at most once per second
+ * await throttled();
+ * await throttled(); // Waits 1 second before executing
+ * ```
+ */
+export declare function asyncThrottle<TFn extends (...args: Array<any>) => Promise<any>>(fn: TFn, initialOptions: Omit<AsyncThrottlerOptions, 'enabled'>): (...args: Parameters<TFn>) => Promise<void>;

package/dist/esm/async-throttler.js

@@ -0,0 +1,115 @@
+const defaultOptions = {
+  enabled: true,
+  onError: () => {
+  },
+  wait: 0
+};
+class AsyncThrottler {
+  constructor(fn, initialOptions) {
+    this.fn = fn;
+    this.abortController = null;
+    this.executionCount = 0;
+    this.isExecuting = false;
+    this.isScheduled = false;
+    this.nextExecutionTime = 0;
+    this.options = {
+      ...defaultOptions,
+      ...initialOptions
+    };
+  }
+  /**
+   * Updates the throttler options
+   * Returns the new options state
+   */
+  setOptions(newOptions) {
+    this.options = {
+      ...this.options,
+      ...newOptions
+    };
+    return this.options;
+  }
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount() {
+    return this.executionCount;
+  }
+  /**
+   * Returns the next execution time
+   */
+  getNextExecutionTime() {
+    return this.nextExecutionTime;
+  }
+  /**
+   * Cancels any pending execution
+   */
+  cancel() {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this.isScheduled = false;
+    this.lastArgs = void 0;
+  }
+  /**
+   * Attempts to execute the throttled function
+   * If a call is already in progress, it may be blocked or queued depending on the `wait` option
+   */
+  async maybeExecute(...args) {
+    this.lastArgs = args;
+    if (this.isScheduled) return;
+    this.isScheduled = true;
+    this.abortController = new AbortController();
+    const signal = this.abortController.signal;
+    try {
+      while (this.isExecuting) {
+        await this.delay(this.options.wait, signal);
+      }
+      while (Date.now() < this.nextExecutionTime) {
+        await this.delay(this.nextExecutionTime - Date.now(), signal);
+      }
+      this.isScheduled = false;
+      this.isExecuting = true;
+      await this.executeFunction(...this.lastArgs);
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        return;
+      }
+      try {
+        this.options.onError(error);
+      } catch {
+      }
+    } finally {
+      this.nextExecutionTime = Date.now() + this.options.wait;
+      this.isExecuting = false;
+      this.abortController = null;
+    }
+  }
+  delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(resolve, ms);
+      signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timeout);
+          reject(new Error("AbortError"));
+        },
+        { once: true }
+      );
+    });
+  }
+  async executeFunction(...args) {
+    if (!this.options.enabled) return;
+    this.executionCount++;
+    await this.fn(...args);
+  }
+}
+function asyncThrottle(fn, initialOptions) {
+  const asyncThrottler = new AsyncThrottler(fn, initialOptions);
+  return asyncThrottler.maybeExecute.bind(asyncThrottler);
+}
+export {
+  AsyncThrottler,
+  asyncThrottle
+};
+//# sourceMappingURL=async-throttler.js.map

package/dist/esm/async-throttler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-throttler.js","sources":["../../src/async-throttler.ts"],"sourcesContent":["/**\n * Options for configuring an async throttled function\n */\nexport interface AsyncThrottlerOptions {\n  /**\n   * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Defaults to true.\n   */\n  enabled?: boolean\n  /**\n   * Time window in milliseconds during which the function can only be executed once\n   * Defaults to 0ms\n   */\n  wait: number\n  /**\n   * Optional error handler for when the throttled function throws\n   */\n  onError?: (error: unknown) => void\n}\n\nconst defaultOptions: Required<AsyncThrottlerOptions> = {\n  enabled: true,\n  onError: () => {},\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 * 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 *   await saveToAPI(value);\n * }, { wait: 1000 });\n *\n * // Will only execute once per second no matter how often called\n * inputElement.addEventListener('input', () => {\n *   throttler.maybeExecute(inputElement.value);\n * });\n * ```\n */\nexport class AsyncThrottler<\n  TFn extends (...args: Array<any>) => Promise<any>,\n  TArgs extends Parameters<TFn>,\n> {\n  private abortController: AbortController | null = null\n  private executionCount = 0\n  private isExecuting = false\n  private isScheduled = false\n  private lastArgs: TArgs | undefined\n  private nextExecutionTime = 0\n  private options: Required<AsyncThrottlerOptions>\n\n  constructor(\n    private fn: TFn,\n    initialOptions: AsyncThrottlerOptions,\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(\n    newOptions: Partial<AsyncThrottlerOptions>,\n  ): Required<AsyncThrottlerOptions> {\n    this.options = {\n      ...this.options,\n      ...newOptions,\n    }\n    return this.options\n  }\n\n  /**\n   * Returns the number of times the function has been executed\n   */\n  getExecutionCount(): number {\n    return this.executionCount\n  }\n\n  /**\n   * Returns the next execution time\n   */\n  getNextExecutionTime(): number {\n    return this.nextExecutionTime\n  }\n\n  /**\n   * Cancels any pending execution\n   */\n  cancel(): void {\n    if (this.abortController) {\n      this.abortController.abort()\n      this.abortController = null\n    }\n    this.isScheduled = false\n    this.lastArgs = undefined\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(...args: TArgs): Promise<void> {\n    this.lastArgs = args\n    if (this.isScheduled) return\n    this.isScheduled = true\n\n    this.abortController = new AbortController()\n    const signal = this.abortController.signal\n\n    try {\n      while (this.isExecuting) {\n        await this.delay(this.options.wait, signal)\n      }\n\n      while (Date.now() < this.nextExecutionTime) {\n        await this.delay(this.nextExecutionTime - Date.now(), signal)\n      }\n\n      this.isScheduled = false\n      this.isExecuting = true\n\n      await this.executeFunction(...this.lastArgs)\n    } catch (error) {\n      if (error instanceof Error && error.name === 'AbortError') {\n        return // Silent return on cancellation\n      }\n      try {\n        this.options.onError(error)\n      } catch {\n        // Ignore errors from error handler\n      }\n    } finally {\n      this.nextExecutionTime = Date.now() + this.options.wait\n      this.isExecuting = false\n      this.abortController = null\n    }\n  }\n\n  private delay(ms: number, signal: AbortSignal): Promise<void> {\n    return new Promise((resolve, reject) => {\n      const timeout = setTimeout(resolve, ms)\n      signal.addEventListener(\n        'abort',\n        () => {\n          clearTimeout(timeout)\n          reject(new Error('AbortError'))\n        },\n        { once: true },\n      )\n    })\n  }\n\n  private async executeFunction(...args: TArgs): Promise<void> {\n    if (!this.options.enabled) return\n    this.executionCount++\n    await this.fn(...args)\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 * @example\n * ```ts\n * const throttled = asyncThrottle(async () => {\n *   await someAsyncOperation();\n * }, { wait: 1000 });\n *\n * // This will execute at most once per second\n * await throttled();\n * await throttled(); // Waits 1 second before executing\n * ```\n */\nexport function asyncThrottle<\n  TFn extends (...args: Array<any>) => Promise<any>,\n>(fn: TFn, initialOptions: Omit<AsyncThrottlerOptions, 'enabled'>) {\n  const asyncThrottler = new AsyncThrottler(fn, initialOptions)\n  return asyncThrottler.maybeExecute.bind(asyncThrottler)\n}\n"],"names":[],"mappings":"AAoBA,MAAM,iBAAkD;AAAA,EACtD,SAAS;AAAA,EACT,SAAS,MAAM;AAAA,EAAC;AAAA,EAChB,MAAM;AACR;AAwBO,MAAM,eAGX;AAAA,EASA,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AATV,SAAQ,kBAA0C;AAClD,SAAQ,iBAAiB;AACzB,SAAQ,cAAc;AACtB,SAAQ,cAAc;AAEtB,SAAQ,oBAAoB;AAO1B,SAAK,UAAU;AAAA,MACb,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WACE,YACiC;AACjC,SAAK,UAAU;AAAA,MACb,GAAG,KAAK;AAAA,MACR,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,uBAA+B;AAC7B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,SAAe;AACb,QAAI,KAAK,iBAAiB;AACxB,WAAK,gBAAgB,MAAM;AAC3B,WAAK,kBAAkB;AAAA,IAAA;AAEzB,SAAK,cAAc;AACnB,SAAK,WAAW;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOlB,MAAM,gBAAgB,MAA4B;AAChD,SAAK,WAAW;AAChB,QAAI,KAAK,YAAa;AACtB,SAAK,cAAc;AAEd,SAAA,kBAAkB,IAAI,gBAAgB;AACrC,UAAA,SAAS,KAAK,gBAAgB;AAEhC,QAAA;AACF,aAAO,KAAK,aAAa;AACvB,cAAM,KAAK,MAAM,KAAK,QAAQ,MAAM,MAAM;AAAA,MAAA;AAG5C,aAAO,KAAK,QAAQ,KAAK,mBAAmB;AAC1C,cAAM,KAAK,MAAM,KAAK,oBAAoB,KAAK,OAAO,MAAM;AAAA,MAAA;AAG9D,WAAK,cAAc;AACnB,WAAK,cAAc;AAEnB,YAAM,KAAK,gBAAgB,GAAG,KAAK,QAAQ;AAAA,aACpC,OAAO;AACd,UAAI,iBAAiB,SAAS,MAAM,SAAS,cAAc;AACzD;AAAA,MAAA;AAEE,UAAA;AACG,aAAA,QAAQ,QAAQ,KAAK;AAAA,MAAA,QACpB;AAAA,MAAA;AAAA,IAER,UACA;AACA,WAAK,oBAAoB,KAAK,IAAI,IAAI,KAAK,QAAQ;AACnD,WAAK,cAAc;AACnB,WAAK,kBAAkB;AAAA,IAAA;AAAA,EACzB;AAAA,EAGM,MAAM,IAAY,QAAoC;AAC5D,WAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AAChC,YAAA,UAAU,WAAW,SAAS,EAAE;AAC/B,aAAA;AAAA,QACL;AAAA,QACA,MAAM;AACJ,uBAAa,OAAO;AACb,iBAAA,IAAI,MAAM,YAAY,CAAC;AAAA,QAChC;AAAA,QACA,EAAE,MAAM,KAAK;AAAA,MACf;AAAA,IAAA,CACD;AAAA,EAAA;AAAA,EAGH,MAAc,mBAAmB,MAA4B;AACvD,QAAA,CAAC,KAAK,QAAQ,QAAS;AACtB,SAAA;AACC,UAAA,KAAK,GAAG,GAAG,IAAI;AAAA,EAAA;AAEzB;AAkBgB,SAAA,cAEd,IAAS,gBAAwD;AACjE,QAAM,iBAAiB,IAAI,eAAe,IAAI,cAAc;AACrD,SAAA,eAAe,aAAa,KAAK,cAAc;AACxD;"}

package/dist/esm/compare.d.ts

@@ -0,0 +1,12 @@
+/**
+ * This function returns `a` if `b` is deeply equal.
+ * If not, it will replace any deeply equal children of `b` with those of `a`.
+ * This can be used for structural sharing between JSON values for example.
+ */
+export declare function replaceEqualDeep<T>(a: unknown, b: T): T;
+/**
+ * Shallow compare objects.
+ */
+export declare function shallowEqualObjects<T extends Record<string, any>>(a: T, b: T | undefined): boolean;
+export declare function isPlainArray(value: unknown): boolean;
+export declare function isPlainObject(o: any): o is Object;

package/dist/esm/compare.js

@@ -0,0 +1,72 @@
+function replaceEqualDeep(a, b) {
+  if (a === b) {
+    return a;
+  }
+  const array = isPlainArray(a) && isPlainArray(b);
+  if (array || isPlainObject(a) && isPlainObject(b)) {
+    const aItems = array ? a : Object.keys(a);
+    const aSize = aItems.length;
+    const bItems = array ? b : Object.keys(b);
+    const bSize = bItems.length;
+    const copy = array ? [] : {};
+    let equalItems = 0;
+    for (let i = 0; i < bSize; i++) {
+      const key = array ? i : bItems[i];
+      if ((!array && aItems.includes(key) || array) && a[key] === void 0 && b[key] === void 0) {
+        copy[key] = void 0;
+        equalItems++;
+      } else {
+        copy[key] = replaceEqualDeep(a[key], b[key]);
+        if (copy[key] === a[key] && a[key] !== void 0) {
+          equalItems++;
+        }
+      }
+    }
+    return aSize === bSize && equalItems === aSize ? a : copy;
+  }
+  return b;
+}
+function shallowEqualObjects(a, b) {
+  if (!b || Object.keys(a).length !== Object.keys(b).length) {
+    return false;
+  }
+  for (const key in a) {
+    if (a[key] !== b[key]) {
+      return false;
+    }
+  }
+  return true;
+}
+function isPlainArray(value) {
+  return Array.isArray(value) && value.length === Object.keys(value).length;
+}
+function isPlainObject(o) {
+  if (!hasObjectPrototype(o)) {
+    return false;
+  }
+  const ctor = o.constructor;
+  if (ctor === void 0) {
+    return true;
+  }
+  const prot = ctor.prototype;
+  if (!hasObjectPrototype(prot)) {
+    return false;
+  }
+  if (!prot.hasOwnProperty("isPrototypeOf")) {
+    return false;
+  }
+  if (Object.getPrototypeOf(o) !== Object.prototype) {
+    return false;
+  }
+  return true;
+}
+function hasObjectPrototype(o) {
+  return Object.prototype.toString.call(o) === "[object Object]";
+}
+export {
+  isPlainArray,
+  isPlainObject,
+  replaceEqualDeep,
+  shallowEqualObjects
+};
+//# sourceMappingURL=compare.js.map

package/dist/esm/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sources":["../../src/compare.ts"],"sourcesContent":["/**\n * This function returns `a` if `b` is deeply equal.\n * If not, it will replace any deeply equal children of `b` with those of `a`.\n * This can be used for structural sharing between JSON values for example.\n */\nexport function replaceEqualDeep<T>(a: unknown, b: T): T\nexport function replaceEqualDeep(a: any, b: any): any {\n  if (a === b) {\n    return a\n  }\n\n  const array = isPlainArray(a) && isPlainArray(b)\n\n  if (array || (isPlainObject(a) && isPlainObject(b))) {\n    const aItems = array ? a : Object.keys(a)\n    const aSize = aItems.length\n    const bItems = array ? b : Object.keys(b)\n    const bSize = bItems.length\n    const copy: any = array ? [] : {}\n\n    let equalItems = 0\n\n    for (let i = 0; i < bSize; i++) {\n      const key = array ? i : bItems[i]\n      if (\n        ((!array && aItems.includes(key)) || array) &&\n        a[key] === undefined &&\n        b[key] === undefined\n      ) {\n        copy[key] = undefined\n        equalItems++\n      } else {\n        copy[key] = replaceEqualDeep(a[key], b[key])\n        if (copy[key] === a[key] && a[key] !== undefined) {\n          equalItems++\n        }\n      }\n    }\n\n    return aSize === bSize && equalItems === aSize ? a : copy\n  }\n\n  return b\n}\n\n/**\n * Shallow compare objects.\n */\nexport function shallowEqualObjects<T extends Record<string, any>>(\n  a: T,\n  b: T | undefined,\n): boolean {\n  if (!b || Object.keys(a).length !== Object.keys(b).length) {\n    return false\n  }\n\n  for (const key in a) {\n    if (a[key] !== b[key]) {\n      return false\n    }\n  }\n\n  return true\n}\n\nexport function isPlainArray(value: unknown) {\n  return Array.isArray(value) && value.length === Object.keys(value).length\n}\n\n// Copied from: https://github.com/jonschlinkert/is-plain-object\n// eslint-disable-next-line @typescript-eslint/no-wrapper-object-types\nexport function isPlainObject(o: any): o is Object {\n  if (!hasObjectPrototype(o)) {\n    return false\n  }\n\n  // If has no constructor\n  const ctor = o.constructor\n  if (ctor === undefined) {\n    return true\n  }\n\n  // If has modified prototype\n  const prot = ctor.prototype\n  if (!hasObjectPrototype(prot)) {\n    return false\n  }\n\n  // If constructor does not have an Object-specific method\n  if (!prot.hasOwnProperty('isPrototypeOf')) {\n    return false\n  }\n\n  // Handles Objects created by Object.create(<arbitrary prototype>)\n  if (Object.getPrototypeOf(o) !== Object.prototype) {\n    return false\n  }\n\n  // Most likely a plain Object\n  return true\n}\n\nfunction hasObjectPrototype(o: any): boolean {\n  return Object.prototype.toString.call(o) === '[object Object]'\n}\n"],"names":[],"mappings":"AAMgB,SAAA,iBAAiB,GAAQ,GAAa;AACpD,MAAI,MAAM,GAAG;AACJ,WAAA;AAAA,EAAA;AAGT,QAAM,QAAQ,aAAa,CAAC,KAAK,aAAa,CAAC;AAE/C,MAAI,SAAU,cAAc,CAAC,KAAK,cAAc,CAAC,GAAI;AACnD,UAAM,SAAS,QAAQ,IAAI,OAAO,KAAK,CAAC;AACxC,UAAM,QAAQ,OAAO;AACrB,UAAM,SAAS,QAAQ,IAAI,OAAO,KAAK,CAAC;AACxC,UAAM,QAAQ,OAAO;AACrB,UAAM,OAAY,QAAQ,CAAA,IAAK,CAAC;AAEhC,QAAI,aAAa;AAEjB,aAAS,IAAI,GAAG,IAAI,OAAO,KAAK;AAC9B,YAAM,MAAM,QAAQ,IAAI,OAAO,CAAC;AAChC,WACI,CAAC,SAAS,OAAO,SAAS,GAAG,KAAM,UACrC,EAAE,GAAG,MAAM,UACX,EAAE,GAAG,MAAM,QACX;AACA,aAAK,GAAG,IAAI;AACZ;AAAA,MAAA,OACK;AACA,aAAA,GAAG,IAAI,iBAAiB,EAAE,GAAG,GAAG,EAAE,GAAG,CAAC;AACvC,YAAA,KAAK,GAAG,MAAM,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,QAAW;AAChD;AAAA,QAAA;AAAA,MACF;AAAA,IACF;AAGF,WAAO,UAAU,SAAS,eAAe,QAAQ,IAAI;AAAA,EAAA;AAGhD,SAAA;AACT;AAKgB,SAAA,oBACd,GACA,GACS;AACL,MAAA,CAAC,KAAK,OAAO,KAAK,CAAC,EAAE,WAAW,OAAO,KAAK,CAAC,EAAE,QAAQ;AAClD,WAAA;AAAA,EAAA;AAGT,aAAW,OAAO,GAAG;AACnB,QAAI,EAAE,GAAG,MAAM,EAAE,GAAG,GAAG;AACd,aAAA;AAAA,IAAA;AAAA,EACT;AAGK,SAAA;AACT;AAEO,SAAS,aAAa,OAAgB;AACpC,SAAA,MAAM,QAAQ,KAAK,KAAK,MAAM,WAAW,OAAO,KAAK,KAAK,EAAE;AACrE;AAIO,SAAS,cAAc,GAAqB;AAC7C,MAAA,CAAC,mBAAmB,CAAC,GAAG;AACnB,WAAA;AAAA,EAAA;AAIT,QAAM,OAAO,EAAE;AACf,MAAI,SAAS,QAAW;AACf,WAAA;AAAA,EAAA;AAIT,QAAM,OAAO,KAAK;AACd,MAAA,CAAC,mBAAmB,IAAI,GAAG;AACtB,WAAA;AAAA,EAAA;AAIT,MAAI,CAAC,KAAK,eAAe,eAAe,GAAG;AAClC,WAAA;AAAA,EAAA;AAIT,MAAI,OAAO,eAAe,CAAC,MAAM,OAAO,WAAW;AAC1C,WAAA;AAAA,EAAA;AAIF,SAAA;AACT;AAEA,SAAS,mBAAmB,GAAiB;AAC3C,SAAO,OAAO,UAAU,SAAS,KAAK,CAAC,MAAM;AAC/C;"}

package/dist/esm/debouncer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Options for configuring a debounced function
+ */
+export interface DebouncerOptions {
+    /**
+     * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
+     * Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * Whether to execute on the leading edge of the timeout.
+     * Defaults to false.
+     */
+    leading?: boolean;
+    /**
+     * Whether to execute on the trailing edge of the timeout.
+     * Defaults to true.
+     */
+    trailing?: boolean;
+    /**
+     * Delay in milliseconds before executing the function
+     * Defaults to 0ms
+     */
+    wait: number;
+}
+/**
+ * A class that creates a debounced function.
+ *
+ * Debouncing ensures that a function is only executed after a certain amount of time has passed
+ * since its last invocation. This is useful for handling frequent events like window resizing,
+ * scroll events, or input changes where you want to limit the rate of execution.
+ *
+ * The debounced function can be configured to execute either at the start of the delay period
+ * (leading edge) or at the end (trailing edge, default). Each new call during the wait period
+ * will reset the timer.
+ *
+ * @example
+ * ```ts
+ * const debouncer = new Debouncer((value: string) => {
+ *   saveToDatabase(value);
+ * }, { wait: 500 });
+ *
+ * // Will only save after 500ms of no new input
+ * inputElement.addEventListener('input', () => {
+ *   debouncer.maybeExecute(inputElement.value);
+ * });
+ * ```
+ */
+export declare class Debouncer<TFn extends (...args: Array<any>) => any, TArgs extends Parameters<TFn>> {
+    private fn;
+    private canLeadingExecute;
+    private executionCount;
+    private options;
+    private timeoutId;
+    constructor(fn: TFn, initialOptions: DebouncerOptions);
+    /**
+     * Updates the debouncer options
+     * Returns the new options state
+     */
+    setOptions(newOptions: Partial<DebouncerOptions>): Required<DebouncerOptions>;
+    /**
+     * Returns the number of times the function has been executed
+     */
+    getExecutionCount(): number;
+    /**
+     * Attempts to execute the debounced function
+     * If a call is already in progress, it will be queued
+     */
+    maybeExecute(...args: TArgs): void;
+    private executeFunction;
+    /**
+     * Cancels any pending execution
+     */
+    cancel(): void;
+}
+/**
+ * Creates a debounced function that delays invoking the provided function until after a specified wait time.
+ * Multiple calls during the wait period will cancel previous pending invocations and reset the timer.
+ *
+ * This the the simple function wrapper implementation pulled from the Debouncer class. If you need
+ * more control over the debouncing behavior, use the Debouncer class directly.
+ *
+ * If leading option is true, the function will execute immediately on the first call, then wait the delay
+ * before allowing another execution.
+ *
+ * @example
+ * ```ts
+ * const debounced = debounce(() => {
+ *   saveChanges();
+ * }, { wait: 1000 });
+ *
+ * // Called repeatedly but executes at most once per second
+ * inputElement.addEventListener('input', debounced);
+ * ```
+ */
+export declare function debounce<TFn extends (...args: Array<any>) => any>(fn: TFn, initialOptions: Omit<DebouncerOptions, 'enabled'>): (...args: Parameters<TFn>) => void;

package/dist/esm/debouncer.js

@@ -0,0 +1,74 @@
+const defaultOptions = {
+  enabled: true,
+  leading: false,
+  trailing: true,
+  wait: 0
+};
+class Debouncer {
+  constructor(fn, initialOptions) {
+    this.fn = fn;
+    this.canLeadingExecute = true;
+    this.executionCount = 0;
+    this.options = {
+      ...defaultOptions,
+      ...initialOptions
+    };
+  }
+  /**
+   * Updates the debouncer options
+   * Returns the new options state
+   */
+  setOptions(newOptions) {
+    this.options = {
+      ...this.options,
+      ...newOptions
+    };
+    return this.options;
+  }
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount() {
+    return this.executionCount;
+  }
+  /**
+   * Attempts to execute the debounced function
+   * If a call is already in progress, it will be queued
+   */
+  maybeExecute(...args) {
+    if (this.options.leading && this.canLeadingExecute) {
+      this.executeFunction(...args);
+      this.canLeadingExecute = false;
+    }
+    if (this.timeoutId) clearTimeout(this.timeoutId);
+    this.timeoutId = setTimeout(() => {
+      this.canLeadingExecute = true;
+      if (this.options.trailing) {
+        this.executeFunction(...args);
+      }
+    }, this.options.wait);
+  }
+  executeFunction(...args) {
+    if (!this.options.enabled) return;
+    this.executionCount++;
+    this.fn(...args);
+  }
+  /**
+   * Cancels any pending execution
+   */
+  cancel() {
+    if (this.timeoutId) {
+      clearTimeout(this.timeoutId);
+      this.canLeadingExecute = true;
+    }
+  }
+}
+function debounce(fn, initialOptions) {
+  const debouncer = new Debouncer(fn, initialOptions);
+  return debouncer.maybeExecute.bind(debouncer);
+}
+export {
+  Debouncer,
+  debounce
+};
+//# sourceMappingURL=debouncer.js.map

package/dist/esm/debouncer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debouncer.js","sources":["../../src/debouncer.ts"],"sourcesContent":["/**\n * Options for configuring a debounced function\n */\nexport interface DebouncerOptions {\n  /**\n   * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.\n   * Defaults to true.\n   */\n  enabled?: boolean\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * Defaults to false.\n   */\n  leading?: boolean\n  /**\n   * Whether to execute on the trailing edge of the timeout.\n   * Defaults to true.\n   */\n  trailing?: boolean\n  /**\n   * Delay in milliseconds before executing the function\n   * Defaults to 0ms\n   */\n  wait: number\n}\n\nconst defaultOptions: Required<DebouncerOptions> = {\n  enabled: true,\n  leading: false,\n  trailing: true,\n  wait: 0,\n}\n\n/**\n * A class that creates a debounced function.\n *\n * Debouncing ensures that a function is only executed after a certain amount of time has passed\n * since its last invocation. This is useful for handling frequent events like window resizing,\n * scroll events, or input changes where you want to limit the rate of execution.\n *\n * The debounced function can be configured to execute either at the start of the delay period\n * (leading edge) or at the end (trailing edge, default). Each new call during the wait period\n * will reset the timer.\n *\n * @example\n * ```ts\n * const debouncer = new Debouncer((value: string) => {\n *   saveToDatabase(value);\n * }, { wait: 500 });\n *\n * // Will only save after 500ms of no new input\n * inputElement.addEventListener('input', () => {\n *   debouncer.maybeExecute(inputElement.value);\n * });\n * ```\n */\nexport class Debouncer<\n  TFn extends (...args: Array<any>) => any,\n  TArgs extends Parameters<TFn>,\n> {\n  private canLeadingExecute = true\n  private executionCount = 0\n  private options: Required<DebouncerOptions>\n  private timeoutId: NodeJS.Timeout | undefined\n\n  constructor(\n    private fn: TFn,\n    initialOptions: DebouncerOptions,\n  ) {\n    this.options = {\n      ...defaultOptions,\n      ...initialOptions,\n    }\n  }\n\n  /**\n   * Updates the debouncer options\n   * Returns the new options state\n   */\n  setOptions(\n    newOptions: Partial<DebouncerOptions>,\n  ): Required<DebouncerOptions> {\n    this.options = {\n      ...this.options,\n      ...newOptions,\n    }\n    return this.options\n  }\n\n  /**\n   * Returns the number of times the function has been executed\n   */\n  getExecutionCount(): number {\n    return this.executionCount\n  }\n\n  /**\n   * Attempts to execute the debounced function\n   * If a call is already in progress, it will be queued\n   */\n  maybeExecute(...args: TArgs): void {\n    // Handle leading execution\n    if (this.options.leading && this.canLeadingExecute) {\n      this.executeFunction(...args)\n      this.canLeadingExecute = false\n    }\n\n    // Clear any existing timeout\n    if (this.timeoutId) clearTimeout(this.timeoutId)\n\n    // Set new timeout that will reset canLeadingExecute\n    this.timeoutId = setTimeout(() => {\n      this.canLeadingExecute = true\n      // Execute trailing only if enabled\n      if (this.options.trailing) {\n        this.executeFunction(...args)\n      }\n    }, this.options.wait)\n  }\n\n  private executeFunction(...args: TArgs): void {\n    if (!this.options.enabled) return\n    this.executionCount++\n    this.fn(...args)\n  }\n\n  /**\n   * Cancels any pending execution\n   */\n  cancel(): void {\n    if (this.timeoutId) {\n      clearTimeout(this.timeoutId)\n      this.canLeadingExecute = true\n    }\n  }\n}\n\n/**\n * Creates a debounced function that delays invoking the provided function until after a specified wait time.\n * Multiple calls during the wait period will cancel previous pending invocations and reset the timer.\n *\n * This the the simple function wrapper implementation pulled from the Debouncer class. If you need\n * more control over the debouncing behavior, use the Debouncer class directly.\n *\n * If leading option is true, the function will execute immediately on the first call, then wait the delay\n * before allowing another execution.\n *\n * @example\n * ```ts\n * const debounced = debounce(() => {\n *   saveChanges();\n * }, { wait: 1000 });\n *\n * // Called repeatedly but executes at most once per second\n * inputElement.addEventListener('input', debounced);\n * ```\n */\nexport function debounce<TFn extends (...args: Array<any>) => any>(\n  fn: TFn,\n  initialOptions: Omit<DebouncerOptions, 'enabled'>,\n) {\n  const debouncer = new Debouncer(fn, initialOptions)\n  return debouncer.maybeExecute.bind(debouncer)\n}\n"],"names":[],"mappings":"AA0BA,MAAM,iBAA6C;AAAA,EACjD,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AAAA,EACV,MAAM;AACR;AAyBO,MAAM,UAGX;AAAA,EAMA,YACU,IACR,gBACA;AAFQ,SAAA,KAAA;AANV,SAAQ,oBAAoB;AAC5B,SAAQ,iBAAiB;AAQvB,SAAK,UAAU;AAAA,MACb,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOF,WACE,YAC4B;AAC5B,SAAK,UAAU;AAAA,MACb,GAAG,KAAK;AAAA,MACR,GAAG;AAAA,IACL;AACA,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMd,oBAA4B;AAC1B,WAAO,KAAK;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOd,gBAAgB,MAAmB;AAEjC,QAAI,KAAK,QAAQ,WAAW,KAAK,mBAAmB;AAC7C,WAAA,gBAAgB,GAAG,IAAI;AAC5B,WAAK,oBAAoB;AAAA,IAAA;AAI3B,QAAI,KAAK,UAAwB,cAAA,KAAK,SAAS;AAG1C,SAAA,YAAY,WAAW,MAAM;AAChC,WAAK,oBAAoB;AAErB,UAAA,KAAK,QAAQ,UAAU;AACpB,aAAA,gBAAgB,GAAG,IAAI;AAAA,MAAA;AAAA,IAC9B,GACC,KAAK,QAAQ,IAAI;AAAA,EAAA;AAAA,EAGd,mBAAmB,MAAmB;AACxC,QAAA,CAAC,KAAK,QAAQ,QAAS;AACtB,SAAA;AACA,SAAA,GAAG,GAAG,IAAI;AAAA,EAAA;AAAA;AAAA;AAAA;AAAA,EAMjB,SAAe;AACb,QAAI,KAAK,WAAW;AAClB,mBAAa,KAAK,SAAS;AAC3B,WAAK,oBAAoB;AAAA,IAAA;AAAA,EAC3B;AAEJ;AAsBgB,SAAA,SACd,IACA,gBACA;AACA,QAAM,YAAY,IAAI,UAAU,IAAI,cAAc;AAC3C,SAAA,UAAU,aAAa,KAAK,SAAS;AAC9C;"}

package/dist/esm/index.d.ts

@@ -0,0 +1,9 @@
+export * from './async-debouncer.js';
+export * from './async-queuer.js';
+export * from './async-rate-limiter.js';
+export * from './async-throttler.js';
+export * from './compare.js';
+export * from './debouncer.js';
+export * from './queuer.js';
+export * from './rate-limiter.js';
+export * from './throttler.js';

package/dist/esm/index.js

@@ -0,0 +1,32 @@
+import { AsyncDebouncer, asyncDebounce } from "./async-debouncer.js";
+import { AsyncQueuer, asyncQueue } from "./async-queuer.js";
+import { AsyncRateLimiter, asyncRateLimit } from "./async-rate-limiter.js";
+import { AsyncThrottler, asyncThrottle } from "./async-throttler.js";
+import { isPlainArray, isPlainObject, replaceEqualDeep, shallowEqualObjects } from "./compare.js";
+import { Debouncer, debounce } from "./debouncer.js";
+import { Queuer, queue } from "./queuer.js";
+import { RateLimiter, rateLimit } from "./rate-limiter.js";
+import { Throttler, throttle } from "./throttler.js";
+export {
+  AsyncDebouncer,
+  AsyncQueuer,
+  AsyncRateLimiter,
+  AsyncThrottler,
+  Debouncer,
+  Queuer,
+  RateLimiter,
+  Throttler,
+  asyncDebounce,
+  asyncQueue,
+  asyncRateLimit,
+  asyncThrottle,
+  debounce,
+  isPlainArray,
+  isPlainObject,
+  queue,
+  rateLimit,
+  replaceEqualDeep,
+  shallowEqualObjects,
+  throttle
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}