feat: add withHistory, devtools, and subscribeKey utilities for enhanced state management

- `withHistory`: Adds undo/redo functionality to stores with a snapshot stack.
- `devtools`: Integrates stores with Redux DevTools for debugging and time travel.
- `subscribeKey`: Enables subscribing to changes on specific properties in stores.

Author: codeBelt

.changeset/good-parts-double.md

@@ -0,0 +1,5 @@
+---
+"@codebelt/classy-store": patch
+---
+
+add `withHistory`, `devtools`, and `subscribeKey` utilities for enhanced state management

src/utils/devtools/devtools.test.ts

@@ -0,0 +1,217 @@
+import {afterEach, describe, expect, it, mock} from 'bun:test';
+import {createClassyStore} from '../../core/core';
+import {devtools} from './devtools';
+
+/** Flush the queueMicrotask-based batching. */
+const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+// ── Mock DevTools Extension ──────────────────────────────────────────────────
+
+type MockConnection = {
+  init: ReturnType<typeof mock>;
+  send: ReturnType<typeof mock>;
+  subscribe: ReturnType<typeof mock>;
+  _listener: ((message: unknown) => void) | null;
+};
+
+function createMockConnection(): MockConnection {
+  const conn: MockConnection = {
+    init: mock(() => {}),
+    send: mock(() => {}),
+    subscribe: mock((listener: (message: unknown) => void) => {
+      conn._listener = listener;
+      return () => {
+        conn._listener = null;
+      };
+    }),
+    _listener: null,
+  };
+  return conn;
+}
+
+function createMockExtension(conn: MockConnection) {
+  return {
+    connect: mock(() => conn),
+  };
+}
+
+/** Helper to set the mock extension on window. */
+function setExtension(ext: ReturnType<typeof createMockExtension>) {
+  (window as unknown as Record<string, unknown>).__REDUX_DEVTOOLS_EXTENSION__ =
+    ext;
+}
+
+/** Helper to delete the extension from window. */
+function deleteExtension() {
+  if (typeof window !== 'undefined') {
+    delete (window as unknown as Record<string, unknown>)
+      .__REDUX_DEVTOOLS_EXTENSION__;
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe('devtools', () => {
+  afterEach(() => {
+    deleteExtension();
+  });
+
+  it('returns a noop if __REDUX_DEVTOOLS_EXTENSION__ is not available', () => {
+    deleteExtension();
+
+    class Store {
+      count = 0;
+    }
+
+    const store = createClassyStore(new Store());
+    const dispose = devtools(store);
+
+    // Should not throw and return a function
+    expect(typeof dispose).toBe('function');
+    dispose(); // noop
+  });
+
+  it('returns a noop when enabled is false', () => {
+    const conn = createMockConnection();
+    const ext = createMockExtension(conn);
+    setExtension(ext);
+
+    class Store {
+      count = 0;
+    }
+
+    const store = createClassyStore(new Store());
+    const dispose = devtools(store, {enabled: false});
+
+    expect(ext.connect).not.toHaveBeenCalled();
+    dispose();
+  });
+
+  it('connects with a custom name and sends init state', () => {
+    const conn = createMockConnection();
+    const ext = createMockExtension(conn);
+    setExtension(ext);
+
+    class Store {
+      count = 0;
+    }
+
+    const store = createClassyStore(new Store());
+    devtools(store, {name: 'MyStore'});
+
+    expect(ext.connect).toHaveBeenCalledWith({name: 'MyStore'});
+    expect(conn.init).toHaveBeenCalledTimes(1);
+
+    // Init should receive a snapshot of the store
+    const initState = conn.init.mock.calls[0][0] as Record<string, unknown>;
+    expect(initState.count).toBe(0);
+  });
+
+  it('sends state updates to DevTools on store mutation', async () => {
+    const conn = createMockConnection();
+    const ext = createMockExtension(conn);
+    setExtension(ext);
+
+    class Store {
+      count = 0;
+    }
+
+    const store = createClassyStore(new Store());
+    devtools(store);
+
+    store.count = 5;
+    await tick();
+
+    expect(conn.send).toHaveBeenCalledTimes(1);
+    const [action, state] = conn.send.mock.calls[0] as [
+      {type: string},
+      Record<string, unknown>,
+    ];
+    expect(action.type).toBe('STORE_UPDATE');
+    expect(state.count).toBe(5);
+  });
+
+  it('handles JUMP_TO_STATE time-travel', async () => {
+    const conn = createMockConnection();
+    const ext = createMockExtension(conn);
+    setExtension(ext);
+
+    class Store {
+      count = 0;
+      name = 'hello';
+    }
+
+    const store = createClassyStore(new Store());
+    devtools(store);
+
+    store.count = 10;
+    store.name = 'world';
+    await tick();
+
+    // Simulate time-travel back to initial state
+    conn._listener?.({
+      type: 'DISPATCH',
+      payload: {type: 'JUMP_TO_STATE'},
+      state: JSON.stringify({count: 0, name: 'hello'}),
+    });
+    await tick();
+
+    expect(store.count).toBe(0);
+    expect(store.name).toBe('hello');
+  });
+
+  it('skips getters during time-travel restore', async () => {
+    const conn = createMockConnection();
+    const ext = createMockExtension(conn);
+    setExtension(ext);
+
+    class Store {
+      count = 5;
+
+      get doubled() {
+        return this.count * 2;
+      }
+    }
+
+    const store = createClassyStore(new Store());
+    devtools(store);
+
+    // Simulate time-travel with a getter key included
+    conn._listener?.({
+      type: 'DISPATCH',
+      payload: {type: 'JUMP_TO_STATE'},
+      state: JSON.stringify({count: 3, doubled: 999}),
+    });
+    await tick();
+
+    expect(store.count).toBe(3);
+    // Getter should recompute, not be overwritten
+    expect(store.doubled).toBe(6);
+  });
+
+  it('disposes correctly (unsubscribes from store and devtools)', async () => {
+    const conn = createMockConnection();
+    const ext = createMockExtension(conn);
+    setExtension(ext);
+
+    class Store {
+      count = 0;
+    }
+
+    const store = createClassyStore(new Store());
+    const dispose = devtools(store);
+
+    store.count = 1;
+    await tick();
+    expect(conn.send).toHaveBeenCalledTimes(1);
+
+    dispose();
+
+    store.count = 2;
+    await tick();
+    // No additional send after dispose
+    expect(conn.send).toHaveBeenCalledTimes(1);
+    // DevTools listener should be removed
+    expect(conn._listener).toBeNull();
+  });
+});

src/utils/devtools/devtools.ts

@@ -0,0 +1,126 @@
+import {subscribe} from '../../core/core';
+import {snapshot} from '../../snapshot/snapshot';
+import {findGetterDescriptor} from '../internal/internal';
+
+// ── Redux DevTools types (minimal subset) ────────────────────────────────────
+
+type DevToolsMessage = {
+  type: string;
+  payload?: {type?: string};
+  state?: string;
+};
+
+type DevToolsConnection = {
+  init: (state: unknown) => void;
+  send: (action: string | {type: string}, state: unknown) => void;
+  subscribe: (
+    listener: (message: DevToolsMessage) => void,
+  ) => (() => void) | {unsubscribe: () => void};
+};
+
+type DevToolsExtension = {
+  connect: (options?: {name?: string}) => DevToolsConnection;
+};
+
+declare global {
+  interface Window {
+    __REDUX_DEVTOOLS_EXTENSION__?: DevToolsExtension;
+  }
+}
+
+// ── Options ──────────────────────────────────────────────────────────────────
+
+export type DevtoolsOptions = {
+  /** Display name in the DevTools panel. Defaults to `'ClassyStore'`. */
+  name?: string;
+  /** Set to `false` to disable the integration (returns a noop). Defaults to `true`. */
+  enabled?: boolean;
+};
+
+// ── Implementation ───────────────────────────────────────────────────────────
+
+/**
+ * Connect a store proxy to Redux DevTools for state inspection and time-travel debugging.
+ *
+ * Uses `subscribe()` + `snapshot()` to send state on each change.
+ * Listens for `DISPATCH` messages (`JUMP_TO_STATE`, `JUMP_TO_ACTION`) and applies
+ * the received state back to the store proxy, skipping getters and methods.
+ *
+ * @param proxyStore - A reactive proxy created by `createClassyStore()`.
+ * @param options - Optional configuration.
+ * @returns A dispose function that disconnects from DevTools and unsubscribes.
+ */
+export function devtools<T extends object>(
+  proxyStore: T,
+  options?: DevtoolsOptions,
+): () => void {
+  const {name = 'ClassyStore', enabled = true} = options ?? {};
+
+  // Guard: no extension or disabled
+  if (
+    !enabled ||
+    typeof window === 'undefined' ||
+    !window.__REDUX_DEVTOOLS_EXTENSION__
+  ) {
+    return () => {};
+  }
+
+  const extension = window.__REDUX_DEVTOOLS_EXTENSION__;
+  const connection = extension.connect({name});
+
+  // Send initial state
+  connection.init(snapshot(proxyStore));
+
+  // Track whether we're currently applying time-travel state to avoid
+  // re-sending the state we just applied.
+  let isTimeTraveling = false;
+
+  // Subscribe to store mutations → send to DevTools
+  const unsubscribeFromStore = subscribe(proxyStore, () => {
+    if (isTimeTraveling) return;
+    connection.send({type: 'STORE_UPDATE'}, snapshot(proxyStore));
+  });
+
+  // Listen for DevTools dispatches (time-travel)
+  const devToolsUnsub = connection.subscribe((message: DevToolsMessage) => {
+    if (message.type === 'DISPATCH' && message.state) {
+      const payloadType = message.payload?.type;
+      if (payloadType === 'JUMP_TO_STATE' || payloadType === 'JUMP_TO_ACTION') {
+        try {
+          const newState = JSON.parse(message.state) as Record<string, unknown>;
+          isTimeTraveling = true;
+
+          // Apply state back to the proxy, skipping getters and methods
+          for (const key of Object.keys(newState)) {
+            // Skip getters
+            if (findGetterDescriptor(proxyStore, key)?.get) continue;
+            // Skip methods
+            if (
+              typeof (proxyStore as Record<string, unknown>)[key] === 'function'
+            ) {
+              continue;
+            }
+            (proxyStore as Record<string, unknown>)[key] = newState[key];
+          }
+
+          isTimeTraveling = false;
+        } catch {
+          isTimeTraveling = false;
+        }
+      }
+    }
+  });
+
+  // Return dispose function
+  return () => {
+    unsubscribeFromStore();
+    if (typeof devToolsUnsub === 'function') {
+      devToolsUnsub();
+    } else if (
+      devToolsUnsub &&
+      typeof devToolsUnsub.unsubscribe === 'function'
+    ) {
+      devToolsUnsub.unsubscribe();
+    }
+  };
+}