@tanstack/pacer 0.8.0 → 0.9.0

package/src/rate-limiter.ts

@@ -1,6 +1,30 @@
+import { Store } from '@tanstack/store'
 import { parseFunctionOrValue } from './utils'
 import type { AnyFunction } from './types'
 
+export interface RateLimiterState {
+  /**
+   * Number of function executions that have been completed
+   */
+  executionCount: number
+  /**
+   * Array of timestamps when executions occurred for rate limiting calculations
+   */
+  executionTimes: Array<number>
+  /**
+   * Number of function executions that have been rejected due to rate limiting
+   */
+  rejectionCount: number
+}
+
+function getDefaultRateLimiterState(): RateLimiterState {
+  return structuredClone({
+    executionCount: 0,
+    executionTimes: [],
+    rejectionCount: 0,
+  })
+}
+
 /**
  * Options for configuring a rate-limited function
  */
@@ -10,6 +34,10 @@ export interface RateLimiterOptions<TFn extends AnyFunction> {
    * Defaults to true.
    */
   enabled?: boolean | ((rateLimiter: RateLimiter<TFn>) => boolean)
+  /**
+   * Initial state for the rate limiter
+   */
+  initialState?: Partial<RateLimiterState>
   /**
    * Maximum number of executions allowed within the time window.
    * Can be a number or a callback function that receives the rate limiter instance and returns a number.
@@ -37,11 +65,12 @@ export interface RateLimiterOptions<TFn extends AnyFunction> {
   windowType?: 'fixed' | 'sliding'
 }
 
-const defaultOptions: Required<RateLimiterOptions<any>> = {
+const defaultOptions: Omit<
+  Required<RateLimiterOptions<any>>,
+  'initialState' | 'onExecute' | 'onReject'
+> = {
   enabled: true,
   limit: 1,
-  onExecute: () => {},
-  onReject: () => {},
   window: 0,
   windowType: 'fixed',
 }
@@ -66,11 +95,24 @@ const defaultOptions: Required<RateLimiterOptions<any>> = {
  * Rate limiting is best used for hard API limits or resource constraints. For UI updates or
  * smoothing out frequent events, throttling or debouncing usually provide better user experience.
  *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the rate limiter
+ * - Use `onExecute` callback to react to function execution and implement custom logic
+ * - Use `onReject` callback to react to executions being rejected when rate limit is exceeded
+ * - The state includes execution count, execution times, and rejection count
+ * - State can be accessed via `rateLimiter.store.state` when using the class directly
+ * - When using framework adapters (React/Solid), state is accessed from `rateLimiter.state`
+ *
  * @example
  * ```ts
  * const rateLimiter = new RateLimiter(
  *   (id: string) => api.getData(id),
- *   { limit: 5, window: 1000, windowType: 'sliding' } // 5 calls per second with sliding window
+ *   {
+ *     limit: 5,
+ *     window: 1000,
+ *     windowType: 'sliding',
+ *   }
  * );
  *
  * // Will execute immediately until limit reached, then block
@@ -78,54 +120,57 @@ const defaultOptions: Required<RateLimiterOptions<any>> = {
  * ```
  */
 export class RateLimiter<TFn extends AnyFunction> {
-  private _executionCount = 0
-  private _rejectionCount = 0
-  private _executionTimes: Array<number> = []
-  private _options: RateLimiterOptions<TFn>
+  readonly store: Store<Readonly<RateLimiterState>> =
+    new Store<RateLimiterState>(getDefaultRateLimiterState())
+  options: RateLimiterOptions<TFn>
 
   constructor(
     private fn: TFn,
     initialOptions: RateLimiterOptions<TFn>,
   ) {
-    this._options = {
+    this.options = {
       ...defaultOptions,
       ...initialOptions,
     }
+    this.#setState(this.options.initialState ?? {})
   }
 
   /**
    * Updates the rate limiter options
    */
-  setOptions(newOptions: Partial<RateLimiterOptions<TFn>>): void {
-    this._options = { ...this._options, ...newOptions }
+  setOptions = (newOptions: Partial<RateLimiterOptions<TFn>>): void => {
+    this.options = { ...this.options, ...newOptions }
   }
 
-  /**
-   * Returns the current rate limiter options
-   */
-  getOptions(): Required<RateLimiterOptions<TFn>> {
-    return this._options as Required<RateLimiterOptions<TFn>>
+  #setState = (newState: Partial<RateLimiterState>): void => {
+    this.store.setState((state) => {
+      const combinedState = {
+        ...state,
+        ...newState,
+      }
+      return combinedState
+    })
   }
 
   /**
    * Returns the current enabled state of the rate limiter
    */
-  getEnabled(): boolean {
-    return parseFunctionOrValue(this._options.enabled, this)!
+  #getEnabled = (): boolean => {
+    return !!parseFunctionOrValue(this.options.enabled, this)
   }
 
   /**
    * Returns the current limit of executions allowed within the time window
    */
-  getLimit(): number {
-    return parseFunctionOrValue(this._options.limit, this)
+  #getLimit = (): number => {
+    return parseFunctionOrValue(this.options.limit, this)
   }
 
   /**
    * Returns the current time window in milliseconds
    */
-  getWindow(): number {
-    return parseFunctionOrValue(this._options.window, this)
+  #getWindow = (): number => {
+    return parseFunctionOrValue(this.options.window, this)
   }
 
   /**
@@ -143,95 +188,86 @@ export class RateLimiter<TFn extends AnyFunction> {
    * rateLimiter.maybeExecute('arg1', 'arg2'); // false
    * ```
    */
-  maybeExecute(...args: Parameters<TFn>): boolean {
-    this.cleanupOldExecutions()
+  maybeExecute = (...args: Parameters<TFn>): boolean => {
+    this.#cleanupOldExecutions()
 
-    if (this._options.windowType === 'sliding') {
-      // For sliding window, we can execute if we have capacity in the current window
-      if (this._executionTimes.length < this.getLimit()) {
-        this.execute(...args)
-        return true
-      }
-    } else {
-      // For fixed window, we need to check if we're in a new window
-      const now = Date.now()
-      const oldestExecution = Math.min(...this._executionTimes)
-      const isNewWindow = oldestExecution + this.getWindow() <= now
+    const relevantExecutionTimes = this.#getRelevantExecutionTimes()
 
-      if (isNewWindow || this._executionTimes.length < this.getLimit()) {
-        this.execute(...args)
-        return true
-      }
+    if (relevantExecutionTimes.length < this.#getLimit()) {
+      this.#execute(...args)
+      return true
     }
 
-    this.rejectFunction()
+    this.#setState({
+      rejectionCount: this.store.state.rejectionCount + 1,
+    })
+    this.options.onReject?.(this)
     return false
   }
 
-  private execute(...args: Parameters<TFn>): void {
-    if (!this.getEnabled()) return
+  #execute = (...args: Parameters<TFn>): void => {
+    if (!this.#getEnabled()) return
     const now = Date.now()
-    this._executionCount++
-    this._executionTimes.push(now)
-    this.fn(...args) // execute the function
-    this._options.onExecute?.(this)
+    this.fn(...args) // EXECUTE!
+    this.store.state.executionTimes.push(now) // mutate state directly for performance
+    this.#setState({
+      executionCount: this.store.state.executionCount + 1,
+    })
+    this.options.onExecute?.(this)
   }
 
-  private rejectFunction(): void {
-    this._rejectionCount++
-    if (this._options.onReject) {
-      this._options.onReject(this)
+  #getRelevantExecutionTimes = (): Array<number> => {
+    if (this.options.windowType === 'sliding') {
+      // For sliding window, return all executions within the current window
+      return this.store.state.executionTimes.filter(
+        (time) => time > Date.now() - this.#getWindow(),
+      )
+    } else {
+      // For fixed window, return all executions in the current window
+      // The window starts from the oldest execution time
+      const oldestExecution = Math.min(...this.store.state.executionTimes)
+      const windowStart = oldestExecution
+      return this.store.state.executionTimes.filter(
+        (time) =>
+          time >= windowStart && time <= windowStart + this.#getWindow(),
+      )
     }
   }
 
-  private cleanupOldExecutions(): void {
+  #cleanupOldExecutions = (): void => {
     const now = Date.now()
-    const windowStart = now - this.getWindow()
-    this._executionTimes = this._executionTimes.filter(
-      (time) => time > windowStart,
-    )
-  }
-
-  /**
-   * Returns the number of times the function has been executed
-   */
-  getExecutionCount(): number {
-    return this._executionCount
-  }
-
-  /**
-   * Returns the number of times the function has been rejected
-   */
-  getRejectionCount(): number {
-    return this._rejectionCount
+    const windowStart = now - this.#getWindow()
+    this.#setState({
+      executionTimes: this.store.state.executionTimes.filter(
+        (time) => time > windowStart,
+      ),
+    })
   }
 
   /**
    * Returns the number of remaining executions allowed in the current window
    */
-  getRemainingInWindow(): number {
-    this.cleanupOldExecutions()
-    return Math.max(0, this.getLimit() - this._executionTimes.length)
+  getRemainingInWindow = (): number => {
+    const relevantExecutionTimes = this.#getRelevantExecutionTimes()
+    return Math.max(0, this.#getLimit() - relevantExecutionTimes.length)
   }
 
   /**
    * Returns the number of milliseconds until the next execution will be possible
    */
-  getMsUntilNextWindow(): number {
+  getMsUntilNextWindow = (): number => {
     if (this.getRemainingInWindow() > 0) {
       return 0
     }
-    const oldestExecution = Math.min(...this._executionTimes)
-    return oldestExecution + this.getWindow() - Date.now()
+    const oldestExecution = this.store.state.executionTimes[0] ?? Infinity
+    return oldestExecution + this.#getWindow() - Date.now()
   }
 
   /**
    * Resets the rate limiter state
    */
-  reset(): void {
-    this._executionTimes = []
-    this._executionCount = 0
-    this._rejectionCount = 0
+  reset = (): void => {
+    this.#setState(getDefaultRateLimiterState())
   }
 }
 
@@ -249,6 +285,15 @@ export class RateLimiter<TFn extends AnyFunction> {
  * - 'sliding': A rolling window that allows executions as old ones expire. This provides a more
  *   consistent rate of execution over time.
  *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the rate limiter
+ * - Use `onExecute` callback to react to function execution and implement custom logic
+ * - Use `onReject` callback to react to executions being rejected when rate limit is exceeded
+ * - The state includes execution count, execution times, and rejection count
+ * - State can be accessed via the underlying RateLimiter instance's `store.state` property
+ * - When using framework adapters (React/Solid), state is accessed from the hook's state property
+ *
  * Consider using throttle() or debounce() if you need more intelligent execution control. Use rate limiting when you specifically
  * need to enforce a hard limit on the number of executions within a time period.
  *
@@ -277,5 +322,5 @@ export function rateLimit<TFn extends AnyFunction>(
   initialOptions: RateLimiterOptions<TFn>,
 ) {
   const rateLimiter = new RateLimiter(fn, initialOptions)
-  return rateLimiter.maybeExecute.bind(rateLimiter)
+  return rateLimiter.maybeExecute
 }

package/src/throttler.ts

@@ -1,6 +1,47 @@
+import { Store } from '@tanstack/store'
 import { parseFunctionOrValue } from './utils'
 import type { AnyFunction } from './types'
 
+export interface ThrottlerState<TFn extends AnyFunction> {
+  /**
+   * Number of function executions that have been completed
+   */
+  executionCount: number
+  /**
+   * The arguments from the most recent call to maybeExecute
+   */
+  lastArgs: Parameters<TFn> | undefined
+  /**
+   * Timestamp of the last function execution in milliseconds
+   */
+  lastExecutionTime: number
+  /**
+   * Timestamp when the next execution can occur in milliseconds
+   */
+  nextExecutionTime: number
+  /**
+   * Whether the throttler is waiting for the timeout to trigger execution
+   */
+  isPending: boolean
+  /**
+   * Current execution status - 'idle' when not active, 'pending' when waiting for timeout
+   */
+  status: 'disabled' | 'idle' | 'pending'
+}
+
+function getDefaultThrottlerState<
+  TFn extends AnyFunction,
+>(): ThrottlerState<TFn> {
+  return structuredClone({
+    executionCount: 0,
+    isPending: false,
+    lastArgs: undefined,
+    lastExecutionTime: 0,
+    nextExecutionTime: 0,
+    status: 'idle',
+  })
+}
+
 /**
  * Options for configuring a throttled function
  */
@@ -11,6 +52,10 @@ export interface ThrottlerOptions<TFn extends AnyFunction> {
    * Defaults to true.
    */
   enabled?: boolean | ((throttler: Throttler<TFn>) => boolean)
+  /**
+   * Initial state for the throttler
+   */
+  initialState?: Partial<ThrottlerState<TFn>>
   /**
    * Whether to execute on the leading edge of the timeout.
    * Defaults to true.
@@ -33,10 +78,12 @@ export interface ThrottlerOptions<TFn extends AnyFunction> {
   wait: number | ((throttler: Throttler<TFn>) => number)
 }
 
-const defaultOptions: Required<ThrottlerOptions<any>> = {
+const defaultOptions: Omit<
+  Required<ThrottlerOptions<any>>,
+  'initialState' | 'onExecute'
+> = {
   enabled: true,
   leading: true,
-  onExecute: () => {},
   trailing: true,
   wait: 0,
 }
@@ -54,6 +101,14 @@ const defaultOptions: Required<ThrottlerOptions<any>> = {
  *
  * For collapsing rapid-fire events where you only care about the last call, consider using Debouncer.
  *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the throttler
+ * - Use `onExecute` callback to react to function execution and implement custom logic
+ * - The state includes execution count, last execution time, pending status, and more
+ * - State can be accessed via `throttler.store.state` when using the class directly
+ * - When using framework adapters (React/Solid), state is accessed from `throttler.state`
+ *
  * @example
  * ```ts
  * const throttler = new Throttler(
@@ -69,53 +124,59 @@ const defaultOptions: Required<ThrottlerOptions<any>> = {
  * ```
  */
 export class Throttler<TFn extends AnyFunction> {
-  private _executionCount = 0
-  private _lastArgs: Parameters<TFn> | undefined
-  private _lastExecutionTime = 0
-  private _options: Required<ThrottlerOptions<TFn>>
-  private _timeoutId: NodeJS.Timeout | undefined
+  readonly store: Store<Readonly<ThrottlerState<TFn>>> = new Store(
+    getDefaultThrottlerState(),
+  )
+  options: ThrottlerOptions<TFn>
+  #timeoutId: NodeJS.Timeout | undefined
 
   constructor(
     private fn: TFn,
     initialOptions: ThrottlerOptions<TFn>,
   ) {
-    this._options = {
+    this.options = {
       ...defaultOptions,
       ...initialOptions,
     }
+    this.#setState(this.options.initialState ?? {})
   }
 
   /**
    * Updates the throttler options
    */
-  setOptions(newOptions: Partial<ThrottlerOptions<TFn>>): void {
-    this._options = { ...this._options, ...newOptions }
+  setOptions = (newOptions: Partial<ThrottlerOptions<TFn>>): void => {
+    this.options = { ...this.options, ...newOptions }
 
-    // End the pending state if the debouncer is disabled
-    if (!this._options.enabled) {
+    // Cancel pending execution if the throttler is disabled
+    if (!this.#getEnabled()) {
       this.cancel()
     }
   }
 
-  /**
-   * Returns the current throttler options
-   */
-  getOptions(): Required<ThrottlerOptions<TFn>> {
-    return this._options
+  #setState = (newState: Partial<ThrottlerState<TFn>>): void => {
+    this.store.setState((state) => {
+      const combinedState = {
+        ...state,
+        ...newState,
+      }
+      const { isPending } = combinedState
+      return {
+        ...combinedState,
+        status: !this.#getEnabled()
+          ? 'disabled'
+          : isPending
+            ? 'pending'
+            : 'idle',
+      }
+    })
   }
 
-  /**
-   * Returns the current enabled state of the throttler
-   */
-  getEnabled(): boolean {
-    return parseFunctionOrValue(this._options.enabled, this)
+  #getEnabled = (): boolean => {
+    return !!parseFunctionOrValue(this.options.enabled, this)
   }
 
-  /**
-   * Returns the current wait time in milliseconds
-   */
-  getWait(): number {
-    return parseFunctionOrValue(this._options.wait, this)
+  #getWait = (): number => {
+    return parseFunctionOrValue(this.options.wait, this)
   }
 
   /**
@@ -140,86 +201,91 @@ export class Throttler<TFn extends AnyFunction> {
    * throttled.maybeExecute('c', 'd');
    * ```
    */
-  maybeExecute(...args: Parameters<TFn>): void {
+  maybeExecute = (...args: Parameters<TFn>): void => {
     const now = Date.now()
-    const timeSinceLastExecution = now - this._lastExecutionTime
-    const wait = this.getWait()
+    const timeSinceLastExecution = now - this.store.state.lastExecutionTime
+    const wait = this.#getWait()
 
     // Handle leading execution
-    if (this._options.leading && timeSinceLastExecution >= wait) {
-      this.execute(...args)
+    if (this.options.leading && timeSinceLastExecution >= wait) {
+      this.#execute(...args)
     } else {
       // Store the most recent arguments for potential trailing execution
-      this._lastArgs = args
-
+      this.#setState({
+        lastArgs: args,
+      })
       // Set up trailing execution if not already scheduled
-      if (!this._timeoutId && this._options.trailing) {
-        const _timeSinceLastExecution = this._lastExecutionTime
-          ? now - this._lastExecutionTime
+      if (!this.#timeoutId && this.options.trailing) {
+        // prevent large number if lastExecutionTime is undefined
+        const _timeSinceLastExecution = this.store.state.lastExecutionTime
+          ? now - this.store.state.lastExecutionTime
           : 0
         const timeoutDuration = wait - _timeSinceLastExecution
-        this._timeoutId = setTimeout(() => {
-          if (this._lastArgs !== undefined) {
-            this.execute(...this._lastArgs)
+        this.#setState({ isPending: true })
+        this.#timeoutId = setTimeout(() => {
+          const { lastArgs } = this.store.state
+          if (lastArgs !== undefined) {
+            this.#execute(...lastArgs)
           }
         }, timeoutDuration)
       }
     }
   }
 
-  private execute(...args: Parameters<TFn>): void {
-    if (!this.getEnabled()) return
+  #execute = (...args: Parameters<TFn>): void => {
+    if (!this.#getEnabled()) return
     this.fn(...args) // EXECUTE!
-    this._executionCount++
-    this._lastExecutionTime = Date.now()
-    this._timeoutId = undefined
-    this._lastArgs = undefined
-    this._options.onExecute(this)
+    const lastExecutionTime = Date.now()
+    const nextExecutionTime = lastExecutionTime + this.#getWait()
+    this.#clearTimeout()
+    this.#setState({
+      executionCount: this.store.state.executionCount + 1,
+      lastExecutionTime,
+      nextExecutionTime,
+      isPending: false,
+      lastArgs: undefined,
+    })
+    this.options.onExecute?.(this)
   }
 
   /**
-   * Cancels any pending trailing execution and clears internal state.
-   *
-   * If a trailing execution is scheduled (due to throttling with trailing=true),
-   * this will prevent that execution from occurring. The internal timeout and
-   * stored arguments will be cleared.
-   *
-   * Has no effect if there is no pending execution.
+   * Processes the current pending execution immediately
    */
-  cancel(): void {
-    if (this._timeoutId) {
-      clearTimeout(this._timeoutId)
-      this._timeoutId = undefined
-      this._lastArgs = undefined
+  flush = (): void => {
+    if (this.store.state.isPending && this.store.state.lastArgs) {
+      this.#execute(...this.store.state.lastArgs)
     }
   }
 
-  /**
-   * Returns the last execution time
-   */
-  getLastExecutionTime(): number {
-    return this._lastExecutionTime
-  }
-
-  /**
-   * Returns the next execution time
-   */
-  getNextExecutionTime(): number {
-    return this._lastExecutionTime + this.getWait()
+  #clearTimeout = (): void => {
+    if (this.#timeoutId) {
+      clearTimeout(this.#timeoutId)
+      this.#timeoutId = undefined
+    }
   }
 
   /**
-   * Returns the number of times the function has been executed
+   * Cancels any pending trailing execution and clears internal state.
+   *
+   * If a trailing execution is scheduled (due to throttling with trailing=true),
+   * this will prevent that execution from occurring. The internal timeout and
+   * stored arguments will be cleared.
+   *
+   * Has no effect if there is no pending execution.
    */
-  getExecutionCount(): number {
-    return this._executionCount
+  cancel = (): void => {
+    this.#clearTimeout()
+    this.#setState({
+      lastArgs: undefined,
+      isPending: false,
+    })
   }
 
   /**
-   * Returns `true` if there is a pending execution
+   * Resets the throttler state to its default values
    */
-  getIsPending(): boolean {
-    return this.getEnabled() && !!this._timeoutId
+  reset = (): void => {
+    this.#setState(getDefaultThrottlerState<TFn>())
   }
 }
 
@@ -236,6 +302,14 @@ export class Throttler<TFn extends AnyFunction> {
  * For handling bursts of events, consider using debounce() instead. For hard execution
  * limits, consider using rateLimit().
  *
+ * State Management:
+ * - Uses TanStack Store for reactive state management
+ * - Use `initialState` to provide initial state values when creating the throttler
+ * - Use `onExecute` callback to react to function execution and implement custom logic
+ * - The state includes execution count, last execution time, pending status, and more
+ * - State can be accessed via the underlying Throttler instance's `store.state` property
+ * - When using framework adapters (React/Solid), state is accessed from the hook's state property
+ *
  * @example
  * ```ts
  * // Basic throttling - max once per second
@@ -254,5 +328,5 @@ export function throttle<TFn extends AnyFunction>(
   initialOptions: ThrottlerOptions<TFn>,
 ) {
   const throttler = new Throttler(fn, initialOptions)
-  return throttler.maybeExecute.bind(throttler)
+  return throttler.maybeExecute
 }

package/src/utils.ts

@@ -10,18 +10,3 @@ export function parseFunctionOrValue<T, TArgs extends Array<any>>(
 ): T {
   return isFunction(value) ? value(...args) : value
 }
-
-export function bindInstanceMethods<T extends Record<string, any>>(
-  instance: T,
-): T {
-  return Object.getOwnPropertyNames(Object.getPrototypeOf(instance)).reduce(
-    (acc: any, key) => {
-      const method = instance[key as keyof T]
-      if (isFunction(method)) {
-        acc[key] = method.bind(instance)
-      }
-      return acc
-    },
-    instance,
-  )
-}