juststore 0.4.1 → 0.4.3

package/dist/atom.d.ts

@@ -0,0 +1,46 @@
+export { createAtom, type Atom };
+/**
+ * An atom is a value that can be subscribed to and updated.
+ *
+ * @param T - The type of the value
+ * @returns The atom
+ */
+type Atom<T> = {
+    /** The current value. */
+    readonly value: T;
+    /** Subscribe to the value. */
+    use: () => T;
+    /** Set the value. */
+    set: (value: T) => void;
+    /** Reset the value to the default value. */
+    reset: () => void;
+    /** Subscribe to the value.with a callback function. */
+    subscribe: (listener: (value: T) => void) => () => void;
+    /** Render the value. */
+    Render: ({ children }: {
+        children: (value: T, setValue: (value: T) => void) => React.ReactNode;
+    }) => React.ReactNode;
+};
+/**
+ * Creates an atom with a given id and default value.
+ *
+ * @param id - The id of the atom
+ * @param defaultValue - The default value of the atom
+ * @returns The atom
+ * @example
+ * const stateA = createAtom(useId(), false)
+ * return (
+ *   <>
+ *    <ComponentA/>
+ *     <ComponentB/>
+ *      <stateA.Render>
+ *        {(value, setValue) => (
+ *          <button onClick={() => setValue(!value)}>{value ? 'Hide' : 'Show'}</button>
+ *        )}
+ *      </stateA.Render>
+ *    <ComponentC/>
+ *    <ComponentD/>
+ *   </>
+ * )
+ */
+declare function createAtom<T>(id: string, defaultValue: T, persistent?: boolean): Atom<T>;

package/dist/atom.js

@@ -0,0 +1,136 @@
+import { useSyncExternalStore } from 'react';
+import { getSnapshot, updateSnapshot } from './impl';
+export { createAtom };
+/**
+ * Creates an atom with a given id and default value.
+ *
+ * @param id - The id of the atom
+ * @param defaultValue - The default value of the atom
+ * @returns The atom
+ * @example
+ * const stateA = createAtom(useId(), false)
+ * return (
+ *   <>
+ *    <ComponentA/>
+ *     <ComponentB/>
+ *      <stateA.Render>
+ *        {(value, setValue) => (
+ *          <button onClick={() => setValue(!value)}>{value ? 'Hide' : 'Show'}</button>
+ *        )}
+ *      </stateA.Render>
+ *    <ComponentC/>
+ *    <ComponentD/>
+ *   </>
+ * )
+ */
+function createAtom(id, defaultValue, persistent = false) {
+    const key = `atom:${id}`;
+    const memoryOnly = !persistent;
+    // set the default value
+    // so getAtom will never return undefined
+    if (getAtom(key, memoryOnly) === undefined) {
+        setAtom(key, defaultValue, memoryOnly);
+    }
+    const atomProxy = new Proxy({}, {
+        get(target, prop) {
+            const cacheKey = `_${String(prop)}`;
+            if (cacheKey in target) {
+                // return cached methods first
+                return target[cacheKey];
+            }
+            if (prop === 'value') {
+                return getAtom(key, memoryOnly);
+            }
+            if (prop === 'use') {
+                return (target._use ??= () => useAtom(key, memoryOnly));
+            }
+            if (prop === 'set') {
+                return (target._set ??= (value) => setAtom(key, value, memoryOnly));
+            }
+            if (prop === 'reset') {
+                return (target._reset ??= () => setAtom(key, defaultValue, memoryOnly));
+            }
+            if (prop === 'subscribe') {
+                return (target._subscribe ??= (listener) => subscribeAtom(key, memoryOnly, listener));
+            }
+            if (prop === 'Render') {
+                return (target._Render ??= ({ children }) => children(useAtom(key, memoryOnly), (value) => setAtom(key, value, memoryOnly)));
+            }
+            return undefined;
+        }
+    });
+    return atomProxy;
+}
+/**
+ * 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
+ * @param memoryOnly - When true, skips localStorage persistence
+ * @returns The current value at the namespace, or the default value if not set
+ */
+function useAtom(key, memoryOnly = true) {
+    const value = useSyncExternalStore(listener => subscribeAtom(key, memoryOnly, listener), () => getSnapshot(key, memoryOnly), () => getSnapshot(key, memoryOnly));
+    return value;
+}
+/**
+ * Gets a value from an atom.
+ *
+ * @param key - The namespace
+ * @returns The value, or the default value if not set
+ */
+function getAtom(key, memoryOnly = true) {
+    return getSnapshot(key, memoryOnly);
+}
+/**
+ * Sets a value at a specific path within a namespace.
+ *
+ * @param key - The namespace
+ * @param value - The value to set
+ * @param memoryOnly - When true, skips localStorage persistence
+ */
+function setAtom(key, value, memoryOnly = true) {
+    updateSnapshot(key, value, memoryOnly);
+    notifyAtom(key);
+}
+const listeners = new Map();
+/**
+ * Subscribes to changes for an atom.
+ *
+ * @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 subscribeAtom(key, memoryOnly, listener) {
+    let listenerSet = listeners.get(key);
+    if (!listenerSet) {
+        listenerSet = new Set();
+        listeners.set(key, listenerSet);
+    }
+    const atomListener = () => listener(getAtom(key, memoryOnly));
+    listenerSet.add(atomListener);
+    return () => {
+        const keyListeners = listeners.get(key);
+        if (keyListeners) {
+            keyListeners.delete(atomListener);
+            if (keyListeners.size === 0) {
+                listeners.delete(key);
+            }
+        }
+    };
+}
+/**
+ * Notifies all listeners for an atom.
+ *
+ * @param namespace - The namespace
+ */
+function notifyAtom(namespace) {
+    const listenerSet = listeners.get(namespace);
+    if (!listenerSet)
+        return;
+    for (const listener of listenerSet) {
+        listener();
+    }
+}

package/dist/form.d.ts

@@ -1,6 +1,6 @@
 import type { FieldPath, FieldPathValue, FieldValues, IsEqual } from './path';
-import type { ArrayProxy, IsNullable, MaybeNullable, ObjectMutationMethods, ValueState } from './types';
-export { useForm, type CreateFormOptions, type DeepNonNullable, type FormArrayState, type FormObjectState, type FormState, type FormStore, type FormValueState };
+import type { ArrayProxy, DerivedStateProps, IsNullable, MaybeNullable, ObjectMutationMethods, Prettify, ValueState } from './types';
+export { createForm, useForm, type CreateFormOptions, type DeepNonNullable, type FormArrayState, type FormObjectState, type FormState, type FormStore, type FormValueState };
 /**
  * Common form field methods available on every form state node.
  */
@@ -13,7 +13,12 @@ type FormCommon = {
     setError: (error: string | undefined) => void;
 };
 type FormState<T> = IsEqual<T, unknown> extends true ? never : [NonNullable<T>] extends [readonly (infer U)[]] ? FormArrayState<U, IsNullable<T>> : [NonNullable<T>] extends [FieldValues] ? FormObjectState<NonNullable<T>, IsNullable<T>> : FormValueState<T>;
-interface FormValueState<T> extends Omit<ValueState<T>, 'withDefault' | 'derived'>, FormCommon {
+type FormReadOnlyState<T> = Prettify<Pick<FormValueState<Readonly<Required<T>>>, 'value' | 'use' | 'useCompute' | 'Render' | 'Show' | 'error' | 'setError'>>;
+interface FormValueState<T> extends Omit<ValueState<T>, 'ensureArray' | 'ensureObject' | 'withDefault' | 'derived'>, FormCommon {
+    /** Ensure the value is an array. */
+    ensureArray(): NonNullable<T> extends (infer U)[] ? FormArrayState<U> : never;
+    /** Ensure the value is an object. */
+    ensureObject(): NonNullable<T> extends FieldValues ? FormObjectState<NonNullable<T>> : never;
     /** Return a new state with a default value, and make the type non-nullable */
     withDefault(defaultValue: T): FormState<NonNullable<T>>;
     /** Virtual state derived from the current value.
@@ -28,15 +33,19 @@ interface FormValueState<T> extends Omit<ValueState<T>, 'withDefault' | 'derived
      * state.set(10) // sets the derived value
      * state.reset() // resets the derived value
      */
-    derived: <R>({ from, to }: {
-        from?: (value: T | undefined) => R;
-        to?: (value: R) => T | undefined;
-    }) => FormState<R>;
+    derived: <R>({ from, to }: DerivedStateProps<T, R>) => FormState<R>;
 }
-type FormArrayState<T, Nullable extends boolean = false, TT = MaybeNullable<T[], Nullable>> = IsEqual<T, unknown> extends true ? never : FormValueState<TT[]> & ArrayProxy<TT, FormState<TT>>;
-type FormObjectState<T extends FieldValues, Nullable extends boolean = false> = {
+type FormObjectProxy<T extends FieldValues> = {
+    /** Virtual state for the object's keys.
+     *
+     * This does NOT read from a real `keys` property on the stored object; it results in a stable array of keys.
+     */
+    readonly keys: FormReadOnlyState<FieldPath<T>[]>;
+} & {
     [K in keyof T]-?: FormState<T[K]>;
-} & FormValueState<MaybeNullable<T, Nullable>> & ObjectMutationMethods;
+};
+type FormArrayState<T, Nullable extends boolean = false> = IsEqual<T, unknown> extends true ? never : FormValueState<MaybeNullable<T[], Nullable>> & ArrayProxy<T, FormState<T>>;
+type FormObjectState<T extends FieldValues, Nullable extends boolean = false> = FormObjectProxy<T> & FormValueState<MaybeNullable<T, Nullable>> & ObjectMutationMethods;
 /** Type for nested objects with proxy methods */
 type DeepNonNullable<T> = [NonNullable<T>] extends [readonly (infer U)[]] ? U[] : [NonNullable<T>] extends [FieldValues] ? {
     [K in keyof NonNullable<T>]-?: DeepNonNullable<NonNullable<T>[K]>;
@@ -52,12 +61,14 @@ type FormStore<T extends FieldValues> = FormState<T> & {
 };
 type NoEmptyValidator = 'not-empty';
 type RegexValidator = RegExp;
-type FunctionValidator<T extends FieldValues> = (value: FieldPathValue<T, FieldPath<T>> | undefined, state: FormStore<T>) => string | undefined;
+type FunctionValidator<T extends FieldValues> = (value: FieldPathValue<T, FieldPath<T>>, state: FormStore<T>) => string | undefined;
 type Validator<T extends FieldValues> = NoEmptyValidator | RegexValidator | FunctionValidator<T>;
 type FieldConfig<T extends FieldValues> = {
     validate?: Validator<T>;
 };
 type CreateFormOptions<T extends FieldValues> = Partial<Record<FieldPath<T>, FieldConfig<T>>>;
+type UnsubscribeFn = () => void;
+type UnsubscribeFns = UnsubscribeFn[];
 /**
  * React hook that creates a form store with validation support.
  *
@@ -83,3 +94,4 @@ type CreateFormOptions<T extends FieldValues> = Partial<Record<FieldPath<T>, Fie
  * </form>
  */
 declare function useForm<T extends FieldValues>(defaultValue: T, fieldConfigs?: CreateFormOptions<T>): FormStore<T>;
+declare function createForm<T extends FieldValues>(namespace: string, defaultValue: T, fieldConfigs?: CreateFormOptions<T>): [FormStore<T>, UnsubscribeFns];

package/dist/form.js

@@ -5,7 +5,7 @@ import { useEffect, useId, useMemo } from 'react';
 import { getSnapshot, produce } from './impl';
 import { createNode } from './node';
 import { createStoreRoot } from './root';
-export { useForm };
+export { createForm, useForm };
 /**
  * React hook that creates a form store with validation support.
  *
@@ -33,61 +33,57 @@ export { useForm };
 function useForm(defaultValue, fieldConfigs = {}) {
     const formId = useId();
     const namespace = `form:${formId}`;
-    const errorNamespace = `errors.${namespace}`;
-    const storeApi = createStoreRoot(namespace, defaultValue, { memoryOnly: true });
+    const [form, unsubscribeFns] = useMemo(() => createForm(namespace, defaultValue, fieldConfigs), [namespace, defaultValue, fieldConfigs]);
+    useEffect(() => {
+        return () => {
+            for (const unsubscribe of unsubscribeFns) {
+                unsubscribe();
+            }
+        };
+    }, [unsubscribeFns]);
+    return form;
+}
+function createForm(namespace, defaultValue, fieldConfigs = {}) {
+    const errorNamespace = `_juststore_form_errors.${namespace}`;
     const errorStore = createStoreRoot(errorNamespace, {}, { memoryOnly: true });
-    const formStore = useMemo(() => ({
+    const storeApi = createStoreRoot(namespace, defaultValue, { memoryOnly: true });
+    const formApi = {
         clearErrors: () => produce(errorNamespace, undefined, false, true),
         handleSubmit: (onSubmit) => (e) => {
             e.preventDefault();
             // disable submit if there are errors
-            if (Object.keys(getSnapshot(errorNamespace) ?? {}).length === 0) {
-                onSubmit(getSnapshot(namespace));
+            if (Object.keys(getSnapshot(errorNamespace, true) ?? {}).length === 0) {
+                onSubmit(getSnapshot(namespace, true));
             }
         }
-    }), [namespace, errorNamespace]);
-    const store = useMemo(() => new Proxy(storeApi, {
-        get(_target, prop) {
-            if (prop in formStore) {
-                return formStore[prop];
-            }
-            if (prop in storeApi) {
-                return storeApi[prop];
-            }
-            if (typeof prop === 'string') {
-                return createFormProxy(storeApi, errorStore, prop);
+    };
+    const store = createFormProxy(storeApi, errorStore);
+    const proxy = new Proxy(formApi, {
+        get(target, prop) {
+            if (prop in target) {
+                return target[prop];
             }
-            return undefined;
+            return store[prop];
         }
-    }), [storeApi, formStore, errorStore]);
-    const unsubscribeFns = useMemo(() => {
-        const unsubscribeFns = [];
-        for (const entry of Object.entries(fieldConfigs)) {
-            const [path, config] = entry;
-            const validator = getValidator(path, config?.validate);
-            if (validator) {
-                const unsubscribe = storeApi.subscribe(path, (value) => {
-                    const error = validator(value, store);
-                    if (!error) {
-                        errorStore.reset(path);
-                    }
-                    else {
-                        errorStore.set(path, error);
-                    }
-                });
-                unsubscribeFns.push(unsubscribe);
-            }
+    });
+    const unsubscribeFns = [];
+    for (const entry of Object.entries(fieldConfigs)) {
+        const [path, config] = entry;
+        const validator = getValidator(path, config?.validate);
+        if (validator) {
+            const unsubscribe = storeApi.subscribe(path, value => {
+                const error = validator(value, store);
+                if (!error) {
+                    errorStore.reset(path);
+                }
+                else {
+                    errorStore.set(path, error);
+                }
+            });
+            unsubscribeFns.push(unsubscribe);
         }
-        return unsubscribeFns;
-    }, [fieldConfigs, storeApi, errorStore, store]);
-    useEffect(() => {
-        return () => {
-            for (const unsubscribe of unsubscribeFns) {
-                unsubscribe();
-            }
-        };
-    }, [unsubscribeFns]);
-    return store;
+    }
+    return [proxy, unsubscribeFns];
 }
 /**
  * Creates a form proxy node that extends the base node with error handling.
@@ -97,26 +93,23 @@ function useForm(defaultValue, fieldConfigs = {}) {
  * @param path - The field path
  * @returns A proxy with both state methods and error methods
  */
-const createFormProxy = (storeApi, errorStore, path) => {
+function createFormProxy(storeApi, errorStore) {
     const proxyCache = new Map();
-    const useError = () => errorStore.use(path);
-    const getError = () => errorStore.value(path);
-    const setError = (error) => {
-        errorStore.set(path, error);
-        return true;
-    };
-    return createNode(storeApi, path, proxyCache, {
+    return createNode(storeApi, '', proxyCache, {
         useError: {
-            get: () => useError
+            get: (path) => () => errorStore.use(path)
         },
         error: {
-            get: getError
+            get: (path) => errorStore.value(path)
         },
         setError: {
-            get: () => setError
+            get: (path) => (error) => {
+                errorStore.set(path, error, false);
+                return true;
+            }
         }
     });
-};
+}
 /**
  * Converts a validator configuration into a validation function.
  *

package/dist/impl.d.ts

@@ -1,8 +1,9 @@
 import type { FieldPath, FieldPathValue, FieldValues } from './path';
-export { getNestedValue, getSnapshot, getStableKeys, isClass, isEqual, joinPath, notifyListeners, produce, rename, setExternalKeyOrder, setLeaf, subscribe, useDebounce, useObject };
-declare function setExternalKeyOrder(target: object, keys: string[]): void;
-declare function getStableKeys(value: unknown): string[];
+import { getStableKeys, setExternalKeyOrder } from './stable_keys';
+export { getNestedValue, getSnapshot, getStableKeys, isClass, isEqual, isRecord, joinPath, notifyListeners, produce, rename, setExternalKeyOrder, setLeaf, setNestedValue, subscribe, testReset, updateSnapshot, useDebounce, useObject };
+declare function testReset(): void;
 declare function isClass(value: unknown): boolean;
+declare function isRecord(value: unknown): boolean;
 /** Compare two values for equality
  * @description
  * - react-fast-compare for non-class instances
@@ -20,8 +21,25 @@ declare function isEqual(a: unknown, b: unknown): boolean;
  * @returns Combined key string (e.g., "app.user.name")
  */
 declare function joinPath(namespace: string, path?: string): string;
+/** Snapshot getter used by React's useSyncExternalStore. */
+declare function getSnapshot(key: string, memoryOnly: boolean): unknown;
+/** Updates the snapshot of a key. */
+declare function updateSnapshot(key: string, value: unknown, memoryOnly: boolean): void;
 /** Get a nested value from an object/array using a dot-separated path. */
 declare function getNestedValue(obj: unknown, path: string): unknown;
+/**
+ * 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
+ */
+declare function setNestedValue(obj: unknown, path: string, value: unknown): unknown;
 /**
  * Notifies all relevant listeners when a value changes.
  *
@@ -38,8 +56,6 @@ declare function notifyListeners(key: string, oldValue: unknown, newValue: unkno
     skipChildren?: boolean | undefined;
     forceNotify?: boolean | undefined;
 }): void;
-/** Snapshot getter used by React's useSyncExternalStore. */
-declare function getSnapshot(key: string): unknown;
 /**
  * Subscribes to changes for a specific key.
  *
@@ -59,7 +75,7 @@ declare function subscribe(key: string, listener: () => void): () => void;
  * @param skipUpdate - When true, skips notifying listeners
  * @param memoryOnly - When true, skips localStorage persistence
  */
-declare function produce(key: string, value: unknown, skipUpdate?: boolean, memoryOnly?: boolean): void;
+declare function produce(key: string, value: unknown, skipUpdate: boolean, memoryOnly: boolean): void;
 /**
  * Renames a key in an object.
  *
@@ -73,7 +89,7 @@ declare function produce(key: string, value: unknown, skipUpdate?: boolean, memo
  * @param oldKey - The old key to rename
  * @param newKey - The new key to rename to
  */
-declare function rename(path: string, oldKey: string, newKey: string): void;
+declare function rename(path: string, oldKey: string, newKey: string, memoryOnly: boolean): void;
 /**
  * React hook that subscribes to and reads a value at a path.
  *
@@ -82,9 +98,10 @@ declare function rename(path: string, oldKey: string, newKey: string): void;
  *
  * @param key - The namespace or full key
  * @param path - Optional path within the namespace
+ * @param memoryOnly - When true, skips localStorage persistence
  * @returns The current value at the path, or undefined if not set
  */
-declare function useObject<T extends FieldValues, P extends FieldPath<T>>(key: string, path?: P): FieldPathValue<T, P> | undefined;
+declare function useObject<T extends FieldValues, P extends FieldPath<T>>(key: string, path: P | undefined, memoryOnly: boolean): FieldPathValue<T, P> | undefined;
 /**
  * React hook that subscribes to a value with debounced updates.
  *
@@ -94,9 +111,10 @@ declare function useObject<T extends FieldValues, P extends FieldPath<T>>(key: s
  * @param key - The namespace or full key
  * @param path - Path within the namespace
  * @param delay - Debounce delay in milliseconds
+ * @param memoryOnly - When true, skips localStorage persistence
  * @returns The debounced value at the path
  */
-declare function useDebounce<T extends FieldValues, P extends FieldPath<T>>(key: string, path: P, delay: number): FieldPathValue<T, P> | undefined;
+declare function useDebounce<T extends FieldValues, P extends FieldPath<T>>(key: string, path: P, delay: number, memoryOnly: boolean): FieldPathValue<T, P> | undefined;
 /**
  * Sets a value at a specific path within a namespace.
  *