docs: update changeset and examples for in-batch deduplication only

Update documentation to reflect the simplified deduplication feature
that only works within a single batch/queue cycle.

Changes:
- Rewrote changeset to describe in-batch deduplication only
- Removed cross-batch specific documentation
- Deleted useBatcherDedup example (cross-batch focused)
- Updated useBatcher example to demonstrate in-batch deduplication
- Added visual test interface with activity log

The feature is now simpler and more focused: it prevents duplicates
within the same batch but does not track across batch cycles.

Author: restareaByWeezy

.changeset/add-deduplication-feature.md

@@ -1,57 +1,44 @@
 ---
-'@tanstack/pacer': minor
+"@tanstack/pacer": minor
 ---
 
-Add cross-batch/cross-execution deduplication support to Batcher and Queuer
+Add in-batch/in-queue deduplication support to Batcher and Queuer
 
-This feature extends the existing `deduplicateItems` option to track processed items across batch/execution cycles. When enabled, items that have already been processed will be automatically skipped.
+This feature adds `deduplicateItems` option to prevent duplicate items within the same batch or queue.
 
-### Enhanced Options
+### New Options
 
-- `deduplicateItems: boolean` - Now prevents duplicates **both within and across batches** (default: false)
-- `deduplicateStrategy: 'keep-first' | 'keep-last'` - Only affects in-batch duplicates (default: 'keep-first')
-- `getItemKey: (item) => string | number` - Extract unique key from item
-- `maxTrackedKeys: number` - Maximum keys to track with FIFO eviction (default: 1000)
-- `onDuplicate: (newItem, existingItem?, instance) => void` - Called for both in-batch and cross-batch duplicates
-
-### New Methods
-
-- `hasProcessedKey(key)` - Check if a key has been processed
-- `peekProcessedKeys()` - Get a copy of all processed keys
-- `clearProcessedKeys()` - Clear the processed keys history
-
-### New State Properties
-
-- `processedKeys: Array<string | number>` - Keys that have been processed (similar to RateLimiter's executionTimes)
+- `deduplicateItems: boolean` - Enable automatic deduplication within the current batch/queue (default: false)
+- `deduplicateStrategy: 'keep-first' | 'keep-last'` - Strategy for handling duplicates (default: 'keep-first')
+- `getItemKey: (item) => string | number` - Extract unique key from item (defaults to JSON.stringify for objects)
 
 ### Behavior
 
 When `deduplicateItems` is enabled:
+- **'keep-first'**: Ignores new items if an item with the same key already exists in the batch/queue
+- **'keep-last'**: Replaces existing items with new items that have the same key
 
-1. **In-batch duplicates**: Merged based on `deduplicateStrategy` ('keep-first' or 'keep-last')
-2. **Cross-batch duplicates**: Skipped entirely (already processed)
-3. `onDuplicate` called with `existingItem` for in-batch, `undefined` for cross-batch
-
-### Use Case
-
-Prevents redundant processing when the same data is requested multiple times:
-
-- API calls: Don't fetch user-123 if it was already fetched
-- No-code tools: Multiple components requesting the same resource
-- Event processing: Skip events that have already been handled
-
-Similar to request deduplication in TanStack Query, but at the batching/queuing level.
+### Use Cases
 
-### Persistence Support
+Prevents redundant items within a single batch or queue cycle:
+- API batching: Avoid duplicate IDs in the same batch request
+- Event processing: Deduplicate events before processing
 
-The `processedKeys` can be persisted via `initialState`, following the existing Pacer pattern (similar to RateLimiter):
+### Example
 
 ```typescript
-const savedState = localStorage.getItem('batcher-state')
-const batcher = new Batcher(fn, {
-  deduplicateItems: true,
-  initialState: savedState ? JSON.parse(savedState) : {},
-})
+const batcher = new Batcher<{ userId: string }>(
+  (items) => fetchUsers(items.map(i => i.userId)),
+  {
+    deduplicateItems: true,
+    getItemKey: (item) => item.userId,
+  }
+);
+
+batcher.addItem({ userId: 'user-1' }); // Added to batch
+batcher.addItem({ userId: 'user-2' }); // Added to batch
+batcher.addItem({ userId: 'user-1' }); // Ignored! Already in current batch
+batcher.flush(); // Processes [user-1, user-2]
 ```
 
 Fully opt-in with no breaking changes to existing behavior.

examples/react/useBatcher/src/index.tsx

@@ -6,30 +6,44 @@ import { PacerProvider } from '@tanstack/react-pacer/provider'
 function App1() {
   // Use your state management library of choice
   const [processedBatches, setProcessedBatches] = useState<
-    Array<Array<number>>
+    Array<Array<string>>
   >([])
+  const [log, setLog] = useState<string[]>([])
 
   // The function that will process a batch of items
-  function processBatch(items: Array<number>) {
+  function processBatch(items: Array<string>) {
     setProcessedBatches((prev) => [...prev, items])
+    setLog((prev) => [...prev, `Processed batch: [${items.join(', ')}]`])
     console.log('processing batch', items)
   }
 
   const batcher = useBatcher(
     processBatch,
     {
-      // started: false, // true by default
-      maxSize: 5, // Process in batches of 5 (if comes before wait time)
-      wait: 3000, // wait up to 3 seconds before processing a batch (if time elapses before maxSize is reached)
-      getShouldExecute: (items, _batcher) => items.includes(42), // or pass in a custom function to determine if the batch should be processed
+      maxSize: 5,
+      wait: 3000,
+      // Enable in-batch deduplication
+      deduplicateItems: true,
+      deduplicateStrategy: 'keep-first', // or 'keep-last'
     },
-    // Alternative to batcher.Subscribe: pass a selector as 3rd arg to cause re-renders and subscribe to state
-    // (state) => state,
   )
 
+  const addItem = (item: string) => {
+    const result = batcher.addItem(item)
+    if (result) {
+      setLog((prev) => [...prev, `Added: ${item}`])
+    } else {
+      setLog((prev) => [...prev, `Duplicate ignored: ${item}`])
+    }
+  }
+
   return (
-    <div>
-      <h1>TanStack Pacer useBatcher Example 1</h1>
+    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
+      <h1>TanStack Pacer - In-Batch Deduplication Test</h1>
+      <p style={{ color: '#666' }}>
+        When <code>deduplicateItems: true</code>, duplicate items within the same batch are ignored.
+      </p>
+      
       <batcher.Subscribe
         selector={(state) => ({
           size: state.size,
@@ -39,59 +53,93 @@ function App1() {
       >
         {({ size, executionCount, totalItemsProcessed }) => (
           <>
-            <div>Batch Size: {size}</div>
-            <div>Batch Max Size: {3}</div>
-            <div>Batch Items: {batcher.peekAllItems().join(', ')}</div>
-            <div>Batches Processed: {executionCount}</div>
-            <div>Items Processed: {totalItemsProcessed}</div>
-            <div>
-              Processed Batches:{' '}
-              {processedBatches.map((b, i) => (
-                <>
-                  <span key={i}>[{b.join(', ')}]</span>,{' '}
-                </>
-              ))}
+            <div style={{ background: '#f5f5f5', padding: '15px', borderRadius: '8px', marginBottom: '20px' }}>
+              <div><strong>Batch Size:</strong> {size}</div>
+              <div><strong>Current Batch Items:</strong> [{batcher.peekAllItems().join(', ')}]</div>
+              <div><strong>Batches Processed:</strong> {executionCount}</div>
+              <div><strong>Total Items Processed:</strong> {totalItemsProcessed}</div>
             </div>
-            <div
-              style={{
-                display: 'grid',
-                gridTemplateColumns: 'repeat(2, 1fr)',
-                gap: '8px',
-                maxWidth: '600px',
-                margin: '16px 0',
-              }}
-            >
-              <button
-                onClick={() => {
-                  const nextNumber = batcher.peekAllItems().length
-                    ? batcher.peekAllItems()[
-                        batcher.peekAllItems().length - 1
-                      ] + 1
-                    : 1
-                  batcher.addItem(nextNumber)
-                }}
-              >
-                Add Number
-              </button>
-              <button
-                disabled={size === 0}
-                onClick={() => {
-                  batcher.flush()
-                }}
-              >
-                Flush Current Batch
-              </button>
+
+            <div style={{ marginBottom: '20px' }}>
+              <h3>Test Deduplication</h3>
+              <p style={{ fontSize: '14px', color: '#666' }}>
+                Click the same button multiple times - duplicates within the batch will be ignored.
+              </p>
+              <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap', marginBottom: '10px' }}>
+                <button onClick={() => addItem('apple')} style={{ padding: '8px 16px' }}>
+                  Add "apple"
+                </button>
+                <button onClick={() => addItem('banana')} style={{ padding: '8px 16px' }}>
+                  Add "banana"
+                </button>
+                <button onClick={() => addItem('cherry')} style={{ padding: '8px 16px' }}>
+                  Add "cherry"
+                </button>
+                <button onClick={() => addItem('apple')} style={{ padding: '8px 16px', background: '#ffcccc' }}>
+                  Add "apple" (duplicate test)
+                </button>
+              </div>
+              <div style={{ display: 'flex', gap: '8px' }}>
+                <button
+                  disabled={size === 0}
+                  onClick={() => batcher.flush()}
+                  style={{ padding: '8px 16px', background: '#4CAF50', color: 'white', border: 'none', borderRadius: '4px' }}
+                >
+                  Flush Batch
+                </button>
+                <button
+                  onClick={() => {
+                    batcher.reset()
+                    setProcessedBatches([])
+                    setLog([])
+                  }}
+                  style={{ padding: '8px 16px', background: '#f44336', color: 'white', border: 'none', borderRadius: '4px' }}
+                >
+                  Reset All
+                </button>
+              </div>
+            </div>
+
+            <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '20px' }}>
+              <div>
+                <h4>Processed Batches</h4>
+                <div style={{ background: '#e8f5e9', padding: '10px', borderRadius: '4px', minHeight: '100px' }}>
+                  {processedBatches.length === 0 ? (
+                    <span style={{ color: '#999' }}>No batches processed yet</span>
+                  ) : (
+                    processedBatches.map((b, i) => (
+                      <div key={i}>Batch #{i + 1}: [{b.join(', ')}]</div>
+                    ))
+                  )}
+                </div>
+              </div>
+              <div>
+                <h4>Activity Log</h4>
+                <div style={{ background: '#fff3e0', padding: '10px', borderRadius: '4px', minHeight: '100px', maxHeight: '200px', overflow: 'auto' }}>
+                  {log.length === 0 ? (
+                    <span style={{ color: '#999' }}>No activity yet</span>
+                  ) : (
+                    log.map((entry, i) => (
+                      <div key={i} style={{ fontSize: '12px', fontFamily: 'monospace' }}>{entry}</div>
+                    ))
+                  )}
+                </div>
+              </div>
             </div>
           </>
         )}
       </batcher.Subscribe>
-      <batcher.Subscribe selector={(state) => state}>
-        {(state) => (
-          <pre style={{ marginTop: '20px' }}>
-            {JSON.stringify(state, null, 2)}
-          </pre>
-        )}
-      </batcher.Subscribe>
+
+      <details style={{ marginTop: '20px' }}>
+        <summary style={{ cursor: 'pointer', fontWeight: 'bold' }}>Debug: Full State</summary>
+        <batcher.Subscribe selector={(state) => state}>
+          {(state) => (
+            <pre style={{ marginTop: '10px', padding: '10px', background: '#f1f3f5', borderRadius: '4px', overflow: 'auto' }}>
+              {JSON.stringify(state, null, 2)}
+            </pre>
+          )}
+        </batcher.Subscribe>
+      </details>
     </div>
   )
 }