@tanstack/solid-pacer 0.2.0

package/src/rate-limiter/createRateLimitedSignal.ts

@@ -0,0 +1,74 @@
+import { createSignal } from 'solid-js'
+import { createRateLimiter } from './createRateLimiter'
+import type { SolidRateLimiter } from './createRateLimiter'
+import type { Accessor, Setter } from 'solid-js'
+import type { RateLimiterOptions } from '@tanstack/pacer/rate-limiter'
+
+/**
+ * A Solid hook that creates a rate-limited state value that enforces a hard limit on state updates within a time window.
+ * This hook combines Solid's createSignal with rate limiting functionality to provide controlled state updates.
+ *
+ * Rate limiting is a simple "hard limit" approach - it allows all updates until the limit is reached, then blocks
+ * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out
+ * or intelligently collapse updates. This can lead to bursts of rapid updates followed by periods of no updates.
+ *
+ * For smoother update patterns, consider:
+ * - createThrottledSignal: When you want consistent spacing between updates (e.g. UI changes)
+ * - createDebouncedSignal: When you want to collapse rapid updates into a single update (e.g. search input)
+ *
+ * Rate limiting should primarily be used when you need to enforce strict limits, like API rate limits.
+ *
+ * The hook returns a tuple containing:
+ * - The rate-limited state value accessor
+ * - A rate-limited setter function that respects the configured limits
+ * - The rateLimiter instance for additional control
+ *
+ * For more direct control over rate limiting without state management,
+ * consider using the lower-level createRateLimiter hook instead.
+ *
+ * @example
+ * ```tsx
+ * // Basic rate limiting - update state at most 5 times per minute
+ * const [value, setValue, rateLimiter] = createRateLimitedSignal(0, {
+ *   limit: 5,
+ *   window: 60000
+ * });
+ *
+ * // With rejection callback
+ * const [value, setValue] = createRateLimitedSignal(0, {
+ *   limit: 3,
+ *   window: 5000,
+ *   onReject: (rateLimiter) => {
+ *     alert(`Rate limit reached. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
+ *   }
+ * });
+ *
+ * // Access rateLimiter state via signals
+ * const handleSubmit = () => {
+ *   const remaining = rateLimiter.remainingInWindow();
+ *   if (remaining > 0) {
+ *     setValue(newValue);
+ *   } else {
+ *     showRateLimitWarning();
+ *   }
+ * };
+ * ```
+ */
+export function createRateLimitedSignal<TValue>(
+  value: TValue,
+  initialOptions: RateLimiterOptions<Setter<TValue>, [Accessor<TValue>]>,
+): [
+  Accessor<TValue>,
+  Setter<TValue>,
+  SolidRateLimiter<Setter<TValue>, [Accessor<TValue>]>,
+] {
+  const [rateLimitedValue, setRateLimitedValue] = createSignal<TValue>(value)
+
+  const rateLimiter = createRateLimiter(setRateLimitedValue, initialOptions)
+
+  return [
+    rateLimitedValue,
+    rateLimiter.maybeExecute.bind(rateLimiter) as Setter<TValue>,
+    rateLimiter,
+  ]
+}

package/src/rate-limiter/createRateLimitedValue.ts

@@ -0,0 +1,66 @@
+import { createEffect } from 'solid-js'
+import { createRateLimitedSignal } from './createRateLimitedSignal'
+import type { SolidRateLimiter } from './createRateLimiter'
+import type { Accessor, Setter } from 'solid-js'
+import type { RateLimiterOptions } from '@tanstack/pacer/rate-limiter'
+
+/**
+ * A high-level Solid hook that creates a rate-limited version of a value that updates at most a certain number of times within a time window.
+ * This hook uses Solid's createSignal internally to manage the rate-limited state.
+ *
+ * Rate limiting is a simple "hard limit" approach - it allows all updates until the limit is reached, then blocks
+ * subsequent updates until the window resets. Unlike throttling or debouncing, it does not attempt to space out
+ * or intelligently collapse updates. This can lead to bursts of rapid updates followed by periods of no updates.
+ *
+ * For smoother update patterns, consider:
+ * - createThrottledValue: When you want consistent spacing between updates (e.g. UI changes)
+ * - createDebouncedValue: When you want to collapse rapid updates into a single update (e.g. search input)
+ *
+ * Rate limiting should primarily be used when you need to enforce strict limits, like API rate limits.
+ *
+ * The hook returns both the rate-limited value and the underlying rateLimiter instance for additional control.
+ *
+ * For more direct control over rate limiting behavior without Solid state management,
+ * consider using the lower-level createRateLimiter hook instead.
+ *
+ * @example
+ * ```tsx
+ * // Basic rate limiting - update at most 5 times per minute
+ * const [rateLimitedValue] = createRateLimitedValue(rawValue, {
+ *   limit: 5,
+ *   window: 60000
+ * });
+ *
+ * // With rejection callback
+ * const [rateLimitedValue, rateLimiter] = createRateLimitedValue(rawValue, {
+ *   limit: 3,
+ *   window: 5000,
+ *   onReject: (rateLimiter) => {
+ *     console.log(`Update rejected. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
+ *   }
+ * });
+ *
+ * // Optionally access rateLimiter state via signals
+ * const handleSubmit = () => {
+ *   const remaining = rateLimiter.remainingInWindow();
+ *   if (remaining > 0) {
+ *     console.log(`${remaining} updates remaining in this window`);
+ *   } else {
+ *     console.log('Rate limit reached for this window');
+ *   }
+ * };
+ * ```
+ */
+export function createRateLimitedValue<TValue>(
+  value: Accessor<TValue>,
+  initialOptions: RateLimiterOptions<Setter<TValue>, [Accessor<TValue>]>,
+): [Accessor<TValue>, SolidRateLimiter<Setter<TValue>, [Accessor<TValue>]>] {
+  const [rateLimitedValue, setRateLimitedValue, rateLimiter] =
+    createRateLimitedSignal(value(), initialOptions)
+
+  createEffect(() => {
+    setRateLimitedValue(value() as any)
+  })
+
+  return [rateLimitedValue, rateLimiter]
+}

package/src/rate-limiter/createRateLimiter.ts

@@ -0,0 +1,115 @@
+import { RateLimiter } from '@tanstack/pacer/rate-limiter'
+import { createSignal } from 'solid-js'
+import { bindInstanceMethods } from '@tanstack/pacer/utils'
+import type { Accessor } from 'solid-js'
+import type { AnyFunction } from '@tanstack/pacer/types'
+import type { RateLimiterOptions } from '@tanstack/pacer/rate-limiter'
+
+export interface SolidRateLimiter<
+  TFn extends AnyFunction,
+  TArgs extends Parameters<TFn>,
+> extends Omit<
+    RateLimiter<TFn, TArgs>,
+    | 'getExecutionCount'
+    | 'getMsUntilNextWindow'
+    | 'getRejectionCount'
+    | 'getRemainingInWindow'
+  > {
+  executionCount: Accessor<number>
+  msUntilNextWindow: Accessor<number>
+  rejectionCount: Accessor<number>
+  remainingInWindow: Accessor<number>
+}
+
+/**
+ * A low-level Solid hook that creates a `RateLimiter` instance to enforce rate limits on function execution.
+ *
+ * This hook is designed to be flexible and state-management agnostic - it simply returns a rate limiter instance that
+ * you can integrate with any state management solution (createSignal, etc).
+ *
+ * Rate limiting is a simple "hard limit" approach that allows executions until a maximum count is reached within
+ * a time window, then blocks all subsequent calls until the window resets. Unlike throttling or debouncing,
+ * it does not attempt to space out or collapse executions intelligently.
+ *
+ * For smoother execution patterns:
+ * - Use throttling when you want consistent spacing between executions (e.g. UI updates)
+ * - Use debouncing when you want to collapse rapid-fire events (e.g. search input)
+ * - Use rate limiting only when you need to enforce hard limits (e.g. API rate limits)
+ *
+ * @example
+ * ```tsx
+ * // Basic rate limiting - max 5 calls per minute
+ * const rateLimiter = createRateLimiter(apiCall, {
+ *   limit: 5,
+ *   window: 60000,
+ * });
+ *
+ * // Monitor rate limit status
+ * const handleClick = () => {
+ *   if (rateLimiter.remainingInWindow() > 0) {
+ *     rateLimiter.maybeExecute(data);
+ *   } else {
+ *     showRateLimitWarning();
+ *   }
+ * };
+ *
+ * // Access rate limiter state via signals
+ * console.log('Executions:', rateLimiter.executionCount());
+ * console.log('Rejections:', rateLimiter.rejectionCount());
+ * console.log('Remaining:', rateLimiter.remainingInWindow());
+ * console.log('Next window in:', rateLimiter.msUntilNextWindow());
+ * ```
+ */
+export function createRateLimiter<
+  TFn extends AnyFunction,
+  TArgs extends Parameters<TFn>,
+>(
+  fn: TFn,
+  initialOptions: RateLimiterOptions<TFn, TArgs>,
+): SolidRateLimiter<TFn, TArgs> {
+  const rateLimiter = new RateLimiter<TFn, TArgs>(fn, initialOptions)
+
+  const [executionCount, setExecutionCount] = createSignal(
+    rateLimiter.getExecutionCount(),
+  )
+  const [rejectionCount, setRejectionCount] = createSignal(
+    rateLimiter.getRejectionCount(),
+  )
+  const [remainingInWindow, setRemainingInWindow] = createSignal(
+    rateLimiter.getRemainingInWindow(),
+  )
+  const [msUntilNextWindow, setMsUntilNextWindow] = createSignal(
+    rateLimiter.getMsUntilNextWindow(),
+  )
+
+  function setOptions(newOptions: Partial<RateLimiterOptions<TFn, TArgs>>) {
+    rateLimiter.setOptions({
+      ...newOptions,
+      onExecute: (rateLimiter) => {
+        setExecutionCount(rateLimiter.getExecutionCount())
+        setRemainingInWindow(rateLimiter.getRemainingInWindow())
+        setMsUntilNextWindow(rateLimiter.getMsUntilNextWindow())
+        const onExecute = newOptions.onExecute ?? initialOptions.onExecute
+        onExecute?.(rateLimiter)
+      },
+      onReject: (rateLimiter) => {
+        setRejectionCount(rateLimiter.getRejectionCount())
+        setRemainingInWindow(rateLimiter.getRemainingInWindow())
+        setMsUntilNextWindow(rateLimiter.getMsUntilNextWindow())
+        const onReject = newOptions.onReject ?? initialOptions.onReject
+        onReject?.(rateLimiter)
+      },
+    })
+  }
+
+  setOptions(initialOptions)
+
+  return {
+    ...bindInstanceMethods(rateLimiter),
+    executionCount,
+    rejectionCount,
+    remainingInWindow,
+    msUntilNextWindow,
+    setOptions,
+  }
+}

package/src/rate-limiter/index.ts

@@ -0,0 +1,5 @@
+export * from '@tanstack/pacer/rate-limiter'
+
+export * from './createRateLimiter'
+export * from './createRateLimitedSignal'
+export * from './createRateLimitedValue'

package/src/throttler/createThrottledSignal.ts

@@ -0,0 +1,52 @@
+import { createSignal } from 'solid-js'
+import { createThrottler } from './createThrottler'
+import type { SolidThrottler } from './createThrottler'
+import type { Accessor, Setter } from 'solid-js'
+import type { ThrottlerOptions } from '@tanstack/pacer/throttler'
+
+/**
+ * A Solid hook that creates a throttled state value that updates at most once within a specified time window.
+ * This hook combines Solid's createSignal with throttling functionality to provide controlled state updates.
+ *
+ * Throttling ensures state updates occur at a controlled rate regardless of how frequently the setter is called.
+ * This is useful for rate-limiting expensive re-renders or operations that depend on rapidly changing state.
+ *
+ * The hook returns a tuple containing:
+ * - The throttled state value accessor
+ * - A throttled setter function that respects the configured wait time
+ * - The throttler instance for additional control
+ *
+ * For more direct control over throttling without state management,
+ * consider using the lower-level createThrottler hook instead.
+ *
+ * @example
+ * ```tsx
+ * // Basic throttling - update state at most once per second
+ * const [value, setValue, throttler] = createThrottledSignal(0, { wait: 1000 });
+ *
+ * // With custom leading/trailing behavior
+ * const [value, setValue] = createThrottledSignal(0, {
+ *   wait: 1000,
+ *   leading: true,   // Update immediately on first change
+ *   trailing: false  // Skip trailing edge updates
+ * });
+ *
+ * // Access throttler state via signals
+ * console.log('Executions:', throttler.executionCount());
+ * console.log('Is pending:', throttler.isPending());
+ * console.log('Last execution:', throttler.lastExecutionTime());
+ * console.log('Next execution:', throttler.nextExecutionTime());
+ * ```
+ */
+export function createThrottledSignal<TValue>(
+  value: TValue,
+  initialOptions: ThrottlerOptions<Setter<TValue>, [Accessor<TValue>]>,
+): [
+  Accessor<TValue>,
+  Setter<TValue>,
+  SolidThrottler<Setter<TValue>, [Accessor<TValue>]>,
+] {
+  const [throttledValue, setThrottledValue] = createSignal<TValue>(value)
+  const throttler = createThrottler(setThrottledValue, initialOptions)
+  return [throttledValue, throttler.maybeExecute as Setter<TValue>, throttler]
+}

package/src/throttler/createThrottledValue.ts

@@ -0,0 +1,56 @@
+import { createEffect, onCleanup } from 'solid-js'
+import { createThrottledSignal } from './createThrottledSignal'
+import type { SolidThrottler } from './createThrottler'
+import type { Accessor, Setter } from 'solid-js'
+import type { ThrottlerOptions } from '@tanstack/pacer/throttler'
+
+/**
+ * A high-level Solid hook that creates a throttled version of a value that updates at most once within a specified time window.
+ * This hook uses Solid's createSignal internally to manage the throttled state.
+ *
+ * Throttling ensures the value updates occur at a controlled rate regardless of how frequently the input value changes.
+ * This is useful for rate-limiting expensive re-renders or API calls that depend on rapidly changing values.
+ *
+ * The hook returns both the throttled value and the underlying throttler instance for additional control.
+ * The throttled value will update according to the leading/trailing edge behavior specified in the options.
+ *
+ * For more direct control over throttling behavior without Solid state management,
+ * consider using the lower-level createThrottler hook instead.
+ *
+ * @example
+ * ```tsx
+ * // Basic throttling - update at most once per second
+ * const [throttledValue] = createThrottledValue(rawValue, { wait: 1000 });
+ *
+ * // With custom leading/trailing behavior
+ * const [throttledValue, throttler] = createThrottledValue(rawValue, {
+ *   wait: 1000,
+ *   leading: true,   // Update immediately on first change
+ *   trailing: false  // Skip trailing edge updates
+ * });
+ *
+ * // Access throttler state via signals
+ * console.log('Executions:', throttler.executionCount());
+ * console.log('Is pending:', throttler.isPending());
+ * console.log('Last execution:', throttler.lastExecutionTime());
+ * console.log('Next execution:', throttler.nextExecutionTime());
+ * ```
+ */
+export function createThrottledValue<TValue>(
+  value: Accessor<TValue>,
+  initialOptions: ThrottlerOptions<Setter<TValue>, [Accessor<TValue>]>,
+): [Accessor<TValue>, SolidThrottler<Setter<TValue>, [Accessor<TValue>]>] {
+  const [throttledValue, setThrottledValue, throttler] = createThrottledSignal(
+    value(),
+    initialOptions,
+  )
+
+  createEffect(() => {
+    setThrottledValue(value() as any)
+    onCleanup(() => {
+      throttler.cancel()
+    })
+  })
+
+  return [throttledValue, throttler]
+}

package/src/throttler/createThrottler.ts

@@ -0,0 +1,106 @@
+import { Throttler } from '@tanstack/pacer/throttler'
+import { createSignal } from 'solid-js'
+import { bindInstanceMethods } from '@tanstack/pacer/utils'
+import type { Accessor } from 'solid-js'
+import type { AnyFunction } from '@tanstack/pacer/types'
+import type { ThrottlerOptions } from '@tanstack/pacer/throttler'
+
+/**
+ * An extension of the Throttler class that adds Solid signals to access the internal state of the throttler
+ */
+export interface SolidThrottler<
+  TFn extends AnyFunction,
+  TArgs extends Parameters<TFn>,
+> extends Omit<
+    Throttler<TFn, TArgs>,
+    | 'getExecutionCount'
+    | 'getIsPending'
+    | 'getLastExecutionTime'
+    | 'getNextExecutionTime'
+  > {
+  executionCount: Accessor<number>
+  isPending: Accessor<boolean>
+  lastExecutionTime: Accessor<number>
+  nextExecutionTime: Accessor<number>
+}
+
+/**
+ * A low-level Solid hook that creates a `Throttler` instance that limits how often the provided function can execute.
+ *
+ * This hook is designed to be flexible and state-management agnostic - it simply returns a throttler instance that
+ * you can integrate with any state management solution (createSignal, Redux, Zustand, Jotai, etc). For a simpler and higher-level hook that
+ * integrates directly with Solid's createSignal, see createThrottledSignal.
+ *
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * // Basic throttling with custom state
+ * const [value, setValue] = createSignal(0);
+ * const throttler = createThrottler(setValue, { wait: 1000 });
+ *
+ * // With any state manager
+ * const throttler = createThrottler(
+ *   (value) => stateManager.setState(value),
+ *   {
+ *     wait: 2000,
+ *     leading: true,   // Execute immediately on first call
+ *     trailing: false  // Skip trailing edge updates
+ *   }
+ * );
+ *
+ * // Access throttler state via signals
+ * console.log(throttler.executionCount()); // number of times executed
+ * console.log(throttler.isPending());      // whether throttled function is pending
+ * console.log(throttler.lastExecutionTime()); // timestamp of last execution
+ * console.log(throttler.nextExecutionTime()); // timestamp of next allowed execution
+ * ```
+ */
+export function createThrottler<
+  TFn extends AnyFunction,
+  TArgs extends Parameters<TFn>,
+>(
+  fn: TFn,
+  initialOptions: ThrottlerOptions<TFn, TArgs>,
+): SolidThrottler<TFn, TArgs> {
+  const throttler = new Throttler<TFn, TArgs>(fn, initialOptions)
+
+  const [executionCount, setExecutionCount] = createSignal(
+    throttler.getExecutionCount(),
+  )
+  const [isPending, setIsPending] = createSignal(throttler.getIsPending())
+  const [lastExecutionTime, setLastExecutionTime] = createSignal(
+    throttler.getLastExecutionTime(),
+  )
+  const [nextExecutionTime, setNextExecutionTime] = createSignal(
+    throttler.getNextExecutionTime(),
+  )
+
+  function setOptions(newOptions: Partial<ThrottlerOptions<TFn, TArgs>>) {
+    throttler.setOptions({
+      ...newOptions,
+      onExecute: (throttler) => {
+        setExecutionCount(throttler.getExecutionCount())
+        setIsPending(throttler.getIsPending())
+        setLastExecutionTime(throttler.getLastExecutionTime())
+        setNextExecutionTime(throttler.getNextExecutionTime())
+
+        const onExecute = newOptions.onExecute ?? initialOptions.onExecute
+        onExecute?.(throttler)
+      },
+    })
+  }
+
+  setOptions(initialOptions)
+
+  return {
+    ...bindInstanceMethods(throttler),
+    executionCount,
+    isPending,
+    lastExecutionTime,
+    nextExecutionTime,
+    setOptions,
+  }
+}

package/src/throttler/index.ts

@@ -0,0 +1,6 @@
+// re-export everything from the core pacer package, BUT ONLY from the throttler module
+export * from '@tanstack/pacer/throttler'
+
+export * from './createThrottledSignal'
+export * from './createThrottledValue'
+export * from './createThrottler'

package/src/types/index.ts

@@ -0,0 +1 @@
+export * from '@tanstack/pacer/types'

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from '@tanstack/pacer/utils'