@storve/core 1.0.1 → 1.0.3

package/src/store.ts

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

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

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

package/src/sync/protocol.ts

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

package/src/sync/withSync.ts

@@ -1,147 +0,0 @@
-import { registerExtension } from '../registry';
-import { openChannel } from './channel';
-import { tabId, SyncMessage } from './protocol';
-import type { Store, StoreState } from '../types';
-
-/**
- * Options for configuring cross-tab synchronization.
- */
-export interface SyncOptions {
-    /** Unique name for the BroadcastChannel */
-    channel: string;
-    /** Optional list of keys to sync. If omitted, all keys are synced. */
-    keys?: string[];
-    /** Whether sync is enabled (default true) */
-    enabled?: boolean;
-}
-
-/** @internal Symbol marker to store sync options on the definition object */
-const SYNC_OPTIONS = Symbol('storve_sync_options');
-
-/**
- * Wraps a store definition with cross-tab synchronization.
- * Updates to the store will be broadcast to other tabs via BroadcastChannel.
- */
-export function withSync<D extends object>(
-    definition: D,
-    options: SyncOptions
-): D {
-    Object.defineProperty(definition, SYNC_OPTIONS, {
-        value: options,
-        enumerable: false,
-        configurable: true
-    });
-    return definition;
-}
-
-registerExtension({
-    key: 'sync',
-    extendStore: (context) => {
-        const { store, definition } = context as { store: Store<object>; definition: object };
-        const options = (definition as Record<symbol, unknown>)[SYNC_OPTIONS] as SyncOptions | undefined;
-
-        if (!options || options.enabled === false) return {};
-
-        const channel = openChannel(options.channel);
-        if (!channel) return {};
-
-        let isSyncUpdate = false;
-        let rehydrated = false;
-
-        // 1. Function to build payload based on selective keys and changes
-        const buildPayload = (nextState: Record<string, unknown>, prevState: Record<string, unknown>) => {
-            const keysToSync = options.keys || Object.keys(nextState);
-            const payload: Record<string, unknown> = {};
-            let hasChanges = false;
-            
-            for (const key of keysToSync) {
-                // Skip internal symbols or non-enumerable props that might have leaked
-                if (typeof key === 'symbol') continue;
-                
-                if (nextState[key] !== prevState[key]) {
-                    payload[key] = nextState[key];
-                    hasChanges = true;
-                }
-            }
-            return hasChanges ? payload : null;
-        };
-
-        // 2. Wrap setState to broadcast local changes
-        const originalSetState = store.setState.bind(store);
-        store.setState = (updater) => {
-            const prevState = { ...store.getState() as Record<string, unknown> };
-            originalSetState(updater);
-            if (!isSyncUpdate) {
-                const nextState = store.getState() as Record<string, unknown>;
-                const payload = buildPayload(nextState, prevState);
-                if (payload) {
-                    channel.postMessage({
-                        type: 'STATE_UPDATE',
-                        payload,
-                        tabId
-                    });
-                }
-            }
-        };
-
-        // 3. Handle incoming messages
-        channel.onmessage = (event) => {
-            const data = event.data as SyncMessage<Record<string, unknown>>;
-            
-            // Ignore messages from self
-            if (data.tabId === tabId) return;
-
-            switch (data.type) {
-                case 'STATE_UPDATE': {
-                    isSyncUpdate = true;
-                    store.setState(data.payload as Partial<StoreState<object>>);
-                    isSyncUpdate = false;
-                    break;
-                }
-                case 'REQUEST_STATE': {
-                    // Provide current state to the requesting tab, filtered by sync keys
-                    const currentState = store.getState() as Record<string, unknown>;
-                    const payload: Record<string, unknown> = {};
-                    const keysToSync = options.keys || Object.keys(currentState);
-                    
-                    for (const key of keysToSync) {
-                        if (typeof key === 'symbol') continue;
-                        if (key in currentState) {
-                            payload[key] = currentState[key];
-                        }
-                    }
-
-                    channel.postMessage({
-                        type: 'PROVIDE_STATE',
-                        payload,
-                        targetTabId: data.tabId,
-                        tabId
-                    });
-                    break;
-                }
-                case 'PROVIDE_STATE': {
-                    // Only apply if it's targeted at us and we haven't rehydrated yet
-                    if (data.targetTabId === tabId && !rehydrated) {
-                        rehydrated = true;
-                        isSyncUpdate = true;
-                        store.setState(data.payload as Partial<StoreState<object>>);
-                        isSyncUpdate = false;
-                    }
-                    break;
-                }
-            }
-        };
-
-        // 4. Trigger rehydration request
-        channel.postMessage({ type: 'REQUEST_STATE', tabId });
-
-        // 5. Cleanup on channel if possible (BroadcastChannel doesn't have a direct destroy hook in our store, 
-        // but it's good practice to close it if the store were to be destroyed).
-        // Since Storve stores are usually singletons per-tab, we rely on browser cleanup,
-        // but we can expose a close method.
-        
-        return {
-            __sync_channel: channel, // for testing
-        };
-    }
-});

package/src/types.ts

@@ -1,159 +0,0 @@
-import type { ComputedValue } from './computed';
-
-/** @internal */
-export const ASYNC_VALUE_MARKER = '__rf_async';
-
-/** Re-export for consumers. Defined in computed.ts. */
-export type { ComputedValue } from './computed';
-
-/**
- * Status of an async operation.
- */
-export type AsyncStatus = 'idle' | 'loading' | 'success' | 'error';
-
-/**
- * The shape of an async state value in the store.
- */
-export interface AsyncState<T> {
-    /** The resolved data or null */
-    data: T | null;
-    /** Error message if the operation failed */
-    error: string | null;
-    /** Current status of the operation */
-    status: AsyncStatus;
-    /** Derived from status === 'loading' */
-    loading: boolean;
-    /** Re-runs the async function with the last used arguments */
-    refetch: () => Promise<void>;
-}
-
-/**
- * Configuration options for an async value.
- */
-export interface AsyncOptions {
-    /** Cache TTL in milliseconds. Default: 0 (no cache) */
-    ttl?: number;
-    /** Enable stale-while-revalidate behavior. Default: false */
-    staleWhileRevalidate?: boolean;
-}
-
-/**
- * Internal interface for the async engine.
- */
-export interface IAsyncEngine<T> {
-    getState: () => AsyncState<T>;
-    fetch: (...args: unknown[]) => Promise<void>;
-    refetch: () => Promise<void>;
-    invalidate: () => void;
-}
-
-/**
- * Internal marker for values created via createAsync().
- * Use this to distinguish async definitions from sync state.
- */
-export interface AsyncValue<T> {
-    readonly [ASYNC_VALUE_MARKER]: true;
-    init: (onUpdate: (s: AsyncState<T>) => void) => IAsyncEngine<T>;
-}
-
-/** Keys of the definition that are computed values (read-only in setState). */
-export type ComputedKeys<D> = {
-    [K in keyof Omit<D, 'actions'>]: Omit<D, 'actions'>[K] extends ComputedValue<unknown> ? K : never;
-}[keyof Omit<D, 'actions'>];
-
-/**
- * State shape with computed keys omitted. Use for setState payloads so TS flags setting computed keys.
- */
-export type WritableStoreState<D> = Omit<StoreState<D>, ComputedKeys<D>>;
-
-/**
- * Utility to extract state, omitting the actions key and unwrapping AsyncValues and ComputedValues.
- */
-export type StoreState<D> = {
-    [K in keyof Omit<D, 'actions'>]: Omit<D, 'actions'>[K] extends AsyncValue<infer T>
-        ? AsyncState<T>
-        : Omit<D, 'actions'>[K] extends ComputedValue<infer T>
-          ? T
-          : Omit<D, 'actions'>[K];
-};
-
-/**
- * Utility to extract actions from the definition.
- */
-export type StoreActions<D> = D extends { actions: infer A } ? A : Record<string, never>;
-
-/**
- * The shape of initial state passed to createStore.
- * D represents the full definition including optional actions.
- */
-export type StoreDefinition<D extends object> = D;
-
-/**
- * Configuration options for the store.
- */
-export interface StoreOptions {
-    /**
-     * Enable Immer for mutation-style state updates.
-     * @default false
-     */
-    immer?: boolean;
-}
-
-// Listener callback — called on every state change
-export type Listener<T> = (state: T) => void;
-
-// Returned by subscribe() — call to stop listening
-export type Unsubscribe = () => void;
-
-/**
- * The store instance returned by createStore().
- */
-export type Store<D extends object> = {
-    /**
-     * Returns the current state snapshot.
-     */
-    getState: () => StoreState<D>;
-    /**
-     * Updates the state. Supports partial objects, updaters, and Immer mutators.
-     * Computed keys are read-only; passing them in the payload is a type error and is ignored at runtime.
-     */
-    setState: (
-        updater:
-            | Partial<WritableStoreState<D>>
-            | ((state: StoreState<D>) => Partial<WritableStoreState<D>>)
-            | ((draft: StoreState<D>) => void)
-    ) => void;
-    /**
-     * Subscribes to state changes.
-     */
-    subscribe: (listener: Listener<StoreState<D>>) => Unsubscribe;
-    /**
-     * Batches multiple state updates to trigger only one notification.
-     */
-    batch: (fn: () => void) => void;
-    /**
-     * Stable reference to the store's actions.
-     */
-    actions: StoreActions<D>;
-
-    /**
-     * Triggers an async fetch for a specific key.
-     */
-    fetch: (key: keyof StoreState<D>, ...args: unknown[]) => Promise<void>;
-    /**
-     * Re-runs the async operation for a key with the last used arguments.
-     */
-    refetch: (key: keyof StoreState<D>) => Promise<void>;
-    /**
-     * Invalidates the cache for a specific async key.
-     */
-    invalidate: (key: keyof StoreState<D>) => void;
-    /**
-     * Invalidates all async caches in the store.
-     */
-    invalidateAll: () => void;
-    /**
-     * Gets the raw async state for a key (internal use).
-     */
-    getAsyncState: (key: keyof StoreState<D>) => AsyncState<unknown> | undefined;
-} & StoreActions<D>;