@storve/core 1.0.0

package/src/devtools/withDevtools.ts

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

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

package/src/index.ts

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

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

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

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

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

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

package/src/persist/hydrate.ts

@@ -0,0 +1,60 @@
+import type { PersistAdapter } from './index.js'
+import { fromJSON } from './serialize.js'
+
+type PersistedWrapper<T> = Partial<T> & { __version?: number }
+
+/**
+ * Hydrates state from a persistence adapter.
+ * Handles reading from the adapter, JSON parsing, version checking, and migration.
+ *
+ * @template T - The state object type.
+ * @param {PersistAdapter} adapter - The persistence adapter to read from.
+ * @param {string} key - The unique namespace/key for the store in the adapter.
+ * @param {T} currentState - The current store state.
+ * @param {number} version - The expected state version.
+ * @param {(persisted: Partial<T>, version: number) => Partial<T>} [migrate] - Optional migration function.
+ * @returns {Promise<Partial<T>>} A promise that resolves to the hydrated partial state (or an empty object).
+ */
+export async function hydrate<T extends object>(
+  adapter: PersistAdapter,
+  key: string,
+  currentState: T,
+  version: number,
+  migrate?: (persisted: Partial<T>, version: number) => Partial<T>
+): Promise<Partial<T>> {
+  const raw = await adapter.getItem(key)
+  if (!raw) {
+    return {}
+  }
+
+  let parsed: PersistedWrapper<T>
+  try {
+    parsed = fromJSON<PersistedWrapper<T>>(raw)
+  } catch (err) {
+    console.warn(`[storve] Hydration failed for key "${key}":`, err)
+    return {}
+  }
+
+  const persistedVersion = parsed.__version !== undefined ? parsed.__version : 0
+
+  let finalState: Partial<T>
+
+  if (persistedVersion !== version) {
+    if (migrate !== undefined) {
+      finalState = migrate(parsed, persistedVersion)
+    } else {
+      console.warn(
+        `Storve: persisted state version mismatch (stored: ${persistedVersion}, expected: ${version}). No migrate function provided — falling back to default state.`
+      )
+      return {} // stale data, no migration path
+    }
+  } else {
+    finalState = parsed
+  }
+
+  // Strip __version from the final state to be merged
+  const cleaned: PersistedWrapper<T> = { ...finalState }
+  delete cleaned.__version
+  
+  return cleaned
+}

package/src/persist/index.ts

@@ -0,0 +1,141 @@
+import type { Store, StoreState } from '../types.js'
+import { pick, toJSON } from './serialize.js'
+import { createDebounce } from './debounce.js'
+import { hydrate } from './hydrate.js'
+
+/**
+ * Core interface for Storve persistence adapters.
+ * All adapters must implement these three methods to be compatible.
+ * Depending on the underlying storage, methods can be sync or async.
+ */
+export interface PersistAdapter {
+  getItem(key: string): string | null | Promise<string | null>
+  setItem(key: string, value: string): void | Promise<void>
+  removeItem(key: string): void | Promise<void>
+}
+
+/**
+ * Options for configuring persistence.
+ * @template T - The state type of the store.
+ */
+export interface PersistOptions<T> {
+  key: string
+  adapter: PersistAdapter
+  pick?: Array<keyof T>
+  version?: number
+  migrate?: (persisted: Partial<T>, version: number) => Partial<T>
+  debounce?: number
+}
+
+// Internal type guard to distinguish options from store while preserving D
+function isPersistOptions<D extends object>(
+  obj: Store<D> | PersistOptions<StoreState<D>>
+): obj is PersistOptions<StoreState<D>> {
+  return obj !== null && typeof obj === 'object' && 'adapter' in obj && 'key' in obj
+}
+
+// Internal helper for withPersist to avoid signature overload complexities
+function createEnhancedStore<D extends object>(
+  store: Store<D>,
+  options: PersistOptions<StoreState<D>>
+): Store<D> & { hydrated: Promise<void> } {
+  let resolveHydrated!: () => void
+  const hydrated = new Promise<void>((resolve) => {
+    resolveHydrated = resolve
+  })
+
+  const version = options.version !== undefined ? options.version : 1
+  const debounceMs = options.debounce !== undefined ? options.debounce : 100
+
+  // 1. Kick off hydration immediately
+  hydrate<StoreState<D>>(
+    options.adapter,
+    options.key,
+    store.getState(),
+    version,
+    options.migrate
+  ).then((hydratedState) => {
+    // Merge result into store via setState
+    store.setState(hydratedState)
+    resolveHydrated()
+  }).catch(
+    /* v8 ignore next 4 */
+    (err: unknown) => {
+      console.warn(`[storve] withPersist hydrate error for key "${options.key}":`, err)
+      resolveHydrated()
+    }
+  )
+
+  // 2. Setup debounced exact writes
+  const debouncedWrite = createDebounce((serialized: string) => {
+    const result = options.adapter.setItem(options.key, serialized)
+    
+    if (result && typeof result.catch === 'function') {
+      /* v8 ignore next 4 */
+      result.catch((e: unknown) => {
+        console.warn(`[storve] Failed to persist state for key "${options.key}":`, e)
+      })
+    }
+  }, debounceMs)
+
+  // Keep a reference to the last persisted picked state
+  const initialPicked = options.pick && options.pick.length > 0
+    ? pick(store.getState(), options.pick)
+    : { ...store.getState() }
+  let lastPersistedSnapshot: string | null = toJSON({ ...initialPicked, __version: version })
+
+  // 3. Subscribe to store changes to trigger writes
+  store.subscribe((newState) => {
+    // 1. Extract only the picked keys (or full state if no pick option)
+    const picked = options.pick && options.pick.length > 0
+      ? pick(newState, options.pick)
+      : { ...newState }
+
+    // 2. Serialize to compare
+    const serialized = toJSON({ ...picked, __version: version })
+
+    // 3. Skip write if nothing changed in the picked portion
+    if (serialized === lastPersistedSnapshot) return
+
+    // 4. Update snapshot reference and write
+    lastPersistedSnapshot = serialized
+    debouncedWrite(serialized)
+  })
+
+  return {
+    ...store,
+    hydrated
+  }
+}
+
+/**
+ * Enhances a Storve store with continuous automatic persistence.
+ * Can be called directly or curried for use with compose().
+ */
+export function withPersist<D extends object>(
+  store: Store<D>,
+  options: PersistOptions<StoreState<D>>
+): Store<D> & { hydrated: Promise<void> }
+
+export function withPersist<D extends object>(
+  options: PersistOptions<StoreState<D>>
+): (store: Store<D>) => Store<D> & { hydrated: Promise<void> }
+
+export function withPersist<D extends object>(
+  storeOrOptions: Store<D> | PersistOptions<StoreState<D>>,
+  options?: PersistOptions<StoreState<D>>
+): (Store<D> & { hydrated: Promise<void> }) | ((store: Store<D>) => Store<D> & { hydrated: Promise<void> }) {
+  if (options !== undefined) {
+    if (!isPersistOptions(storeOrOptions)) {
+      return createEnhancedStore(storeOrOptions, options)
+    }
+  }
+  
+  if (isPersistOptions(storeOrOptions)) {
+    return (store: Store<D>) => createEnhancedStore(store, storeOrOptions)
+  }
+
+  /* v8 ignore next 2 */
+  throw new Error('[storve] Invalid withPersist arguments')
+}
+