@storve/core 1.0.0

package/src/persist/serialize.ts

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

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

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

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

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

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

package/src/store.ts

@@ -0,0 +1,250 @@
+import { Store, StoreDefinition, Listener, StoreOptions, StoreState, StoreActions } from './types'
+import { createStateProxy } from './proxy'
+import { produce } from 'immer'
+import { isBatching, subscribeToBatch } from './batch'
+import { getExtensions } from './registry'
+
+/**
+ * Creates a reactive store with auto-tracking features via Proxies.
+ * Any mutations to the state via setState or directly to deep objects will notify subscribers.
+ * Extensions (async, computed) register when their modules are imported and extend the store.
+ *
+ * @param definition - The initial state object including optional actions.
+ * @param options - Configuration options for the store (e.g., immer).
+ * @returns A generic store instance with getState, setState, subscribe, batch, and actions.
+ */
+export function createStore<D extends object>(
+    definition: StoreDefinition<D>,
+    options: StoreOptions = {}
+): Store<D> {
+    const { actions: rawActions = {}, ...initialData } =
+        definition as D & { actions?: Record<string, (...args: unknown[]) => unknown> }
+
+    let workingData: Record<string, unknown> = { ...initialData }
+    const allAsyncInits: Array<{ key: string; init: (onUpdate: (state: unknown) => void) => unknown }> = []
+    const readOnlyKeys = new Set<string>()
+    const onStateChangedCallbacks: Array<(ctx: {
+        changedKeys: Set<string>;
+        getState: () => Record<string, unknown>;
+        setComputed: (key: string, value: unknown) => void;
+        store: Store<D>;
+    }) => void> = []
+
+    // Run extension pipeline
+    for (const ext of getExtensions()) {
+        if (ext.processDefinition) {
+            const result = ext.processDefinition(workingData)
+            workingData = { ...workingData, ...result.state }
+            if (result.asyncInits) allAsyncInits.push(...result.asyncInits)
+            if (result.readOnlyKeys) result.readOnlyKeys.forEach((k) => readOnlyKeys.add(k))
+            if (result.onStateChanged) onStateChangedCallbacks.push(result.onStateChanged)
+        }
+    }
+
+    // Run async inits — use ref so callback can call setState before store is assigned
+    const setStateRef: { current: ((p: Partial<StoreState<D>>) => void) | null } = { current: null }
+    const engines = new Map<string, unknown>()
+    for (const { key, init } of allAsyncInits) {
+        const engine = init((nodeState) => {
+            setStateRef.current?.({ [key]: nodeState } as Partial<StoreState<D>>)
+        })
+        engines.set(key, engine)
+        workingData[key] = (engine as { getState: () => unknown }).getState()
+    }
+
+    const initialState = workingData as StoreState<D>
+    const listeners = new Set<Listener<StoreState<D>>>()
+    let currentState = initialState as StoreState<D>
+    let batchCount = 0
+    let batchDirty = false
+    let unsubscribeBatch: (() => void) | null = null
+    let pendingChangedKeys = new Set<string>()
+    let lastSnapshot: StoreState<D> | null = null
+    let lastSnapshotState: StoreState<D> | null = null
+
+    const notify = () => {
+        if (batchCount > 0 || isBatching()) {
+            batchDirty = true
+            return
+        }
+        batchDirty = false
+        listeners.forEach((listener) => listener(currentState))
+    }
+
+    const runOnStateChanged = (changedKeys: Set<string>) => {
+        const setComputed = (key: string, value: unknown) => {
+            (currentState as Record<string, unknown>)[key] = value
+        }
+        for (const cb of onStateChangedCallbacks) {
+            cb({
+                changedKeys,
+                getState: () => currentState as Record<string, unknown>,
+                setComputed,
+                store,
+            })
+        }
+    }
+
+    const proxyState = createStateProxy(initialState, notify)
+
+    const setState = (
+        updater:
+            | Partial<StoreState<D>>
+            | ((s: StoreState<D>) => Partial<StoreState<D>>)
+            | ((draft: StoreState<D>) => void)
+    ) => {
+        let nextState: StoreState<D>
+
+        if (typeof updater === 'function') {
+            if (options.immer) {
+                nextState = produce(currentState, updater as (draft: StoreState<D>) => void) as StoreState<D>
+            } else {
+                nextState = {
+                    ...currentState,
+                    ...(updater as (s: StoreState<D>) => Partial<StoreState<D>>)(currentState),
+                }
+            }
+        } else {
+            nextState = { ...currentState, ...updater }
+        }
+
+        if (nextState === currentState) return
+
+        const writableNext = { ...nextState } as Record<string, unknown>
+        readOnlyKeys.forEach((k) => delete writableNext[k])
+        const prevState = currentState
+        const updatedKeys = new Set(
+            Object.keys(writableNext).filter(
+                (k) => (prevState as Record<string, unknown>)[k] !== writableNext[k]
+            )
+        )
+        // Notify even if no keys changed, because signals or other extensions might care about 
+        // derived changes or reference-based equality in transforms.
+        // if (updatedKeys.size === 0) return
+
+        currentState = { ...currentState, ...writableNext } as StoreState<D>
+
+        if (batchCount > 0 || isBatching()) {
+            updatedKeys.forEach((k) => pendingChangedKeys.add(k))
+            batchDirty = true
+        } else {
+            runOnStateChanged(updatedKeys)
+        }
+
+        lastSnapshot = null
+        lastSnapshotState = null
+
+        batchCount++
+        try {
+            for (const key in currentState) {
+                if (
+                    Object.prototype.hasOwnProperty.call(currentState, key) &&
+                    (currentState as Record<string, unknown>)[key] !==
+                        (prevState as Record<string, unknown>)[key]
+                ) {
+                    (proxyState as Record<string, unknown>)[key] =
+                        currentState[key as keyof StoreState<D>]
+                }
+            }
+        } finally {
+            batchCount--
+        }
+
+        if (batchCount > 0) {
+            batchDirty = true
+        } else {
+            notify()
+        }
+    }
+
+    setStateRef.current = setState
+
+    const store = {
+        getState: () => {
+            if (lastSnapshot !== null && lastSnapshotState === currentState) {
+                return lastSnapshot
+            }
+            const snapshot = { ...currentState } as StoreState<D>
+            lastSnapshot = snapshot
+            lastSnapshotState = currentState
+            return snapshot
+        },
+
+        setState,
+
+        subscribe: (listener: Listener<StoreState<D>>) => {
+            listeners.add(listener)
+            if (listeners.size === 1) {
+                unsubscribeBatch = subscribeToBatch(() => {
+                    if (batchDirty) {
+                        batchDirty = false
+                        runOnStateChanged(pendingChangedKeys)
+                        pendingChangedKeys = new Set()
+                        notify()
+                    }
+                })
+                if (batchDirty) {
+                    batchDirty = false
+                    runOnStateChanged(pendingChangedKeys)
+                    pendingChangedKeys = new Set()
+                    notify()
+                }
+            }
+            return () => {
+                listeners.delete(listener)
+                if (listeners.size === 0) {
+                    unsubscribeBatch?.()
+                    unsubscribeBatch = null
+                }
+            }
+        },
+
+        batch: (fn: () => void) => {
+            batchCount++
+            try {
+                fn()
+            } finally {
+                batchCount--
+                if (batchCount === 0 && batchDirty) {
+                    batchDirty = false
+                    runOnStateChanged(pendingChangedKeys)
+                    pendingChangedKeys = new Set()
+                    notify()
+                }
+            }
+        },
+
+        actions: {} as StoreActions<D>,
+
+        // Default async stubs — overwritten by async extension when engines exist
+        fetch: async (key: string) => {
+            throw new Error(`Storve: no async key "${key}" found in store. Import "storve/async" to use createAsync.`);
+        },
+        refetch: async () => {},
+        invalidate: () => {},
+        invalidateAll: () => {},
+        getAsyncState: () => undefined,
+    } as Store<D>
+
+    // Add methods from extensions (async overwrites stubs when engines exist)
+    for (const ext of getExtensions()) {
+        if (ext.extendStore) {
+            const methods = ext.extendStore({ engines, store: store as unknown as Store<object>, definition: definition as object })
+            Object.defineProperties(store, Object.getOwnPropertyDescriptors(methods))
+        }
+    }
+
+    // Trigger initial onStateChanged for extensions (e.g. devtools init)
+    runOnStateChanged(new Set(Object.keys(currentState)))
+
+    type RawActionsType = Record<string, (...args: unknown[]) => unknown>
+    const boundActions = {} as StoreActions<D>
+    Object.keys(rawActions).forEach((key) => {
+        (boundActions as RawActionsType)[key] = (...args: unknown[]) =>
+            (rawActions as RawActionsType)[key](...args)
+    })
+    Object.assign(store, boundActions)
+    store.actions = boundActions
+
+    return store
+}

package/src/sync/channel.ts

@@ -0,0 +1,15 @@
+/**
+ * Opens a BroadcastChannel if available in the current environment.
+ * Gracefully returns null in SSR or older browsers.
+ * @internal
+ */
+export function openChannel(name: string): BroadcastChannel | null {
+    if (typeof window === 'undefined') return null;
+    if (typeof BroadcastChannel === 'undefined') return null;
+    try {
+        return new BroadcastChannel(name);
+    } catch {
+        /* v8 ignore next 2 */
+        return null;
+    }
+}

package/src/sync/index.ts

@@ -0,0 +1,3 @@
+/* v8 ignore next 10 */
+export { withSync } from './withSync';
+export type { SyncOptions } from './withSync';

package/src/sync/protocol.ts

@@ -0,0 +1,18 @@
+/**
+ * Random tab ID generated once per tab session.
+ */
+export const tabId = (function () {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return Math.random().toString(36).substring(2, 11);
+})();
+
+/**
+ * Message types for cross-tab synchronization.
+ * @template S - The state type
+ */
+export type SyncMessage<S> =
+    | { type: 'STATE_UPDATE'; payload: Partial<S>; tabId: string }
+    | { type: 'REQUEST_STATE'; tabId: string }
+    | { type: 'PROVIDE_STATE'; payload: S; targetTabId: string; tabId: string };