@tanstack/pacer 0.13.0 → 0.15.0

package/src/queuer.ts

@@ -1,7 +1,12 @@
 import { Store } from '@tanstack/store'
-import { parseFunctionOrValue } from './utils'
+import { createKey, parseFunctionOrValue } from './utils'
+import { emitChange, pacerEventClient } from './event-client'
 
 export interface QueuerState<TValue> {
+  /**
+   * Number of times addItem has been called (for reduction calculations)
+   */
+  addItemCount: number
   /**
    * Number of items that have been processed by the queuer
    */
@@ -66,6 +71,7 @@ function getDefaultQueuerState<TValue>(): QueuerState<TValue> {
     rejectionCount: 0,
     size: 0,
     status: 'idle',
+    addItemCount: 0,
   }
 }
 
@@ -108,6 +114,11 @@ export interface QueuerOptions<TValue> {
    * Initial state for the queuer
    */
   initialState?: Partial<QueuerState<TValue>>
+  /**
+   * Optional key to identify this queuer instance.
+   * If provided, the queuer will be identified by this key in the devtools and PacerProvider if applicable.
+   */
+  key?: string
   /**
    * Maximum number of items allowed in the queuer
    */
@@ -148,6 +159,7 @@ const defaultOptions: Omit<
   | 'onItemsChange'
   | 'onReject'
   | 'onExpire'
+  | 'key'
 > = {
   addItemsTo: 'back',
   getItemsFrom: 'front',
@@ -244,13 +256,15 @@ export class Queuer<TValue> {
   readonly store: Store<Readonly<QueuerState<TValue>>> = new Store(
     getDefaultQueuerState<TValue>(),
   )
+  key: string
   options: QueuerOptions<TValue>
   #timeoutId: NodeJS.Timeout | null = null
 
   constructor(
-    private fn: (item: TValue) => void,
+    public fn: (item: TValue) => void,
     initialOptions: QueuerOptions<TValue> = {},
   ) {
+    this.key = createKey(initialOptions.key)
     this.options = {
       ...defaultOptions,
       ...initialOptions,
@@ -273,6 +287,11 @@ export class Queuer<TValue> {
         this.addItem(item, this.options.addItemsTo ?? 'back', isLast)
       }
     }
+    pacerEventClient.on('d-Queuer', (event) => {
+      if (event.payload.key !== this.key) return
+      this.#setState(event.payload.store.state)
+      this.setOptions(event.payload.options)
+    })
   }
 
   /**
@@ -307,6 +326,7 @@ export class Queuer<TValue> {
         status,
       }
     })
+    emitChange('Queuer', this)
   }
 
   /**
@@ -366,6 +386,10 @@ export class Queuer<TValue> {
     position: QueuePosition = this.options.addItemsTo ?? 'back',
     runOnItemsChange: boolean = true,
   ): boolean => {
+    this.#setState({
+      addItemCount: this.store.state.addItemCount + 1,
+    })
+
     if (this.store.state.items.length >= (this.options.maxSize ?? Infinity)) {
       this.#setState({
         rejectionCount: this.store.state.rejectionCount + 1,

package/src/rate-limiter.ts

@@ -1,5 +1,6 @@
 import { Store } from '@tanstack/store'
-import { parseFunctionOrValue } from './utils'
+import { createKey, parseFunctionOrValue } from './utils'
+import { emitChange, pacerEventClient } from './event-client'
 import type { AnyFunction } from './types'
 
 export interface RateLimiterState {
@@ -15,6 +16,10 @@ export interface RateLimiterState {
    * Whether the rate limiter has exceeded the limit
    */
   isExceeded: boolean
+  /**
+   * Number of times maybeExecute has been called (for reduction calculations)
+   */
+  maybeExecuteCount: number
   /**
    * Number of function executions that have been rejected due to rate limiting
    */
@@ -26,13 +31,14 @@ export interface RateLimiterState {
 }
 
 function getDefaultRateLimiterState(): RateLimiterState {
-  return structuredClone({
+  return {
     executionCount: 0,
     executionTimes: [],
     isExceeded: false,
     rejectionCount: 0,
     status: 'idle',
-  })
+    maybeExecuteCount: 0,
+  }
 }
 
 /**
@@ -48,6 +54,11 @@ export interface RateLimiterOptions<TFn extends AnyFunction> {
    * Initial state for the rate limiter
    */
   initialState?: Partial<RateLimiterState>
+  /**
+   * Optional key to identify this rate limiter instance.
+   * If provided, the rate limiter will be identified by this key in the devtools and PacerProvider if applicable.
+   */
+  key?: string
   /**
    * 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.
@@ -77,7 +88,7 @@ export interface RateLimiterOptions<TFn extends AnyFunction> {
 
 const defaultOptions: Omit<
   Required<RateLimiterOptions<any>>,
-  'initialState' | 'onExecute' | 'onReject'
+  'initialState' | 'onExecute' | 'onReject' | 'key'
 > = {
   enabled: true,
   limit: 1,
@@ -132,13 +143,15 @@ const defaultOptions: Omit<
 export class RateLimiter<TFn extends AnyFunction> {
   readonly store: Store<Readonly<RateLimiterState>> =
     new Store<RateLimiterState>(getDefaultRateLimiterState())
+  key: string
   options: RateLimiterOptions<TFn>
   #timeoutIds: Set<NodeJS.Timeout> = new Set()
 
   constructor(
-    private fn: TFn,
+    public fn: TFn,
     initialOptions: RateLimiterOptions<TFn>,
   ) {
+    this.key = createKey(initialOptions.key)
     this.options = {
       ...defaultOptions,
       ...initialOptions,
@@ -147,6 +160,12 @@ export class RateLimiter<TFn extends AnyFunction> {
     for (const executionTime of this.#getExecutionTimesInWindow()) {
       this.#setCleanupTimeout(executionTime)
     }
+
+    pacerEventClient.on('d-RateLimiter', (event) => {
+      if (event.payload.key !== this.key) return
+      this.#setState(event.payload.store.state)
+      this.setOptions(event.payload.options)
+    })
   }
 
   /**
@@ -174,6 +193,7 @@ export class RateLimiter<TFn extends AnyFunction> {
         status,
       }
     })
+    emitChange('RateLimiter', this)
   }
 
   /**
@@ -213,6 +233,10 @@ export class RateLimiter<TFn extends AnyFunction> {
    * ```
    */
   maybeExecute = (...args: Parameters<TFn>): boolean => {
+    this.#setState({
+      maybeExecuteCount: this.store.state.maybeExecuteCount + 1,
+    })
+
     this.#cleanupOldExecutions()
 
     const relevantExecutionTimes = this.#getExecutionTimesInWindow()

package/src/throttler.ts

@@ -1,5 +1,6 @@
 import { Store } from '@tanstack/store'
-import { parseFunctionOrValue } from './utils'
+import { createKey, parseFunctionOrValue } from './utils'
+import { emitChange, pacerEventClient } from './event-client'
 import type { AnyFunction } from './types'
 
 export interface ThrottlerState<TFn extends AnyFunction> {
@@ -19,6 +20,10 @@ export interface ThrottlerState<TFn extends AnyFunction> {
    * Timestamp of the last function execution in milliseconds
    */
   lastExecutionTime: number
+  /**
+   * Number of times maybeExecute has been called (for reduction calculations)
+   */
+  maybeExecuteCount: number
   /**
    * Timestamp when the next execution can occur in milliseconds
    */
@@ -32,14 +37,15 @@ export interface ThrottlerState<TFn extends AnyFunction> {
 function getDefaultThrottlerState<
   TFn extends AnyFunction,
 >(): ThrottlerState<TFn> {
-  return structuredClone({
+  return {
     executionCount: 0,
     isPending: false,
     lastArgs: undefined,
     lastExecutionTime: 0,
     nextExecutionTime: 0,
     status: 'idle',
-  })
+    maybeExecuteCount: 0,
+  }
 }
 
 /**
@@ -56,6 +62,11 @@ export interface ThrottlerOptions<TFn extends AnyFunction> {
    * Initial state for the throttler
    */
   initialState?: Partial<ThrottlerState<TFn>>
+  /**
+   * A key to identify the throttler.
+   * If provided, the throttler will be identified by this key in the devtools and PacerProvider if applicable.
+   */
+  key?: string
   /**
    * Whether to execute on the leading edge of the timeout.
    * Defaults to true.
@@ -80,7 +91,7 @@ export interface ThrottlerOptions<TFn extends AnyFunction> {
 
 const defaultOptions: Omit<
   Required<ThrottlerOptions<any>>,
-  'initialState' | 'onExecute'
+  'initialState' | 'onExecute' | 'key'
 > = {
   enabled: true,
   leading: true,
@@ -127,18 +138,26 @@ export class Throttler<TFn extends AnyFunction> {
   readonly store: Store<Readonly<ThrottlerState<TFn>>> = new Store(
     getDefaultThrottlerState(),
   )
+  key: string | undefined
   options: ThrottlerOptions<TFn>
   #timeoutId: NodeJS.Timeout | undefined
 
   constructor(
-    private fn: TFn,
+    public fn: TFn,
     initialOptions: ThrottlerOptions<TFn>,
   ) {
+    this.key = createKey(initialOptions.key)
     this.options = {
       ...defaultOptions,
       ...initialOptions,
     }
     this.#setState(this.options.initialState ?? {})
+
+    pacerEventClient.on('d-Throttler', (event) => {
+      if (event.payload.key !== this.key) return
+      this.#setState(event.payload.store.state as ThrottlerState<TFn>)
+      this.setOptions(event.payload.options)
+    })
   }
 
   /**
@@ -169,6 +188,7 @@ export class Throttler<TFn extends AnyFunction> {
             : 'idle',
       }
     })
+    emitChange('Throttler', this)
   }
 
   #getEnabled = (): boolean => {
@@ -202,6 +222,10 @@ export class Throttler<TFn extends AnyFunction> {
    * ```
    */
   maybeExecute = (...args: Parameters<TFn>): void => {
+    this.#setState({
+      maybeExecuteCount: this.store.state.maybeExecuteCount + 1,
+    })
+
     const now = Date.now()
     const timeSinceLastExecution = now - this.store.state.lastExecutionTime
     const wait = this.#getWait()

package/src/utils.ts

@@ -10,3 +10,18 @@ export function parseFunctionOrValue<T, TArgs extends Array<any>>(
 ): T {
   return isFunction(value) ? value(...args) : value
 }
+
+export function createKey(key?: string): string {
+  if (key) {
+    return key
+  }
+
+  if (
+    typeof crypto !== 'undefined' &&
+    typeof crypto.randomUUID === 'function'
+  ) {
+    return crypto.randomUUID()
+  }
+
+  return ''
+}