@tanstack/pacer-devtools 0.1.0

package/src/PacerDevtools.tsx

@@ -0,0 +1,10 @@
+import { PacerContextProvider } from './PacerContextProvider'
+import { Shell } from './components/Shell'
+
+export default function PacerDevtools() {
+  return (
+    <PacerContextProvider>
+      <Shell />
+    </PacerContextProvider>
+  )
+}

package/src/components/ActionButtons.tsx

@@ -0,0 +1,143 @@
+import { pacerEventClient } from '@tanstack/pacer'
+import { useStyles } from '../styles/use-styles'
+import type { PacerEventName } from '@tanstack/pacer'
+
+type ActionButtonsProps = {
+  instance: any
+  utilName: string
+}
+
+export function ActionButtons(props: ActionButtonsProps) {
+  const styles = useStyles()
+  const utilInstance = props.instance
+  const utilState = utilInstance?.store?.state
+  const hasPending = utilState && 'isPending' in utilState
+  const hasEmpty = utilState && 'isEmpty' in utilState
+  const isPending = hasPending ? !!utilState.isPending : false
+  const isEmpty = hasEmpty ? utilState.isEmpty : undefined
+
+  const hasFlush = typeof utilInstance.flush === 'function'
+  const hasCancel = typeof utilInstance.cancel === 'function'
+  const hasReset = typeof utilInstance.reset === 'function'
+  const hasClear = typeof utilInstance.clear === 'function'
+  const hasStart = typeof utilInstance.start === 'function'
+  const hasStop = typeof utilInstance.stop === 'function'
+  const hasStartStop = hasStart && hasStop
+
+  const isRunning = utilState?.isRunning ?? true
+
+  if (!hasPending && !hasFlush && !hasCancel && !hasReset && !hasClear) {
+    return (
+      <div class={styles().sectionEmpty}>
+        No actions available for this util
+      </div>
+    )
+  }
+
+  const emitName = `d-${props.utilName}` as PacerEventName
+
+  return (
+    <div class={styles().actionsRow}>
+      {hasPending && (
+        <button
+          class={styles().actionButton}
+          onMouseDown={() => {
+            const next = !isPending
+            utilInstance.store.setState((prev: any) => ({
+              ...prev,
+              isPending: next,
+            }))
+            pacerEventClient.emit(emitName, utilInstance)
+          }}
+        >
+          <span class={styles().actionDotBlue} />
+          {isPending ? 'Restore Pending' : 'Trigger Pending'}
+        </button>
+      )}
+      {hasFlush && (
+        <button
+          class={styles().actionButton}
+          onMouseDown={() => {
+            utilInstance.flush()
+            pacerEventClient.emit(emitName, utilInstance)
+          }}
+          disabled={
+            (props.utilName.toLowerCase().includes('debouncer') &&
+              !isPending) ||
+            (props.utilName.toLowerCase().includes('throttler') &&
+              !isPending) ||
+            (props.utilName.toLowerCase().includes('batcher') && isEmpty) ||
+            (props.utilName.toLowerCase().includes('queuer') && isEmpty)
+          }
+        >
+          <span class={styles().actionDotGreen} />
+          Flush
+        </button>
+      )}
+      {hasCancel && (
+        <button
+          class={styles().actionButton}
+          onMouseDown={() => {
+            utilInstance.cancel()
+            pacerEventClient.emit(emitName, utilInstance)
+          }}
+          disabled={
+            (props.utilName.toLowerCase().includes('debouncer') &&
+              !isPending) ||
+            (props.utilName.toLowerCase().includes('throttler') &&
+              !isPending) ||
+            (props.utilName.toLowerCase().includes('batcher') && isEmpty) ||
+            (props.utilName.toLowerCase().includes('queuer') && isEmpty)
+          }
+        >
+          <span class={styles().actionDotRed} />
+          Cancel
+        </button>
+      )}
+      {hasReset && (
+        <button
+          class={styles().actionButton}
+          onMouseDown={() => {
+            utilInstance.reset()
+            pacerEventClient.emit(emitName, utilInstance)
+          }}
+        >
+          <span class={styles().actionDotYellow} />
+          Reset
+        </button>
+      )}
+      {hasClear && (
+        <button
+          class={styles().actionButton}
+          onMouseDown={() => {
+            utilInstance.clear()
+            pacerEventClient.emit(emitName, utilInstance)
+          }}
+          disabled={
+            (props.utilName.toLowerCase().includes('batcher') && isEmpty) ||
+            (props.utilName.toLowerCase().includes('queuer') && isEmpty)
+          }
+        >
+          <span class={styles().actionDotOrange} />
+          Clear
+        </button>
+      )}
+      {hasStartStop && (
+        <button
+          class={styles().actionButton}
+          onMouseDown={() => {
+            if (isRunning) {
+              utilInstance.stop()
+            } else {
+              utilInstance.start()
+            }
+            pacerEventClient.emit(emitName, utilInstance)
+          }}
+        >
+          <span class={styles().actionDotPurple} />
+          {isRunning ? 'Stop' : 'Start'}
+        </button>
+      )}
+    </div>
+  )
+}

package/src/components/DetailsPanel.tsx

@@ -0,0 +1,61 @@
+import { JsonTree } from '@tanstack/devtools-ui'
+import { useStyles } from '../styles/use-styles'
+import { ActionButtons } from './ActionButtons'
+import { StateHeader } from './StateHeader'
+
+type DetailsPanelProps = {
+  selectedInstance: () => { instance: any; type: string } | null
+  utilState: () => { lastUpdatedByKey: Record<string, number> }
+}
+
+export function DetailsPanel(props: DetailsPanelProps) {
+  const styles = useStyles()
+
+  return (
+    <div class={styles().stateDetails}>
+      {(() => {
+        const entry = props.selectedInstance()
+        if (!entry) {
+          return (
+            <div class={styles().noSelection}>
+              Select a util from the left panel to view its state
+            </div>
+          )
+        }
+
+        return (
+          <>
+            <StateHeader
+              selectedInstance={props.selectedInstance}
+              utilState={props.utilState}
+            />
+
+            <div class={styles().detailsGrid}>
+              <div class={styles().detailSection}>
+                <div class={styles().detailSectionHeader}>Actions</div>
+                <ActionButtons
+                  instance={entry.instance}
+                  utilName={entry.type}
+                />
+              </div>
+
+              <div class={styles().detailSection}>
+                <div class={styles().detailSectionHeader}>State</div>
+                <div class={styles().stateContent}>
+                  <JsonTree value={entry.instance.store?.state} />
+                </div>
+              </div>
+
+              <div class={styles().detailSection}>
+                <div class={styles().detailSectionHeader}>Options</div>
+                <div class={styles().stateContent}>
+                  <JsonTree value={entry.instance.options} />
+                </div>
+              </div>
+            </div>
+          </>
+        )
+      })()}
+    </div>
+  )
+}

package/src/components/Shell.tsx

@@ -0,0 +1,102 @@
+import { createMemo, createSignal, onCleanup, onMount } from 'solid-js'
+import { useStyles } from '../styles/use-styles'
+import { usePacerDevtoolsState } from '../PacerContextProvider'
+import { UTIL_GROUPS } from './util-groups'
+import { UtilList } from './UtilList'
+import { DetailsPanel } from './DetailsPanel'
+import type { StateKey } from './util-groups'
+
+export function Shell() {
+  const styles = useStyles()
+  const state = usePacerDevtoolsState()
+  const utilState = () => state
+  const [selectedKey, setSelectedKey] = createSignal<string | null>(null)
+  const [leftPanelWidth, setLeftPanelWidth] = createSignal(300)
+  const [isDragging, setIsDragging] = createSignal(false)
+
+  const selectedInstance = createMemo(() => {
+    const key = selectedKey()
+    if (!key) return null
+    for (const group of UTIL_GROUPS) {
+      const instance = (utilState() as unknown as Record<StateKey, Array<any>>)[
+        group.key
+      ].find((inst) => inst.key === key)
+      if (instance) return { instance, type: group.displayName }
+    }
+    return null
+  })
+
+  let dragStartX = 0
+  let dragStartWidth = 0
+
+  const handleMouseDown = (e: MouseEvent) => {
+    e.preventDefault()
+    e.stopPropagation()
+    setIsDragging(true)
+    document.body.style.cursor = 'col-resize'
+    document.body.style.userSelect = 'none'
+    dragStartX = e.clientX
+    dragStartWidth = leftPanelWidth()
+  }
+
+  const handleMouseMove = (e: MouseEvent) => {
+    if (!isDragging()) return
+
+    e.preventDefault()
+    const deltaX = e.clientX - dragStartX
+    const newWidth = Math.max(150, Math.min(800, dragStartWidth + deltaX))
+    setLeftPanelWidth(newWidth)
+  }
+
+  const handleMouseUp = () => {
+    setIsDragging(false)
+    document.body.style.cursor = ''
+    document.body.style.userSelect = ''
+  }
+
+  onMount(() => {
+    document.addEventListener('mousemove', handleMouseMove)
+    document.addEventListener('mouseup', handleMouseUp)
+  })
+
+  onCleanup(() => {
+    document.removeEventListener('mousemove', handleMouseMove)
+    document.removeEventListener('mouseup', handleMouseUp)
+  })
+
+  return (
+    <div class={styles().devtoolsPanel}>
+      <div class={styles().stickyHeader}>TanStack Pacer</div>
+
+      <div class={styles().mainContainer}>
+        <div
+          class={styles().leftPanel}
+          style={{
+            width: `${leftPanelWidth()}px`,
+            'min-width': '150px',
+            'max-width': '800px',
+          }}
+        >
+          <UtilList
+            selectedKey={selectedKey}
+            setSelectedKey={setSelectedKey}
+            utilState={utilState}
+          />
+        </div>
+
+        <div
+          class={`${styles().dragHandle} ${isDragging() ? 'dragging' : ''}`}
+          onMouseDown={handleMouseDown}
+        />
+
+        <div class={styles().rightPanel} style={{ flex: 1 }}>
+          <div class={styles().panelHeader}>Details</div>
+          <DetailsPanel
+            selectedInstance={selectedInstance}
+            utilState={utilState}
+          />
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/StateHeader.tsx

@@ -0,0 +1,106 @@
+import dayjs from 'dayjs'
+import relativeTime from 'dayjs/plugin/relativeTime'
+import { createSignal, onCleanup, onMount } from 'solid-js'
+import { useStyles } from '../styles/use-styles'
+
+dayjs.extend(relativeTime)
+
+type StateHeaderProps = {
+  selectedInstance: () => { instance: any; type: string } | null
+  utilState: () => { lastUpdatedByKey: Record<string, number> }
+}
+
+export function StateHeader(props: StateHeaderProps) {
+  const styles = useStyles()
+  const [now, setNow] = createSignal(Date.now())
+
+  onMount(() => {
+    const interval = setInterval(() => {
+      setNow(Date.now())
+    }, 1000)
+
+    onCleanup(() => {
+      clearInterval(interval)
+    })
+  })
+
+  const entry = props.selectedInstance()
+  if (!entry) return null
+
+  const key = entry.instance.key as string
+  const updatedAt = props.utilState().lastUpdatedByKey[key] ?? Date.now()
+
+  const getRelativeTime = () => {
+    const diffMs = now() - updatedAt
+    const diffSeconds = Math.floor(diffMs / 1000)
+
+    if (diffSeconds < 60) {
+      return `${diffSeconds} second${diffSeconds !== 1 ? 's' : ''} ago`
+    }
+
+    return dayjs(updatedAt).fromNow()
+  }
+
+  const getReductionPercentage = () => {
+    const state = entry.instance.store?.state || entry.instance.state
+
+    if (!state) return 0
+
+    // Use settleCount for async utilities, executionCount for sync utilities
+    const isAsync = entry.type.toLowerCase().includes('async')
+    const completedExecutions = isAsync
+      ? state.settleCount || 0
+      : state.executionCount || 0
+
+    // For batchers, calculate reduction based on items processed vs executions
+    if (entry.type.toLowerCase().includes('batcher')) {
+      const totalItemsProcessed = state.totalItemsProcessed || 0
+      if (totalItemsProcessed === 0) return 0
+      return Math.round(
+        ((totalItemsProcessed - completedExecutions) / totalItemsProcessed) *
+          100,
+      )
+    }
+
+    // For other utilities, calculate reduction based on request tracking
+    let requestCount = 0
+
+    if (state.maybeExecuteCount !== undefined) {
+      requestCount = state.maybeExecuteCount
+    } else if (state.addItemCount !== undefined) {
+      requestCount = state.addItemCount
+    } else {
+      // For utilities that don't track requests, show 0%
+      return 0
+    }
+
+    if (requestCount === 0) return 0
+
+    const reduction = requestCount - completedExecutions
+    return Math.round((reduction / requestCount) * 100)
+  }
+
+  const reductionPercentage = getReductionPercentage()
+
+  return (
+    <div class={styles().stateHeader}>
+      <div class={styles().stateTitle}>{entry.type}</div>
+      <div style={{ display: 'flex', 'align-items': 'center', gap: '16px' }}>
+        <div class={styles().infoGrid}>
+          <div class={styles().infoLabel}>Key</div>
+          <div class={styles().infoValueMono}>{key}</div>
+          <div class={styles().infoLabel}>Last Updated</div>
+          <div class={styles().infoValueMono}>
+            {new Date(updatedAt).toLocaleTimeString()} ({getRelativeTime()})
+          </div>
+        </div>
+        <div
+          class={styles().infoValueMono}
+          style={{ 'margin-left': 'auto', 'font-weight': 'bold' }}
+        >
+          {reductionPercentage}% reduction
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/UtilList.tsx

@@ -0,0 +1,62 @@
+import { For } from 'solid-js'
+import { useStore } from '@tanstack/solid-store'
+import clsx from 'clsx'
+import { useStyles } from '../styles/use-styles'
+import { UTIL_GROUPS } from './util-groups'
+import type { StateKey } from './util-groups'
+
+type UtilListProps = {
+  selectedKey: () => string | null
+  setSelectedKey: (key: string | null) => void
+  utilState: () => Record<StateKey, Array<any>>
+}
+
+export function UtilList(props: UtilListProps) {
+  const styles = useStyles()
+
+  return (
+    <div class={styles().utilList}>
+      <For each={UTIL_GROUPS}>
+        {(group) => (
+          <>
+            {props.utilState()[group.key].length > 0 && (
+              <div class={styles().utilGroup}>
+                <div class={styles().utilGroupHeader}>{group.label}</div>
+                <For each={props.utilState()[group.key]}>
+                  {(instance) => {
+                    const status = (() => {
+                      try {
+                        const statusAccessor = useStore(
+                          instance.store,
+                          (s: any) => s.status,
+                        )
+                        return () => statusAccessor() ?? 'unknown'
+                      } catch {
+                        return () => 'unknown'
+                      }
+                    })()
+                    return (
+                      <div
+                        class={clsx(
+                          styles().utilRow,
+                          props.selectedKey() === instance.key &&
+                            styles().utilRowSelected,
+                        )}
+                        onClick={() =>
+                          props.setSelectedKey(instance.key ?? null)
+                        }
+                      >
+                        <div class={styles().utilKey}>{instance.key}</div>
+                        <div class={styles().utilStatus}>{status()}</div>
+                      </div>
+                    )
+                  }}
+                </For>
+              </div>
+            )}
+          </>
+        )}
+      </For>
+    </div>
+  )
+}

package/src/components/util-groups.ts

@@ -0,0 +1,54 @@
+export type StateKey =
+  | 'asyncBatchers'
+  | 'asyncDebouncers'
+  | 'asyncQueuers'
+  | 'asyncRateLimiters'
+  | 'asyncThrottlers'
+  | 'batchers'
+  | 'debouncers'
+  | 'queuers'
+  | 'rateLimiters'
+  | 'throttlers'
+
+type UtilGroup = {
+  key: StateKey
+  label: string
+  displayName: string
+}
+
+export const UTIL_GROUPS: Array<UtilGroup> = [
+  { key: 'debouncers', label: 'Debouncers', displayName: 'Debouncer' },
+  { key: 'throttlers', label: 'Throttlers', displayName: 'Throttler' },
+  { key: 'batchers', label: 'Batchers', displayName: 'Batcher' },
+  { key: 'queuers', label: 'Queuers', displayName: 'Queuer' },
+  {
+    key: 'rateLimiters',
+    label: 'Rate Limiters',
+    displayName: 'Rate Limiter',
+  },
+  {
+    key: 'asyncDebouncers',
+    label: 'Async Debouncers',
+    displayName: 'Async Debouncer',
+  },
+  {
+    key: 'asyncThrottlers',
+    label: 'Async Throttlers',
+    displayName: 'Async Throttler',
+  },
+  {
+    key: 'asyncBatchers',
+    label: 'Async Batchers',
+    displayName: 'Async Batcher',
+  },
+  {
+    key: 'asyncQueuers',
+    label: 'Async Queuers',
+    displayName: 'Async Queuer',
+  },
+  {
+    key: 'asyncRateLimiters',
+    label: 'Async Rate Limiters',
+    displayName: 'Async Rate Limiter',
+  },
+]

package/src/core.tsx

@@ -0,0 +1,41 @@
+import { lazy } from 'solid-js'
+import { Portal, render } from 'solid-js/web'
+
+export interface PacerDevtoolsInit {}
+
+export class PacerDevtoolsCore {
+  #isMounted = false
+  #dispose?: () => void
+  #Component: any
+
+  constructor(_init?: PacerDevtoolsInit | undefined) {}
+
+  mount<T extends HTMLElement>(el: T) {
+    if (this.#isMounted) {
+      throw new Error('Devtools is already mounted')
+    }
+    const mountTo = el
+    const dispose = render(() => {
+      this.#Component = lazy(() => import('./PacerDevtools'))
+      const Devtools = this.#Component
+
+      return (
+        <Portal mount={mountTo}>
+          <div style={{ height: '100%' }}>
+            <Devtools />
+          </div>
+        </Portal>
+      )
+    }, mountTo)
+    this.#isMounted = true
+    this.#dispose = dispose
+  }
+
+  unmount() {
+    if (!this.#isMounted) {
+      throw new Error('Devtools is not mounted')
+    }
+    this.#dispose?.()
+    this.#isMounted = false
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+'use client'
+
+import * as Devtools from './core'
+
+// Create a dummy class for production that does nothing
+class DummyPacerDevtoolsCore {
+  constructor() {}
+  mount() {}
+  unmount() {}
+}
+
+export const PacerDevtoolsCore: (typeof Devtools)['PacerDevtoolsCore'] =
+  process.env.NODE_ENV !== 'development'
+    ? (DummyPacerDevtoolsCore as any)
+    : Devtools.PacerDevtoolsCore
+
+export type { PacerDevtoolsInit } from './core'

package/src/production.ts

@@ -0,0 +1,7 @@
+'use client'
+
+import * as Devtools from './core'
+
+export const PacerDevtoolsCore = Devtools.PacerDevtoolsCore
+
+export type { PacerDevtoolsInit } from './core'