juststore 1.1.1 → 1.2.0

package/dist/src/atom.js

@@ -0,0 +1,141 @@
+import { useSyncExternalStore } from "react";
+import { getSnapshot, updateSnapshot, useCompute } 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/>
+ *      <Render state={stateA}>
+ *        {(value, setValue) => (
+ *          <button onClick={() => setValue(!value)}>{value ? 'Hide' : 'Show'}</button>
+ *        )}
+ *      </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 === "useCompute") {
+                return (target._useCompute ??= (fn, deps) => useCompute(key, undefined, fn, deps, 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) {
+    if (typeof value !== "function") {
+        updateSnapshot(key, value, memoryOnly);
+    }
+    else {
+        updateSnapshot(key, value(getAtom(key, memoryOnly)), 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/src/form.d.ts

@@ -0,0 +1,97 @@
+import type { FieldPath, FieldPathValue, FieldValues, IsEqual } from "./path";
+import type { ArrayProxy, DerivedStateProps, ObjectMutationMethods, Prettify, ValueState } from "./types";
+export { type CreateFormOptions, createForm, type DeepNonNullable, type FormArrayState, type FormObjectState, type FormState, type FormStore, type FormValueState, useForm, };
+/**
+ * Common form field methods available on every form state node.
+ */
+type FormCommon = {
+    /** Subscribe and read the validation error. Re-renders when the error changes. */
+    useError: () => string | undefined;
+    /** Read the validation error without subscribing. */
+    readonly error: string | undefined;
+    /** Manually set a validation error. */
+    setError: (error: string | undefined) => void;
+};
+type FormState<T> = IsEqual<T, unknown> extends true ? never : [NonNullable<T>] extends [readonly (infer U)[]] ? FormArrayState<U, T> : [NonNullable<T>] extends [FieldValues] ? FormObjectState<NonNullable<T>, T> : FormValueState<T>;
+type FormReadOnlyState<T> = Prettify<Pick<FormValueState<Readonly<Required<T>>>, "value" | "use" | "useCompute" | "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.
+     *
+     * @returns ArrayState if the derived value is an array, ObjectState if the derived value is an object, otherwise State.
+     * @example
+     * const state = store.a.b.c.derived({
+     *   from: value => value + 1,
+     *   to: value => value - 1
+     * })
+     * state.use() // returns the derived value
+     * state.set(10) // sets the derived value
+     * state.reset() // resets the derived value
+     */
+    derived: <R>({ from, to }: DerivedStateProps<T, R>) => FormState<R>;
+}
+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]>;
+};
+type FormArrayState<TValue, TArray = TValue[]> = IsEqual<TValue, unknown> extends true ? never : FormValueState<TArray> & ArrayProxy<TValue, FormState<TValue>>;
+type FormObjectState<TNonNullable extends FieldValues, TObject = TNonNullable> = FormObjectProxy<TNonNullable> & FormValueState<TObject> & 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]>;
+} : NonNullable<T>;
+/**
+ * The form store type, combining form state with validation and submission handling.
+ */
+type FormStore<T extends FieldValues> = FormState<T> & {
+    /** Clears all validation errors from the form. */
+    clearErrors(): void;
+    /** Returns a form submit handler that validates and calls onSubmit with form values. */
+    handleSubmit(onSubmit: (values: T) => void): (e: React.SyntheticEvent) => void;
+};
+type NoEmptyValidator = "not-empty";
+type RegexValidator = RegExp;
+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.
+ *
+ * The form store extends the memory store with error handling and validation.
+ * Fields can be configured with validators that run on every change.
+ *
+ * @param defaultValue - Initial form values
+ * @param fieldConfigs - Optional validation configuration per field
+ * @returns A form store with validation and submission handling
+ *
+ * @example
+ * const form = useForm(
+ *   { email: '', password: '' },
+ *   {
+ *     email: { validate: 'not-empty' },
+ *     password: { validate: v => v && v.length < 8 ? 'Too short' : undefined }
+ *   }
+ * )
+ *
+ * <form onSubmit={form.handleSubmit(values => console.log(values))}>
+ *   <input value={form.email.use() ?? ''} onChange={e => form.email.set(e.target.value)} />
+ *   {form.email.useError() && <span>{form.email.error}</span>}
+ * </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/src/form.js

@@ -0,0 +1,176 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: intended */
+"use client";
+import { pascalCase } from "change-case";
+import { useEffect, useId, useMemo } from "react";
+import { getSnapshot, produce } from "./impl";
+import { createNode } from "./node";
+import { createStoreRoot } from "./root";
+export { createForm, useForm, };
+/**
+ * React hook that creates a form store with validation support.
+ *
+ * The form store extends the memory store with error handling and validation.
+ * Fields can be configured with validators that run on every change.
+ *
+ * @param defaultValue - Initial form values
+ * @param fieldConfigs - Optional validation configuration per field
+ * @returns A form store with validation and submission handling
+ *
+ * @example
+ * const form = useForm(
+ *   { email: '', password: '' },
+ *   {
+ *     email: { validate: 'not-empty' },
+ *     password: { validate: v => v && v.length < 8 ? 'Too short' : undefined }
+ *   }
+ * )
+ *
+ * <form onSubmit={form.handleSubmit(values => console.log(values))}>
+ *   <input value={form.email.use() ?? ''} onChange={e => form.email.set(e.target.value)} />
+ *   {form.email.useError() && <span>{form.email.error}</span>}
+ * </form>
+ */
+function useForm(defaultValue, fieldConfigs = {}) {
+    const formId = useId();
+    const namespace = `form:${formId}`;
+    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 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, true) ?? {}).length === 0) {
+                onSubmit(getSnapshot(namespace, true));
+            }
+        },
+    };
+    const store = createFormProxy(storeApi, errorStore);
+    const proxy = new Proxy(formApi, {
+        get(target, prop) {
+            if (prop in target) {
+                return target[prop];
+            }
+            return store[prop];
+        },
+    });
+    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 [proxy, unsubscribeFns];
+}
+/**
+ * Creates a form proxy node that extends the base node with error handling.
+ *
+ * @param storeApi - The form's value store
+ * @param errorStore - The form's error store
+ * @param path - The field path
+ * @returns A proxy with both state methods and error methods
+ */
+function createFormProxy(storeApi, errorStore) {
+    const proxyCache = new Map();
+    return createNode(storeApi, "", proxyCache, {
+        useError: {
+            get: (path) => () => errorStore.use(path),
+        },
+        error: {
+            get: (path) => errorStore.value(path),
+        },
+        setError: {
+            get: (path) => (error) => {
+                errorStore.set(path, error, false);
+                return true;
+            },
+        },
+    });
+}
+/**
+ * Converts a validator configuration into a validation function.
+ *
+ * @param field - The field path (used for error messages)
+ * @param validator - The validator config ('not-empty', RegExp, or function)
+ * @returns A validation function, or undefined if no validator provided
+ */
+function getValidator(field, validator) {
+    if (!validator) {
+        return undefined;
+    }
+    if (validator === "not-empty") {
+        return (value) => validateNoEmpty(field, value);
+    }
+    if (validator instanceof RegExp) {
+        return (value) => validateRegex(field, value, validator);
+    }
+    return validator;
+}
+/**
+ * Validates that a field has a non-empty value.
+ *
+ * @param field - The field path (used for error message)
+ * @param value - The value to validate
+ * @returns Error message if empty, undefined if valid
+ */
+function validateNoEmpty(field, value) {
+    if (!stringValue(value)) {
+        return `${pascalCase(field)} is required`;
+    }
+    return undefined;
+}
+/**
+ * Validates that a field matches a regular expression.
+ *
+ * @param field - The field path (used for error message)
+ * @param value - The value to validate
+ * @param regex - The pattern to match against
+ * @returns Error message if invalid, undefined if valid
+ */
+function validateRegex(field, value, regex) {
+    if (!regex.test(stringValue(value))) {
+        return `${pascalCase(field)} is invalid`;
+    }
+    return undefined;
+}
+/**
+ * Converts a value to a string for validation purposes.
+ * Returns empty string for non-primitive values.
+ */
+function stringValue(v) {
+    if (typeof v === "string") {
+        return v;
+    }
+    if (typeof v === "number") {
+        return String(v);
+    }
+    if (typeof v === "boolean") {
+        return String(v);
+    }
+    return "";
+}

package/dist/src/impl.d.ts

@@ -0,0 +1,128 @@
+import type { FieldPath, FieldPathValue, FieldValues } from "./path";
+import { getStableKeys, setExternalKeyOrder } from "./stable_keys";
+export { getNestedValue, getSnapshot, getStableKeys, isClass, isEqual, isRecord, joinPath, notifyListeners, produce, rename, setExternalKeyOrder, setLeaf, setNestedValue, subscribe, testReset, updateSnapshot, useCompute, 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
+ * - reference equality for class instances
+ * @param a - The first value to compare
+ * @param b - The second value to compare
+ * @returns True if the values are equal, false otherwise
+ */
+declare function isEqual(a: unknown, b: unknown): boolean;
+/**
+ * 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")
+ */
+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.
+ *
+ * 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.
+ */
+declare function notifyListeners(key: string, oldValue: unknown, newValue: unknown, { skipRoot, skipChildren, forceNotify }?: {
+    skipRoot?: boolean | undefined;
+    skipChildren?: boolean | undefined;
+    forceNotify?: boolean | undefined;
+}): void;
+/**
+ * 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
+ */
+declare function subscribe(key: string, listener: () => void): () => void;
+declare function useCompute<T = unknown, R = unknown>(namespace: string, path: string | undefined, fn: (value: T) => R, deps?: readonly unknown[], memoryOnly?: boolean): R;
+/**
+ * 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
+ */
+declare function produce(key: string, value: unknown, skipUpdate: boolean, memoryOnly: boolean): void;
+/**
+ * Renames a key in an object.
+ *
+ * It trigger updates to
+ *
+ *  - listeners to `path` (key is updated)
+ *  - listeners to `path.oldKey` (deleted)
+ *  - listeners to `path.newKey` (created)
+ *
+ * @param path - The full key path to rename
+ * @param oldKey - The old key to rename
+ * @param newKey - The new key to rename to
+ */
+declare function rename(path: string, oldKey: string, newKey: string, memoryOnly: boolean): void;
+/**
+ * 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
+ * @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 | undefined, memoryOnly: boolean): FieldPathValue<T, P> | undefined;
+/**
+ * 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
+ * @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, memoryOnly: boolean): FieldPathValue<T, P> | undefined;
+/**
+ * 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
+ */
+declare function setLeaf<T extends FieldValues, P extends FieldPath<T>>(key: string, path: P, value: FieldPathValue<T, P> | undefined, skipUpdate?: boolean, memoryOnly?: boolean): void;