@storve/core 1.0.1 → 1.0.3

package/src/devtools/history.ts

@@ -1,103 +0,0 @@
-/**
- * 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

@@ -1,5 +0,0 @@
-/* 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

@@ -1,70 +0,0 @@
-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

@@ -1,54 +0,0 @@
-/**
- * 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());
-}

package/src/devtools/withDevtools.ts

@@ -1,196 +0,0 @@
-import { registerExtension } from '../registry';
-import { createRingBuffer, push, undo, redo, canUndo, canRedo } from './history';
-import { createSnapshotMap, saveSnapshot, getSnapshot, deleteSnapshot, listSnapshots } from './snapshots';
-import { connectReduxDevtools, DevtoolsInternals } from './redux-bridge';
-import type { Store, StoreState } from '../types';
-
-/**
- * Configuration options for DevTools.
- */
-export interface DevtoolsOptions {
-    /** Label shown in Redux DevTools panel */
-    name: string;
-    /** Max history entries in ring buffer (default 50) */
-    maxHistory?: number;
-    /** Whether devtools are enabled (default true) */
-    enabled?: boolean;
-}
-
-/** @internal WeakMap to store devtools options for definitions without polluting state */
-const DEVTOOLS_OPTIONS = new WeakMap<object, DevtoolsOptions>();
-
-/**
- * Augmented store type with devtools properties.
- * @internal
- */
-type StoreWithDevtools<S extends object> = Store<S> & {
-    __devtools?: DevtoolsInternals<S>;
-    undo?: () => void;
-    redo?: () => void;
-    canUndo?: boolean;
-    canRedo?: boolean;
-    snapshot?: (name: string) => void;
-    restore?: (name: string) => void;
-    deleteSnapshot?: (name: string) => void;
-    clearHistory?: () => void;
-    history?: readonly S[];
-    snapshots?: readonly string[];
-}
-
-
-/**
- * Wraps a store definition with DevTools capabilities.
- * Must be imported to register the devtools extension.
- */
-export function withDevtools<D extends object>(
-    definition: D,
-    options: DevtoolsOptions
-): D {
-    DEVTOOLS_OPTIONS.set(definition, options);
-    return definition;
-}
-
-// Register the extension via the registry pattern
-registerExtension({
-    key: 'devtools',
-    processDefinition: (definition) => {
-        const options = DEVTOOLS_OPTIONS.get(definition);
-        if (!options || options.enabled === false) return { state: {} };
-
-        return {
-            state: {},
-        };
-    },
-    extendStore: (context) => {
-        const { store, definition } = context as { store: Store<object>; definition: object };
-        const options = DEVTOOLS_OPTIONS.get(definition);
-        if (!options || options.enabled === false) return {};
-
-        const initialState = store.getState();
-        const internals: DevtoolsInternals<object> = {
-            buffer: createRingBuffer<object>(options.maxHistory || 50),
-            snapshots: createSnapshotMap<object>(),
-            initialState,
-            _isInternalUpdate: false,
-            _lastActionName: null,
-            _applySnapshot: (state: object) => {
-                internals._isInternalUpdate = true;
-                store.setState(state as unknown as Partial<StoreState<object>>);
-                internals._isInternalUpdate = false;
-            }
-        };
-        const devStore = store as unknown as StoreWithDevtools<object>;
-        devStore.__devtools = internals;
-
-        // One-shot flag: the very first subscribe callback after withSync broadcasts
-        // REQUEST_STATE may fire setState back to initialState. We skip that single echo
-        // so it doesn't appear as a spurious history entry.
-        let _initEchoPending = true;
-
-        // Use subscribe instead of wrapping setState to capture history.
-        // This is more robust against extension ordering issues.
-        store.subscribe(() => {
-            if (internals._isInternalUpdate) return;
-
-            const currentState = store.getState();
-
-            // On first callback: if there's no explicit action name and state matches
-            // initialState, this is likely a withSync echo — skip once and clear flag.
-            if (_initEchoPending && internals._lastActionName === null) {
-                const init = internals.initialState as Record<string, unknown>;
-                const curr = currentState as Record<string, unknown>;
-                const keys = Object.keys(init);
-                const matchesInit = keys.length === Object.keys(curr).length
-                    && keys.every((k) => curr[k] === init[k]);
-                if (matchesInit) {
-                    _initEchoPending = false;
-                    return;
-                }
-            }
-            _initEchoPending = false;
-
-            const actionName = internals._lastActionName ?? 'setState';
-            internals.buffer = push(internals.buffer, currentState, actionName);
-            internals._lastActionName = null; // Reset after capture
-        });
-
-        // Bridge actions to capture names. 
-        const rawActions = store.actions as Record<string, (...args: unknown[]) => unknown>;
-        Object.keys(rawActions).forEach((key) => {
-            const original = rawActions[key];
-            const wrapped = (...args: unknown[]) => {
-                internals._lastActionName = key;
-                return original(...args);
-            };
-            rawActions[key] = wrapped;
-            // Also update the store property if it was bound directly
-            const storeAsRecord = store as unknown as Record<string, unknown>;
-            if (storeAsRecord[key] === original) {
-                storeAsRecord[key] = wrapped;
-            }
-        });
-
-        if (typeof window !== 'undefined') {
-            connectReduxDevtools(devStore as Required<StoreWithDevtools<object>>, options.name);
-        }
-
-        return {
-            undo: () => {
-                const { buffer, state } = undo(internals.buffer);
-                if (state) {
-                    internals.buffer = buffer;
-                    internals._applySnapshot(state);
-                }
-            },
-            redo: () => {
-                const { buffer, state } = redo(internals.buffer);
-                if (state) {
-                    internals.buffer = buffer;
-                    internals._applySnapshot(state);
-                }
-            },
-            get canUndo() {
-                return canUndo(internals.buffer);
-            },
-            get canRedo() {
-                return canRedo(internals.buffer);
-            },
-            snapshot: (name: string) => {
-                internals.snapshots = saveSnapshot(internals.snapshots, name, store.getState());
-                // We use an internal update to trigger subscribers without pushing to history
-                internals._isInternalUpdate = true;
-                store.setState({} as unknown as Partial<StoreState<object>>);
-                internals._isInternalUpdate = false;
-            },
-            restore: (name: string) => {
-                const entry = getSnapshot(internals.snapshots, name);
-                if (!entry) {
-                    throw new Error(`Storve DevTools: Snapshot "${name}" not found.`);
-                }
-                
-                // restore() DOES push to history
-                internals._applySnapshot(entry.state);
-                internals.buffer = push(internals.buffer, entry.state, `restore('${name}')`);
-            },
-            deleteSnapshot: (name: string) => {
-                internals.snapshots = deleteSnapshot(internals.snapshots, name);
-                internals._isInternalUpdate = true;
-                store.setState({} as unknown as Partial<StoreState<object>>);
-                internals._isInternalUpdate = false;
-            },
-            clearHistory: () => {
-                internals.buffer = createRingBuffer(internals.buffer.capacity);
-                internals._isInternalUpdate = true;
-                store.setState({} as unknown as Partial<StoreState<object>>);
-                internals._isInternalUpdate = false;
-            },
-            get history() {
-                return [...internals.buffer.entries];
-            },
-            get snapshots() {
-                return listSnapshots(internals.snapshots);
-            }
-        };
-    }
-});
-

package/src/extensions/noop.ts

@@ -1,12 +0,0 @@
-/**
- * No-op extension for validating the registry pattern.
- * @internal
- */
-import { registerExtension } from '../registry';
-
-registerExtension({
-    key: '__noop',
-    processDefinition: (definition) => ({
-        state: { ...definition },
-    }),
-});

package/src/index.ts

@@ -1,4 +0,0 @@
-export { createStore } from './store';
-export { batch } from './batch';
-export { compose } from './compose';
-export type { Store, StoreDefinition, Listener, Unsubscribe, StoreOptions, StoreState, StoreActions, AsyncState, AsyncOptions, AsyncStatus, ComputedValue, WritableStoreState, ComputedKeys } from './types';

package/src/persist/adapters/indexedDB.ts

@@ -1,114 +0,0 @@
-import type { PersistAdapter } from '../index.js'
-
-/**
- * Creates an IndexedDB persistence adapter.
- * Lazily opens the database on first interaction and caches the Promise.
- * Safe for Server-Side Rendering (SSR) — if 'indexedDB' is totally unavailable,
- * methods elegantly degrade to returning null / no-op promises.
- *
- * @param {string} [dbName='storve-persist'] - Optional custom database name.
- * @returns {PersistAdapter} The IndexedDB persistence adapter.
- */
-export function indexedDBAdapter(dbName: string = 'storve-persist'): PersistAdapter {
-  const STORE_NAME = 'keyval'
-  const isServer = typeof indexedDB === 'undefined'
-  let dbPromise: Promise<IDBDatabase | null> | null = null
-
-  function getDB(): Promise<IDBDatabase | null> {
-    if (isServer) return Promise.resolve(null)
-    if (dbPromise !== null) return dbPromise
-
-    dbPromise = new Promise((resolve) => {
-      try {
-        const request = indexedDB.open(dbName, 1)
-
-        request.onupgradeneeded = () => {
-          const db = request.result
-          if (!db.objectStoreNames.contains(STORE_NAME)) {
-            db.createObjectStore(STORE_NAME)
-          }
-        }
-
-        request.onsuccess = () => {
-          resolve(request.result)
-        }
-
-        request.onerror = () => {
-          console.warn(`[storve] Failed to open IndexedDB "${dbName}"`)
-          resolve(null)
-        }
-      } catch (err) {
-        console.warn(`[storve] Exception opening IndexedDB "${dbName}":`, err)
-        resolve(null)
-      }
-    })
-
-    return dbPromise
-  }
-
-  return {
-    async getItem(key: string): Promise<string | null> {
-      const db = await getDB()
-      if (db === null) return null
-
-      return new Promise((resolve) => {
-        try {
-          const transaction = db.transaction(STORE_NAME, 'readonly')
-          const store = transaction.objectStore(STORE_NAME)
-          const request = store.get(key)
-
-          request.onsuccess = () => {
-            const result = request.result
-            if (typeof result === 'string') {
-              resolve(result)
-            } else {
-              resolve(null)
-            }
-          }
-
-          request.onerror = () => {
-            resolve(null)
-          }
-        } catch {
-          resolve(null)
-        }
-      })
-    },
-
-    async setItem(key: string, value: string): Promise<void> {
-      const db = await getDB()
-      if (db === null) return
-
-      return new Promise((resolve) => {
-        try {
-          const transaction = db.transaction(STORE_NAME, 'readwrite')
-          const store = transaction.objectStore(STORE_NAME)
-          const request = store.put(value, key)
-
-          request.onsuccess = () => resolve()
-          request.onerror = () => resolve()
-        } catch {
-          resolve()
-        }
-      })
-    },
-
-    async removeItem(key: string): Promise<void> {
-      const db = await getDB()
-      if (db === null) return
-
-      return new Promise((resolve) => {
-        try {
-          const transaction = db.transaction(STORE_NAME, 'readwrite')
-          const store = transaction.objectStore(STORE_NAME)
-          const request = store.delete(key)
-
-          request.onsuccess = () => resolve()
-          request.onerror = () => resolve()
-        } catch {
-          resolve()
-        }
-      })
-    }
-  }
-}

package/src/persist/adapters/localStorage.ts

@@ -1,28 +0,0 @@
-import type { PersistAdapter } from '../index.js'
-
-/**
- * Creates a localStorage persistence adapter.
- * Uses window.localStorage to automatically persist state modifications in the browser.
- * Safe for Server-Side Rendering (SSR) — if 'window' is completely undefined, 
- * methods gracefully return null or perform no-ops.
- *
- * @returns {PersistAdapter} The localStorage persistence adapter.
- */
-export function localStorageAdapter(): PersistAdapter {
-  const isServer = typeof window === 'undefined'
-
-  return {
-    getItem(key: string): string | null {
-      if (isServer) return null
-      return window.localStorage.getItem(key)
-    },
-    setItem(key: string, value: string): void {
-      if (isServer) return
-      window.localStorage.setItem(key, value)
-    },
-    removeItem(key: string): void {
-      if (isServer) return
-      window.localStorage.removeItem(key)
-    }
-  }
-}

package/src/persist/adapters/memory.ts

@@ -1,26 +0,0 @@
-import type { PersistAdapter } from '../index.js'
-
-/**
- * Creates an entirely isolated memory-based persistence adapter.
- * This adapter uses a closure-scoped Map to store data, ensuring fully
- * segregated instances without any module-level state.
- * Ideal for testing or Node/SSR environments where no real storage is available.
- * 
- * @returns {PersistAdapter} An isolated memory adapter instance.
- */
-export function memoryAdapter(): PersistAdapter {
-  const store = new Map<string, string>()
-
-  return {
-    getItem(key: string): string | null {
-      const value = store.get(key)
-      return value !== undefined ? value : null
-    },
-    setItem(key: string, value: string): void {
-      store.set(key, value)
-    },
-    removeItem(key: string): void {
-      store.delete(key)
-    }
-  }
-}

package/src/persist/adapters/sessionStorage.ts

@@ -1,28 +0,0 @@
-import type { PersistAdapter } from '../index.js'
-
-/**
- * Creates a sessionStorage persistence adapter.
- * Uses window.sessionStorage to persist state for the lifespan of the browser tab.
- * Safe for Server-Side Rendering (SSR) — if 'window' is completely undefined,
- * methods gracefully return null or perform no-ops.
- *
- * @returns {PersistAdapter} The sessionStorage persistence adapter.
- */
-export function sessionStorageAdapter(): PersistAdapter {
-  const isServer = typeof window === 'undefined'
-
-  return {
-    getItem(key: string): string | null {
-      if (isServer) return null
-      return window.sessionStorage.getItem(key)
-    },
-    setItem(key: string, value: string): void {
-      if (isServer) return
-      window.sessionStorage.setItem(key, value)
-    },
-    removeItem(key: string): void {
-      if (isServer) return
-      window.sessionStorage.removeItem(key)
-    }
-  }
-}

package/src/persist/debounce.ts

@@ -1,28 +0,0 @@
-/**
- * Creates a debounced version of a provided function that delays its execution until after
- * the specified milliseconds have elapsed since the last time it was called.
- * If 'ms' is 0, the function invokes immediately.
- * 
- * @template T - The arguments type array.
- * @param {(...args: T) => void} fn - The function to debounce.
- * @param {number} ms - The number of milliseconds to wait.
- * @returns {(...args: T) => void} The new debounced function.
- */
-export function createDebounce<T extends unknown[]>(fn: (...args: T) => void, ms: number): (...args: T) => void {
-  let timerId: ReturnType<typeof setTimeout> | undefined;
-
-  return function(...args: T): void {
-    if (ms === 0) {
-      fn(...args)
-      return
-    }
-
-    if (timerId !== undefined) {
-      clearTimeout(timerId)
-    }
-
-    timerId = setTimeout(() => {
-      fn(...args)
-    }, ms)
-  }
-}