@storve/core 1.0.0

package/src/batch.ts

@@ -0,0 +1,33 @@
+let batchCount = 0;
+const subscribers = new Set<() => void>();
+
+/**
+ * Batches multiple state updates across any number of stores.
+ * Listeners will only be notified once after the batch function completes.
+ * 
+ * @param fn - The function containing state updates to batch.
+ */
+export function batch(fn: () => void): void {
+    batchCount++;
+    try {
+        fn();
+    } finally {
+        batchCount--;
+        if (batchCount === 0) {
+            subscribers.forEach((s) => s());
+        }
+    }
+}
+
+/** @internal */
+export function isBatching(): boolean {
+    return batchCount > 0;
+}
+
+/** @internal */
+export function subscribeToBatch(cb: () => void): () => void {
+    subscribers.add(cb);
+    return () => {
+        subscribers.delete(cb);
+    };
+}

package/src/compose.ts

@@ -0,0 +1,50 @@
+import type { Store } from './types.js'
+
+export function compose<D extends object, S extends Store<D>>(store: S): S
+
+export function compose<D extends object, S extends Store<D>, R1>(
+  store: S,
+  f1: (store: S) => R1
+): R1
+
+export function compose<D extends object, S extends Store<D>, R1, R2>(
+  store: S,
+  f1: (store: S) => R1,
+  f2: (store: R1) => R2
+): R2
+
+export function compose<D extends object, S extends Store<D>, R1, R2, R3>(
+  store: S,
+  f1: (store: S) => R1,
+  f2: (store: R1) => R2,
+  f3: (store: R2) => R3
+): R3
+
+export function compose<D extends object>(
+  store: Store<D>,
+  ...enhancers: Array<(store: unknown) => unknown>
+): unknown
+
+/**
+ * Pipes a Storve store through one or more enhancer functions left to right.
+ * Each enhancer receives the output of the previous one.
+ *
+ * @template D - The generic parameter for the base store definition object.
+ * @param {Store<D>} store - The base store to enhance.
+ * @param {...Array<Function>} enhancers - The enhancer functions applied left to right.
+ * @returns {unknown} The enhanced store instance.
+ */
+export function compose<D extends object>(
+  store: Store<D>,
+  ...enhancers: Array<(store: unknown) => unknown>
+): unknown {
+  if (enhancers.length === 0) {
+    return store
+  }
+
+  let currentStore: unknown = store
+  for (let i = 0; i < enhancers.length; i++) {
+    currentStore = enhancers[i](currentStore)
+  }
+  return currentStore
+}

package/src/computed-entry.ts

@@ -0,0 +1,6 @@
+/**
+ * Computed entry point. Import from 'storve/computed'.
+ * Side-effect: registers computed extension so createStore handles computed values.
+ */
+export { computed, COMPUTED_MARKER } from './computed';
+export type { ComputedValue } from './types';

package/src/computed.ts

@@ -0,0 +1,187 @@
+/**
+ * Computed values implementation for Storve.
+ * Provides synchronous derived state with automatic dependency tracking.
+ */
+
+import { registerExtension } from './registry';
+
+/** Marker constant used to identify computed definitions in store definitions. */
+export const COMPUTED_MARKER = '__rf_computed' as const;
+
+/**
+ * Type representing a computed value definition.
+ * Used as a value in the store definition; the store unwraps it to the computed result type T.
+ */
+export type ComputedValue<T> = {
+    [COMPUTED_MARKER]: true;
+    fn: (state: unknown) => T;
+};
+
+/**
+ * Internal engine shape for a single computed value.
+ * @internal
+ */
+export interface ComputedEngine<T> {
+    fn: (state: unknown) => T;
+    value: T;
+    deps: Set<string>;
+    dirty: boolean;
+}
+
+/**
+ * Creates a computed value definition. When used in a store definition, the store
+ * will run the function against the current state, track which keys were read,
+ * and recompute when those dependencies change. Supports chaining (computed can
+ * depend on other computeds). Circular dependencies are detected and throw at creation.
+ *
+ * @param fn - Function that receives the current state and returns the derived value.
+ * @returns A marker object that the store recognizes as a computed definition.
+ *
+ * @example
+ * const store = createStore({
+ *   a: 1,
+ *   b: 2,
+ *   sum: computed((s) => s.a + s.b),
+ * });
+ * store.getState().sum; // 3
+ */
+export function computed<T>(fn: (state: unknown) => T): ComputedValue<T> {
+    return {
+        [COMPUTED_MARKER]: true,
+        fn,
+    };
+}
+
+/**
+ * Tracks which top-level state keys are accessed during the execution of a computed function.
+ * Runs the function against a shallow Proxy of the state and returns the result plus the set of keys read.
+ * Used internally by the store for dependency tracking and dirty marking.
+ *
+ * @param state - Current state object (base + resolved computeds).
+ * @param fn - The computed function to run.
+ * @returns The computed result and a Set of dependency keys (top-level only).
+ */
+export function trackDependencies<S extends object, T>(
+    state: S,
+    fn: (state: S) => T
+): { result: T; deps: Set<string> } {
+    const deps = new Set<string>();
+    const proxy = new Proxy(state, {
+        get(target, key) {
+            deps.add(key as string);
+            return (target as Record<string, unknown>)[key as string];
+        },
+    });
+    const result = fn(proxy as S);
+    return { result, deps };
+}
+
+function detectCircular(computedKeys: string[], getDeps: (key: string) => Set<string>): void {
+    const keySet = new Set(computedKeys);
+    const path: string[] = [];
+    const visited = new Set<string>();
+    function visit(key: string): void {
+        if (path.includes(key)) {
+            throw new Error(`Storve: circular dependency in computed values: ${[...path, key].join(' → ')}`);
+        }
+        if (visited.has(key)) return;
+        path.push(key);
+        for (const d of getDeps(key)) {
+            if (keySet.has(d)) visit(d);
+        }
+        path.pop();
+        visited.add(key);
+    }
+    for (const k of computedKeys) {
+        if (!visited.has(k)) visit(k);
+    }
+}
+
+function topologicalSort(computedKeys: string[], getDeps: (key: string) => Set<string>): string[] {
+    const result: string[] = [];
+    const visited = new Set<string>();
+    const keySet = new Set(computedKeys);
+    function visit(k: string): void {
+        if (visited.has(k)) return;
+        visited.add(k);
+        for (const d of getDeps(k)) {
+            if (keySet.has(d)) visit(d);
+        }
+        result.push(k);
+    }
+    for (const k of computedKeys) visit(k);
+    return result;
+}
+
+// Register computed extension when module is imported (order 1 = runs after async)
+registerExtension({
+    key: 'computed',
+    order: 1,
+    processDefinition: (definition) => {
+        const state = { ...definition };
+        const computedKeys = new Set<string>();
+        const computedEngines = new Map<string, ComputedEngine<unknown>>();
+
+        for (const key of Object.keys(definition)) {
+            const val = definition[key];
+            if (val && typeof val === 'object' && COMPUTED_MARKER in val) {
+                const comp = val as { [COMPUTED_MARKER]: true; fn: (state: unknown) => unknown };
+                computedKeys.add(key);
+                delete state[key];
+                const { result, deps } = trackDependencies(state, comp.fn);
+                computedEngines.set(key, { fn: comp.fn, value: result, deps, dirty: false });
+            }
+        }
+
+        const computedKeysList = Array.from(computedKeys);
+        let topoOrder: string[] = [];
+        if (computedKeysList.length > 0) {
+            const getDeps = (k: string) => computedEngines.get(k)!.deps;
+            detectCircular(computedKeysList, getDeps);
+            topoOrder = topologicalSort(computedKeysList, getDeps);
+            for (const key of topoOrder) {
+                const engine = computedEngines.get(key)!;
+                const { result, deps } = trackDependencies(state, engine.fn);
+                engine.value = result;
+                engine.deps = deps;
+                state[key] = result;
+            }
+        }
+
+        const runRecompute = (
+            changedKeys: Set<string>,
+            getState: () => Record<string, unknown>,
+            setComputed: (key: string, value: unknown) => void
+        ) => {
+            topoOrder.forEach((key) => {
+                const engine = computedEngines.get(key)!;
+                for (const d of engine.deps) {
+                    if (changedKeys.has(d)) {
+                        engine.dirty = true;
+                        break;
+                    }
+                }
+            });
+            topoOrder.forEach((key) => {
+                const engine = computedEngines.get(key)!;
+                if (!engine.dirty) return;
+                const currentState = getState();
+                const { result, deps } = trackDependencies(currentState, engine.fn);
+                engine.value = result;
+                engine.deps = deps;
+                engine.dirty = false;
+                setComputed(key, result);
+                topoOrder.forEach((other) => {
+                    if (other === key) return;
+                    if (computedEngines.get(other)!.deps.has(key)) computedEngines.get(other)!.dirty = true;
+                });
+            });
+        };
+
+        return {
+            state,
+            readOnlyKeys: computedKeys,
+            onStateChanged: (ctx) => runRecompute(ctx.changedKeys, ctx.getState, ctx.setComputed),
+        };
+    },
+});

package/src/devtools/history.ts

@@ -0,0 +1,103 @@
+/**
+ * Internal structure for a history entry in the ring buffer.
+ */
+export interface HistoryEntry<S> {
+    state: S;
+    timestamp: number;
+    actionName: string;
+}
+
+/**
+ * Ring buffer for time-travel debugging.
+ * Fixed capacity ensures no unbounded growth.
+ */
+export interface RingBuffer<S> {
+    entries: HistoryEntry<S>[];
+    cursor: number;
+    capacity: number;
+}
+
+/**
+ * Creates an empty ring buffer with the given capacity.
+ * @param capacity - Max number of entries (default 50)
+ */
+export function createRingBuffer<S>(capacity: number = 50): RingBuffer<S> {
+    return {
+        entries: [],
+        cursor: -1,
+        capacity,
+    };
+}
+
+/**
+ * Pushes a new state to the ring buffer.
+ * Discards any redo stack (entries after the cursor).
+ * Drops oldest entry if capacity is exceeded.
+ */
+export function push<S>(buffer: RingBuffer<S>, state: S, actionName: string): RingBuffer<S> {
+    const entry: HistoryEntry<S> = {
+        state,
+        timestamp: Date.now(),
+        actionName,
+    };
+
+    // Discard any entries after the current cursor (redo stack)
+    const currentEntries = buffer.entries.slice(0, buffer.cursor + 1);
+    
+    let newEntries = [...currentEntries, entry];
+    let newCursor = newEntries.length - 1;
+
+    // Maintain capacity
+    if (newEntries.length > buffer.capacity) {
+        newEntries = newEntries.slice(newEntries.length - buffer.capacity);
+        newCursor = newEntries.length - 1;
+    }
+
+    return {
+        ...buffer,
+        entries: newEntries,
+        cursor: newCursor,
+    };
+}
+
+/**
+ * Moves the cursor back one position and returns the state.
+ */
+export function undo<S>(buffer: RingBuffer<S>): { buffer: RingBuffer<S>; state: S | null } {
+    if (buffer.cursor > 0) {
+        const newCursor = buffer.cursor - 1;
+        return {
+            buffer: { ...buffer, cursor: newCursor },
+            state: buffer.entries[newCursor].state,
+        };
+    }
+    return { buffer, state: null };
+}
+
+/**
+ * Moves the cursor forward one position and returns the state.
+ */
+export function redo<S>(buffer: RingBuffer<S>): { buffer: RingBuffer<S>; state: S | null } {
+    if (buffer.cursor < buffer.entries.length - 1) {
+        const newCursor = buffer.cursor + 1;
+        return {
+            buffer: { ...buffer, cursor: newCursor },
+            state: buffer.entries[newCursor].state,
+        };
+    }
+    return { buffer, state: null };
+}
+
+/**
+ * Returns true if the ring buffer can perform an undo.
+ */
+export function canUndo<S>(buffer: RingBuffer<S>): boolean {
+    return buffer.cursor > 0;
+}
+
+/**
+ * Returns true if the ring buffer can perform a redo.
+ */
+export function canRedo<S>(buffer: RingBuffer<S>): boolean {
+    return buffer.cursor < buffer.entries.length - 1;
+}

package/src/devtools/index.ts

@@ -0,0 +1,5 @@
+/* v8 ignore next 10 */
+export { withDevtools } from './withDevtools';
+export type { DevtoolsOptions } from './withDevtools';
+export type { HistoryEntry } from './history';
+export type { SnapshotEntry } from './snapshots';

package/src/devtools/redux-bridge.ts

@@ -0,0 +1,70 @@
+import { Store } from '../types';
+import { RingBuffer } from './history';
+
+/** @internal */
+export interface DevtoolsInternals<S> {
+    buffer: RingBuffer<S>;
+    initialState: S;
+    snapshots: Map<string, { state: S; timestamp: number }>;
+    _lastActionName: string | null;
+    _applySnapshot: (state: S) => void;
+    _isInternalUpdate: boolean;
+}
+
+interface DevtoolsInstance {
+    init(state: unknown): void;
+    send(action: { type: string }, state: unknown): void;
+    subscribe(listener: (msg: { type: string; payload?: { type: string }; state?: string }) => void): () => void;
+}
+
+interface ReduxDevtoolsExtension {
+    connect(options: { name: string; maxAge?: number }): DevtoolsInstance;
+}
+
+/**
+ * Connects a devtools-enabled store to the Redux DevTools browser extension.
+ */
+export function connectReduxDevtools<S extends object>(
+    store: Store<S> & { __devtools: DevtoolsInternals<S> },
+    name: string
+): () => void {
+    if (typeof window === 'undefined') return () => {};
+
+    const extension = (window as unknown as { __REDUX_DEVTOOLS_EXTENSION__?: ReduxDevtoolsExtension }).__REDUX_DEVTOOLS_EXTENSION__;
+    if (!extension) return () => {};
+
+    const devtools: DevtoolsInstance = extension.connect({
+        name: `Storve | ${name}`,
+        maxAge: store.__devtools.buffer.capacity,
+    });
+
+    devtools.init(store.getState());
+
+    const unsubscribeStore = store.subscribe((state) => {
+        // Only send updates if they are NOT internal (undo/redo/restore from ourselves)
+        if (store.__devtools._isInternalUpdate) return;
+        
+        devtools.send(
+            { type: store.__devtools._lastActionName ?? 'setState' },
+            state
+        );
+    });
+
+    const unsubscribeDevtools = devtools.subscribe((message) => {
+        if (message.type === 'DISPATCH') {
+            if (message.payload?.type === 'JUMP_TO_STATE' || message.payload?.type === 'JUMP_TO_ACTION') {
+                if (message.state) {
+                    store.__devtools._applySnapshot(JSON.parse(message.state));
+                }
+            } else if (message.payload?.type === 'RESET') {
+                store.__devtools._applySnapshot(store.__devtools.initialState);
+            }
+        }
+    });
+
+
+    return () => {
+        unsubscribeStore();
+        unsubscribeDevtools();
+    };
+}

package/src/devtools/snapshots.ts

@@ -0,0 +1,54 @@
+/**
+ * Internal structure for a named snapshot entry.
+ */
+export interface SnapshotEntry<S> {
+    state: S;
+    timestamp: number;
+}
+
+/**
+ * A Map of named state checkpoints.
+ */
+export type SnapshotMap<S> = Map<string, SnapshotEntry<S>>;
+
+/**
+ * Creates a new empty snapshot map.
+ */
+export function createSnapshotMap<S>(): SnapshotMap<S> {
+    return new Map<string, SnapshotEntry<S>>();
+}
+
+/**
+ * Saves a state snapshot under the given name.
+ */
+export function saveSnapshot<S>(map: SnapshotMap<S>, name: string, state: S): SnapshotMap<S> {
+    const nextMap = new Map(map);
+    nextMap.set(name, {
+        state,
+        timestamp: Date.now(),
+    });
+    return nextMap;
+}
+
+/**
+ * Returns the snapshot entry for the given name, or null if not found.
+ */
+export function getSnapshot<S>(map: SnapshotMap<S>, name: string): SnapshotEntry<S> | null {
+    return map.get(name) || null;
+}
+
+/**
+ * Removes the snapshot with the given name.
+ */
+export function deleteSnapshot<S>(map: SnapshotMap<S>, name: string): SnapshotMap<S> {
+    const nextMap = new Map(map);
+    nextMap.delete(name);
+    return nextMap;
+}
+
+/**
+ * Returns an array of all snapshot names.
+ */
+export function listSnapshots<S>(map: SnapshotMap<S>): string[] {
+    return Array.from(map.keys());
+}