@tanstack/pacer-lite 0.1.0 → 0.2.0

package/dist/{cjs/lite-rate-limiter.d.cts → lite-rate-limiter.d.cts}

@@ -1,31 +1,34 @@
-import { AnyFunction } from '@tanstack/pacer/types';
+import { AnyFunction } from "@tanstack/pacer/types";
+
+//#region src/lite-rate-limiter.d.ts
+
 /**
  * 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';
+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.
@@ -65,47 +68,47 @@ export interface LiteRateLimiterOptions<TFn extends AnyFunction = AnyFunction> {
  * }
  * ```
  */
-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;
+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.
@@ -140,4 +143,7 @@ export declare class LiteRateLimiter<TFn extends AnyFunction> {
  * });
  * ```
  */
-export declare function liteRateLimit<TFn extends AnyFunction>(fn: TFn, options: LiteRateLimiterOptions<TFn>): (...args: Parameters<TFn>) => boolean;
+declare function liteRateLimit<TFn extends AnyFunction>(fn: TFn, options: LiteRateLimiterOptions<TFn>): (...args: Parameters<TFn>) => boolean;
+//#endregion
+export { LiteRateLimiter, LiteRateLimiterOptions, liteRateLimit };
+//# sourceMappingURL=lite-rate-limiter.d.cts.map

package/dist/{esm/lite-rate-limiter.d.ts → lite-rate-limiter.d.ts}

@@ -1,31 +1,34 @@
-import { AnyFunction } from '@tanstack/pacer/types';
+import { AnyFunction } from "@tanstack/pacer/types";
+
+//#region src/lite-rate-limiter.d.ts
+
 /**
  * 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';
+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.
@@ -65,47 +68,47 @@ export interface LiteRateLimiterOptions<TFn extends AnyFunction = AnyFunction> {
  * }
  * ```
  */
-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;
+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.
@@ -140,4 +143,7 @@ export declare class LiteRateLimiter<TFn extends AnyFunction> {
  * });
  * ```
  */
-export declare function liteRateLimit<TFn extends AnyFunction>(fn: TFn, options: LiteRateLimiterOptions<TFn>): (...args: Parameters<TFn>) => boolean;
+declare function liteRateLimit<TFn extends AnyFunction>(fn: TFn, options: LiteRateLimiterOptions<TFn>): (...args: Parameters<TFn>) => boolean;
+//#endregion
+export { LiteRateLimiter, LiteRateLimiterOptions, liteRateLimit };
+//# sourceMappingURL=lite-rate-limiter.d.ts.map

package/dist/lite-rate-limiter.js

@@ -0,0 +1,147 @@
+//#region src/lite-rate-limiter.ts
+/**
+* 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');
+* }
+* ```
+*/
+var LiteRateLimiter = class {
+	constructor(fn, options) {
+		this.fn = fn;
+		this.options = options;
+		this.executionTimes = [];
+		this.timeoutIds = /* @__PURE__ */ new Set();
+		this.maybeExecute = (...args) => {
+			this.cleanupOldExecutions();
+			if (this.getExecutionTimesInWindow().length < this.options.limit) {
+				this.execute(...args);
+				return true;
+			}
+			this.options.onReject?.(this);
+			return false;
+		};
+		this.execute = (...args) => {
+			const now = Date.now();
+			this.fn(...args);
+			this.options.onExecute?.(args, this);
+			this.executionTimes.push(now);
+			this.setCleanupTimeout(now);
+		};
+		this.getExecutionTimesInWindow = () => {
+			if (this.options.windowType === "sliding") return this.executionTimes.filter((time) => time > Date.now() - this.options.window);
+			else {
+				if (this.executionTimes.length === 0) return [];
+				const windowStart = Math.min(...this.executionTimes);
+				const windowEnd = windowStart + this.options.window;
+				if (Date.now() > windowEnd) return [];
+				return this.executionTimes.filter((time) => time >= windowStart && time <= windowEnd);
+			}
+		};
+		this.setCleanupTimeout = (executionTime) => {
+			if (this.options.windowType === "sliding" || this.timeoutIds.size === 0) {
+				const timeUntilExpiration = executionTime - Date.now() + this.options.window + 1;
+				const timeoutId = setTimeout(() => {
+					this.cleanupOldExecutions();
+					this.clearTimeout(timeoutId);
+				}, timeUntilExpiration);
+				this.timeoutIds.add(timeoutId);
+			}
+		};
+		this.clearTimeout = (timeoutId) => {
+			clearTimeout(timeoutId);
+			this.timeoutIds.delete(timeoutId);
+		};
+		this.clearTimeouts = () => {
+			this.timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId));
+			this.timeoutIds.clear();
+		};
+		this.cleanupOldExecutions = () => {
+			this.executionTimes = this.getExecutionTimesInWindow();
+		};
+		this.getRemainingInWindow = () => {
+			const relevantExecutionTimes = this.getExecutionTimesInWindow();
+			return Math.max(0, this.options.limit - relevantExecutionTimes.length);
+		};
+		this.getMsUntilNextWindow = () => {
+			if (this.getRemainingInWindow() > 0) return 0;
+			return (this.executionTimes[0] ?? Infinity) + this.options.window - Date.now();
+		};
+		this.reset = () => {
+			this.executionTimes = [];
+			this.clearTimeouts();
+		};
+		if (this.options.windowType === void 0) this.options.windowType = "fixed";
+	}
+};
+/**
+* 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'
+* });
+* ```
+*/
+function liteRateLimit(fn, options) {
+	return new LiteRateLimiter(fn, options).maybeExecute;
+}
+
+//#endregion
+export { LiteRateLimiter, liteRateLimit };
+//# sourceMappingURL=lite-rate-limiter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lite-rate-limiter.js","names":["fn: TFn","options: LiteRateLimiterOptions<TFn>"],"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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqEA,IAAa,kBAAb,MAAsD;CAIpD,YACE,AAAOA,IACP,AAAOC,SACP;EAFO;EACA;wBAL+B,EAAE;oCACA,IAAI,KAAK;uBA2BnC,GAAG,SAAmC;AACpD,QAAK,sBAAsB;AAI3B,OAF+B,KAAK,2BAA2B,CAEpC,SAAS,KAAK,QAAQ,OAAO;AACtD,SAAK,QAAQ,GAAG,KAAK;AACrB,WAAO;;AAGT,QAAK,QAAQ,WAAW,KAAK;AAC7B,UAAO;;kBAGU,GAAG,SAAgC;GACpD,MAAM,MAAM,KAAK,KAAK;AACtB,QAAK,GAAG,GAAG,KAAK;AAChB,QAAK,QAAQ,YAAY,MAAM,KAAK;AACpC,QAAK,eAAe,KAAK,IAAI;AAC7B,QAAK,kBAAkB,IAAI;;yCAG4B;AACvD,OAAI,KAAK,QAAQ,eAAe,UAE9B,QAAO,KAAK,eAAe,QACxB,SAAS,OAAO,KAAK,KAAK,GAAG,KAAK,QAAQ,OAC5C;QACI;AAEL,QAAI,KAAK,eAAe,WAAW,EACjC,QAAO,EAAE;IAGX,MAAM,cADkB,KAAK,IAAI,GAAG,KAAK,eAAe;IAExD,MAAM,YAAY,cAAc,KAAK,QAAQ;AAI7C,QAHY,KAAK,KAAK,GAGZ,UACR,QAAO,EAAE;AAIX,WAAO,KAAK,eAAe,QACxB,SAAS,QAAQ,eAAe,QAAQ,UAC1C;;;4BAIwB,kBAAgC;AAC3D,OACE,KAAK,QAAQ,eAAe,aAC5B,KAAK,WAAW,SAAS,GACzB;IAEA,MAAM,sBAAsB,gBADhB,KAAK,KAAK,GAC4B,KAAK,QAAQ,SAAS;IACxE,MAAM,YAAY,iBAAiB;AACjC,UAAK,sBAAsB;AAC3B,UAAK,aAAa,UAAU;OAC3B,oBAAoB;AACvB,SAAK,WAAW,IAAI,UAAU;;;uBAIV,cAAoC;AAC1D,gBAAa,UAAU;AACvB,QAAK,WAAW,OAAO,UAAU;;6BAGC;AAClC,QAAK,WAAW,SAAS,cAAc,aAAa,UAAU,CAAC;AAC/D,QAAK,WAAW,OAAO;;oCAGkB;AACzC,QAAK,iBAAiB,KAAK,2BAA2B;;oCAMnB;GACnC,MAAM,yBAAyB,KAAK,2BAA2B;AAC/D,UAAO,KAAK,IAAI,GAAG,KAAK,QAAQ,QAAQ,uBAAuB,OAAO;;oCAOnC;AACnC,OAAI,KAAK,sBAAsB,GAAG,EAChC,QAAO;AAGT,WADwB,KAAK,eAAe,MAAM,YACzB,KAAK,QAAQ,SAAS,KAAK,KAAK;;qBAMvC;AAClB,QAAK,iBAAiB,EAAE;AACxB,QAAK,eAAe;;AA5HpB,MAAI,KAAK,QAAQ,eAAe,OAC9B,MAAK,QAAQ,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgKhC,SAAgB,cACd,IACA,SACuC;AAEvC,QADoB,IAAI,gBAAgB,IAAI,QAAQ,CACjC"}

package/dist/lite-throttler.cjs

@@ -0,0 +1,127 @@
+
+//#region src/lite-throttler.ts
+/**
+* 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);
+* });
+* ```
+*/
+var LiteThrottler = class {
+	constructor(fn, options) {
+		this.fn = fn;
+		this.options = options;
+		this.lastExecutionTime = 0;
+		this.isPending = false;
+		this.maybeExecute = (...args) => {
+			const timeSinceLastExecution = Date.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;
+		}
+	}
+};
+/**
+* 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 });
+* ```
+*/
+function liteThrottle(fn, options) {
+	return new LiteThrottler(fn, options).maybeExecute;
+}
+
+//#endregion
+exports.LiteThrottler = LiteThrottler;
+exports.liteThrottle = liteThrottle;
+//# sourceMappingURL=lite-throttler.cjs.map

package/dist/lite-throttler.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lite-throttler.cjs","names":["fn: TFn","options: LiteThrottlerOptions<TFn>"],"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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkEA,IAAa,gBAAb,MAAoD;CAMlD,YACE,AAAOA,IACP,AAAOC,SACP;EAFO;EACA;2BALmB;mBACR;uBA2BJ,GAAG,SAAgC;GAEjD,MAAM,yBADM,KAAK,KAAK,GACe,KAAK;AAG1C,OAAI,KAAK,QAAQ,WAAW,0BAA0B,KAAK,QAAQ,KACjE,MAAK,QAAQ,GAAG,KAAK;QAChB;AAEL,SAAK,WAAW;AAGhB,QAAI,CAAC,KAAK,aAAa,KAAK,QAAQ,UAAU;KAC5C,MAAM,kBAAkB,KAAK,QAAQ,OAAO;AAC5C,UAAK,YAAY;AACjB,UAAK,YAAY,iBAAiB;AAChC,UAAI,KAAK,aAAa,OACpB,MAAK,QAAQ,GAAG,KAAK,SAAS;QAE/B,gBAAgB;;;;kBAKN,GAAG,SAAgC;AACpD,QAAK,GAAG,GAAG,KAAK;AAChB,QAAK,QAAQ,YAAY,MAAM,KAAK;AACpC,QAAK,oBAAoB,KAAK,KAAK;AACnC,QAAK,cAAc;AACnB,QAAK,WAAW;AAChB,QAAK,YAAY;;qBAQC;AAClB,OAAI,KAAK,aAAa,KAAK,SACzB,MAAK,QAAQ,GAAG,KAAK,SAAS;;sBAQb;AACnB,QAAK,cAAc;AACnB,QAAK,WAAW;AAChB,QAAK,YAAY;;4BAGgB;AACjC,OAAI,KAAK,WAAW;AAClB,iBAAa,KAAK,UAAU;AAC5B,SAAK,YAAY;;;AA7EnB,MACE,KAAK,QAAQ,YAAY,UACzB,KAAK,QAAQ,aAAa,QAC1B;AACA,QAAK,QAAQ,UAAU;AACvB,QAAK,QAAQ,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0G9B,SAAgB,aACd,IACA,SACoC;AAEpC,QADkB,IAAI,cAAc,IAAI,QAAQ,CAC/B"}