feat: add initial setup for devtools (#53)

* feat: add initial setup for devtools

* ci: apply automated fixes

* chore: fix test issues

* ci: apply automated fixes

* chore:fix render issue

* ci: apply automated fixes

* feat: drastically improve the pacer devtools UI

* ci: apply automated fixes

* chore: remove built-in tree in favor of devtools/ui

* ci: apply automated fixes

* refactor to key

* ci: apply automated fixes

* rename devtool packages to be consistent with query devtool package names

* fix sherif

* separate left and right panels of devtools

* denser ui

* better right panel, emit entire instance

* add some action buttons to devtools that kind of work

* event bus goes both ways

* all utils listen to devtools

* remove console log

* ci: apply automated fixes

* break up devtools components

* chore: improve the event listening/emitting

* ci: apply automated fixes

* fix action buttons and add reduction stat

* ci: apply automated fixes

* fix reactivity issues

* add devtools docs and exclude from production builds

* fix: utils shouldn't listen to other instances with different key

* start to add a few solid devtools to examples

* fix devtool versions

* fix solid devtools

* remove unnecessary public _emit

* update guides

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Kevin Van Cott <[email protected]>

Author: 3 people

docs/config.json

@@ -20,6 +20,10 @@
         {
           "label": "Installation",
           "to": "installation"
+        },
+        {
+          "label": "Devtools",
+          "to": "devtools"
         }
       ],
       "frameworks": [

docs/devtools.md

@@ -0,0 +1,99 @@
+---
+title: Devtools
+id: devtools
+---
+
+What? My debouncer can have dedicated devtools? Yep!
+
+TanStack Pacer provides devtools for debugging and monitoring all your utilities in real-time. The devtools integrate seamlessly within the new [TanStack Devtools](https://tanstack.com/devtools) multi-panel UI.
+
+> [!NOTE] By default, the TanStack Devtools and TanStack Pacer Devtools will only be included in development mode. This helps keep your production bundle size minimal. If you need to include devtools in production builds (e.g., for debugging production issues), you can use the alternative "production" imports.
+
+## Installation
+
+Install the devtools packages for your framework:
+
+### React
+
+```sh
+npm install @tanstack/react-devtools @tanstack/react-pacer-devtools
+```
+
+### Solid
+
+```sh
+npm install @tanstack/solid-devtools @tanstack/solid-pacer-devtools
+```
+
+## Basic Setup
+
+### React Setup
+
+```tsx
+import { TanStackDevtools } from '@tanstack/react-devtools'
+import { PacerDevtoolsPanel } from '@tanstack/react-pacer-devtools'
+
+function App() {
+  return (
+    <div>
+      {/* Your app content */}
+      
+      <TanStackDevtools
+        eventBusConfig={{
+          debug: false,
+        }}
+        plugins={[{ name: 'TanStack Pacer', render: <PacerDevtoolsPanel /> }]}
+      />
+    </div>
+  )
+}
+```
+
+### Solid Setup
+
+```tsx
+import { TanStackDevtools } from '@tanstack/solid-devtools'
+import { PacerDevtoolsPanel } from '@tanstack/solid-pacer-devtools'
+
+function App() {
+  return (
+    <div>
+      {/* Your app content */}
+      
+      <TanStackDevtools
+        eventBusConfig={{
+          debug: false,
+        }}
+        plugins={[{ name: 'TanStack Pacer', render: <PacerDevtoolsPanel /> }]}
+      />
+    </div>
+  )
+}
+```
+
+## Production Builds
+
+By default, devtools are excluded from production builds to minimize bundle size. The default imports will return no-op implementations in production:
+
+```tsx
+// This will be a no-op in production builds
+import { PacerDevtoolsPanel } from '@tanstack/react-pacer-devtools'
+```
+
+If you need to include devtools in production builds (e.g., for debugging production issues), use the production-specific imports:
+
+```tsx
+// This will include full devtools even in production builds
+import { PacerDevtoolsPanel } from '@tanstack/react-pacer-devtools/production'
+```
+
+## Registering Utilities
+
+Each utility should automatically be detected and displayed in the devtools. However, if you don't provide a `key` option to the utility, it will show with a uuid for its name. Give it an identifiable name with the `key` option.
+
+```tsx
+const debouncer = new Debouncer(myDebounceFn, {
+  key: 'My Debouncer', // friendly name for the utility instead of auto-generated uuid
+  wait: 1000,
+})
+```

docs/guides/async-debouncing.md

@@ -200,6 +200,7 @@ The `AsyncDebouncerState` includes:
 - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
 - `lastArgs`: The arguments from the most recent call to `maybeExecute`
 - `lastResult`: The result from the most recent successful function execution
+- `maybeExecuteCount`: Number of times `maybeExecute` has been called
 - `settleCount`: Number of function executions that have completed (either successfully or with errors)
 - `status`: Current execution status ('disabled' | 'idle' | 'pending' | 'executing' | 'settled')
 - `successCount`: Number of function executions that have completed successfully

docs/guides/async-queuing.md

@@ -96,7 +96,8 @@ const queue = new AsyncQueuer(
   {
     concurrency: 2, // Process 2 items at once
     wait: 1000,     // Wait 1 second between starting new items
-    started: true   // Start processing immediately
+    started: true,  // Start processing immediately
+    key: 'data-processor' // Identify this queuer in devtools
   }
 )
 
@@ -325,6 +326,7 @@ unsubscribe()
 The `AsyncQueuerState` includes all properties from the core queuing guide plus:
 
 - `activeItems`: Array of items currently being processed
+- `addItemCount`: Number of times addItem has been called (for reduction calculations)
 - `errorCount`: Number of function executions that have resulted in errors
 - `expirationCount`: Number of items that have been removed from the queue due to expiration
 - `isEmpty`: Whether the queuer has no items to process (items array is empty)

docs/guides/async-rate-limiting.md

@@ -187,6 +187,7 @@ The `AsyncRateLimiterState` includes:
 - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations
 - `isExecuting`: Whether the rate-limited function is currently executing asynchronously
 - `lastResult`: The result from the most recent successful function execution
+- `maybeExecuteCount`: Number of times `maybeExecute` has been called
 - `rejectionCount`: Number of function executions that have been rejected due to rate limiting
 - `settledCount`: Number of function executions that have completed (either successfully or with errors)
 - `status`: Current execution status ('disabled' | 'exceeded' | 'idle')

docs/guides/async-throttling.md

@@ -201,6 +201,7 @@ The `AsyncThrottlerState` includes:
 - `lastArgs`: The arguments from the most recent call to `maybeExecute`
 - `lastExecutionTime`: Timestamp of the last function execution in milliseconds
 - `lastResult`: The result from the most recent successful function execution
+- `maybeExecuteCount`: Number of times `maybeExecute` has been called
 - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
 - `settleCount`: Number of function executions that have completed (either successfully or with errors)
 - `status`: Current execution status ('disabled' | 'idle' | 'pending' | 'executing' | 'settled')

docs/guides/debouncing.md

@@ -243,6 +243,7 @@ const initialState = savedState ? JSON.parse(savedState) : {}
 
 const debouncer = new Debouncer(fn, {
   wait: 500,
+  key: 'search-debouncer',
   initialState
 })
 ```
@@ -273,6 +274,7 @@ The `DebouncerState` includes:
 - `executionCount`: Number of function executions that have been completed
 - `isPending`: Whether the debouncer is waiting for the timeout to trigger execution
 - `lastArgs`: The arguments from the most recent call to `maybeExecute`
+- `maybeExecuteCount`: Number of times `maybeExecute` has been called
 - `status`: Current execution status ('disabled' | 'idle' | 'pending')
 
 ## Framework Adapters

docs/guides/queuing.md

@@ -473,6 +473,7 @@ unsubscribe()
 
 The `QueuerState` includes:
 
+- `addItemCount`: Number of times addItem has been called (for reduction calculations)
 - `executionCount`: Number of items that have been processed by the queuer
 - `expirationCount`: Number of items that have been removed from the queue due to expiration
 - `isEmpty`: Whether the queuer has no items to process (items array is empty)

docs/guides/rate-limiting.md

@@ -292,6 +292,7 @@ The `RateLimiterState` includes:
 - `executionCount`: Number of function executions that have been completed
 - `executionTimes`: Array of timestamps when executions occurred for rate limiting calculations
 - `isExceeded`: Whether the rate limiter has exceeded the limit
+- `maybeExecuteCount`: Number of times `maybeExecute` has been called
 - `rejectionCount`: Number of function executions that have been rejected due to rate limiting
 - `status`: Current execution status ('disabled' | 'exceeded' | 'idle')
 

docs/guides/throttling.md

@@ -264,6 +264,7 @@ The `ThrottlerState` includes:
 - `isPending`: Whether the throttler is waiting for the timeout to trigger execution
 - `lastArgs`: The arguments from the most recent call to `maybeExecute`
 - `lastExecutionTime`: Timestamp of the last function execution in milliseconds
+- `maybeExecuteCount`: Number of times `maybeExecute` has been called
 - `nextExecutionTime`: Timestamp when the next execution can occur in milliseconds
 - `status`: Current execution status ('disabled' | 'idle' | 'pending')