@tanstack/pacer 0.1.0

package/src/async-rate-limiter.ts

@@ -0,0 +1,228 @@
+import type { RateLimitRejectionInfo } from './rate-limiter'
+
+/**
+ * Options for configuring an async rate-limited function
+ */
+export interface AsyncRateLimiterOptions {
+  /**
+   * Whether the rate limiter is enabled. When disabled, maybeExecute will not trigger any executions.
+   * Defaults to true.
+   */
+  enabled?: boolean
+  /**
+   * Maximum number of executions allowed within the time window
+   */
+  limit: number
+  /**
+   * Time window in milliseconds within which the limit applies
+   */
+  window: number
+  /**
+   * Optional callback function that is called when an execution is rejected due to rate limiting
+   */
+  onReject?: (info: RateLimitRejectionInfo) => void
+  /**
+   * Optional error handler for when the rate-limited function throws
+   */
+  onError?: (error: unknown) => void
+}
+
+/**
+ * A class that creates an async rate-limited function.
+ *
+ * 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.
+ *
+ * For smoother execution patterns, consider using:
+ * - Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)
+ * - Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const rateLimiter = new AsyncRateLimiter(
+ *   async (id: string) => await api.getData(id),
+ *   { limit: 5, window: 1000 } // 5 calls per second
+ * );
+ *
+ * // Will execute immediately until limit reached, then block
+ * await rateLimiter.maybeExecute('123');
+ * ```
+ */
+export class AsyncRateLimiter<
+  TFn extends (...args: Array<any>) => Promise<any>,
+  TArgs extends Parameters<TFn>,
+> {
+  private executionCount = 0
+  private rejectionCount = 0
+  private executionTimes: Array<number> = []
+  private options: AsyncRateLimiterOptions
+
+  constructor(
+    private fn: TFn,
+    initialOptions: AsyncRateLimiterOptions,
+  ) {
+    this.options = {
+      enabled: true,
+      ...initialOptions,
+    }
+  }
+
+  /**
+   * Updates the rate limiter options
+   * Returns the new options state
+   */
+  setOptions(
+    newOptions: Partial<AsyncRateLimiterOptions>,
+  ): AsyncRateLimiterOptions {
+    this.options = {
+      ...this.options,
+      ...newOptions,
+    }
+    return this.options
+  }
+
+  /**
+   * 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
+  }
+
+  /**
+   * Returns the number of remaining executions allowed in the current window
+   */
+  getRemainingInWindow(): number {
+    this.cleanupOldExecutions()
+    return Math.max(0, this.options.limit - this.executionTimes.length)
+  }
+
+  /**
+   * Attempts to execute the rate-limited function if within the configured limits.
+   * Will reject execution if the number of calls in the current window exceeds the limit.
+   * If execution is allowed, waits for any previous execution to complete before proceeding.
+   *
+   * @example
+   * ```ts
+   * const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
+   *
+   * // First 5 calls will execute
+   * await rateLimiter.maybeExecute('arg1', 'arg2');
+   *
+   * // Additional calls within the window will be rejected
+   * await rateLimiter.maybeExecute('arg1', 'arg2'); // Rejected
+   * ```
+   */
+  async maybeExecute(...args: TArgs): Promise<boolean> {
+    this.cleanupOldExecutions()
+
+    if (this.executionTimes.length < this.options.limit) {
+      await this.executeFunction(...args)
+      return true
+    }
+
+    this.rejectFunction()
+    return false
+  }
+
+  private async executeFunction(...args: TArgs): Promise<void> {
+    if (!this.options.enabled) return
+    const now = Date.now()
+    this.executionCount++
+    this.executionTimes.push(now)
+
+    try {
+      await this.fn(...args)
+    } catch (error) {
+      if (this.options.onError) {
+        try {
+          this.options.onError(error)
+        } catch {
+          // Ignore errors from error handler
+        }
+      }
+      throw error
+    } finally {
+    }
+  }
+
+  private rejectFunction(): void {
+    this.rejectionCount++
+    if (this.options.onReject) {
+      const oldestExecution = Math.min(...this.executionTimes)
+      const msUntilNextWindow =
+        oldestExecution + this.options.window - Date.now()
+
+      this.options.onReject({
+        msUntilNextWindow,
+        currentExecutions: this.executionTimes.length,
+        limit: this.options.limit,
+        rejectionCount: this.rejectionCount,
+      })
+    }
+  }
+
+  private cleanupOldExecutions(): void {
+    const now = Date.now()
+    const windowStart = now - this.options.window
+    this.executionTimes = this.executionTimes.filter(
+      (time) => time > windowStart,
+    )
+  }
+
+  /**
+   * Resets the rate limiter state
+   */
+  reset(): void {
+    this.executionTimes = []
+    this.executionCount = 0
+    this.rejectionCount = 0
+  }
+}
+
+/**
+ * Creates an async rate-limited function that will execute the provided function up to a maximum number of times within a time window.
+ *
+ * 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
+ * - A debouncer collapses multiple calls into one, which is better for handling bursts of events
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * // Rate limit to 5 calls per minute
+ * const rateLimited = asyncRateLimit(makeApiCall, {
+ *   limit: 5,
+ *   window: 60000,
+ *   onReject: ({ msUntilNextWindow }) => {
+ *     console.log(`Rate limit exceeded. Try again in ${msUntilNextWindow}ms`);
+ *   }
+ * });
+ *
+ * // First 5 calls will execute immediately
+ * // Additional calls will be rejected until the minute window resets
+ * await rateLimited();
+ *
+ * // For more even execution, consider using throttle instead:
+ * const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
+ * ```
+ */
+export function asyncRateLimit<
+  TFn extends (...args: Array<any>) => Promise<any>,
+>(fn: TFn, initialOptions: Omit<AsyncRateLimiterOptions, 'enabled'>) {
+  const rateLimiter = new AsyncRateLimiter(fn, initialOptions)
+  return rateLimiter.maybeExecute.bind(rateLimiter)
+}

package/src/async-throttler.ts

@@ -0,0 +1,194 @@
+/**
+ * Options for configuring an async throttled function
+ */
+export interface AsyncThrottlerOptions {
+  /**
+   * Whether the throttler is enabled. When disabled, maybeExecute will not trigger any executions.
+   * Defaults to true.
+   */
+  enabled?: boolean
+  /**
+   * Time window in milliseconds during which the function can only be executed once
+   * Defaults to 0ms
+   */
+  wait: number
+  /**
+   * Optional error handler for when the throttled function throws
+   */
+  onError?: (error: unknown) => void
+}
+
+const defaultOptions: Required<AsyncThrottlerOptions> = {
+  enabled: true,
+  onError: () => {},
+  wait: 0,
+}
+
+/**
+ * A class that creates an async throttled function.
+ *
+ * Throttling limits how often a function can be executed, allowing only one execution within a specified time window.
+ * Unlike debouncing which resets the delay timer on each call, throttling ensures the function executes at a
+ * regular interval regardless of how often it's called.
+ *
+ * This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to
+ * ensure a maximum execution frequency.
+ *
+ * @example
+ * ```ts
+ * const throttler = new AsyncThrottler(async (value: string) => {
+ *   await saveToAPI(value);
+ * }, { wait: 1000 });
+ *
+ * // Will only execute once per second no matter how often called
+ * inputElement.addEventListener('input', () => {
+ *   throttler.maybeExecute(inputElement.value);
+ * });
+ * ```
+ */
+export class AsyncThrottler<
+  TFn extends (...args: Array<any>) => Promise<any>,
+  TArgs extends Parameters<TFn>,
+> {
+  private abortController: AbortController | null = null
+  private executionCount = 0
+  private isExecuting = false
+  private isScheduled = false
+  private lastArgs: TArgs | undefined
+  private nextExecutionTime = 0
+  private options: Required<AsyncThrottlerOptions>
+
+  constructor(
+    private fn: TFn,
+    initialOptions: AsyncThrottlerOptions,
+  ) {
+    this.options = {
+      ...defaultOptions,
+      ...initialOptions,
+    }
+  }
+
+  /**
+   * Updates the throttler options
+   * Returns the new options state
+   */
+  setOptions(
+    newOptions: Partial<AsyncThrottlerOptions>,
+  ): Required<AsyncThrottlerOptions> {
+    this.options = {
+      ...this.options,
+      ...newOptions,
+    }
+    return this.options
+  }
+
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount(): number {
+    return this.executionCount
+  }
+
+  /**
+   * Returns the next execution time
+   */
+  getNextExecutionTime(): number {
+    return this.nextExecutionTime
+  }
+
+  /**
+   * Cancels any pending execution
+   */
+  cancel(): void {
+    if (this.abortController) {
+      this.abortController.abort()
+      this.abortController = null
+    }
+    this.isScheduled = false
+    this.lastArgs = undefined
+  }
+
+  /**
+   * Attempts to execute the throttled function
+   * If a call is already in progress, it may be blocked or queued depending on the `wait` option
+   */
+  async maybeExecute(...args: TArgs): Promise<void> {
+    this.lastArgs = args
+    if (this.isScheduled) return
+    this.isScheduled = true
+
+    this.abortController = new AbortController()
+    const signal = this.abortController.signal
+
+    try {
+      while (this.isExecuting) {
+        await this.delay(this.options.wait, signal)
+      }
+
+      while (Date.now() < this.nextExecutionTime) {
+        await this.delay(this.nextExecutionTime - Date.now(), signal)
+      }
+
+      this.isScheduled = false
+      this.isExecuting = true
+
+      await this.executeFunction(...this.lastArgs)
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') {
+        return // Silent return on cancellation
+      }
+      try {
+        this.options.onError(error)
+      } catch {
+        // Ignore errors from error handler
+      }
+    } finally {
+      this.nextExecutionTime = Date.now() + this.options.wait
+      this.isExecuting = false
+      this.abortController = null
+    }
+  }
+
+  private delay(ms: number, signal: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(resolve, ms)
+      signal.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(timeout)
+          reject(new Error('AbortError'))
+        },
+        { once: true },
+      )
+    })
+  }
+
+  private async executeFunction(...args: TArgs): Promise<void> {
+    if (!this.options.enabled) return
+    this.executionCount++
+    await this.fn(...args)
+  }
+}
+
+/**
+ * Creates an async throttled function that limits how often the function can execute.
+ * The throttled function will execute at most once per wait period, even if called multiple times.
+ * If called while executing, it will wait until execution completes before scheduling the next call.
+ *
+ * @example
+ * ```ts
+ * const throttled = asyncThrottle(async () => {
+ *   await someAsyncOperation();
+ * }, { wait: 1000 });
+ *
+ * // This will execute at most once per second
+ * await throttled();
+ * await throttled(); // Waits 1 second before executing
+ * ```
+ */
+export function asyncThrottle<
+  TFn extends (...args: Array<any>) => Promise<any>,
+>(fn: TFn, initialOptions: Omit<AsyncThrottlerOptions, 'enabled'>) {
+  const asyncThrottler = new AsyncThrottler(fn, initialOptions)
+  return asyncThrottler.maybeExecute.bind(asyncThrottler)
+}

package/src/compare.ts

@@ -0,0 +1,105 @@
+/**
+ * This function returns `a` if `b` is deeply equal.
+ * If not, it will replace any deeply equal children of `b` with those of `a`.
+ * This can be used for structural sharing between JSON values for example.
+ */
+export function replaceEqualDeep<T>(a: unknown, b: T): T
+export function replaceEqualDeep(a: any, b: any): any {
+  if (a === b) {
+    return a
+  }
+
+  const array = isPlainArray(a) && isPlainArray(b)
+
+  if (array || (isPlainObject(a) && isPlainObject(b))) {
+    const aItems = array ? a : Object.keys(a)
+    const aSize = aItems.length
+    const bItems = array ? b : Object.keys(b)
+    const bSize = bItems.length
+    const copy: any = array ? [] : {}
+
+    let equalItems = 0
+
+    for (let i = 0; i < bSize; i++) {
+      const key = array ? i : bItems[i]
+      if (
+        ((!array && aItems.includes(key)) || array) &&
+        a[key] === undefined &&
+        b[key] === undefined
+      ) {
+        copy[key] = undefined
+        equalItems++
+      } else {
+        copy[key] = replaceEqualDeep(a[key], b[key])
+        if (copy[key] === a[key] && a[key] !== undefined) {
+          equalItems++
+        }
+      }
+    }
+
+    return aSize === bSize && equalItems === aSize ? a : copy
+  }
+
+  return b
+}
+
+/**
+ * Shallow compare objects.
+ */
+export function shallowEqualObjects<T extends Record<string, any>>(
+  a: T,
+  b: T | undefined,
+): boolean {
+  if (!b || Object.keys(a).length !== Object.keys(b).length) {
+    return false
+  }
+
+  for (const key in a) {
+    if (a[key] !== b[key]) {
+      return false
+    }
+  }
+
+  return true
+}
+
+export function isPlainArray(value: unknown) {
+  return Array.isArray(value) && value.length === Object.keys(value).length
+}
+
+// Copied from: https://github.com/jonschlinkert/is-plain-object
+// eslint-disable-next-line @typescript-eslint/no-wrapper-object-types
+export function isPlainObject(o: any): o is Object {
+  if (!hasObjectPrototype(o)) {
+    return false
+  }
+
+  // If has no constructor
+  const ctor = o.constructor
+  if (ctor === undefined) {
+    return true
+  }
+
+  // If has modified prototype
+  const prot = ctor.prototype
+  if (!hasObjectPrototype(prot)) {
+    return false
+  }
+
+  // If constructor does not have an Object-specific method
+  if (!prot.hasOwnProperty('isPrototypeOf')) {
+    return false
+  }
+
+  // Handles Objects created by Object.create(<arbitrary prototype>)
+  if (Object.getPrototypeOf(o) !== Object.prototype) {
+    return false
+  }
+
+  // Most likely a plain Object
+  return true
+}
+
+function hasObjectPrototype(o: any): boolean {
+  return Object.prototype.toString.call(o) === '[object Object]'
+}

package/src/debouncer.ts

@@ -0,0 +1,164 @@
+/**
+ * Options for configuring a debounced function
+ */
+export interface DebouncerOptions {
+  /**
+   * Whether the debouncer is enabled. When disabled, maybeExecute will not trigger any executions.
+   * Defaults to true.
+   */
+  enabled?: boolean
+  /**
+   * Whether to execute on the leading edge of the timeout.
+   * Defaults to false.
+   */
+  leading?: boolean
+  /**
+   * Whether to execute on the trailing edge of the timeout.
+   * Defaults to true.
+   */
+  trailing?: boolean
+  /**
+   * Delay in milliseconds before executing the function
+   * Defaults to 0ms
+   */
+  wait: number
+}
+
+const defaultOptions: Required<DebouncerOptions> = {
+  enabled: true,
+  leading: false,
+  trailing: true,
+  wait: 0,
+}
+
+/**
+ * A class that creates a debounced function.
+ *
+ * Debouncing ensures that a function is only executed after a certain amount of time has passed
+ * since its last invocation. This is useful for handling frequent events like window resizing,
+ * scroll events, or input changes where you want to limit the rate of execution.
+ *
+ * The debounced function can be configured to execute either at the start of the delay period
+ * (leading edge) or at the end (trailing edge, default). Each new call during the wait period
+ * will reset the timer.
+ *
+ * @example
+ * ```ts
+ * const debouncer = new Debouncer((value: string) => {
+ *   saveToDatabase(value);
+ * }, { wait: 500 });
+ *
+ * // Will only save after 500ms of no new input
+ * inputElement.addEventListener('input', () => {
+ *   debouncer.maybeExecute(inputElement.value);
+ * });
+ * ```
+ */
+export class Debouncer<
+  TFn extends (...args: Array<any>) => any,
+  TArgs extends Parameters<TFn>,
+> {
+  private canLeadingExecute = true
+  private executionCount = 0
+  private options: Required<DebouncerOptions>
+  private timeoutId: NodeJS.Timeout | undefined
+
+  constructor(
+    private fn: TFn,
+    initialOptions: DebouncerOptions,
+  ) {
+    this.options = {
+      ...defaultOptions,
+      ...initialOptions,
+    }
+  }
+
+  /**
+   * Updates the debouncer options
+   * Returns the new options state
+   */
+  setOptions(
+    newOptions: Partial<DebouncerOptions>,
+  ): Required<DebouncerOptions> {
+    this.options = {
+      ...this.options,
+      ...newOptions,
+    }
+    return this.options
+  }
+
+  /**
+   * Returns the number of times the function has been executed
+   */
+  getExecutionCount(): number {
+    return this.executionCount
+  }
+
+  /**
+   * Attempts to execute the debounced function
+   * If a call is already in progress, it will be queued
+   */
+  maybeExecute(...args: TArgs): void {
+    // Handle leading execution
+    if (this.options.leading && this.canLeadingExecute) {
+      this.executeFunction(...args)
+      this.canLeadingExecute = false
+    }
+
+    // Clear any existing timeout
+    if (this.timeoutId) clearTimeout(this.timeoutId)
+
+    // Set new timeout that will reset canLeadingExecute
+    this.timeoutId = setTimeout(() => {
+      this.canLeadingExecute = true
+      // Execute trailing only if enabled
+      if (this.options.trailing) {
+        this.executeFunction(...args)
+      }
+    }, this.options.wait)
+  }
+
+  private executeFunction(...args: TArgs): void {
+    if (!this.options.enabled) return
+    this.executionCount++
+    this.fn(...args)
+  }
+
+  /**
+   * Cancels any pending execution
+   */
+  cancel(): void {
+    if (this.timeoutId) {
+      clearTimeout(this.timeoutId)
+      this.canLeadingExecute = true
+    }
+  }
+}
+
+/**
+ * Creates a debounced function that delays invoking the provided function until after a specified wait time.
+ * Multiple calls during the wait period will cancel previous pending invocations and reset the timer.
+ *
+ * This the the simple function wrapper implementation pulled from the Debouncer class. If you need
+ * more control over the debouncing behavior, use the Debouncer class directly.
+ *
+ * If leading option is true, the function will execute immediately on the first call, then wait the delay
+ * before allowing another execution.
+ *
+ * @example
+ * ```ts
+ * const debounced = debounce(() => {
+ *   saveChanges();
+ * }, { wait: 1000 });
+ *
+ * // Called repeatedly but executes at most once per second
+ * inputElement.addEventListener('input', debounced);
+ * ```
+ */
+export function debounce<TFn extends (...args: Array<any>) => any>(
+  fn: TFn,
+  initialOptions: Omit<DebouncerOptions, 'enabled'>,
+) {
+  const debouncer = new Debouncer(fn, initialOptions)
+  return debouncer.maybeExecute.bind(debouncer)
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './async-debouncer'
+export * from './async-queuer'
+export * from './async-rate-limiter'
+export * from './async-throttler'
+export * from './compare'
+export * from './debouncer'
+export * from './queuer'
+export * from './rate-limiter'
+export * from './throttler'