@storve/core 1.0.1 → 1.0.3

package/src/persist/hydrate.ts

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

@@ -1,141 +0,0 @@
-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')
-}
-

package/src/persist/serialize.ts

@@ -1,60 +0,0 @@
-/**
- * Returns a new object with only the specified keys from state.
- * If keys is undefine or empty, returns the full state.
- *
- * @template T - The state object type.
- * @param {T} state - The complete state object.
- * @param {Array<keyof T>} [keys] - The keys to pick.
- * @returns {Partial<T> | T} A new object with picked keys, or the original state.
- */
-export function pick<T extends object>(state: T, keys?: Array<keyof T>): Partial<T> | T {
-  if (keys === undefined || keys.length === 0) {
-    return { ...state }
-  }
-  
-  const result: Partial<T> = {}
-  
-  for (let i = 0; i < keys.length; i++) {
-    const key = keys[i]
-    if (key in state) {
-      result[key] = state[key]
-    }
-  }
-  
-  return result
-}
-
-/**
- * Safely stringifies a value to JSON, throwing a clear error if it fails.
- *
- * @param {unknown} value - The object or value to serialize.
- * @returns {string} The JSON string representation.
- * @throws {Error} Throws a detailed error if JSON.stringify fails.
- */
-export function toJSON(value: unknown): string {
-  try {
-    return JSON.stringify(value)
-  } catch (err) {
-    throw new Error(`[storve] Failed to serialize state to JSON: ${err instanceof Error ? err.message : String(err)}`)
-  }
-}
-
-/**
- * Safely parses a JSON string, throwing a clear error if parsing fails or if the string is empty/null.
- *
- * @template T - The expected output type.
- * @param {string} raw - The string to parse.
- * @returns {T} The typed parsed JSON object.
- * @throws {Error} Throws if 'raw' is empty or if JSON.parse fails.
- */
-export function fromJSON<T>(raw: string): T {
-  if (!raw) {
-    throw new Error('[storve] Cannot parse empty or null/undefined JSON string.')
-  }
-  try {
-    const parsed: T = JSON.parse(raw)
-    return parsed
-  } catch (err) {
-    throw new Error(`[storve] Failed to parse JSON state: ${err instanceof Error ? err.message : String(err)}`)
-  }
-}

package/src/proxy.ts

@@ -1,87 +0,0 @@
-const proxyMap = new WeakMap<object, object>();
-const rawMap = new WeakMap<object, object>();
-
-let isBatching = false;
-
-function isPlainObjectOrArray(value: unknown): value is object {
-    if (value === null || typeof value !== 'object') return false;
-    const proto = Object.getPrototypeOf(value);
-    return proto === Object.prototype || Array.isArray(value);
-}
-
-export function createStateProxy<T extends object>(state: T, onChange: () => void): T {
-    if (!isPlainObjectOrArray(state)) {
-        return state;
-    }
-
-    if (proxyMap.has(state)) {
-        return proxyMap.get(state) as T;
-    }
-
-    if (rawMap.has(state)) {
-        return state; // It's already a proxy
-    }
-
-    const handler: ProxyHandler<T> = {
-        get(target, prop, receiver) {
-            if (Array.isArray(target) && typeof prop === 'string' && ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'].includes(prop)) {
-                return (...args: unknown[]) => {
-                    const prevBatching = isBatching;
-                    isBatching = true;
-
-                    const method = Reflect.get(target, prop, receiver) as (...a: unknown[]) => unknown;
-                    const result = Reflect.apply(method, receiver, args);
-
-                    isBatching = prevBatching;
-                    if (!isBatching) {
-                        onChange();
-                    }
-                    return result;
-                };
-            }
-
-            const value = Reflect.get(target, prop, receiver);
-            if (isPlainObjectOrArray(value) && proxyMap.has(value)) {
-                return proxyMap.get(value);
-            }
-            return value;
-        },
-        set(target, prop, value, receiver) {
-            // Unpack if value is a proxy itself
-            const rawValue = rawMap.has(value as object) ? rawMap.get(value as object) : value;
-
-            // Immediately wrap new nested objects
-            if (isPlainObjectOrArray(rawValue)) {
-                createStateProxy(rawValue as object, onChange);
-            }
-
-            const result = Reflect.set(target, prop, rawValue, receiver);
-
-            // Trigger listeners on write
-            if (!isBatching) onChange();
-
-            return result;
-        },
-        deleteProperty(target, prop) {
-            const result = Reflect.deleteProperty(target, prop);
-            if (!isBatching) onChange();
-            return result;
-        }
-    };
-
-    const proxy = new Proxy(state, handler);
-    proxyMap.set(state, proxy);
-    rawMap.set(proxy, state);
-
-    // Recursively proxy existing nested objects upfront
-    for (const key in state) {
-        if (Object.prototype.hasOwnProperty.call(state, key)) {
-            const val = state[(key as keyof typeof state)];
-            if (isPlainObjectOrArray(val)) {
-                createStateProxy(val as object, onChange);
-            }
-        }
-    }
-
-    return proxy;
-}

package/src/registry.ts

@@ -1,67 +0,0 @@
-import type { Store } from './types';
-
-/**
- * Extension registry for store plugins.
- * Features register when imported; createStore applies all registered extensions.
- * @internal
- */
-
-export interface ProcessDefinitionResult {
-    state: Record<string, unknown>;
-    engines?: Map<string, unknown>;
-    /** Async keys to init after store has setState. Each init receives (onUpdate) => engine. */
-    asyncInits?: Array<{ key: string; init: (onUpdate: (state: unknown) => void) => unknown }>;
-    readOnlyKeys?: Set<string>;
-    /** Called when state changes. Extensions can recompute derived values via setComputed. */
-    onStateChanged?: (ctx: {
-        changedKeys: Set<string>;
-        getState: () => Record<string, unknown>;
-        setComputed: (key: string, value: unknown) => void;
-        store: unknown;
-    }) => void;
-}
-
-export interface ExtensionContext {
-    engines: Map<string, unknown>;
-    store: Store<object>;
-    definition: object;
-}
-
-
-
-export interface StoreExtension {
-    /** Unique key to avoid double registration */
-    key: string;
-    /** Process definition values before store init. Return modified state + optional metadata. */
-    processDefinition?: (definition: Record<string, unknown>) => ProcessDefinitionResult;
-    /** Add methods to the store. Called after store is created. */
-    extendStore?: (context: ExtensionContext) => Record<string, unknown>;
-}
-
-const extensions: StoreExtension[] = [];
-
-/**
- * Register an extension. Called by feature modules on import (side-effect).
- * @internal
- */
-export function registerExtension(ext: StoreExtension & { order?: number }): void {
-    if (extensions.some((e) => e.key === ext.key)) return;
-    extensions.push(ext);
-    extensions.sort((a, b) => ((a as { order?: number }).order ?? 99) - ((b as { order?: number }).order ?? 99));
-}
-
-/**
- * Get all registered extensions. Used by createStore.
- * @internal
- */
-export function getExtensions(): readonly StoreExtension[] {
-    return extensions;
-}
-
-/**
- * Clear all extensions. For testing only.
- * @internal
- */
-export function __testingOnlyClearExtensions(): void {
-    extensions.length = 0
-}

package/src/signals/createSignal.ts

@@ -1,81 +0,0 @@
-import type { Store, StoreState } from '../types';
-import type { Signal } from './index';
-
-/**
- * Creates a Signal that subscribes to a specific key in a Storve store.
- * Signals provide fine-grained reactivity by only notifying listeners when
- * the specific key's value changes.
- *
- * @example
- * const countSignal = signal(store, 'count');
- */
-export function signal<D extends object, K extends keyof StoreState<D>>(
-    store: Store<D>,
-    key: K
-): Signal<StoreState<D>[K]>;
-
-/**
- * Creates a derived read-only Signal that transforms a value from the store.
- *
- * @example
- * const doubleSignal = signal(store, 'count', v => v * 2);
- */
-export function signal<D extends object, K extends keyof StoreState<D>, R>(
-    store: Store<D>,
-    key: K,
-    transform: (value: StoreState<D>[K]) => R
-): Signal<R>;
-
-export function signal<D extends object, K extends keyof StoreState<D>, R>(
-    store: Store<D>,
-    key: K,
-    transform?: (value: StoreState<D>[K]) => R
-): Signal<R | StoreState<D>[K]> {
-    const isDerived = !!transform;
-
-    const get = () => {
-        const value = store.getState()[key];
-        return transform ? transform(value) : value;
-    };
-
-    const signalInstance = {
-        get,
-        set(value: StoreState<D>[K] | ((prev: StoreState<D>[K]) => StoreState<D>[K])) {
-            if (isDerived) {
-                throw new Error(
-                    'Storve: cannot call set() on a derived signal. Derived signals are read-only.'
-                );
-            }
-            const next =
-                typeof value === 'function'
-                    ? (value as (prev: StoreState<D>[K]) => StoreState<D>[K])(store.getState()[key])
-                    : value;
-            store.setState({ [key]: next } as Partial<StoreState<D>>);
-        },
-        subscribe(listener: (value: R | StoreState<D>[K]) => void) {
-            let prev = transform
-                ? transform(store.getState()[key])
-                : (store.getState()[key] as R | StoreState<D>[K]);
-
-            return store.subscribe(() => {
-                const next = transform
-                    ? transform(store.getState()[key])
-                    : (store.getState()[key] as R | StoreState<D>[K]);
-
-                if (Object.is(prev, next)) return;
-                prev = next;
-                listener(next);
-            });
-        },
-        _derived: isDerived,
-    };
-
-    return new Proxy(signalInstance, {
-        set(target, prop, value) {
-            if (prop === '_derived') {
-                return true; // Silently ignore writes to _derived
-            }
-            return Reflect.set(target, prop, value);
-        },
-    }) as Signal<R | StoreState<D>[K]>;
-}

package/src/signals/index.ts

@@ -1,20 +0,0 @@
-/**
- * A subscribable reference to a single key in a Storve store.
- * Read-only signals (derived) throw a clear error when set() is called.
- */
-export interface Signal<T> {
-    /** Returns the current value of this signal */
-    get(): T;
-    /**
-     * Sets a new value. Throws if called on a derived (read-only) signal.
-     * Writes back to the store — the store remains the single source of truth.
-     */
-    set(value: T | ((prev: T) => T)): void;
-    /** Subscribe to value changes. Returns an unsubscribe function. */
-    subscribe(listener: (value: T) => void): () => void;
-    /** Internal flag — true if this is a derived read-only signal */
-    readonly _derived: boolean;
-}
-
-export { signal } from './createSignal';
-export { useSignal } from './useSignal';

package/src/signals/useSignal.ts

@@ -1,18 +0,0 @@
-import { useSyncExternalStore } from 'react';
-import type { Signal } from './index';
-
-/**
- * React hook that subscribes to a Signal and returns its current value.
- * The component re-renders ONLY when this signal's value changes.
- * Unrelated store key changes are completely ignored.
- *
- * @example
- * const count = useSignal(countSignal) // re-renders only when count changes
- */
-export function useSignal<T>(signal: Signal<T>): T {
-    return useSyncExternalStore(
-        (onStoreChange: () => void) => signal.subscribe(onStoreChange),
-        () => signal.get(),
-        () => signal.get()
-    );
-}