@tanstack/solid-pacer 0.2.0 → 0.3.0

package/src/rate-limiter/createRateLimitedValue.ts

@@ -18,7 +18,9 @@ import type { RateLimiterOptions } from '@tanstack/pacer/rate-limiter'
  *
  * 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.
+ * The hook returns a tuple containing:
+ * - An accessor function that provides the rate-limited value
+ * - The rate limiter instance with control methods
  *
  * For more direct control over rate limiting behavior without Solid state management,
  * consider using the lower-level createRateLimiter hook instead.
@@ -26,35 +28,22 @@ import type { RateLimiterOptions } from '@tanstack/pacer/rate-limiter'
  * @example
  * ```tsx
  * // Basic rate limiting - update at most 5 times per minute
- * const [rateLimitedValue] = createRateLimitedValue(rawValue, {
+ * const [rateLimitedValue, rateLimiter] = 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`);
- *   }
- * });
+ * // Use the rate-limited value
+ * console.log(rateLimitedValue()); // Access the current rate-limited value
  *
- * // 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');
- *   }
- * };
+ * // Control the rate limiter
+ * rateLimiter.reset(); // Reset the rate limit window
  * ```
  */
 export function createRateLimitedValue<TValue>(
   value: Accessor<TValue>,
-  initialOptions: RateLimiterOptions<Setter<TValue>, [Accessor<TValue>]>,
-): [Accessor<TValue>, SolidRateLimiter<Setter<TValue>, [Accessor<TValue>]>] {
+  initialOptions: RateLimiterOptions<Setter<TValue>>,
+): [Accessor<TValue>, SolidRateLimiter<Setter<TValue>>] {
   const [rateLimitedValue, setRateLimitedValue, rateLimiter] =
     createRateLimitedSignal(value(), initialOptions)
 

package/src/rate-limiter/createRateLimiter.ts

@@ -5,11 +5,9 @@ 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>,
+export interface SolidRateLimiter<TFn extends AnyFunction>
+  extends Omit<
+    RateLimiter<TFn>,
     | 'getExecutionCount'
     | 'getMsUntilNextWindow'
     | 'getRejectionCount'
@@ -60,14 +58,13 @@ export interface SolidRateLimiter<
  * console.log('Next window in:', rateLimiter.msUntilNextWindow());
  * ```
  */
-export function createRateLimiter<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
->(
+export function createRateLimiter<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: RateLimiterOptions<TFn, TArgs>,
-): SolidRateLimiter<TFn, TArgs> {
-  const rateLimiter = new RateLimiter<TFn, TArgs>(fn, initialOptions)
+  initialOptions: RateLimiterOptions<TFn>,
+): SolidRateLimiter<TFn> {
+  const rateLimiter = bindInstanceMethods(
+    new RateLimiter<TFn>(fn, initialOptions),
+  )
 
   const [executionCount, setExecutionCount] = createSignal(
     rateLimiter.getExecutionCount(),
@@ -82,13 +79,14 @@ export function createRateLimiter<
     rateLimiter.getMsUntilNextWindow(),
   )
 
-  function setOptions(newOptions: Partial<RateLimiterOptions<TFn, TArgs>>) {
+  function setOptions(newOptions: Partial<RateLimiterOptions<TFn>>) {
     rateLimiter.setOptions({
       ...newOptions,
       onExecute: (rateLimiter) => {
         setExecutionCount(rateLimiter.getExecutionCount())
         setRemainingInWindow(rateLimiter.getRemainingInWindow())
         setMsUntilNextWindow(rateLimiter.getMsUntilNextWindow())
+
         const onExecute = newOptions.onExecute ?? initialOptions.onExecute
         onExecute?.(rateLimiter)
       },
@@ -96,6 +94,7 @@ export function createRateLimiter<
         setRejectionCount(rateLimiter.getRejectionCount())
         setRemainingInWindow(rateLimiter.getRemainingInWindow())
         setMsUntilNextWindow(rateLimiter.getMsUntilNextWindow())
+
         const onReject = newOptions.onReject ?? initialOptions.onReject
         onReject?.(rateLimiter)
       },
@@ -105,11 +104,11 @@ export function createRateLimiter<
   setOptions(initialOptions)
 
   return {
-    ...bindInstanceMethods(rateLimiter),
+    ...rateLimiter,
     executionCount,
     rejectionCount,
     remainingInWindow,
     msUntilNextWindow,
     setOptions,
-  }
+  } as SolidRateLimiter<TFn>
 }

package/src/throttler/createThrottledSignal.ts

@@ -40,12 +40,8 @@ import type { ThrottlerOptions } from '@tanstack/pacer/throttler'
  */
 export function createThrottledSignal<TValue>(
   value: TValue,
-  initialOptions: ThrottlerOptions<Setter<TValue>, [Accessor<TValue>]>,
-): [
-  Accessor<TValue>,
-  Setter<TValue>,
-  SolidThrottler<Setter<TValue>, [Accessor<TValue>]>,
-] {
+  initialOptions: ThrottlerOptions<Setter<TValue>>,
+): [Accessor<TValue>, Setter<TValue>, SolidThrottler<Setter<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

@@ -1,4 +1,4 @@
-import { createEffect, onCleanup } from 'solid-js'
+import { createEffect } from 'solid-js'
 import { createThrottledSignal } from './createThrottledSignal'
 import type { SolidThrottler } from './createThrottler'
 import type { Accessor, Setter } from 'solid-js'
@@ -11,7 +11,10 @@ import type { ThrottlerOptions } from '@tanstack/pacer/throttler'
  * 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 hook returns a tuple containing:
+ * - An accessor function that provides the throttled value
+ * - The throttler instance with control methods
+ *
  * 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,
@@ -20,26 +23,19 @@ import type { ThrottlerOptions } from '@tanstack/pacer/throttler'
  * @example
  * ```tsx
  * // Basic throttling - update at most once per second
- * const [throttledValue] = createThrottledValue(rawValue, { wait: 1000 });
+ * const [throttledValue, throttler] = 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
- * });
+ * // Use the throttled value
+ * console.log(throttledValue()); // Access the current throttled value
  *
- * // 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());
+ * // Control the throttler
+ * throttler.cancel(); // Cancel any pending updates
  * ```
  */
 export function createThrottledValue<TValue>(
   value: Accessor<TValue>,
-  initialOptions: ThrottlerOptions<Setter<TValue>, [Accessor<TValue>]>,
-): [Accessor<TValue>, SolidThrottler<Setter<TValue>, [Accessor<TValue>]>] {
+  initialOptions: ThrottlerOptions<Setter<TValue>>,
+): [Accessor<TValue>, SolidThrottler<Setter<TValue>>] {
   const [throttledValue, setThrottledValue, throttler] = createThrottledSignal(
     value(),
     initialOptions,
@@ -47,9 +43,6 @@ export function createThrottledValue<TValue>(
 
   createEffect(() => {
     setThrottledValue(value() as any)
-    onCleanup(() => {
-      throttler.cancel()
-    })
   })
 
   return [throttledValue, throttler]

package/src/throttler/createThrottler.ts

@@ -1,5 +1,5 @@
 import { Throttler } from '@tanstack/pacer/throttler'
-import { createSignal } from 'solid-js'
+import { createEffect, createSignal, onCleanup } from 'solid-js'
 import { bindInstanceMethods } from '@tanstack/pacer/utils'
 import type { Accessor } from 'solid-js'
 import type { AnyFunction } from '@tanstack/pacer/types'
@@ -8,11 +8,9 @@ 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>,
+export interface SolidThrottler<TFn extends AnyFunction>
+  extends Omit<
+    Throttler<TFn>,
     | 'getExecutionCount'
     | 'getIsPending'
     | 'getLastExecutionTime'
@@ -58,14 +56,11 @@ export interface SolidThrottler<
  * console.log(throttler.nextExecutionTime()); // timestamp of next allowed execution
  * ```
  */
-export function createThrottler<
-  TFn extends AnyFunction,
-  TArgs extends Parameters<TFn>,
->(
+export function createThrottler<TFn extends AnyFunction>(
   fn: TFn,
-  initialOptions: ThrottlerOptions<TFn, TArgs>,
-): SolidThrottler<TFn, TArgs> {
-  const throttler = new Throttler<TFn, TArgs>(fn, initialOptions)
+  initialOptions: ThrottlerOptions<TFn>,
+): SolidThrottler<TFn> {
+  const throttler = bindInstanceMethods(new Throttler<TFn>(fn, initialOptions))
 
   const [executionCount, setExecutionCount] = createSignal(
     throttler.getExecutionCount(),
@@ -78,7 +73,7 @@ export function createThrottler<
     throttler.getNextExecutionTime(),
   )
 
-  function setOptions(newOptions: Partial<ThrottlerOptions<TFn, TArgs>>) {
+  function setOptions(newOptions: Partial<ThrottlerOptions<TFn>>) {
     throttler.setOptions({
       ...newOptions,
       onExecute: (throttler) => {
@@ -95,12 +90,18 @@ export function createThrottler<
 
   setOptions(initialOptions)
 
+  createEffect(() => {
+    onCleanup(() => {
+      throttler.cancel()
+    })
+  })
+
   return {
-    ...bindInstanceMethods(throttler),
+    ...throttler,
     executionCount,
     isPending,
     lastExecutionTime,
     nextExecutionTime,
     setOptions,
-  }
+  } as SolidThrottler<TFn>
 }