@tanstack/pacer 0.19.0 → 0.20.0

package/src/event-client.ts

@@ -1,68 +1,129 @@
 import { EventClient } from '@tanstack/devtools-event-client'
-import type { AsyncBatcher } from './async-batcher'
-import type { AsyncDebouncer } from './async-debouncer'
-import type { AsyncQueuer } from './async-queuer'
-import type { AsyncRateLimiter } from './async-rate-limiter'
-import type { AsyncRetryer } from './async-retryer'
-import type { AsyncThrottler } from './async-throttler'
-import type { Debouncer } from './debouncer'
-import type { Batcher } from './batcher'
-import type { Queuer } from './queuer'
-import type { RateLimiter } from './rate-limiter'
-import type { Throttler } from './throttler'
 
+/**
+ * Payload on the devtools event bus must be JSON-serializable: `ClientEventBus`
+ * always stringifies events for `emitToServer` and `BroadcastChannel`, so live
+ * util instances (with reactive `store` graphs) cannot be sent as-is.
+ *
+ * Live instances are kept in {@link pacerDevtoolsInstancesByKey} for the panel.
+ */
+export interface PacerDevtoolsWirePayload {
+  key: string
+  store: { state: unknown }
+  options: unknown
+}
+
+const pacerDevtoolsInstancesByKey = new Map<string, unknown>()
+
+export function registerPacerDevtoolsInstance(
+  key: string,
+  instance: unknown,
+): void {
+  pacerDevtoolsInstancesByKey.set(key, instance)
+}
+
+export function getPacerDevtoolsInstance(key: string): unknown {
+  return pacerDevtoolsInstancesByKey.get(key)
+}
+
+function cloneJsonSafe(value: unknown): unknown {
+  if (value === undefined) {
+    return undefined
+  }
+  try {
+    return JSON.parse(JSON.stringify(value)) as unknown
+  } catch {
+    return null
+  }
+}
+
+function readStoreSnapshot(store: {
+  get?: () => unknown
+  state?: unknown
+}): unknown {
+  if (typeof store.get === 'function') {
+    return store.get()
+  }
+  return store.state
+}
+
+function toPacerDevtoolsWirePayload(instance: {
+  key: string
+  store: { get?: () => unknown; state?: unknown }
+  options: unknown
+}): PacerDevtoolsWirePayload {
+  return {
+    key: instance.key,
+    store: { state: cloneJsonSafe(readStoreSnapshot(instance.store)) },
+    options: cloneJsonSafe(instance.options),
+  }
+}
+
+/**
+ * Suffix-only keys: {@link EventClient} prepends `pluginId:` (`pacer:`) at runtime
+ * for `emit` / `on`. Wire `type` values are `pacer:${key}`.
+ */
 export interface PacerEventMap {
-  'pacer:d-AsyncBatcher': AsyncBatcher<any>
-  'pacer:d-AsyncDebouncer': AsyncDebouncer<any>
-  'pacer:d-AsyncQueuer': AsyncQueuer<any>
-  'pacer:d-AsyncRateLimiter': AsyncRateLimiter<any>
-  'pacer:d-AsyncRetryer': AsyncRetryer<any>
-  'pacer:d-AsyncThrottler': AsyncThrottler<any>
-  'pacer:d-Batcher': Batcher<any>
-  'pacer:d-Debouncer': Debouncer<any>
-  'pacer:d-Queuer': Queuer<any>
-  'pacer:d-RateLimiter': RateLimiter<any>
-  'pacer:d-Throttler': Throttler<any>
-  'pacer:AsyncBatcher': AsyncBatcher<any>
-  'pacer:AsyncDebouncer': AsyncDebouncer<any>
-  'pacer:AsyncQueuer': AsyncQueuer<any>
-  'pacer:AsyncRateLimiter': AsyncRateLimiter<any>
-  'pacer:AsyncRetryer': AsyncRetryer<any>
-  'pacer:AsyncThrottler': AsyncThrottler<any>
-  'pacer:Batcher': Batcher<any>
-  'pacer:Debouncer': Debouncer<any>
-  'pacer:Queuer': Queuer<any>
-  'pacer:RateLimiter': RateLimiter<any>
-  'pacer:Throttler': Throttler<any>
+  'd-AsyncBatcher': PacerDevtoolsWirePayload
+  'd-AsyncDebouncer': PacerDevtoolsWirePayload
+  'd-AsyncQueuer': PacerDevtoolsWirePayload
+  'd-AsyncRateLimiter': PacerDevtoolsWirePayload
+  'd-AsyncRetryer': PacerDevtoolsWirePayload
+  'd-AsyncThrottler': PacerDevtoolsWirePayload
+  'd-Batcher': PacerDevtoolsWirePayload
+  'd-Debouncer': PacerDevtoolsWirePayload
+  'd-Queuer': PacerDevtoolsWirePayload
+  'd-RateLimiter': PacerDevtoolsWirePayload
+  'd-Throttler': PacerDevtoolsWirePayload
+  AsyncBatcher: PacerDevtoolsWirePayload
+  AsyncDebouncer: PacerDevtoolsWirePayload
+  AsyncQueuer: PacerDevtoolsWirePayload
+  AsyncRateLimiter: PacerDevtoolsWirePayload
+  AsyncRetryer: PacerDevtoolsWirePayload
+  AsyncThrottler: PacerDevtoolsWirePayload
+  Batcher: PacerDevtoolsWirePayload
+  Debouncer: PacerDevtoolsWirePayload
+  Queuer: PacerDevtoolsWirePayload
+  RateLimiter: PacerDevtoolsWirePayload
+  Throttler: PacerDevtoolsWirePayload
 }
 
-export type PacerEventName = keyof PacerEventMap extends `pacer:${infer T}`
-  ? T
-  : never
+export type PacerEventName = keyof PacerEventMap
+
+type PacerUtilEmitSource = {
+  key?: string
+  store: { get?: () => unknown; state?: unknown }
+  options: unknown
+}
 
 class PacerEventClient extends EventClient<PacerEventMap> {
   constructor(props?: { debug: boolean }) {
     super({
       pluginId: 'pacer',
       debug: props?.debug,
+      /**
+       * TanStack Devtools starts `ClientEventBus` inside an async dynamic import
+       * after the first commit. Pacer utils often emit during the first render
+       * (constructor → store sync). `EventClient` only retries `tanstack-connect`
+       * `#maxRetries` times at `reconnectEveryMs` before it gives up and drops
+       * all queued events permanently. Default 300ms × 5 ≈ 1.5s is often too
+       * short; Form uses 1000ms here for the same reason.
+       */
+      reconnectEveryMs: 1000,
     })
   }
 }
 
-export const emitChange = <
-  TSuffix extends Extract<
-    keyof PacerEventMap,
-    `${string}:${string}`
-  > extends `${string}:${infer S}`
-    ? S
-    : never,
->(
-  event: TSuffix,
-  payload: PacerEventMap[`pacer:${TSuffix}`],
+export const emitChange = <TEvent extends keyof PacerEventMap>(
+  event: TEvent,
+  instance: PacerUtilEmitSource,
 ) => {
-  if (payload.key) {
-    pacerEventClient.emit(event, payload)
+  const key = instance.key
+  if (!key) {
+    return
   }
+  registerPacerDevtoolsInstance(key, instance)
+  pacerEventClient.emit(event, toPacerDevtoolsWirePayload({ ...instance, key }))
 }
 
 export const pacerEventClient = new PacerEventClient()

package/src/index.ts

@@ -12,5 +12,13 @@ export * from './throttler'
 export * from './types'
 export * from './utils'
 
-export { pacerEventClient } from './event-client'
-export type { PacerEventMap, PacerEventName } from './event-client'
+export {
+  emitChange,
+  getPacerDevtoolsInstance,
+  pacerEventClient,
+} from './event-client'
+export type {
+  PacerDevtoolsWirePayload,
+  PacerEventMap,
+  PacerEventName,
+} from './event-client'

package/src/queuer.ts

@@ -305,8 +305,10 @@ export class Queuer<TValue> {
     if (this.key) {
       pacerEventClient.on('d-Queuer', (event) => {
         if (event.payload.key !== this.key) return
-        this.#setState(event.payload.store.state)
-        this.setOptions(event.payload.options)
+        this.#setState(
+          event.payload.store.state as Partial<QueuerState<TValue>>,
+        )
+        this.setOptions(event.payload.options as Partial<QueuerOptions<TValue>>)
       })
     }
   }

package/src/rate-limiter.ts

@@ -177,8 +177,10 @@ export class RateLimiter<TFn extends AnyFunction> {
     if (this.key) {
       pacerEventClient.on('d-RateLimiter', (event) => {
         if (event.payload.key !== this.key) return
-        this.#setState(event.payload.store.state)
-        this.setOptions(event.payload.options)
+        this.#setState(event.payload.store.state as Partial<RateLimiterState>)
+        this.setOptions(
+          event.payload.options as Partial<RateLimiterOptions<TFn>>,
+        )
       })
     }
   }

package/src/throttler.ts

@@ -149,7 +149,7 @@ const defaultOptions: Omit<
  */
 export class Throttler<TFn extends AnyFunction> {
   readonly store: Store<Readonly<ThrottlerState<TFn>>> = new Store(
-    getDefaultThrottlerState(),
+    getDefaultThrottlerState<TFn>(),
   )
   key: string | undefined
   options: ThrottlerOptions<TFn>
@@ -169,8 +169,10 @@ export class Throttler<TFn extends AnyFunction> {
     if (this.key) {
       pacerEventClient.on('d-Throttler', (event) => {
         if (event.payload.key !== this.key) return
-        this.#setState(event.payload.store.state as ThrottlerState<TFn>)
-        this.setOptions(event.payload.options)
+        this.#setState(
+          event.payload.store.state as Partial<ThrottlerState<TFn>>,
+        )
+        this.setOptions(event.payload.options as Partial<ThrottlerOptions<TFn>>)
       })
     }
   }