@tanstack/pacer 0.15.4 → 0.16.1

package/src/rate-limiter.ts

@@ -1,5 +1,5 @@
 import { Store } from '@tanstack/store'
-import { createKey, parseFunctionOrValue } from './utils'
+import { parseFunctionOrValue } from './utils'
 import { emitChange, pacerEventClient } from './event-client'
 import type { AnyFunction } from './types'
 
@@ -86,6 +86,18 @@ export interface RateLimiterOptions<TFn extends AnyFunction> {
   windowType?: 'fixed' | 'sliding'
 }
 
+/**
+ * Utility function for sharing common `RateLimiterOptions` options between different `RateLimiter` instances.
+ */
+export function rateLimiterOptions<
+  TFn extends AnyFunction = AnyFunction,
+  TOptions extends Partial<RateLimiterOptions<TFn>> = Partial<
+    RateLimiterOptions<TFn>
+  >,
+>(options: TOptions): TOptions {
+  return options
+}
+
 const defaultOptions: Omit<
   Required<RateLimiterOptions<any>>,
   'initialState' | 'onExecute' | 'onReject' | 'key'
@@ -102,6 +114,7 @@ const defaultOptions: Omit<
  * Rate limiting is a simple approach that 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.
+ * This synchronous version is lighter weight and often all you need - upgrade to AsyncRateLimiter when you need promises, retry support, abort capabilities, or advanced error handling.
  *
  * The rate limiter supports two types of windows:
  * - 'fixed': A strict window that resets after the window period. All executions within the window count
@@ -143,7 +156,7 @@ const defaultOptions: Omit<
 export class RateLimiter<TFn extends AnyFunction> {
   readonly store: Store<Readonly<RateLimiterState>> =
     new Store<RateLimiterState>(getDefaultRateLimiterState())
-  key: string
+  key: string | undefined
   options: RateLimiterOptions<TFn>
   #timeoutIds: Set<NodeJS.Timeout> = new Set()
 
@@ -151,7 +164,7 @@ export class RateLimiter<TFn extends AnyFunction> {
     public fn: TFn,
     initialOptions: RateLimiterOptions<TFn>,
   ) {
-    this.key = createKey(initialOptions.key)
+    this.key = initialOptions.key
     this.options = {
       ...defaultOptions,
       ...initialOptions,
@@ -358,6 +371,8 @@ export class RateLimiter<TFn extends AnyFunction> {
 /**
  * Creates a rate-limited function that will execute the provided function up to a maximum number of times within a time window.
  *
+ * This synchronous version is lighter weight and often all you need - upgrade to asyncRateLimit when you need promises, retry support, abort capabilities, or advanced error handling.
+ *
  * Note that rate limiting is a simpler form of execution control compared to throttling or debouncing:
  * - A rate limiter will allow all executions until the limit is reached, then block all subsequent calls until the window resets
  * - A throttler ensures even spacing between executions, which can be better for consistent performance

package/src/throttler.ts

@@ -1,5 +1,5 @@
 import { Store } from '@tanstack/store'
-import { createKey, parseFunctionOrValue } from './utils'
+import { parseFunctionOrValue } from './utils'
 import { emitChange, pacerEventClient } from './event-client'
 import type { AnyFunction } from './types'
 
@@ -89,6 +89,18 @@ export interface ThrottlerOptions<TFn extends AnyFunction> {
   wait: number | ((throttler: Throttler<TFn>) => number)
 }
 
+/**
+ * Utility function for sharing common `ThrottlerOptions` options between different `Throttler` instances.
+ */
+export function throttlerOptions<
+  TFn extends AnyFunction = AnyFunction,
+  TOptions extends Partial<ThrottlerOptions<TFn>> = Partial<
+    ThrottlerOptions<TFn>
+  >,
+>(options: TOptions): TOptions {
+  return options
+}
+
 const defaultOptions: Omit<
   Required<ThrottlerOptions<any>>,
   'initialState' | 'onExecute' | 'key'
@@ -105,6 +117,7 @@ const defaultOptions: Omit<
  * 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.
+ * This synchronous version is lighter weight and often all you need - upgrade to AsyncThrottler when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
  *
  * Supports both leading and trailing edge execution:
  * - Leading: Execute immediately on first call (default: true)
@@ -146,7 +159,7 @@ export class Throttler<TFn extends AnyFunction> {
     public fn: TFn,
     initialOptions: ThrottlerOptions<TFn>,
   ) {
-    this.key = createKey(initialOptions.key)
+    this.key = initialOptions.key
     this.options = {
       ...defaultOptions,
       ...initialOptions,
@@ -321,6 +334,8 @@ export class Throttler<TFn extends AnyFunction> {
 /**
  * Creates a throttled function that limits how often the provided function can execute.
  *
+ * This synchronous version is lighter weight and often all you need - upgrade to asyncThrottle when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
+ *
  * 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.

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 createKey(key?: string): string {
-  if (key) {
-    return key
-  }
-
-  if (
-    typeof crypto !== 'undefined' &&
-    typeof crypto.randomUUID === 'function'
-  ) {
-    return crypto.randomUUID()
-  }
-
-  return ''
-}