@tanstack/pacer-lite 0.1.0

package/dist/cjs/lite-rate-limiter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lite-rate-limiter.cjs","sources":["../../src/lite-rate-limiter.ts"],"sourcesContent":["import type { AnyFunction } from '@tanstack/pacer/types'\n\n/**\n * Options for configuring a lite rate-limited function\n */\nexport interface LiteRateLimiterOptions<TFn extends AnyFunction = AnyFunction> {\n  /**\n   * Maximum number of executions allowed within the time window.\n   */\n  limit: number\n  /**\n   * Callback function that is called after the function is executed\n   */\n  onExecute?: (args: Parameters<TFn>, rateLimiter: LiteRateLimiter<TFn>) => void\n  /**\n   * Optional callback function that is called when an execution is rejected due to rate limiting\n   */\n  onReject?: (rateLimiter: LiteRateLimiter<TFn>) => void\n  /**\n   * Time window in milliseconds within which the limit applies.\n   */\n  window: number\n  /**\n   * Type of window to use for rate limiting\n   * - 'fixed': Uses a fixed window that resets after the window period\n   * - 'sliding': Uses a sliding window that allows executions as old ones expire\n   * Defaults to 'fixed'\n   */\n  windowType?: 'fixed' | 'sliding'\n}\n\n/**\n * A lightweight class that creates a rate-limited function.\n *\n * This is an alternative to the RateLimiter in the core @tanstack/pacer package, but is more\n * suitable for libraries and npm packages that need minimal overhead. Unlike the core RateLimiter,\n * this version does not use TanStack Store for state management, has no devtools integration,\n * and provides only essential rate limiting functionality.\n *\n * Rate limiting allows a function to execute up to a limit within a time window,\n * then blocks all subsequent calls until the window passes. This can lead to \"bursty\" behavior where\n * all executions happen immediately, followed by a complete block.\n *\n * The rate limiter supports two types of windows:\n * - 'fixed': A strict window that resets after the window period. All executions within the window count\n *   towards the limit, and the window resets completely after the period.\n * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more\n *   consistent rate of execution over time.\n *\n * Features:\n * - Zero dependencies - no external libraries required\n * - Minimal API surface - only essential methods (maybeExecute, getRemainingInWindow, getMsUntilNextWindow, reset)\n * - Simple state management - uses basic private properties instead of reactive stores\n * - Lightweight - designed for use in npm packages where bundle size matters\n *\n * @example\n * ```ts\n * const rateLimiter = new LiteRateLimiter((id: string) => {\n *   api.getData(id);\n * }, { limit: 5, window: 1000 });\n *\n * // First 5 calls will execute, then block until window resets\n * if (rateLimiter.maybeExecute('123')) {\n *   console.log('API call made');\n * } else {\n *   console.log('Rate limited - try again in', rateLimiter.getMsUntilNextWindow(), 'ms');\n * }\n * ```\n */\nexport class LiteRateLimiter<TFn extends AnyFunction> {\n  private executionTimes: Array<number> = []\n  private timeoutIds: Set<NodeJS.Timeout> = new Set()\n\n  constructor(\n    public fn: TFn,\n    public options: LiteRateLimiterOptions<TFn>,\n  ) {\n    // Default windowType to 'fixed' if not specified\n    if (this.options.windowType === undefined) {\n      this.options.windowType = 'fixed'\n    }\n  }\n\n  /**\n   * Attempts to execute the rate-limited function if within the configured limits.\n   * Returns true if executed, false if rejected due to rate limiting.\n   *\n   * @example\n   * ```ts\n   * const rateLimiter = new LiteRateLimiter(fn, { limit: 5, window: 1000 });\n   *\n   * // First 5 calls return true\n   * rateLimiter.maybeExecute('arg1', 'arg2'); // true\n   *\n   * // Additional calls within the window return false\n   * rateLimiter.maybeExecute('arg1', 'arg2'); // false\n   * ```\n   */\n  maybeExecute = (...args: Parameters<TFn>): boolean => {\n    this.cleanupOldExecutions()\n\n    const relevantExecutionTimes = this.getExecutionTimesInWindow()\n\n    if (relevantExecutionTimes.length < this.options.limit) {\n      this.execute(...args)\n      return true\n    }\n\n    this.options.onReject?.(this)\n    return false\n  }\n\n  private execute = (...args: Parameters<TFn>): void => {\n    const now = Date.now()\n    this.fn(...args)\n    this.options.onExecute?.(args, this)\n    this.executionTimes.push(now)\n    this.setCleanupTimeout(now)\n  }\n\n  private getExecutionTimesInWindow = (): Array<number> => {\n    if (this.options.windowType === 'sliding') {\n      // For sliding window, return all executions within the current window\n      return this.executionTimes.filter(\n        (time) => time > Date.now() - this.options.window,\n      )\n    } else {\n      // For fixed window, return all executions in the current window\n      if (this.executionTimes.length === 0) {\n        return []\n      }\n      const oldestExecution = Math.min(...this.executionTimes)\n      const windowStart = oldestExecution\n      const windowEnd = windowStart + this.options.window\n      const now = Date.now()\n\n      // If the window has expired, return empty array\n      if (now > windowEnd) {\n        return []\n      }\n\n      // Otherwise, return all executions in the current window\n      return this.executionTimes.filter(\n        (time) => time >= windowStart && time <= windowEnd,\n      )\n    }\n  }\n\n  private setCleanupTimeout = (executionTime: number): void => {\n    if (\n      this.options.windowType === 'sliding' ||\n      this.timeoutIds.size === 0 // new fixed window\n    ) {\n      const now = Date.now()\n      const timeUntilExpiration = executionTime - now + this.options.window + 1\n      const timeoutId = setTimeout(() => {\n        this.cleanupOldExecutions()\n        this.clearTimeout(timeoutId)\n      }, timeUntilExpiration)\n      this.timeoutIds.add(timeoutId)\n    }\n  }\n\n  private clearTimeout = (timeoutId: NodeJS.Timeout): void => {\n    clearTimeout(timeoutId)\n    this.timeoutIds.delete(timeoutId)\n  }\n\n  private clearTimeouts = (): void => {\n    this.timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId))\n    this.timeoutIds.clear()\n  }\n\n  private cleanupOldExecutions = (): void => {\n    this.executionTimes = this.getExecutionTimesInWindow()\n  }\n\n  /**\n   * Returns the number of remaining executions allowed in the current window.\n   */\n  getRemainingInWindow = (): number => {\n    const relevantExecutionTimes = this.getExecutionTimesInWindow()\n    return Math.max(0, this.options.limit - relevantExecutionTimes.length)\n  }\n\n  /**\n   * Returns the number of milliseconds until the next execution will be possible.\n   * Returns 0 if executions are currently allowed.\n   */\n  getMsUntilNextWindow = (): number => {\n    if (this.getRemainingInWindow() > 0) {\n      return 0\n    }\n    const oldestExecution = this.executionTimes[0] ?? Infinity\n    return oldestExecution + this.options.window - Date.now()\n  }\n\n  /**\n   * Resets the rate limiter state, clearing all execution history.\n   */\n  reset = (): void => {\n    this.executionTimes = []\n    this.clearTimeouts()\n  }\n}\n\n/**\n * Creates a lightweight rate-limited function that will execute the provided function up to a maximum number of times within a time window.\n *\n * This is an alternative to the rateLimit function in the core @tanstack/pacer package, but is more\n * suitable for libraries and npm packages that need minimal overhead. Unlike the core version,\n * this function creates a rate limiter with no external dependencies, devtools integration, or reactive state.\n *\n * Rate limiting allows all executions until the limit is reached, then blocks all subsequent calls until the window resets.\n * This differs from throttling (which ensures even spacing) and debouncing (which waits for pauses).\n *\n * @example\n * ```ts\n * const rateLimitedApi = liteRateLimit(makeApiCall, {\n *   limit: 5,\n *   window: 60000, // 1 minute\n *   windowType: 'sliding'\n * });\n *\n * // First 5 calls execute immediately\n * // Additional calls are rejected until window allows\n * rateLimitedApi();\n * ```\n *\n * @example\n * ```ts\n * // Fixed window - all 10 calls happen in first second, then 10 second wait\n * const rateLimitedFixed = liteRateLimit(logEvent, {\n *   limit: 10,\n *   window: 10000,\n *   windowType: 'fixed'\n * });\n * ```\n */\nexport function liteRateLimit<TFn extends AnyFunction>(\n  fn: TFn,\n  options: LiteRateLimiterOptions<TFn>,\n): (...args: Parameters<TFn>) => boolean {\n  const rateLimiter = new LiteRateLimiter(fn, options)\n  return rateLimiter.maybeExecute\n}\n"],"names":[],"mappings":";;AAqEO,MAAM,gBAAyC;AAAA,EAIpD,YACS,IACA,SACP;AAFO,SAAA,KAAA;AACA,SAAA,UAAA;AALT,SAAQ,iBAAgC,CAAA;AACxC,SAAQ,iCAAsC,IAAA;AA2B9C,SAAA,eAAe,IAAI,SAAmC;AACpD,WAAK,qBAAA;AAEL,YAAM,yBAAyB,KAAK,0BAAA;AAEpC,UAAI,uBAAuB,SAAS,KAAK,QAAQ,OAAO;AACtD,aAAK,QAAQ,GAAG,IAAI;AACpB,eAAO;AAAA,MACT;AAEA,WAAK,QAAQ,WAAW,IAAI;AAC5B,aAAO;AAAA,IACT;AAEA,SAAQ,UAAU,IAAI,SAAgC;AACpD,YAAM,MAAM,KAAK,IAAA;AACjB,WAAK,GAAG,GAAG,IAAI;AACf,WAAK,QAAQ,YAAY,MAAM,IAAI;AACnC,WAAK,eAAe,KAAK,GAAG;AAC5B,WAAK,kBAAkB,GAAG;AAAA,IAC5B;AAEA,SAAQ,4BAA4B,MAAqB;AACvD,UAAI,KAAK,QAAQ,eAAe,WAAW;AAEzC,eAAO,KAAK,eAAe;AAAA,UACzB,CAAC,SAAS,OAAO,KAAK,IAAA,IAAQ,KAAK,QAAQ;AAAA,QAAA;AAAA,MAE/C,OAAO;AAEL,YAAI,KAAK,eAAe,WAAW,GAAG;AACpC,iBAAO,CAAA;AAAA,QACT;AACA,cAAM,kBAAkB,KAAK,IAAI,GAAG,KAAK,cAAc;AACvD,cAAM,cAAc;AACpB,cAAM,YAAY,cAAc,KAAK,QAAQ;AAC7C,cAAM,MAAM,KAAK,IAAA;AAGjB,YAAI,MAAM,WAAW;AACnB,iBAAO,CAAA;AAAA,QACT;AAGA,eAAO,KAAK,eAAe;AAAA,UACzB,CAAC,SAAS,QAAQ,eAAe,QAAQ;AAAA,QAAA;AAAA,MAE7C;AAAA,IACF;AAEA,SAAQ,oBAAoB,CAAC,kBAAgC;AAC3D,UACE,KAAK,QAAQ,eAAe,aAC5B,KAAK,WAAW,SAAS,GACzB;AACA,cAAM,MAAM,KAAK,IAAA;AACjB,cAAM,sBAAsB,gBAAgB,MAAM,KAAK,QAAQ,SAAS;AACxE,cAAM,YAAY,WAAW,MAAM;AACjC,eAAK,qBAAA;AACL,eAAK,aAAa,SAAS;AAAA,QAC7B,GAAG,mBAAmB;AACtB,aAAK,WAAW,IAAI,SAAS;AAAA,MAC/B;AAAA,IACF;AAEA,SAAQ,eAAe,CAAC,cAAoC;AAC1D,mBAAa,SAAS;AACtB,WAAK,WAAW,OAAO,SAAS;AAAA,IAClC;AAEA,SAAQ,gBAAgB,MAAY;AAClC,WAAK,WAAW,QAAQ,CAAC,cAAc,aAAa,SAAS,CAAC;AAC9D,WAAK,WAAW,MAAA;AAAA,IAClB;AAEA,SAAQ,uBAAuB,MAAY;AACzC,WAAK,iBAAiB,KAAK,0BAAA;AAAA,IAC7B;AAKA,SAAA,uBAAuB,MAAc;AACnC,YAAM,yBAAyB,KAAK,0BAAA;AACpC,aAAO,KAAK,IAAI,GAAG,KAAK,QAAQ,QAAQ,uBAAuB,MAAM;AAAA,IACvE;AAMA,SAAA,uBAAuB,MAAc;AACnC,UAAI,KAAK,qBAAA,IAAyB,GAAG;AACnC,eAAO;AAAA,MACT;AACA,YAAM,kBAAkB,KAAK,eAAe,CAAC,KAAK;AAClD,aAAO,kBAAkB,KAAK,QAAQ,SAAS,KAAK,IAAA;AAAA,IACtD;AAKA,SAAA,QAAQ,MAAY;AAClB,WAAK,iBAAiB,CAAA;AACtB,WAAK,cAAA;AAAA,IACP;AA7HE,QAAI,KAAK,QAAQ,eAAe,QAAW;AACzC,WAAK,QAAQ,aAAa;AAAA,IAC5B;AAAA,EACF;AA2HF;AAmCO,SAAS,cACd,IACA,SACuC;AACvC,QAAM,cAAc,IAAI,gBAAgB,IAAI,OAAO;AACnD,SAAO,YAAY;AACrB;;;"}

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

@@ -0,0 +1,143 @@
+import { AnyFunction } from '@tanstack/pacer/types';
+/**
+ * Options for configuring a lite rate-limited function
+ */
+export interface LiteRateLimiterOptions<TFn extends AnyFunction = AnyFunction> {
+    /**
+     * Maximum number of executions allowed within the time window.
+     */
+    limit: number;
+    /**
+     * Callback function that is called after the function is executed
+     */
+    onExecute?: (args: Parameters<TFn>, rateLimiter: LiteRateLimiter<TFn>) => void;
+    /**
+     * Optional callback function that is called when an execution is rejected due to rate limiting
+     */
+    onReject?: (rateLimiter: LiteRateLimiter<TFn>) => void;
+    /**
+     * Time window in milliseconds within which the limit applies.
+     */
+    window: number;
+    /**
+     * Type of window to use for rate limiting
+     * - 'fixed': Uses a fixed window that resets after the window period
+     * - 'sliding': Uses a sliding window that allows executions as old ones expire
+     * Defaults to 'fixed'
+     */
+    windowType?: 'fixed' | 'sliding';
+}
+/**
+ * A lightweight class that creates a rate-limited function.
+ *
+ * This is an alternative to the RateLimiter in the core @tanstack/pacer package, but is more
+ * suitable for libraries and npm packages that need minimal overhead. Unlike the core RateLimiter,
+ * this version does not use TanStack Store for state management, has no devtools integration,
+ * and provides only essential rate limiting functionality.
+ *
+ * Rate limiting allows a function to execute up to a limit within a time window,
+ * then blocks all subsequent calls until the window passes. This can lead to "bursty" behavior where
+ * all executions happen immediately, followed by a complete block.
+ *
+ * The rate limiter supports two types of windows:
+ * - 'fixed': A strict window that resets after the window period. All executions within the window count
+ *   towards the limit, and the window resets completely after the period.
+ * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more
+ *   consistent rate of execution over time.
+ *
+ * Features:
+ * - Zero dependencies - no external libraries required
+ * - Minimal API surface - only essential methods (maybeExecute, getRemainingInWindow, getMsUntilNextWindow, reset)
+ * - Simple state management - uses basic private properties instead of reactive stores
+ * - Lightweight - designed for use in npm packages where bundle size matters
+ *
+ * @example
+ * ```ts
+ * const rateLimiter = new LiteRateLimiter((id: string) => {
+ *   api.getData(id);
+ * }, { limit: 5, window: 1000 });
+ *
+ * // First 5 calls will execute, then block until window resets
+ * if (rateLimiter.maybeExecute('123')) {
+ *   console.log('API call made');
+ * } else {
+ *   console.log('Rate limited - try again in', rateLimiter.getMsUntilNextWindow(), 'ms');
+ * }
+ * ```
+ */
+export declare class LiteRateLimiter<TFn extends AnyFunction> {
+    fn: TFn;
+    options: LiteRateLimiterOptions<TFn>;
+    private executionTimes;
+    private timeoutIds;
+    constructor(fn: TFn, options: LiteRateLimiterOptions<TFn>);
+    /**
+     * Attempts to execute the rate-limited function if within the configured limits.
+     * Returns true if executed, false if rejected due to rate limiting.
+     *
+     * @example
+     * ```ts
+     * const rateLimiter = new LiteRateLimiter(fn, { limit: 5, window: 1000 });
+     *
+     * // First 5 calls return true
+     * rateLimiter.maybeExecute('arg1', 'arg2'); // true
+     *
+     * // Additional calls within the window return false
+     * rateLimiter.maybeExecute('arg1', 'arg2'); // false
+     * ```
+     */
+    maybeExecute: (...args: Parameters<TFn>) => boolean;
+    private execute;
+    private getExecutionTimesInWindow;
+    private setCleanupTimeout;
+    private clearTimeout;
+    private clearTimeouts;
+    private cleanupOldExecutions;
+    /**
+     * Returns the number of remaining executions allowed in the current window.
+     */
+    getRemainingInWindow: () => number;
+    /**
+     * Returns the number of milliseconds until the next execution will be possible.
+     * Returns 0 if executions are currently allowed.
+     */
+    getMsUntilNextWindow: () => number;
+    /**
+     * Resets the rate limiter state, clearing all execution history.
+     */
+    reset: () => void;
+}
+/**
+ * Creates a lightweight rate-limited function that will execute the provided function up to a maximum number of times within a time window.
+ *
+ * This is an alternative to the rateLimit function in the core @tanstack/pacer package, but is more
+ * suitable for libraries and npm packages that need minimal overhead. Unlike the core version,
+ * this function creates a rate limiter with no external dependencies, devtools integration, or reactive state.
+ *
+ * Rate limiting allows all executions until the limit is reached, then blocks all subsequent calls until the window resets.
+ * This differs from throttling (which ensures even spacing) and debouncing (which waits for pauses).
+ *
+ * @example
+ * ```ts
+ * const rateLimitedApi = liteRateLimit(makeApiCall, {
+ *   limit: 5,
+ *   window: 60000, // 1 minute
+ *   windowType: 'sliding'
+ * });
+ *
+ * // First 5 calls execute immediately
+ * // Additional calls are rejected until window allows
+ * rateLimitedApi();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Fixed window - all 10 calls happen in first second, then 10 second wait
+ * const rateLimitedFixed = liteRateLimit(logEvent, {
+ *   limit: 10,
+ *   window: 10000,
+ *   windowType: 'fixed'
+ * });
+ * ```
+ */
+export declare function liteRateLimit<TFn extends AnyFunction>(fn: TFn, options: LiteRateLimiterOptions<TFn>): (...args: Parameters<TFn>) => boolean;

package/dist/cjs/lite-throttler.cjs

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class LiteThrottler {
+  constructor(fn, options) {
+    this.fn = fn;
+    this.options = options;
+    this.lastExecutionTime = 0;
+    this.isPending = false;
+    this.maybeExecute = (...args) => {
+      const now = Date.now();
+      const timeSinceLastExecution = now - this.lastExecutionTime;
+      if (this.options.leading && timeSinceLastExecution >= this.options.wait) {
+        this.execute(...args);
+      } else {
+        this.lastArgs = args;
+        if (!this.timeoutId && this.options.trailing) {
+          const timeoutDuration = this.options.wait - timeSinceLastExecution;
+          this.isPending = true;
+          this.timeoutId = setTimeout(() => {
+            if (this.lastArgs !== void 0) {
+              this.execute(...this.lastArgs);
+            }
+          }, timeoutDuration);
+        }
+      }
+    };
+    this.execute = (...args) => {
+      this.fn(...args);
+      this.options.onExecute?.(args, this);
+      this.lastExecutionTime = Date.now();
+      this.clearTimeout();
+      this.lastArgs = void 0;
+      this.isPending = false;
+    };
+    this.flush = () => {
+      if (this.isPending && this.lastArgs) {
+        this.execute(...this.lastArgs);
+      }
+    };
+    this.cancel = () => {
+      this.clearTimeout();
+      this.lastArgs = void 0;
+      this.isPending = false;
+    };
+    this.clearTimeout = () => {
+      if (this.timeoutId) {
+        clearTimeout(this.timeoutId);
+        this.timeoutId = void 0;
+      }
+    };
+    if (this.options.leading === void 0 && this.options.trailing === void 0) {
+      this.options.leading = true;
+      this.options.trailing = true;
+    }
+  }
+}
+function liteThrottle(fn, options) {
+  const throttler = new LiteThrottler(fn, options);
+  return throttler.maybeExecute;
+}
+exports.LiteThrottler = LiteThrottler;
+exports.liteThrottle = liteThrottle;
+//# sourceMappingURL=lite-throttler.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lite-throttler.cjs","sources":["../../src/lite-throttler.ts"],"sourcesContent":["import type { AnyFunction } from '@tanstack/pacer/types'\n\n/**\n * Options for configuring a lite throttled function\n */\nexport interface LiteThrottlerOptions<TFn extends AnyFunction = AnyFunction> {\n  /**\n   * Whether to execute on the leading edge of the timeout.\n   * Defaults to true.\n   */\n  leading?: boolean\n  /**\n   * Callback function that is called after the function is executed\n   */\n  onExecute?: (args: Parameters<TFn>, throttler: LiteThrottler<TFn>) => void\n  /**\n   * Whether to execute on the trailing edge of the timeout.\n   * Defaults to true.\n   */\n  trailing?: boolean\n  /**\n   * Time window in milliseconds during which the function can only be executed once.\n   */\n  wait: number\n}\n\n/**\n * A lightweight class that creates a throttled function.\n *\n * This is an alternative to the Throttler in the core @tanstack/pacer package, but is more\n * suitable for libraries and npm packages that need minimal overhead. Unlike the core Throttler,\n * this version does not use TanStack Store for state management, has no devtools integration,\n * and provides only essential throttling functionality.\n *\n * Throttling ensures a function is called at most once within a specified time window.\n * Unlike debouncing which waits for a pause in calls, throttling guarantees consistent\n * execution timing regardless of call frequency.\n *\n * Supports both leading and trailing edge execution:\n * - Leading: Execute immediately on first call (default: true)\n * - Trailing: Execute after wait period if called during throttle (default: true)\n *\n * Features:\n * - Zero dependencies - no external libraries required\n * - Minimal API surface - only essential methods (maybeExecute, flush, cancel)\n * - Simple state management - uses basic private properties instead of reactive stores\n * - Callback support for monitoring execution events\n * - Lightweight - designed for use in npm packages where bundle size matters\n *\n * @example\n * ```ts\n * const throttler = new LiteThrottler((scrollY: number) => {\n *   updateScrollPosition(scrollY);\n * }, {\n *   wait: 100,\n *   onExecute: (args, throttler) => {\n *     console.log('Updated scroll position:', args[0]);\n *   }\n * });\n *\n * // Will execute at most once per 100ms\n * window.addEventListener('scroll', () => {\n *   throttler.maybeExecute(window.scrollY);\n * });\n * ```\n */\nexport class LiteThrottler<TFn extends AnyFunction> {\n  private timeoutId: NodeJS.Timeout | undefined\n  private lastArgs: Parameters<TFn> | undefined\n  private lastExecutionTime = 0\n  private isPending = false\n\n  constructor(\n    public fn: TFn,\n    public options: LiteThrottlerOptions<TFn>,\n  ) {\n    // Default both leading and trailing to true if neither is specified\n    if (\n      this.options.leading === undefined &&\n      this.options.trailing === undefined\n    ) {\n      this.options.leading = true\n      this.options.trailing = true\n    }\n  }\n\n  /**\n   * Attempts to execute the throttled function. The execution behavior depends on the throttler options:\n   *\n   * - If enough time has passed since the last execution (>= wait period):\n   *   - With leading=true: Executes immediately\n   *   - With leading=false: Waits for the next trailing execution\n   *\n   * - If within the wait period:\n   *   - With trailing=true: Schedules execution for end of wait period\n   *   - With trailing=false: Drops the execution\n   */\n  maybeExecute = (...args: Parameters<TFn>): void => {\n    const now = Date.now()\n    const timeSinceLastExecution = now - this.lastExecutionTime\n\n    // Handle leading execution\n    if (this.options.leading && timeSinceLastExecution >= this.options.wait) {\n      this.execute(...args)\n    } else {\n      // Store the most recent arguments for potential trailing execution\n      this.lastArgs = args\n\n      // Set up trailing execution if not already scheduled\n      if (!this.timeoutId && this.options.trailing) {\n        const timeoutDuration = this.options.wait - timeSinceLastExecution\n        this.isPending = true\n        this.timeoutId = setTimeout(() => {\n          if (this.lastArgs !== undefined) {\n            this.execute(...this.lastArgs)\n          }\n        }, timeoutDuration)\n      }\n    }\n  }\n\n  private execute = (...args: Parameters<TFn>): void => {\n    this.fn(...args)\n    this.options.onExecute?.(args, this)\n    this.lastExecutionTime = Date.now()\n    this.clearTimeout()\n    this.lastArgs = undefined\n    this.isPending = false\n  }\n\n  /**\n   * Processes the current pending execution immediately.\n   * If there's a pending execution, it will be executed right away\n   * and the timeout will be cleared.\n   */\n  flush = (): void => {\n    if (this.isPending && this.lastArgs) {\n      this.execute(...this.lastArgs)\n    }\n  }\n\n  /**\n   * Cancels any pending trailing execution and clears internal state.\n   * If a trailing execution is scheduled, this will prevent that execution from occurring.\n   */\n  cancel = (): void => {\n    this.clearTimeout()\n    this.lastArgs = undefined\n    this.isPending = false\n  }\n\n  private clearTimeout = (): void => {\n    if (this.timeoutId) {\n      clearTimeout(this.timeoutId)\n      this.timeoutId = undefined\n    }\n  }\n}\n\n/**\n * Creates a lightweight throttled function that limits how often the provided function can execute.\n *\n * This is an alternative to the throttle function in the core @tanstack/pacer package, but is more\n * suitable for libraries and npm packages that need minimal overhead. Unlike the core version,\n * this function creates a throttler with no external dependencies, devtools integration, or reactive state.\n *\n * Throttling ensures a function executes at most once within a specified time window,\n * regardless of how many times it is called. This is useful for rate-limiting\n * expensive operations or UI updates.\n *\n * @example\n * ```ts\n * const throttledScroll = liteThrottle(() => {\n *   updateScrollIndicator();\n * }, { wait: 100 });\n *\n * // Will execute at most once per 100ms\n * window.addEventListener('scroll', throttledScroll);\n * ```\n *\n * @example\n * ```ts\n * // Leading edge execution - fires immediately then throttles\n * const throttledResize = liteThrottle(() => {\n *   recalculateLayout();\n * }, { wait: 250, leading: true, trailing: false });\n * ```\n */\nexport function liteThrottle<TFn extends AnyFunction>(\n  fn: TFn,\n  options: LiteThrottlerOptions<TFn>,\n): (...args: Parameters<TFn>) => void {\n  const throttler = new LiteThrottler(fn, options)\n  return throttler.maybeExecute\n}\n"],"names":[],"mappings":";;AAkEO,MAAM,cAAuC;AAAA,EAMlD,YACS,IACA,SACP;AAFO,SAAA,KAAA;AACA,SAAA,UAAA;AALT,SAAQ,oBAAoB;AAC5B,SAAQ,YAAY;AA2BpB,SAAA,eAAe,IAAI,SAAgC;AACjD,YAAM,MAAM,KAAK,IAAA;AACjB,YAAM,yBAAyB,MAAM,KAAK;AAG1C,UAAI,KAAK,QAAQ,WAAW,0BAA0B,KAAK,QAAQ,MAAM;AACvE,aAAK,QAAQ,GAAG,IAAI;AAAA,MACtB,OAAO;AAEL,aAAK,WAAW;AAGhB,YAAI,CAAC,KAAK,aAAa,KAAK,QAAQ,UAAU;AAC5C,gBAAM,kBAAkB,KAAK,QAAQ,OAAO;AAC5C,eAAK,YAAY;AACjB,eAAK,YAAY,WAAW,MAAM;AAChC,gBAAI,KAAK,aAAa,QAAW;AAC/B,mBAAK,QAAQ,GAAG,KAAK,QAAQ;AAAA,YAC/B;AAAA,UACF,GAAG,eAAe;AAAA,QACpB;AAAA,MACF;AAAA,IACF;AAEA,SAAQ,UAAU,IAAI,SAAgC;AACpD,WAAK,GAAG,GAAG,IAAI;AACf,WAAK,QAAQ,YAAY,MAAM,IAAI;AACnC,WAAK,oBAAoB,KAAK,IAAA;AAC9B,WAAK,aAAA;AACL,WAAK,WAAW;AAChB,WAAK,YAAY;AAAA,IACnB;AAOA,SAAA,QAAQ,MAAY;AAClB,UAAI,KAAK,aAAa,KAAK,UAAU;AACnC,aAAK,QAAQ,GAAG,KAAK,QAAQ;AAAA,MAC/B;AAAA,IACF;AAMA,SAAA,SAAS,MAAY;AACnB,WAAK,aAAA;AACL,WAAK,WAAW;AAChB,WAAK,YAAY;AAAA,IACnB;AAEA,SAAQ,eAAe,MAAY;AACjC,UAAI,KAAK,WAAW;AAClB,qBAAa,KAAK,SAAS;AAC3B,aAAK,YAAY;AAAA,MACnB;AAAA,IACF;AA/EE,QACE,KAAK,QAAQ,YAAY,UACzB,KAAK,QAAQ,aAAa,QAC1B;AACA,WAAK,QAAQ,UAAU;AACvB,WAAK,QAAQ,WAAW;AAAA,IAC1B;AAAA,EACF;AAyEF;AA+BO,SAAS,aACd,IACA,SACoC;AACpC,QAAM,YAAY,IAAI,cAAc,IAAI,OAAO;AAC/C,SAAO,UAAU;AACnB;;;"}

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

@@ -0,0 +1,128 @@
+import { AnyFunction } from '@tanstack/pacer/types';
+/**
+ * Options for configuring a lite throttled function
+ */
+export interface LiteThrottlerOptions<TFn extends AnyFunction = AnyFunction> {
+    /**
+     * Whether to execute on the leading edge of the timeout.
+     * Defaults to true.
+     */
+    leading?: boolean;
+    /**
+     * Callback function that is called after the function is executed
+     */
+    onExecute?: (args: Parameters<TFn>, throttler: LiteThrottler<TFn>) => void;
+    /**
+     * Whether to execute on the trailing edge of the timeout.
+     * Defaults to true.
+     */
+    trailing?: boolean;
+    /**
+     * Time window in milliseconds during which the function can only be executed once.
+     */
+    wait: number;
+}
+/**
+ * A lightweight class that creates a throttled function.
+ *
+ * This is an alternative to the Throttler in the core @tanstack/pacer package, but is more
+ * suitable for libraries and npm packages that need minimal overhead. Unlike the core Throttler,
+ * this version does not use TanStack Store for state management, has no devtools integration,
+ * and provides only essential throttling functionality.
+ *
+ * Throttling ensures a function is called at most once within a specified time window.
+ * Unlike debouncing which waits for a pause in calls, throttling guarantees consistent
+ * execution timing regardless of call frequency.
+ *
+ * Supports both leading and trailing edge execution:
+ * - Leading: Execute immediately on first call (default: true)
+ * - Trailing: Execute after wait period if called during throttle (default: true)
+ *
+ * Features:
+ * - Zero dependencies - no external libraries required
+ * - Minimal API surface - only essential methods (maybeExecute, flush, cancel)
+ * - Simple state management - uses basic private properties instead of reactive stores
+ * - Callback support for monitoring execution events
+ * - Lightweight - designed for use in npm packages where bundle size matters
+ *
+ * @example
+ * ```ts
+ * const throttler = new LiteThrottler((scrollY: number) => {
+ *   updateScrollPosition(scrollY);
+ * }, {
+ *   wait: 100,
+ *   onExecute: (args, throttler) => {
+ *     console.log('Updated scroll position:', args[0]);
+ *   }
+ * });
+ *
+ * // Will execute at most once per 100ms
+ * window.addEventListener('scroll', () => {
+ *   throttler.maybeExecute(window.scrollY);
+ * });
+ * ```
+ */
+export declare class LiteThrottler<TFn extends AnyFunction> {
+    fn: TFn;
+    options: LiteThrottlerOptions<TFn>;
+    private timeoutId;
+    private lastArgs;
+    private lastExecutionTime;
+    private isPending;
+    constructor(fn: TFn, options: LiteThrottlerOptions<TFn>);
+    /**
+     * Attempts to execute the throttled function. The execution behavior depends on the throttler options:
+     *
+     * - If enough time has passed since the last execution (>= wait period):
+     *   - With leading=true: Executes immediately
+     *   - With leading=false: Waits for the next trailing execution
+     *
+     * - If within the wait period:
+     *   - With trailing=true: Schedules execution for end of wait period
+     *   - With trailing=false: Drops the execution
+     */
+    maybeExecute: (...args: Parameters<TFn>) => void;
+    private execute;
+    /**
+     * Processes the current pending execution immediately.
+     * If there's a pending execution, it will be executed right away
+     * and the timeout will be cleared.
+     */
+    flush: () => void;
+    /**
+     * Cancels any pending trailing execution and clears internal state.
+     * If a trailing execution is scheduled, this will prevent that execution from occurring.
+     */
+    cancel: () => void;
+    private clearTimeout;
+}
+/**
+ * Creates a lightweight throttled function that limits how often the provided function can execute.
+ *
+ * This is an alternative to the throttle function in the core @tanstack/pacer package, but is more
+ * suitable for libraries and npm packages that need minimal overhead. Unlike the core version,
+ * this function creates a throttler with no external dependencies, devtools integration, or reactive state.
+ *
+ * Throttling ensures a function executes at most once within a specified time window,
+ * regardless of how many times it is called. This is useful for rate-limiting
+ * expensive operations or UI updates.
+ *
+ * @example
+ * ```ts
+ * const throttledScroll = liteThrottle(() => {
+ *   updateScrollIndicator();
+ * }, { wait: 100 });
+ *
+ * // Will execute at most once per 100ms
+ * window.addEventListener('scroll', throttledScroll);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Leading edge execution - fires immediately then throttles
+ * const throttledResize = liteThrottle(() => {
+ *   recalculateLayout();
+ * }, { wait: 250, leading: true, trailing: false });
+ * ```
+ */
+export declare function liteThrottle<TFn extends AnyFunction>(fn: TFn, options: LiteThrottlerOptions<TFn>): (...args: Parameters<TFn>) => void;

package/dist/esm/index.d.ts

@@ -0,0 +1,5 @@
+export * from './lite-debouncer.js';
+export * from './lite-throttler.js';
+export * from './lite-rate-limiter.js';
+export * from './lite-queuer.js';
+export * from './lite-batcher.js';

package/dist/esm/index.js

@@ -0,0 +1,18 @@
+import { LiteDebouncer, liteDebounce } from "./lite-debouncer.js";
+import { LiteThrottler, liteThrottle } from "./lite-throttler.js";
+import { LiteRateLimiter, liteRateLimit } from "./lite-rate-limiter.js";
+import { LiteQueuer, liteQueue } from "./lite-queuer.js";
+import { LiteBatcher, liteBatch } from "./lite-batcher.js";
+export {
+  LiteBatcher,
+  LiteDebouncer,
+  LiteQueuer,
+  LiteRateLimiter,
+  LiteThrottler,
+  liteBatch,
+  liteDebounce,
+  liteQueue,
+  liteRateLimit,
+  liteThrottle
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

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

package/dist/esm/lite-batcher.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Options for configuring a lite batcher instance
+ */
+export interface LiteBatcherOptions<TValue> {
+    /**
+     * Custom function to determine if a batch should be processed
+     * Return true to process the batch immediately
+     */
+    getShouldExecute?: (items: Array<TValue>, batcher: LiteBatcher<TValue>) => boolean;
+    /**
+     * Maximum number of items in a batch
+     * @default Infinity
+     */
+    maxSize?: number;
+    /**
+     * Callback fired after a batch is processed
+     */
+    onExecute?: (batch: Array<TValue>, batcher: LiteBatcher<TValue>) => void;
+    /**
+     * Callback fired after items are added to the batcher
+     */
+    onItemsChange?: (batcher: LiteBatcher<TValue>) => void;
+    /**
+     * Whether the batcher should start processing immediately
+     * @default true
+     */
+    started?: boolean;
+    /**
+     * Maximum time in milliseconds to wait before processing a batch.
+     * If the wait duration has elapsed, the batch will be processed.
+     * If not provided, the batch will not be triggered by a timeout.
+     * @default Infinity
+     */
+    wait?: number | ((batcher: LiteBatcher<TValue>) => number);
+}
+/**
+ * A lightweight class that collects items and processes them in batches.
+ *
+ * This is an alternative to the Batcher in the core @tanstack/pacer package, but is more
+ * suitable for libraries and npm packages that need minimal overhead. Unlike the core Batcher,
+ * this version does not use TanStack Store for state management, has no devtools integration,
+ * no callbacks, and provides only essential batching functionality.
+ *
+ * Batching is a technique for grouping multiple operations together to be processed as a single unit.
+ * This synchronous version is lighter weight and often all you need.
+ *
+ * The Batcher provides a flexible way to implement batching with configurable:
+ * - Maximum batch size (number of items per batch)
+ * - Time-based batching (process after X milliseconds)
+ * - Custom batch processing logic via getShouldExecute
+ *
+ * Features included:
+ * - Core batching functionality (addItem, flush, clear, cancel)
+ * - Size-based batching (maxSize)
+ * - Time-based batching (wait timeout)
+ * - Custom condition batching (getShouldExecute)
+ * - Manual processing controls
+ * - Public mutable options
+ * - Callback support for monitoring batch execution and state changes
+ *
+ * Features NOT included (compared to core Batcher):
+ * - No TanStack Store state management
+ * - No devtools integration
+ * - No complex state tracking (execution counts, etc.)
+ * - No reactive state management
+ *
+ * @example
+ * ```ts
+ * // Basic batching
+ * const batcher = new LiteBatcher<number>(
+ *   (items) => console.log('Processing batch:', items),
+ *   {
+ *     maxSize: 5,
+ *     wait: 2000,
+ *     onExecute: (batch, batcher) => {
+ *       console.log('Batch executed with', batch.length, 'items');
+ *     },
+ *     onItemsChange: (batcher) => {
+ *       console.log('Batch size changed to:', batcher.size);
+ *     }
+ *   }
+ * );
+ *
+ * batcher.addItem(1);
+ * batcher.addItem(2);
+ * // After 2 seconds or when 5 items are added, whichever comes first,
+ * // the batch will be processed
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Custom condition batching
+ * const batcher = new LiteBatcher<Task>(
+ *   (items) => processTasks(items),
+ *   {
+ *     getShouldExecute: (items) => items.some(task => task.urgent),
+ *     maxSize: 10,
+ *   }
+ * );
+ *
+ * batcher.addItem({ name: 'normal', urgent: false });
+ * batcher.addItem({ name: 'urgent', urgent: true }); // Triggers immediate processing
+ * ```
+ */
+export declare class LiteBatcher<TValue> {
+    fn: (items: Array<TValue>) => void;
+    options: LiteBatcherOptions<TValue>;
+    private items;
+    private timeoutId;
+    private _isPending;
+    constructor(fn: (items: Array<TValue>) => void, options?: LiteBatcherOptions<TValue>);
+    /**
+     * Number of items currently in the batch
+     */
+    get size(): number;
+    /**
+     * Whether the batch has no items to process (items array is empty)
+     */
+    get isEmpty(): boolean;
+    /**
+     * Whether the batcher is waiting for the timeout to trigger batch processing
+     */
+    get isPending(): boolean;
+    private getWait;
+    /**
+     * Adds an item to the batcher
+     * If the batch size is reached, timeout occurs, or getShouldExecute returns true, the batch will be processed
+     */
+    addItem: (item: TValue) => void;
+    /**
+     * 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 maxSize
+     * - 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.
+     */
+    private execute;
+    /**
+     * Processes the current batch of items immediately
+     */
+    flush: () => void;
+    /**
+     * Returns a copy of all items in the batcher
+     */
+    peekAllItems: () => Array<TValue>;
+    private clearTimeout;
+    /**
+     * Removes all items from the batcher
+     */
+    clear: () => void;
+    /**
+     * Cancels any pending execution that was scheduled.
+     * Does NOT clear out the items.
+     */
+    cancel: () => void;
+}
+/**
+ * Creates a batcher that processes items in batches.
+ *
+ * This is an alternative to the batch function in the core @tanstack/pacer package, but is more
+ * suitable for libraries and npm packages that need minimal overhead. Unlike the core version,
+ * this function creates a batcher with no external dependencies, devtools integration, or reactive state.
+ *
+ * @example
+ * ```ts
+ * const batchItems = liteBatch<number>(
+ *   (items) => console.log('Processing:', items),
+ *   {
+ *     maxSize: 3,
+ *   }
+ * );
+ *
+ * batchItems(1);
+ * batchItems(2);
+ * batchItems(3); // Triggers batch processing
+ * ```
+ */
+export declare function liteBatch<TValue>(fn: (items: Array<TValue>) => void, options?: LiteBatcherOptions<TValue>): (item: TValue) => void;

package/dist/esm/lite-batcher.js

@@ -0,0 +1,92 @@
+class LiteBatcher {
+  constructor(fn, options = {}) {
+    this.fn = fn;
+    this.options = options;
+    this.items = [];
+    this.timeoutId = null;
+    this._isPending = false;
+    this.addItem = (item) => {
+      this.items.push(item);
+      this._isPending = this.options.wait !== Infinity;
+      this.options.onItemsChange?.(this);
+      const shouldProcess = this.items.length >= this.options.maxSize || this.options.getShouldExecute(this.items, this);
+      if (shouldProcess) {
+        this.execute();
+      } else if (this.options.wait !== Infinity) {
+        this.clearTimeout();
+        this.timeoutId = setTimeout(() => this.execute(), this.getWait());
+      }
+    };
+    this.execute = () => {
+      if (this.items.length === 0) {
+        return;
+      }
+      const batch = this.peekAllItems();
+      this.clear();
+      this.fn(batch);
+      this.options.onExecute?.(batch, this);
+    };
+    this.flush = () => {
+      this.clearTimeout();
+      this.execute();
+    };
+    this.peekAllItems = () => {
+      return [...this.items];
+    };
+    this.clearTimeout = () => {
+      if (this.timeoutId) {
+        clearTimeout(this.timeoutId);
+        this.timeoutId = null;
+      }
+    };
+    this.clear = () => {
+      const hadItems = this.items.length > 0;
+      this.items = [];
+      this._isPending = false;
+      if (hadItems) {
+        this.options.onItemsChange?.(this);
+      }
+    };
+    this.cancel = () => {
+      this.clearTimeout();
+      this._isPending = false;
+    };
+    this.options.maxSize = this.options.maxSize ?? Infinity;
+    this.options.started = this.options.started ?? true;
+    this.options.wait = this.options.wait ?? Infinity;
+    this.options.getShouldExecute = this.options.getShouldExecute ?? (() => false);
+  }
+  /**
+   * Number of items currently in the batch
+   */
+  get size() {
+    return this.items.length;
+  }
+  /**
+   * Whether the batch has no items to process (items array is empty)
+   */
+  get isEmpty() {
+    return this.items.length === 0;
+  }
+  /**
+   * Whether the batcher is waiting for the timeout to trigger batch processing
+   */
+  get isPending() {
+    return this._isPending;
+  }
+  getWait() {
+    if (typeof this.options.wait === "function") {
+      return this.options.wait(this);
+    }
+    return this.options.wait;
+  }
+}
+function liteBatch(fn, options = {}) {
+  const batcher = new LiteBatcher(fn, options);
+  return batcher.addItem;
+}
+export {
+  LiteBatcher,
+  liteBatch
+};
+//# sourceMappingURL=lite-batcher.js.map