@tanstack/pacer-lite 0.2.1 → 0.3.0

package/src/lite-queuer.ts

@@ -1,434 +0,0 @@
-/**
- * Position type for addItem and getNextItem operations.
- *
- * - 'front': Operate on the front of the queue (FIFO for getNextItem)
- * - 'back': Operate on the back of the queue (LIFO for getNextItem)
- */
-export type QueuePosition = 'front' | 'back'
-
-/**
- * Options for configuring a lite queuer instance
- */
-export interface LiteQueuerOptions<TValue> {
-  /**
-   * Default position to add items to the queue
-   * @default 'back'
-   */
-  addItemsTo?: QueuePosition
-  /**
-   * Default position to get items from during processing
-   * @default 'front'
-   */
-  getItemsFrom?: QueuePosition
-  /**
-   * Function to determine priority of items in the queue
-   * Higher priority items will be processed first
-   * Return undefined for items that should use positional ordering
-   */
-  getPriority?: (item: TValue) => number | undefined
-  /**
-   * Initial items to populate the queue with
-   */
-  initialItems?: Array<TValue>
-  /**
-   * Maximum number of items allowed in the queue
-   */
-  maxSize?: number
-  /**
-   * Whether the queuer should start processing items immediately
-   * @default true
-   */
-  started?: boolean
-  /**
-   * Time in milliseconds to wait between processing items
-   * @default 0
-   */
-  wait?: number
-}
-
-/**
- * A lightweight class that creates a queue for processing items.
- *
- * This is an alternative to the Queuer in the core @tanstack/pacer package, but is more
- * suitable for libraries and npm packages that need minimal overhead. Unlike the core Queuer,
- * this version does not use TanStack Store for state management, has no devtools integration,
- * no callbacks, and provides only essential queueing functionality.
- *
- * The queuer supports FIFO (First In First Out), LIFO (Last In First Out), and priority-based
- * processing of items. Items can be processed automatically with configurable wait times
- * between executions, or processed manually using the execute methods.
- *
- * Features included:
- * - Automatic or manual processing of items
- * - FIFO, LIFO, and priority-based ordering
- * - Queue size limits with item rejection
- * - Configurable wait times between processing
- * - Batch processing capabilities
- * - Start/stop processing control
- * - Callback support for monitoring execution, rejection, and state change events
- *
- * Features NOT included (compared to core Queuer):
- * - No TanStack Store state management
- * - No devtools integration
- * - No item expiration functionality (no onExpire callback)
- * - No dynamic options updates (setOptions)
- * - No detailed state tracking (execution counts, etc.)
- *
- * Queue behavior:
- * - Default: FIFO (add to back, process from front)
- * - LIFO: Configure addItemsTo: 'back', getItemsFrom: 'back'
- * - Priority: Provide getPriority function; higher values processed first
- *
- * @example
- * ```ts
- * // Basic FIFO queue
- * const queue = new LiteQueuer((item: string) => {
- *   console.log('Processing:', item);
- * }, { wait: 100 });
- *
- * queue.addItem('task1');
- * queue.addItem('task2');
- * // Processes: task1, then task2 after 100ms delay
- * ```
- *
- * @example
- * ```ts
- * // Priority queue
- * const priorityQueue = new LiteQueuer((item: Task) => {
- *   processTask(item);
- * }, {
- *   getPriority: task => task.priority,
- *   wait: 500
- * });
- *
- * priorityQueue.addItem({ name: 'low', priority: 1 });
- * priorityQueue.addItem({ name: 'high', priority: 10 });
- * // Processes high priority task first
- * ```
- */
-export class LiteQueuer<TValue> {
-  private items: Array<TValue> = []
-  private timeoutId: NodeJS.Timeout | null = null
-  private isRunning = true
-  private pendingTick = false
-
-  constructor(
-    public fn: (item: TValue) => void,
-    public options: LiteQueuerOptions<TValue> = {},
-  ) {
-    // Set defaults
-    this.options.addItemsTo = this.options.addItemsTo ?? 'back'
-    this.options.getItemsFrom = this.options.getItemsFrom ?? 'front'
-    this.options.maxSize = this.options.maxSize ?? Infinity
-    this.options.started = this.options.started ?? true
-    this.options.wait = this.options.wait ?? 0
-
-    this.isRunning = this.options.started
-
-    // Add initial items if provided
-    if (this.options.initialItems) {
-      for (const item of this.options.initialItems) {
-        this.addItem(item, this.options.addItemsTo, false)
-      }
-    }
-
-    // Start processing if enabled and has items
-    if (this.isRunning && this.items.length > 0) {
-      this.tick()
-    }
-  }
-
-  /**
-   * Number of items currently in the queue
-   */
-  get size(): number {
-    return this.items.length
-  }
-
-  /**
-   * Whether the queue is empty
-   */
-  get isEmpty(): boolean {
-    return this.items.length === 0
-  }
-
-  /**
-   * Whether the queue is currently running (auto-processing items)
-   */
-  get isQueueRunning(): boolean {
-    return this.isRunning
-  }
-
-  /**
-   * Adds an item to the queue. If the queue is full, the item is rejected.
-   * Items can be inserted at the front or back, and priority ordering is applied if getPriority is configured.
-   *
-   * Returns true if the item was added, false if the queue is full.
-   *
-   * @example
-   * ```ts
-   * queue.addItem('task1');           // Add to default position (back)
-   * queue.addItem('task2', 'front');  // Add to front
-   * ```
-   */
-  addItem = (
-    item: TValue,
-    position: QueuePosition = this.options.addItemsTo!,
-    startProcessing: boolean = true,
-  ): boolean => {
-    // Check size limit
-    if (this.items.length >= this.options.maxSize!) {
-      return false
-    }
-
-    // Handle priority insertion
-    if (this.options.getPriority) {
-      const priority = this.options.getPriority(item)
-      if (priority !== undefined) {
-        // Find insertion point for priority
-        const insertIndex = this.items.findIndex((existing) => {
-          const existingPriority = this.options.getPriority!(existing)
-          // Treat undefined priority as negative infinity for comparison
-          const effectivePriority = existingPriority ?? -Infinity
-          return effectivePriority < priority
-        })
-
-        if (insertIndex === -1) {
-          this.items.push(item)
-        } else {
-          this.items.splice(insertIndex, 0, item)
-        }
-      } else {
-        // No priority, use position
-        this.insertAtPosition(item, position)
-      }
-    } else {
-      // No priority function, use position
-      this.insertAtPosition(item, position)
-    }
-
-    // Start processing if running and not already processing
-    if (startProcessing && this.isRunning && !this.pendingTick) {
-      this.tick()
-    }
-
-    return true
-  }
-
-  private insertAtPosition = (item: TValue, position: QueuePosition): void => {
-    if (position === 'front') {
-      this.items.unshift(item)
-    } else {
-      this.items.push(item)
-    }
-  }
-
-  /**
-   * Removes and returns the next item from the queue without executing the function.
-   * Use for manual queue management. Normally, use execute() to process items.
-   *
-   * @example
-   * ```ts
-   * const nextItem = queue.getNextItem();        // Get from default position (front)
-   * const lastItem = queue.getNextItem('back');  // Get from back (LIFO)
-   * ```
-   */
-  getNextItem = (
-    position: QueuePosition = this.options.getItemsFrom!,
-  ): TValue | undefined => {
-    if (this.items.length === 0) {
-      return undefined
-    }
-
-    let item: TValue | undefined
-
-    // When priority function is provided, always get from front (highest priority)
-    if (this.options.getPriority || position === 'front') {
-      item = this.items.shift()
-    } else {
-      item = this.items.pop()
-    }
-
-    return item
-  }
-
-  /**
-   * Removes and returns the next item from the queue and processes it using the provided function.
-   *
-   * @example
-   * ```ts
-   * queue.execute();        // Execute from default position
-   * queue.execute('back');  // Execute from back (LIFO)
-   * ```
-   */
-  execute = (position?: QueuePosition): TValue | undefined => {
-    const item = this.getNextItem(position)
-    if (item !== undefined) {
-      this.fn(item)
-    }
-    return item
-  }
-
-  /**
-   * Internal method that processes items in the queue with wait intervals
-   */
-  private tick = (): void => {
-    if (!this.isRunning) {
-      this.pendingTick = false
-      return
-    }
-
-    this.pendingTick = true
-
-    // Process items while queue is not empty
-    while (this.items.length > 0) {
-      const item = this.execute(this.options.getItemsFrom)
-      if (item === undefined) {
-        break
-      }
-
-      const wait = this.options.wait!
-      if (wait > 0) {
-        // Schedule next processing after wait time
-        this.timeoutId = setTimeout(() => this.tick(), wait)
-        return
-      }
-
-      // No wait time, continue processing immediately
-    }
-
-    this.pendingTick = false
-  }
-
-  /**
-   * Starts processing items in the queue. If already running, does nothing.
-   */
-  start = (): void => {
-    this.isRunning = true
-    if (!this.pendingTick && this.items.length > 0) {
-      this.tick()
-    }
-  }
-
-  /**
-   * Stops processing items in the queue. Does not clear the queue.
-   */
-  stop = (): void => {
-    this.clearTimeout()
-    this.isRunning = false
-    this.pendingTick = false
-  }
-
-  /**
-   * Clears any pending timeout
-   */
-  private clearTimeout = (): void => {
-    if (this.timeoutId) {
-      clearTimeout(this.timeoutId)
-      this.timeoutId = null
-    }
-  }
-
-  /**
-   * Returns the next item in the queue without removing it.
-   *
-   * @example
-   * ```ts
-   * const next = queue.peekNextItem();        // Peek at front
-   * const last = queue.peekNextItem('back');  // Peek at back
-   * ```
-   */
-  peekNextItem = (position: QueuePosition = 'front'): TValue | undefined => {
-    if (this.items.length === 0) {
-      return undefined
-    }
-
-    if (this.options.getPriority || position === 'front') {
-      return this.items[0]
-    } else {
-      return this.items[this.items.length - 1]
-    }
-  }
-
-  /**
-   * Returns a copy of all items in the queue.
-   */
-  peekAllItems = (): Array<TValue> => {
-    return [...this.items]
-  }
-
-  /**
-   * Processes a specified number of items immediately with no wait time.
-   * If no numberOfItems is provided, all items will be processed.
-   *
-   * @example
-   * ```ts
-   * queue.flush();     // Process all items immediately
-   * queue.flush(3);    // Process next 3 items immediately
-   * ```
-   */
-  flush = (
-    numberOfItems: number = this.items.length,
-    position?: QueuePosition,
-  ): void => {
-    this.clearTimeout() // Clear any pending timeout
-    for (let i = 0; i < numberOfItems && this.items.length > 0; i++) {
-      this.execute(position)
-    }
-    // Restart normal processing if still running and has items
-    if (this.isRunning && this.items.length > 0 && !this.pendingTick) {
-      this.tick()
-    }
-  }
-
-  /**
-   * Processes all items in the queue as a batch using the provided function.
-   * The queue is cleared after processing.
-   *
-   * @example
-   * ```ts
-   * queue.flushAsBatch((items) => {
-   *   console.log('Processing batch:', items);
-   *   // Process all items together
-   * });
-   * ```
-   */
-  flushAsBatch = (batchFunction: (items: Array<TValue>) => void): void => {
-    const items = this.peekAllItems()
-    this.clear()
-    batchFunction(items)
-  }
-
-  /**
-   * Removes all items from the queue. Does not affect items being processed.
-   */
-  clear = (): void => {
-    this.items = []
-  }
-}
-
-/**
- * Creates a lightweight queue that processes items using the provided function.
- *
- * This is an alternative to the queue 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 queuer with no external dependencies, devtools integration, or reactive state.
- *
- * @example
- * ```ts
- * const processItem = liteQueue((item: string) => {
- *   console.log('Processing:', item);
- * }, { wait: 1000 });
- *
- * processItem('task1');
- * processItem('task2');
- * // Processes each item with 1 second delay between them
- * ```
- */
-export function liteQueue<TValue>(
-  fn: (item: TValue) => void,
-  options: LiteQueuerOptions<TValue> = {},
-): (item: TValue) => boolean {
-  const queuer = new LiteQueuer(fn, options)
-  return (item: TValue) => queuer.addItem(item)
-}

package/src/lite-rate-limiter.ts

@@ -1,246 +0,0 @@
-import type { AnyFunction } from '@tanstack/pacer/types'
-
-/**
- * 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'
-}
-
-/**
- * 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');
- * }
- * ```
- */
-export class LiteRateLimiter<TFn extends AnyFunction> {
-  private executionTimes: Array<number> = []
-  private timeoutIds: Set<NodeJS.Timeout> = new Set()
-
-  constructor(
-    public fn: TFn,
-    public options: LiteRateLimiterOptions<TFn>,
-  ) {
-    // Default windowType to 'fixed' if not specified
-    if (this.options.windowType === undefined) {
-      this.options.windowType = 'fixed'
-    }
-  }
-
-  /**
-   * 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 => {
-    this.cleanupOldExecutions()
-
-    const relevantExecutionTimes = this.getExecutionTimesInWindow()
-
-    if (relevantExecutionTimes.length < this.options.limit) {
-      this.execute(...args)
-      return true
-    }
-
-    this.options.onReject?.(this)
-    return false
-  }
-
-  private execute = (...args: Parameters<TFn>): void => {
-    const now = Date.now()
-    this.fn(...args)
-    this.options.onExecute?.(args, this)
-    this.executionTimes.push(now)
-    this.setCleanupTimeout(now)
-  }
-
-  private getExecutionTimesInWindow = (): Array<number> => {
-    if (this.options.windowType === 'sliding') {
-      // For sliding window, return all executions within the current window
-      return this.executionTimes.filter(
-        (time) => time > Date.now() - this.options.window,
-      )
-    } else {
-      // For fixed window, return all executions in the current window
-      if (this.executionTimes.length === 0) {
-        return []
-      }
-      const oldestExecution = Math.min(...this.executionTimes)
-      const windowStart = oldestExecution
-      const windowEnd = windowStart + this.options.window
-      const now = Date.now()
-
-      // If the window has expired, return empty array
-      if (now > windowEnd) {
-        return []
-      }
-
-      // Otherwise, return all executions in the current window
-      return this.executionTimes.filter(
-        (time) => time >= windowStart && time <= windowEnd,
-      )
-    }
-  }
-
-  private setCleanupTimeout = (executionTime: number): void => {
-    if (
-      this.options.windowType === 'sliding' ||
-      this.timeoutIds.size === 0 // new fixed window
-    ) {
-      const now = Date.now()
-      const timeUntilExpiration = executionTime - now + this.options.window + 1
-      const timeoutId = setTimeout(() => {
-        this.cleanupOldExecutions()
-        this.clearTimeout(timeoutId)
-      }, timeUntilExpiration)
-      this.timeoutIds.add(timeoutId)
-    }
-  }
-
-  private clearTimeout = (timeoutId: NodeJS.Timeout): void => {
-    clearTimeout(timeoutId)
-    this.timeoutIds.delete(timeoutId)
-  }
-
-  private clearTimeouts = (): void => {
-    this.timeoutIds.forEach((timeoutId) => clearTimeout(timeoutId))
-    this.timeoutIds.clear()
-  }
-
-  private cleanupOldExecutions = (): void => {
-    this.executionTimes = this.getExecutionTimesInWindow()
-  }
-
-  /**
-   * Returns the number of remaining executions allowed in the current window.
-   */
-  getRemainingInWindow = (): number => {
-    const relevantExecutionTimes = this.getExecutionTimesInWindow()
-    return Math.max(0, this.options.limit - relevantExecutionTimes.length)
-  }
-
-  /**
-   * Returns the number of milliseconds until the next execution will be possible.
-   * Returns 0 if executions are currently allowed.
-   */
-  getMsUntilNextWindow = (): number => {
-    if (this.getRemainingInWindow() > 0) {
-      return 0
-    }
-    const oldestExecution = this.executionTimes[0] ?? Infinity
-    return oldestExecution + this.options.window - Date.now()
-  }
-
-  /**
-   * Resets the rate limiter state, clearing all execution history.
-   */
-  reset = (): void => {
-    this.executionTimes = []
-    this.clearTimeouts()
-  }
-}
-
-/**
- * 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'
- * });
- * ```
- */
-export function liteRateLimit<TFn extends AnyFunction>(
-  fn: TFn,
-  options: LiteRateLimiterOptions<TFn>,
-): (...args: Parameters<TFn>) => boolean {
-  const rateLimiter = new LiteRateLimiter(fn, options)
-  return rateLimiter.maybeExecute
-}