juststore 0.0.1 → 0.0.2

package/dist/impl.js

@@ -3,6 +3,13 @@ import isEqual from 'react-fast-compare';
 import { localStorageDelete, localStorageGet, localStorageSet } from './local_storage';
 export { getNestedValue, getSnapshot, joinPath, notifyListeners, produce, setLeaf, useDebounce, useObject, useSubscribe };
 const memoryStore = new Map();
+/**
+ * Joins a namespace and path into a full key string.
+ *
+ * @param namespace - The store namespace (root key)
+ * @param path - Optional dot-separated path within the namespace
+ * @returns Combined key string (e.g., "app.user.name")
+ */
 function joinPath(namespace, path) {
     if (!path)
         return namespace;
@@ -32,22 +39,27 @@ function getNestedValue(obj, path) {
     }
     return current;
 }
+/**
+ * Creates a deep clone of an object, optimized for common cases.
+ *
+ * Uses fast paths for primitives and arrays of primitives, falling back
+ * to structuredClone for complex objects. Returns null if cloning fails.
+ *
+ * @param obj - The value to clone
+ * @returns A deep copy of the value, or null if cloning fails
+ */
 function tryStructuredClone(obj) {
     if (obj === null || obj === undefined)
         return null;
     if (typeof obj !== 'object')
         return obj;
-    // Fast path for array type
     if (Array.isArray(obj)) {
-        // Check if array needs deep cloning (contains objects/arrays)
         const needsDeepClone = obj.some(item => item !== null && typeof item === 'object');
         if (!needsDeepClone) {
-            // Array of primitives - just return new array reference
             return [...obj];
         }
         return obj.map(item => tryStructuredClone(item));
     }
-    // Fallback to structuredClone for complex objects
     try {
         return structuredClone(obj);
     }
@@ -56,10 +68,16 @@ function tryStructuredClone(obj) {
     }
 }
 /**
- * Immutable set/delete of a nested value using a dot-separated path.
- * - Creates intermediate nodes (array if next segment is a numeric index).
- * - If value is undefined, deletes object key or removes array index.
- * - Returns a new root object/array; when path is empty, returns value.
+ * Immutably sets or deletes a nested value using a dot-separated path.
+ *
+ * Creates intermediate objects or arrays as needed based on whether the next
+ * path segment is numeric. When value is undefined, the key is deleted from
+ * objects or the index is spliced from arrays.
+ *
+ * @param obj - The root object to update
+ * @param path - Dot-separated path to the target location
+ * @param value - The value to set, or undefined to delete
+ * @returns A new root object with the change applied
  */
 function setNestedValue(obj, path, value) {
     if (!path)
@@ -111,17 +129,36 @@ function setNestedValue(obj, path, value) {
     }
     return result;
 }
-/** Extract the root namespace from a full key (e.g. "ns.a.b" => "ns"). */
+/**
+ * Extracts the root namespace from a full key.
+ *
+ * @param key - Full key string (e.g., "app.user.name")
+ * @returns The first segment (e.g., "app")
+ */
 function getRootKey(key) {
     return key.split('.')[0];
 }
-/** Extract the nested path from a full key (e.g. "ns.a.b" => "a.b"). */
+/**
+ * Extracts the nested path from a full key, excluding the namespace.
+ *
+ * @param key - Full key string (e.g., "app.user.name")
+ * @returns The path after the namespace (e.g., "user.name")
+ */
 function getPath(key) {
     const segments = key.split('.');
     return segments.slice(1).join('.');
 }
-// Helper function to notify listeners hierarchically
-/** Notify exact, root, and affected child listeners for a given key change. */
+/**
+ * Notifies all relevant listeners when a value changes.
+ *
+ * Handles three types of listeners:
+ * 1. Exact match - listeners subscribed to the exact changed path
+ * 2. Root listeners - listeners on the namespace root (for full-store subscriptions)
+ * 3. Child listeners - listeners on nested paths that may be affected by the change
+ *
+ * Child listeners are only notified if their specific value actually changed,
+ * determined by deep equality comparison.
+ */
 function notifyListeners(key, oldValue, newValue, skipRoot = false, skipChildren = false) {
     const rootKey = skipRoot ? null : key.split('.').slice(0, 2).join('.');
     const keyPrefix = skipChildren ? null : key + '.';
@@ -282,7 +319,13 @@ if (broadcastChannel) {
     });
 }
 const listeners = new Map();
-/** Subscribe to changes for a key; returns an unsubscribe function. */
+/**
+ * Subscribes to changes for a specific key.
+ *
+ * @param key - The full key path to subscribe to
+ * @param listener - Callback invoked when the value changes
+ * @returns An unsubscribe function to remove the listener
+ */
 function subscribe(key, listener) {
     if (!listeners.has(key)) {
         listeners.set(key, new Set());
@@ -298,7 +341,17 @@ function subscribe(key, listener) {
         }
     };
 }
-/** Core mutation function that updates store and notifies listeners. */
+/**
+ * Core mutation function that updates the store and notifies listeners.
+ *
+ * Handles both setting and deleting values, with optimizations to skip
+ * unnecessary updates when the value hasn't changed.
+ *
+ * @param key - The full key path to update
+ * @param value - The new value, or undefined to delete
+ * @param skipUpdate - When true, skips notifying listeners
+ * @param memoryOnly - When true, skips localStorage persistence
+ */
 function produce(key, value, skipUpdate = false, memoryOnly = false) {
     const current = store.get(key);
     if (value === undefined) {
@@ -315,13 +368,32 @@ function produce(key, value, skipUpdate = false, memoryOnly = false) {
     // Notify listeners hierarchically with old and new values
     notifyListeners(key, current, value);
 }
-/** React hook: subscribe to and read a namespaced path value. */
+/**
+ * React hook that subscribes to and reads a value at a path.
+ *
+ * Uses useSyncExternalStore for tear-free reads and automatic re-rendering
+ * when the subscribed value changes.
+ *
+ * @param key - The namespace or full key
+ * @param path - Optional path within the namespace
+ * @returns The current value at the path, or undefined if not set
+ */
 function useObject(key, path) {
     const fullKey = joinPath(key, path);
     const value = useSyncExternalStore(listener => subscribe(fullKey, listener), () => getSnapshot(fullKey), () => getSnapshot(fullKey));
     return value;
 }
-/** React hook: subscribe to and read a namespaced path debounced value. */
+/**
+ * React hook that subscribes to a value with debounced updates.
+ *
+ * The returned value only updates after the specified delay has passed
+ * since the last change, useful for expensive operations like search.
+ *
+ * @param key - The namespace or full key
+ * @param path - Path within the namespace
+ * @param delay - Debounce delay in milliseconds
+ * @returns The debounced value at the path
+ */
 function useDebounce(key, path, delay) {
     const fullKey = joinPath(key, path);
     const currentValue = useSyncExternalStore(listener => subscribe(fullKey, listener), () => getSnapshot(fullKey), () => getSnapshot(fullKey));
@@ -344,7 +416,16 @@ function useDebounce(key, path, delay) {
     }, [currentValue, delay, debouncedValue]);
     return debouncedValue;
 }
-/** Effectful subscription helper that calls onChange with the latest value. */
+/**
+ * React hook for side effects when a value changes.
+ *
+ * Unlike `use()`, this doesn't cause re-renders. Instead, it calls the
+ * provided callback whenever the value changes, useful for syncing with
+ * external systems or triggering effects.
+ *
+ * @param key - The full key path to subscribe to
+ * @param onChange - Callback invoked with the new value on each change
+ */
 function useSubscribe(key, onChange) {
     const onChangeRef = useRef(onChange);
     useEffect(() => {
@@ -358,7 +439,15 @@ function useSubscribe(key, onChange) {
         return unsubscribe;
     }, [key]);
 }
-/** Set a leaf value under namespace.path, optionally skipping notifications. */
+/**
+ * Sets a value at a specific path within a namespace.
+ *
+ * @param key - The namespace
+ * @param path - Path within the namespace
+ * @param value - The value to set, or undefined to delete
+ * @param skipUpdate - When true, skips notifying listeners
+ * @param memoryOnly - When true, skips localStorage persistence
+ */
 function setLeaf(key, path, value, skipUpdate = false, memoryOnly = false) {
     const fullKey = joinPath(key, path);
     produce(fullKey, value, skipUpdate, memoryOnly);

package/dist/memory.d.ts

@@ -14,8 +14,40 @@ type MemoryStore<T extends FieldValues> = State<T> & {
     [K in keyof T]: NonNullable<T[K]> extends object ? DeepProxy<T[K]> : State<T[K]>;
 };
 /**
- * Create a memory store. The returned object is a Proxy that
- * exposes the base API (use/set/value/reset/...) and also allows deep, dynamic
- * access: e.g. `store.user.profile.name.use()` or `store.todos.at(0).title.set('x')`.
+ * 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>;

package/dist/memory.js

@@ -3,9 +3,41 @@ import { createRootNode } from './node';
 import { createStoreRoot } from './root';
 export { useMemoryStore };
 /**
- * Create a memory store. The returned object is a Proxy that
- * exposes the base API (use/set/value/reset/...) and also allows deep, dynamic
- * access: e.g. `store.user.profile.name.use()` or `store.todos.at(0).title.set('x')`.
+ * 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();

package/dist/mixed_state.d.ts

@@ -1,5 +1,9 @@
 import type { Prettify, State } from './types';
 export { createMixedState, type MixedState };
+/**
+ * A combined state that aggregates multiple independent states into a tuple.
+ * Provides read-only access via `value`, `use`, `Render`, and `Show`.
+ */
 type MixedState<T extends readonly unknown[]> = Prettify<Pick<State<Readonly<T>>, 'value' | 'use' | 'Render' | 'Show'>>;
 /**
  * Creates a mixed state that combines multiple states into a tuple.

package/dist/node.d.ts

@@ -1,11 +1,41 @@
 import type { FieldValues } from './path';
 import type { State, StoreRoot } from './types';
 export { createNode, createRootNode, type Extension };
-/** Build a deep proxy for dynamic path access under a namespace. */
+/**
+ * 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>(storeApi: StoreRoot<T>, initialPath?: string): State<T>;
+/**
+ * Extension interface for adding custom getters/setters to proxy nodes.
+ * Used internally by form handling to add error-related methods.
+ */
 type Extension = {
+    /** Custom getter function */
     get?: () => any;
+    /** Custom setter function; returns true if the set was handled */
     set?: (value: any) => 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>, from?: typeof unchanged, to?: typeof unchanged): State<T>;
 declare function unchanged(value: any): any;

package/dist/node.js

@@ -1,11 +1,35 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { useState } from 'react';
 export { createNode, createRootNode };
-/** Build a deep proxy for dynamic path access under a namespace. */
+/**
+ * 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
+ */
 function createRootNode(storeApi, initialPath = '') {
     const proxyCache = new Map();
     return createNode(storeApi, initialPath, proxyCache);
 }
+/**
+ * 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
+ */
 function createNode(storeApi, path, cache, extensions, from = unchanged, to = unchanged) {
     const isDerived = from !== unchanged || to !== unchanged;
     if (!isDerived && cache.has(path)) {

package/dist/root.d.ts

@@ -1,7 +1,23 @@
 import type { FieldValues } from './path';
 import type { StoreRoot } from './types';
 export { createStoreRoot, type StoreOptions };
+/**
+ * Configuration options for store creation.
+ */
 type StoreOptions = {
+    /** When true, the store only uses memory and does not persist to localStorage */
     memoryOnly?: boolean;
 };
+/**
+ * Creates the core store API with path-based methods.
+ *
+ * This is an internal function that sets up the subscription system, persistence,
+ * and provides the base API that the proxy wraps. The returned object contains
+ * methods like `use`, `set`, `value`, etc. that accept path strings.
+ *
+ * @param namespace - Unique identifier for the store
+ * @param defaultValue - Initial state merged with any persisted data
+ * @param options - Configuration options
+ * @returns The store API object with path-based methods
+ */
 declare function createStoreRoot<T extends FieldValues>(namespace: string, defaultValue: T, options?: StoreOptions): StoreRoot<T>;

package/dist/root.js

@@ -1,6 +1,18 @@
 import { useCallback, useRef } from 'react';
 import { getNestedValue, getSnapshot, joinPath, notifyListeners, produce, setLeaf, useDebounce, useObject, useSubscribe } from './impl';
 export { createStoreRoot };
+/**
+ * Creates the core store API with path-based methods.
+ *
+ * This is an internal function that sets up the subscription system, persistence,
+ * and provides the base API that the proxy wraps. The returned object contains
+ * methods like `use`, `set`, `value`, etc. that accept path strings.
+ *
+ * @param namespace - Unique identifier for the store
+ * @param defaultValue - Initial state merged with any persisted data
+ * @param options - Configuration options
+ * @returns The store API object with path-based methods
+ */
 function createStoreRoot(namespace, defaultValue, options = {}) {
     const memoryOnly = options?.memoryOnly ?? false;
     if (memoryOnly) {

package/dist/store.d.ts

@@ -16,4 +16,27 @@ export { createStore, type Store };
 type Store<T extends FieldValues> = StoreRoot<T> & {
     [K in keyof T]: NonNullable<T[K]> extends object ? DeepProxy<T[K]> : State<T[K]>;
 };
+/**
+ * Creates a persistent, hierarchical store with localStorage backing and cross-tab synchronization.
+ *
+ * @param namespace - Unique identifier for the store, used as the localStorage key prefix
+ * @param defaultValue - Initial state shape; merged with any existing persisted data
+ * @param options - Configuration options
+ * @param options.memoryOnly - When true, disables localStorage persistence (default: false)
+ * @returns A proxy object providing both path-based and dynamic property access to the store
+ *
+ * @example
+ * const store = createStore('app', {
+ *   user: { name: 'Guest' },
+ *   todos: []
+ * })
+ *
+ * // Dynamic access
+ * store.user.name.use()
+ * store.todos.push({ text: 'New todo' })
+ *
+ * // Path-based access
+ * store.use('user.name')
+ * store.set('user.name', 'Alice')
+ */
 declare function createStore<T extends FieldValues>(namespace: string, defaultValue: T, options?: StoreOptions): Store<T>;

package/dist/store.js

@@ -1,6 +1,29 @@
 import { createRootNode } from './node';
 import { createStoreRoot } from './root';
 export { createStore };
+/**
+ * Creates a persistent, hierarchical store with localStorage backing and cross-tab synchronization.
+ *
+ * @param namespace - Unique identifier for the store, used as the localStorage key prefix
+ * @param defaultValue - Initial state shape; merged with any existing persisted data
+ * @param options - Configuration options
+ * @param options.memoryOnly - When true, disables localStorage persistence (default: false)
+ * @returns A proxy object providing both path-based and dynamic property access to the store
+ *
+ * @example
+ * const store = createStore('app', {
+ *   user: { name: 'Guest' },
+ *   todos: []
+ * })
+ *
+ * // Dynamic access
+ * store.user.name.use()
+ * store.todos.push({ text: 'New todo' })
+ *
+ * // Path-based access
+ * store.use('user.name')
+ * store.set('user.name', 'Alice')
+ */
 function createStore(namespace, defaultValue, options = {}) {
     const storeApi = createStoreRoot(namespace, defaultValue, options);
     return new Proxy(storeApi, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "juststore",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "A small, expressive, and type-safe state management library for React.",
   "type": "module",
   "main": "dist/index.js",