juststore 1.1.2 → 1.2.0

package/dist/src/kv_store.js

@@ -0,0 +1,127 @@
+import { getNestedValue, setNestedValue } from "./impl";
+import { localStorageDelete, localStorageGet, localStorageSet, } from "./local_storage";
+export { getNestedValue, KVStore, setNestedValue };
+class KVStore {
+    inMemStorage;
+    broadcastChannel;
+    memoryOnly;
+    constructor(options) {
+        this.inMemStorage = options.inMemStorage;
+        this.broadcastChannel = options.broadcastChannel;
+        this.memoryOnly = options.memoryOnly;
+    }
+    getBroadcastChannel() {
+        return this.broadcastChannel;
+    }
+    setBroadcastChannel(broadcastChannel) {
+        this.broadcastChannel = broadcastChannel;
+    }
+    get(key) {
+        const [rootKey, path] = splitNSPath(key);
+        // Get root object from memory or localStorage
+        let rootValue;
+        if (this.inMemStorage.has(rootKey)) {
+            rootValue = this.inMemStorage.get(rootKey);
+        }
+        else if (!this.memoryOnly && typeof window !== "undefined") {
+            rootValue = localStorageGet(rootKey);
+            if (rootValue !== undefined) {
+                this.inMemStorage.set(rootKey, rootValue);
+            }
+        }
+        // If no path, return root value
+        if (!path)
+            return rootValue;
+        // Traverse to nested value
+        return getNestedValue(rootValue, path);
+    }
+    set(key, value) {
+        if (value === undefined) {
+            return this.delete(key);
+        }
+        const [rootKey, path] = splitNSPath(key);
+        let rootValue;
+        if (!path) {
+            // Setting root value directly
+            rootValue = value;
+        }
+        else {
+            // Setting nested value
+            const currentRoot = this.inMemStorage.get(rootKey) ?? localStorageGet(rootKey) ?? {};
+            rootValue = setNestedValue(currentRoot, path, value);
+        }
+        // Update memory
+        this.inMemStorage.set(rootKey, rootValue);
+        // Persist to localStorage (unless memoryOnly)
+        if (!this.memoryOnly && typeof window !== "undefined") {
+            localStorageSet(rootKey, rootValue);
+            // Broadcast change to other tabs
+            if (this.broadcastChannel) {
+                this.broadcastChannel.postMessage({
+                    type: "set",
+                    key: rootKey,
+                    value: rootValue,
+                });
+            }
+        }
+    }
+    delete(key) {
+        const [rootKey, path] = splitNSPath(key);
+        if (!path) {
+            // Deleting root key
+            this.inMemStorage.delete(rootKey);
+            if (!this.memoryOnly && typeof window !== "undefined") {
+                localStorageDelete(rootKey);
+                if (this.broadcastChannel) {
+                    this.broadcastChannel.postMessage({ type: "delete", key: rootKey });
+                }
+            }
+        }
+        else {
+            // Deleting nested value
+            const currentRoot = this.inMemStorage.get(rootKey) ?? localStorageGet(rootKey);
+            if (currentRoot !== undefined) {
+                const updatedRoot = setNestedValue(currentRoot, path, undefined);
+                this.inMemStorage.set(rootKey, updatedRoot);
+                if (!this.memoryOnly && typeof window !== "undefined") {
+                    localStorageSet(rootKey, updatedRoot);
+                    if (this.broadcastChannel) {
+                        this.broadcastChannel.postMessage({
+                            type: "set",
+                            key: rootKey,
+                            value: updatedRoot,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    reset() {
+        if (!this.memoryOnly && typeof window !== "undefined") {
+            for (const key of this.inMemStorage.keys()) {
+                localStorageDelete(key);
+            }
+        }
+        this.inMemStorage.clear();
+        if (this.broadcastChannel) {
+            this.broadcastChannel.postMessage({ type: "reset" });
+        }
+    }
+    get size() {
+        return this.inMemStorage.size;
+    }
+}
+/**
+ * Extracts the namespace and path from a full key.
+ *
+ * @param key - Full key string
+ * @returns [namespace, path]
+ * @example
+ * splitNSPath('app.user.name') // ['app', 'user.name']
+ */
+function splitNSPath(key) {
+    const index = key.indexOf(".");
+    if (index === -1)
+        return [key, ""];
+    return [key.slice(0, index), key.slice(index + 1)];
+}

package/dist/src/local_storage.d.ts

@@ -0,0 +1,7 @@
+export { localStorageDelete, localStorageGet, localStorageSet };
+/** Read from localStorage (JSON.parse) with prefix; undefined on SSR or error. */
+declare function localStorageGet(key: string): unknown;
+/** Write to localStorage (JSON.stringify); remove key when value is undefined. */
+declare function localStorageSet(key: string, value: unknown): void;
+/** Delete from localStorage with prefix. */
+declare function localStorageDelete(key: string): void;

package/dist/src/local_storage.js

@@ -0,0 +1,43 @@
+// localStorage operations
+const STORAGE_PREFIX = "juststore:";
+export { localStorageDelete, localStorageGet, localStorageSet };
+/** Read from localStorage (JSON.parse) with prefix; undefined on SSR or error. */
+function localStorageGet(key) {
+    try {
+        if (typeof window === "undefined")
+            return undefined;
+        const item = localStorage.getItem(`${STORAGE_PREFIX}${key}`);
+        return item ? JSON.parse(item) : undefined;
+    }
+    catch (e) {
+        console.error("Failed to get key from localStorage", key, e);
+        return undefined;
+    }
+}
+/** Write to localStorage (JSON.stringify); remove key when value is undefined. */
+function localStorageSet(key, value) {
+    try {
+        if (typeof window === "undefined")
+            return;
+        if (value === undefined) {
+            localStorage.removeItem(`${STORAGE_PREFIX}${key}`);
+        }
+        else {
+            localStorage.setItem(`${STORAGE_PREFIX}${key}`, JSON.stringify(value));
+        }
+    }
+    catch (e) {
+        console.error("Failed to set key in localStorage", key, value, e);
+    }
+}
+/** Delete from localStorage with prefix. */
+function localStorageDelete(key) {
+    try {
+        if (typeof window === "undefined")
+            return;
+        localStorage.removeItem(`${STORAGE_PREFIX}${key}`);
+    }
+    catch (e) {
+        console.error("Failed to delete key from localStorage", key, e);
+    }
+}

package/dist/src/memory.d.ts

@@ -0,0 +1,54 @@
+import type { FieldValues } from "./path";
+import type { State, ValueState } from "./types";
+export { createMemoryStore, type MemoryStore, useMemoryStore };
+/**
+ * A component local store with React bindings.
+ *
+ * - Dot-path addressing for nested values (e.g. "state.ui.theme").
+ * - Immutable partial updates with automatic object/array creation.
+ * - Fine-grained subscriptions built on useSyncExternalStore.
+ * - Type-safe paths using FieldPath.
+ * - Dynamic deep access via Proxy for ergonomic usage like `state.a.b.c.use()` and `state.a.b.c.set(v)`.
+ */
+type MemoryStore<T extends FieldValues> = ValueState<T> & {
+    [K in keyof T]-?: State<T[K]>;
+};
+/**
+ * React hook that creates a component-scoped memory store.
+ *
+ * Unlike `createStore`, this store is not persisted to localStorage and is
+ * unique to each component instance. Useful for complex local state that
+ * benefits from the store's path-based API without persistence.
+ *
+ * @param defaultValue - Initial state shape
+ * @returns A proxy providing dynamic path access to the store
+ *
+ * @example
+ * type SearchState = {
+ *   query: string
+ *   filters: { category: string }
+ *   results: { id: number; name: string }[]
+ * }
+ *
+ * function ProductSearch() {
+ *   const state = useMemoryStore<SearchState>({
+ *     query: '',
+ *     filters: { category: 'all' },
+ *     results: []
+ *   })
+ *
+ *   return (
+ *     <>
+ *       <SearchInput state={state} />
+ *       <FilterPanel state={state} />
+ *     </>
+ *   )
+ * }
+ *
+ * function SearchInput({ state }: { state: MemoryStore<SearchState> }) {
+ *   const query = state.query.use()
+ *   return <input value={query} onChange={e => state.query.set(e.target.value)} />
+ * }
+ */
+declare function useMemoryStore<T extends FieldValues>(defaultValue: T): MemoryStore<T>;
+declare function createMemoryStore<T extends FieldValues>(namespace: string, defaultValue: T): MemoryStore<T>;

package/dist/src/memory.js

@@ -0,0 +1,55 @@
+import { useId } from "react";
+import { createRootNode } from "./node";
+import { createStoreRoot } from "./root";
+export { createMemoryStore, useMemoryStore };
+/**
+ * React hook that creates a component-scoped memory store.
+ *
+ * Unlike `createStore`, this store is not persisted to localStorage and is
+ * unique to each component instance. Useful for complex local state that
+ * benefits from the store's path-based API without persistence.
+ *
+ * @param defaultValue - Initial state shape
+ * @returns A proxy providing dynamic path access to the store
+ *
+ * @example
+ * type SearchState = {
+ *   query: string
+ *   filters: { category: string }
+ *   results: { id: number; name: string }[]
+ * }
+ *
+ * function ProductSearch() {
+ *   const state = useMemoryStore<SearchState>({
+ *     query: '',
+ *     filters: { category: 'all' },
+ *     results: []
+ *   })
+ *
+ *   return (
+ *     <>
+ *       <SearchInput state={state} />
+ *       <FilterPanel state={state} />
+ *     </>
+ *   )
+ * }
+ *
+ * function SearchInput({ state }: { state: MemoryStore<SearchState> }) {
+ *   const query = state.query.use()
+ *   return <input value={query} onChange={e => state.query.set(e.target.value)} />
+ * }
+ */
+function useMemoryStore(defaultValue) {
+    const memoryStoreId = useId();
+    const namespace = `memory:${memoryStoreId}`;
+    const storeApi = createStoreRoot(namespace, defaultValue, {
+        memoryOnly: true,
+    });
+    return createRootNode(storeApi);
+}
+function createMemoryStore(namespace, defaultValue) {
+    const storeApi = createStoreRoot(namespace, defaultValue, {
+        memoryOnly: true,
+    });
+    return createRootNode(storeApi);
+}

package/dist/src/mixed_state.d.ts

@@ -0,0 +1,20 @@
+import type { ReadOnlyState, ValueState } from "./types";
+export { createMixedState };
+/**
+ * Creates a mixed state that combines multiple states into a tuple.
+ *
+ * If one of the states is changed, the mixed state will be updated.
+ *
+ * @param states - Array of states to combine
+ * @returns A new state that provides all values as a tuple
+ *
+ * @example
+ * const mixedState = createMixedState(states.addLoading, states.copyLoading, state.agent)
+ *
+ * <Render state={mixedState}>
+ *   {[addLoading, copyLoading, agent] => <SomeComponent />}
+ * </Render>
+ */
+declare function createMixedState<T extends readonly unknown[]>(...states: {
+    [K in keyof T]-?: ValueState<T[K]>;
+}): ReadOnlyState<T>;

package/dist/src/mixed_state.js

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useState } from "react";
+import { isEqual } from "./impl";
+export { createMixedState };
+/**
+ * Creates a mixed state that combines multiple states into a tuple.
+ *
+ * If one of the states is changed, the mixed state will be updated.
+ *
+ * @param states - Array of states to combine
+ * @returns A new state that provides all values as a tuple
+ *
+ * @example
+ * const mixedState = createMixedState(states.addLoading, states.copyLoading, state.agent)
+ *
+ * <Render state={mixedState}>
+ *   {[addLoading, copyLoading, agent] => <SomeComponent />}
+ * </Render>
+ */
+function createMixedState(...states) {
+    const use = () => states.map((state) => state.use());
+    const mixedState = {
+        get value() {
+            return states.map((state) => state.value);
+        },
+        use,
+        useCompute(fn) {
+            const [value, setValue] = useState(fn(this.value));
+            const recompute = useCallback(() => {
+                const newValue = fn(this.value);
+                // skip update if the new value is the same as the previous value
+                setValue((prev) => (isEqual(prev, newValue) ? prev : newValue));
+            }, [fn]);
+            useEffect(() => {
+                const unsubscribeFns = states.map((state) => state.subscribe(recompute));
+                return () => {
+                    unsubscribeFns.forEach((unsubscribe) => {
+                        unsubscribe();
+                    });
+                };
+            });
+            return value;
+        },
+    };
+    return mixedState;
+}

package/dist/src/node.d.ts

@@ -0,0 +1,41 @@
+import type { FieldPath, FieldPathValue, FieldValues } from "./path";
+import type { State, StoreRoot } from "./types";
+export { createNode, createRootNode, type Extension };
+/**
+ * Creates the root proxy node for dynamic path access.
+ *
+ * This is an internal function that wraps a store API in a Proxy, enabling
+ * property-chain syntax like `store.user.profile.name.use()`.
+ *
+ * @param storeApi - The underlying store API with path-based methods
+ * @param initialPath - Starting path segment (default: empty string for root)
+ * @returns A proxy that intercepts property access and returns nested proxies or state methods
+ */
+declare function createRootNode<T extends FieldValues, P extends FieldPath<T>>(storeApi: StoreRoot<T>, initialPath?: P): State<FieldPathValue<T, P>>;
+/**
+ * Extension interface for adding custom getters/setters to proxy nodes.
+ * Used internally by form handling to add error-related methods.
+ */
+type Extension<T extends FieldValues> = {
+    /** Custom getter function */
+    get?: (path: FieldPath<T>) => any;
+    /** Custom setter function; returns true if the set was handled */
+    set?: <P extends FieldPath<T>>(path: P, value: FieldPathValue<T, P>) => boolean;
+};
+/**
+ * Creates a proxy node for a specific path in the store.
+ *
+ * The proxy intercepts property access to provide state methods (use, set, value, etc.)
+ * and recursively creates child proxies for nested paths. Supports derived state
+ * transformations via the `from` and `to` parameters.
+ *
+ * @param storeApi - The underlying store API
+ * @param path - Dot-separated path to this node (e.g., "user.profile.name")
+ * @param cache - Shared cache to avoid recreating proxies for the same path
+ * @param extensions - Optional custom getters/setters (used by form handling)
+ * @param from - Transform function applied when reading values (for derived state)
+ * @param to - Transform function applied when writing values (for derived state)
+ * @returns A proxy implementing the State interface for the given path
+ */
+declare function createNode<T extends FieldValues>(storeApi: StoreRoot<any>, path: string, cache: Map<string, any>, extensions?: Record<string | symbol, Extension<T>>, from?: typeof unchanged, to?: typeof unchanged): State<T>;
+declare function unchanged(value: any): any;