juststore 0.1.4 → 0.3.2

package/README.md

@@ -454,38 +454,44 @@ Creates a form store with validation support.
 
 The store root provides path-based methods for dynamic access:
 
-| Method                          | Description                                             |
-| ------------------------------- | ------------------------------------------------------- |
-| `.use(path)`                    | Subscribe and read value (triggers re-render on change) |
-| `.useDebounce(path, ms)`        | Subscribe with debounced updates                        |
-| `.useState(path)`               | Returns `[value, setValue]` tuple                       |
-| `.value(path)`                  | Read without subscribing                                |
-| `.set(path, value)`             | Update value                                            |
-| `.set(path, fn)`                | Functional update                                       |
-| `.reset(path)`                  | Delete value at path                                    |
-| `.subscribe(path, fn)`          | Subscribe to changes (for effects)                      |
-| `.notify(path)`                 | Manually trigger subscribers                            |
-| `.useCompute(path, fn)`         | Derive a computed value                                 |
-| `.Render({ path, children })`   | Render prop component                                   |
-| `.Show({ path, children, on })` | Conditional render component                            |
+| Method                                         | Description                                             |
+| ---------------------------------------------- | ------------------------------------------------------- |
+| `.state(path)`                                 | Get the state object for a path                         |
+| `.use(path)`                                   | Subscribe and read value (triggers re-render on change) |
+| `.useDebounce(path, ms)`                       | Subscribe with debounced updates                        |
+| `.useState(path)`                              | Returns `[value, setValue]` tuple                       |
+| `.value(path)`                                 | Read without subscribing                                |
+| `.set(path, value)`                            | Update value                                            |
+| `.set(path, fn)`                               | Functional update                                       |
+| `.reset(path)`                                 | Delete value at path                                    |
+| `.rename(path, oldKey, newKey, notifyObject?)` | Rename a key in an object                               |
+| `.subscribe(path, fn)`                         | Subscribe to changes (for effects)                      |
+| `.notify(path)`                                | Manually trigger subscribers                            |
+| `.useCompute(path, fn)`                        | Derive a computed value                                 |
+| `.Render({ path, children })`                  | Render prop component                                   |
+| `.Show({ path, children, on })`                | Conditional render component                            |
 
 ### State Methods
 
-| Method                    | Description                                             |
-| ------------------------- | ------------------------------------------------------- |
-| `.use()`                  | Subscribe and read value (triggers re-render on change) |
-| `.useDebounce(ms)`        | Subscribe with debounced updates                        |
-| `.useState()`             | Returns `[value, setValue]` tuple                       |
-| `.value`                  | Read without subscribing                                |
-| `.set(value)`             | Update value                                            |
-| `.set(fn)`                | Functional update                                       |
-| `.reset()`                | Delete value at path                                    |
-| `.subscribe(fn)`          | Subscribe to changes (for effects)                      |
-| `.notify()`               | Manually trigger subscribers                            |
-| `.useCompute(fn)`         | Derive a computed value                                 |
-| `.derived({ from, to })`  | Create bidirectional transform                          |
-| `.Render({ children })`   | Render prop component                                   |
-| `.Show({ children, on })` | Conditional render component                            |
+| Method                                   | Description                                                             |
+| ---------------------------------------- | ----------------------------------------------------------------------- |
+| `.use()`                                 | Subscribe and read value (triggers re-render on change)                 |
+| `.useDebounce(ms)`                       | Subscribe with debounced updates                                        |
+| `.useState()`                            | Returns `[value, setValue]` tuple                                       |
+| `.value`                                 | Read without subscribing                                                |
+| `.set(value)`                            | Update value                                                            |
+| `.set(fn)`                               | Functional update                                                       |
+| `.reset()`                               | Delete value at path                                                    |
+| `.subscribe(fn)`                         | Subscribe to changes (for effects)                                      |
+| `.rename(oldKey, newKey, notifyObject?)` | Rename a key in an object                                               |
+| `.notify()`                              | Manually trigger subscribers                                            |
+| `.useCompute(fn)`                        | Derive a computed value                                                 |
+| `.derived({ from, to })`                 | Create bidirectional transform                                          |
+| `.ensureArray()`                         | Ensure the value is an array                                            |
+| `.ensureObject()`                        | Ensure the value is an object                                           |
+| `.withDefault(defaultValue)`             | Return a new state with a default value, and make the type non-nullable |
+| `.Render({ children })`                  | Render prop component                                                   |
+| `.Show({ children, on })`                | Conditional render component                                            |
 
 ## License
 

package/dist/form.d.ts

@@ -1,6 +1,6 @@
-import type { FieldPath, FieldPathValue, FieldValues } from './path';
-import type { ArrayProxy, State } from './types';
-export { useForm, type CreateFormOptions, type DeepNonNullable, type FormArrayProxy, type FormDeepProxy, type FormState, type FormStore };
+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 };
 /**
  * Common form field methods available on every form state node.
  */
@@ -12,20 +12,39 @@ type FormCommon = {
     /** Manually set a validation error. */
     setError: (error: string | undefined) => void;
 };
-type FormArrayProxy<T> = ArrayProxy<T> & FormCommon;
-type FormState<T> = State<T> & FormCommon;
+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 {
+    /** 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 }: {
+        from?: (value: T | undefined) => R;
+        to?: (value: R) => T | undefined;
+    }) => 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> = {
+    [K in keyof T]-?: FormState<T[K]>;
+} & FormValueState<MaybeNullable<T, Nullable>> & ObjectMutationMethods;
 /** Type for nested objects with proxy methods */
-type FormDeepProxy<T> = NonNullable<T> extends readonly (infer U)[] ? FormArrayProxy<U> & FormState<T> : NonNullable<T> extends FieldValues ? {
-    [K in keyof NonNullable<T>]-?: NonNullable<NonNullable<T>[K]> extends object ? FormDeepProxy<NonNullable<T>[K]> : FormState<NonNullable<T>[K]>;
-} & FormState<T> : FormState<T>;
-/** Type for nested objects with proxy methods */
-type DeepNonNullable<T> = NonNullable<T> extends readonly (infer U)[] ? U[] : NonNullable<T> extends FieldValues ? {
+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> = FormDeepProxy<T> & {
+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. */

package/dist/impl.d.ts

@@ -1,5 +1,5 @@
 import type { FieldPath, FieldPathValue, FieldValues } from './path';
-export { getNestedValue, getSnapshot, isClass, isEqual, joinPath, notifyListeners, produce, setLeaf, useDebounce, useObject, useSubscribe };
+export { getNestedValue, getSnapshot, isClass, isEqual, joinPath, notifyListeners, produce, rename, setLeaf, subscribe, useDebounce, useObject, useSubscribe };
 declare function isClass(value: unknown): boolean;
 /** Compare two values for equality
  * @description
@@ -31,9 +31,21 @@ declare function getNestedValue(obj: unknown, path: string): unknown;
  * 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?: boolean, skipChildren?: boolean): void;
+declare function notifyListeners(key: string, oldValue: unknown, newValue: unknown, { skipRoot, skipChildren, forceNotify }?: {
+    skipRoot?: boolean | undefined;
+    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.
+ *
+ * @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;
 /**
  * Core mutation function that updates the store and notifies listeners.
  *
@@ -46,6 +58,21 @@ declare function getSnapshot(key: string): unknown;
  * @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
+ * @param notifyObject - Whether to notify listeners to the object path
+ */
+declare function rename(path: string, oldKey: string, newKey: string, notifyObject?: boolean): void;
 /**
  * React hook that subscribes to and reads a value at a path.
  *

package/dist/impl.js

@@ -1,8 +1,10 @@
 import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
 import rfcIsEqual from 'react-fast-compare';
 import { localStorageDelete, localStorageGet, localStorageSet } from './local_storage';
-export { getNestedValue, getSnapshot, isClass, isEqual, joinPath, notifyListeners, produce, setLeaf, useDebounce, useObject, useSubscribe };
+export { getNestedValue, getSnapshot, isClass, isEqual, joinPath, notifyListeners, produce, rename, setLeaf, subscribe, useDebounce, useObject, useSubscribe };
 const memoryStore = new Map();
+const listeners = new Map();
+const descendantListenerKeysByPrefix = new Map();
 // check if the value is a class instance
 function isClass(value) {
     if (value === null || value === undefined)
@@ -14,7 +16,7 @@ function isClass(value) {
         return false;
     const descriptors = Object.getOwnPropertyDescriptors(proto);
     for (const key in descriptors) {
-        if (descriptors[key].get)
+        if (descriptors[key]?.get)
             return true;
     }
     return false;
@@ -28,6 +30,8 @@ function isClass(value) {
  * @returns True if the values are equal, false otherwise
  */
 function isEqual(a, b) {
+    if (a === b)
+        return true;
     if (isClass(a) || isClass(b))
         return a === b;
     return rfcIsEqual(a, b);
@@ -68,34 +72,6 @@ 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;
-    if (Array.isArray(obj)) {
-        const needsDeepClone = obj.some(item => item !== null && typeof item === 'object');
-        if (!needsDeepClone) {
-            return [...obj];
-        }
-        return obj.map(item => tryStructuredClone(item));
-    }
-    try {
-        return structuredClone(obj);
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Immutably sets or deletes a nested value using a dot-separated path.
  *
@@ -112,8 +88,15 @@ function setNestedValue(obj, path, value) {
     if (!path)
         return value;
     const segments = path.split('.');
-    const result = segments.length === 1 ? obj : tryStructuredClone(obj);
-    let current = result ?? {};
+    if (obj !== null && obj !== undefined && typeof obj !== 'object') {
+        return obj;
+    }
+    const result = obj === null || obj === undefined
+        ? {}
+        : Array.isArray(obj)
+            ? [...obj]
+            : { ...obj };
+    let current = result;
     for (let i = 0; i < segments.length - 1; i++) {
         const segment = segments[i];
         const nextSegment = segments[i + 1];
@@ -122,17 +105,41 @@ function setNestedValue(obj, path, value) {
             const index = Number(segment);
             if (Number.isNaN(index))
                 break;
-            if (!current[index]) {
-                current[index] = isNextIndex ? [] : {};
+            const existing = current[index];
+            let next;
+            if (existing === null || existing === undefined) {
+                next = isNextIndex ? [] : {};
             }
-            current = current[index];
+            else if (typeof existing !== 'object') {
+                next = isNextIndex ? [] : {};
+            }
+            else if (Array.isArray(existing)) {
+                next = [...existing];
+            }
+            else {
+                next = { ...existing };
+            }
+            current[index] = next;
+            current = next;
         }
         else if (typeof current === 'object' && current !== null) {
             const currentObj = current;
-            if (!currentObj[segment]) {
-                currentObj[segment] = isNextIndex ? [] : {};
+            const existing = currentObj[segment];
+            let next;
+            if (existing === null || existing === undefined) {
+                next = isNextIndex ? [] : {};
+            }
+            else if (typeof existing !== 'object') {
+                next = isNextIndex ? [] : {};
+            }
+            else if (Array.isArray(existing)) {
+                next = [...existing];
+            }
+            else {
+                next = { ...existing };
             }
-            current = currentObj[segment];
+            currentObj[segment] = next;
+            current = next;
         }
     }
     const lastSegment = segments[segments.length - 1];
@@ -161,21 +168,46 @@ function setNestedValue(obj, path, value) {
 /**
  * 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")
+ * @param key - Full key string
+ * @returns Namespace
+ * @example
+ * getNamespace('app.user.name') // 'app'
  */
-function getRootKey(key) {
-    return key.split('.')[0];
+function getNamespace(key) {
+    const index = key.indexOf('.');
+    if (index === -1)
+        return key;
+    return key.slice(0, index);
 }
 /**
- * Extracts the nested path from a full key, excluding the namespace.
+ * Extracts the namespace and path from a full key.
  *
- * @param key - Full key string (e.g., "app.user.name")
- * @returns The path after the namespace (e.g., "user.name")
+ * @param key - Full key string
+ * @returns [namespace, path]
+ * @example
+ * splitNSPath('app.user.name') // ['app', 'user.name']
  */
-function getPath(key) {
-    const segments = key.split('.');
-    return segments.slice(1).join('.');
+function splitNSPath(key) {
+    const index = key.indexOf('.');
+    if (index === -1)
+        return [key, ''];
+    return [key.slice(0, index), key.slice(index + 1)];
+}
+function getKeyPrefixes(key) {
+    const dot = key.indexOf('.');
+    if (dot === -1)
+        return [];
+    const parts = key.split('.');
+    if (parts.length <= 1)
+        return [];
+    const prefixes = [];
+    let current = parts[0];
+    for (let i = 1; i < parts.length - 1; i++) {
+        current += '.' + parts[i];
+        prefixes.push(current);
+    }
+    prefixes.unshift(parts[0]);
+    return prefixes;
 }
 /**
  * Notifies all relevant listeners when a value changes.
@@ -188,35 +220,64 @@ function getPath(key) {
  * 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 + '.';
-    // Single pass: collect listeners to notify
-    const listenersToNotify = new Set();
-    for (const [listenerKey, listenerSet] of listeners.entries()) {
-        if (listenerKey === key) {
-            // Exact key match
-            listenerSet.forEach(listener => listenersToNotify.add(listener));
+function notifyListeners(key, oldValue, newValue, { skipRoot = false, skipChildren = false, forceNotify = false } = {}) {
+    if (skipRoot && skipChildren) {
+        if (!forceNotify && isEqual(oldValue, newValue)) {
+            return;
         }
-        else if (rootKey && listenerKey === rootKey) {
-            // Root key match
-            listenerSet.forEach(listener => listenersToNotify.add(listener));
+        // exact match only
+        const listenerSet = listeners.get(key);
+        if (listenerSet) {
+            listenerSet.forEach(listener => listener());
         }
-        else if (keyPrefix && listenerKey.startsWith(keyPrefix)) {
-            // Child key match - check if value actually changed
-            const childPath = listenerKey.substring(key.length + 1);
-            const oldChildValue = getNestedValue(oldValue, childPath);
-            const newChildValue = getNestedValue(newValue, childPath);
-            if (!isEqual(oldChildValue, newChildValue)) {
-                listenerSet.forEach(listener => listenersToNotify.add(listener));
+        return;
+    }
+    // Exact key match
+    const exactSet = listeners.get(key);
+    if (exactSet) {
+        exactSet.forEach(listener => listener());
+    }
+    // Ancestor keys match (including namespace root)
+    if (!skipRoot) {
+        const namespace = getNamespace(key);
+        const rootSet = listeners.get(namespace);
+        if (rootSet) {
+            rootSet.forEach(listener => listener());
+        }
+        // Also notify intermediate ancestors
+        const prefixes = getKeyPrefixes(key);
+        for (const prefix of prefixes) {
+            if (prefix === namespace)
+                continue; // Already handled
+            const prefixSet = listeners.get(prefix);
+            if (prefixSet) {
+                prefixSet.forEach(listener => listener());
+            }
+        }
+    }
+    // Child key match - check if value actually changed
+    if (!skipChildren) {
+        const childKeys = descendantListenerKeysByPrefix.get(key);
+        if (childKeys) {
+            for (const childKey of childKeys) {
+                const childPath = childKey.slice(key.length + 1);
+                const oldChildValue = getNestedValue(oldValue, childPath);
+                const newChildValue = getNestedValue(newValue, childPath);
+                if (forceNotify || !isEqual(oldChildValue, newChildValue)) {
+                    const childSet = listeners.get(childKey);
+                    if (childSet) {
+                        childSet.forEach(listener => listener());
+                    }
+                }
             }
         }
     }
-    // Notify all collected listeners
-    listenersToNotify.forEach(listener => listener());
+}
+function forceNotifyListeners(key, options = {}) {
+    notifyListeners(key, undefined, undefined, { ...options, forceNotify: true });
 }
 // BroadcastChannel for cross-tab synchronization
-const broadcastChannel = typeof window !== 'undefined' ? new BroadcastChannel('godoxy-producer-consumer') : null;
+const broadcastChannel = typeof window !== 'undefined' ? new BroadcastChannel('juststore') : null;
 /**
  * Backing store providing in-memory data with localStorage persistence
  * and cross-tab synchronization. All operations are namespaced at the root key
@@ -224,13 +285,12 @@ const broadcastChannel = typeof window !== 'undefined' ? new BroadcastChannel('g
  */
 const store = {
     has(key) {
-        const rootKey = getRootKey(key);
+        const rootKey = getNamespace(key);
         return (memoryStore.has(rootKey) ||
             (typeof window !== 'undefined' && localStorageGet(rootKey) !== undefined));
     },
     get(key) {
-        const rootKey = getRootKey(key);
-        const path = getPath(key);
+        const [rootKey, path] = splitNSPath(key);
         // Get root object from memory or localStorage
         let rootValue;
         if (memoryStore.has(rootKey)) {
@@ -249,8 +309,10 @@ const store = {
         return getNestedValue(rootValue, path);
     },
     set(key, value, memoryOnly = false) {
-        const rootKey = getRootKey(key);
-        const path = getPath(key);
+        if (value === undefined) {
+            return this.delete(key, memoryOnly);
+        }
+        const [rootKey, path] = splitNSPath(key);
         let rootValue;
         if (!path) {
             // Setting root value directly
@@ -262,12 +324,7 @@ const store = {
             rootValue = setNestedValue(currentRoot, path, value);
         }
         // Update memory
-        if (rootValue === undefined) {
-            memoryStore.delete(rootKey);
-        }
-        else {
-            memoryStore.set(rootKey, rootValue);
-        }
+        memoryStore.set(rootKey, rootValue);
         // Persist to localStorage (unless memoryOnly)
         if (!memoryOnly && typeof window !== 'undefined') {
             localStorageSet(rootKey, rootValue);
@@ -278,8 +335,7 @@ const store = {
         }
     },
     delete(key, memoryOnly = false) {
-        const rootKey = getRootKey(key);
-        const path = getPath(key);
+        const [rootKey, path] = splitNSPath(key);
         if (!path) {
             // Deleting root key
             memoryStore.delete(rootKey);
@@ -329,25 +385,9 @@ if (broadcastChannel) {
         }
         // Notify all listeners that might be affected by this root key change
         const newRootValue = type === 'delete' ? undefined : value;
-        for (const listenerKey of listeners.keys()) {
-            if (listenerKey === key) {
-                // Direct key match - notify with old and new values
-                notifyListeners(listenerKey, oldRootValue, newRootValue);
-            }
-            else if (listenerKey.startsWith(key + '.')) {
-                // Child key - check if its value actually changed
-                const childPath = listenerKey.substring(key.length + 1);
-                const oldChildValue = getNestedValue(oldRootValue, childPath);
-                const newChildValue = getNestedValue(newRootValue, childPath);
-                if (!isEqual(oldChildValue, newChildValue)) {
-                    const childListeners = listeners.get(listenerKey);
-                    childListeners?.forEach(listener => listener());
-                }
-            }
-        }
+        notifyListeners(key, oldRootValue, newRootValue);
     });
 }
-const listeners = new Map();
 /**
  * Subscribes to changes for a specific key.
  *
@@ -360,6 +400,13 @@ function subscribe(key, listener) {
         listeners.set(key, new Set());
     }
     listeners.get(key).add(listener);
+    const prefixes = getKeyPrefixes(key);
+    for (const prefix of prefixes) {
+        if (!descendantListenerKeysByPrefix.has(prefix)) {
+            descendantListenerKeysByPrefix.set(prefix, new Set());
+        }
+        descendantListenerKeysByPrefix.get(prefix).add(key);
+    }
     return () => {
         const keyListeners = listeners.get(key);
         if (keyListeners) {
@@ -368,6 +415,15 @@ function subscribe(key, listener) {
                 listeners.delete(key);
             }
         }
+        for (const prefix of prefixes) {
+            const prefixKeys = descendantListenerKeysByPrefix.get(prefix);
+            if (prefixKeys) {
+                prefixKeys.delete(key);
+                if (prefixKeys.size === 0) {
+                    descendantListenerKeysByPrefix.delete(prefix);
+                }
+            }
+        }
     };
 }
 /**
@@ -383,20 +439,50 @@ function subscribe(key, listener) {
  */
 function produce(key, value, skipUpdate = false, memoryOnly = false) {
     const current = store.get(key);
-    if (value === undefined) {
-        skipUpdate = current === undefined;
-        store.delete(key, memoryOnly);
-    }
-    else {
-        if (isEqual(current, value))
-            return;
-        store.set(key, value, memoryOnly);
-    }
+    if (isEqual(current, value))
+        return;
+    store.set(key, value, memoryOnly);
     if (skipUpdate)
         return;
     // Notify listeners hierarchically with old and new values
     notifyListeners(key, current, value);
 }
+/**
+ * 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
+ * @param notifyObject - Whether to notify listeners to the object path
+ */
+function rename(path, oldKey, newKey, notifyObject = true) {
+    const current = store.get(path);
+    if (current === undefined || current === null || typeof current !== 'object') {
+        // assign a new object with the new key
+        store.set(path, { [newKey]: undefined });
+        if (notifyObject) {
+            forceNotifyListeners(path, { skipChildren: true });
+        }
+        return;
+    }
+    const oldValue = current[oldKey];
+    const newObject = { ...current, [oldKey]: undefined, [newKey]: oldValue };
+    delete newObject[oldKey];
+    store.set(path, newObject);
+    if (oldValue !== undefined) {
+        forceNotifyListeners(joinPath(path, oldKey));
+    }
+    forceNotifyListeners(joinPath(path, newKey));
+    if (notifyObject) {
+        forceNotifyListeners(path, { skipChildren: true });
+    }
+}
 /**
  * React hook that subscribes to and reads a value at a path.
  *
@@ -487,7 +573,8 @@ const __pc_debug = {
     getStoreSize: () => store.size,
     getListenerSize: () => listeners.size,
     getStore: () => memoryStore,
-    getStoreValue: (key) => memoryStore.get(key)
+    getStoreValue: (key) => memoryStore.get(key),
+    getListeners: () => listeners
 };
 // Expose debug in browser for quick inspection during development
 if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
+export type * from './form';
 export { useForm } from './form';
-export type { CreateFormOptions, FormState, FormStore } from './form';
 export { useMemoryStore, type MemoryStore } from './memory';
 export { createMixedState, type MixedState } from './mixed_state';
 export type * from './path';

package/dist/memory.d.ts

@@ -1,5 +1,5 @@
 import type { FieldValues } from './path';
-import type { DeepProxy, State } from './types';
+import type { State, ValueState } from './types';
 export { useMemoryStore, type MemoryStore };
 /**
  * A component local store with React bindings.
@@ -10,8 +10,8 @@ export { useMemoryStore, type MemoryStore };
  * - 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> = State<T> & {
-    [K in keyof T]: NonNullable<T[K]> extends object ? DeepProxy<T[K]> : State<T[K]>;
+type MemoryStore<T extends FieldValues> = ValueState<T> & {
+    [K in keyof T]-?: State<T[K]>;
 };
 /**
  * React hook that creates a component-scoped memory store.

package/dist/mixed_state.d.ts

@@ -1,10 +1,10 @@
-import type { Prettify, State } from './types';
+import type { Prettify, ValueState } 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'>>;
+type MixedState<T extends readonly unknown[]> = Prettify<Pick<ValueState<Readonly<Required<T>>>, 'value' | 'use' | 'Render' | 'Show'>>;
 /**
  * Creates a mixed state that combines multiple states into a tuple.
  *
@@ -21,5 +21,5 @@ type MixedState<T extends readonly unknown[]> = Prettify<Pick<State<Readonly<T>>
  * </mixedState.Render>
  */
 declare function createMixedState<T extends readonly unknown[]>(...states: {
-    [K in keyof T]: State<T[K]>;
+    [K in keyof T]-?: ValueState<T[K]>;
 }): MixedState<T>;

package/dist/node.d.ts

@@ -1,4 +1,4 @@
-import type { FieldValues } from './path';
+import type { FieldPath, FieldPathValue, FieldValues } from './path';
 import type { State, StoreRoot } from './types';
 export { createNode, createRootNode, type Extension };
 /**
@@ -11,7 +11,7 @@ export { createNode, createRootNode, type Extension };
  * @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>;
+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.

package/dist/node.js

@@ -30,13 +30,14 @@ function createRootNode(storeApi, initialPath = '') {
  */
 function createNode(storeApi, path, cache, extensions, from = unchanged, to = unchanged) {
     const isDerived = from !== unchanged || to !== unchanged;
+    const fieldName = path.split('.').pop();
     if (!isDerived && cache.has(path)) {
         return cache.get(path);
     }
     const proxy = new Proxy({}, {
         get(_target, prop) {
             if (prop === 'field') {
-                return path.split('.').pop();
+                return fieldName;
             }
             if (prop === 'use') {
                 return () => from(storeApi.use(path));
@@ -45,7 +46,10 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
                 return (delay) => from(storeApi.useDebounce(path, delay));
             }
             if (prop === 'useState') {
-                return () => [from(storeApi.use(path)), (value) => storeApi.set(path, to(value))];
+                return () => {
+                    const value = storeApi.use(path);
+                    return [from(value), (next) => storeApi.set(path, to(next))];
+                };
             }
             if (prop === 'value') {
                 return from(storeApi.value(path));
@@ -75,116 +79,126 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
             }
             if (prop === 'derived') {
                 if (isDerived) {
-                    throw new Error('Derived method cannot be called on a derived node');
+                    throw new Error(`Derived method cannot be called on a derived node: ${path}`);
                 }
                 return ({ from, to }) => createNode(storeApi, path, cache, extensions, from, to);
             }
-            if (Array.isArray(storeApi.value(path))) {
+            if (prop === 'notify') {
+                return () => storeApi.notify(path);
+            }
+            if (prop === 'ensureArray') {
+                return () => createNode(storeApi, path, cache, extensions, value => ensureArray(value, from), unchanged);
+            }
+            if (prop === 'ensureObject') {
+                return () => createNode(storeApi, path, cache, extensions, value => ensureObject(value, from), to);
+            }
+            if (prop === 'withDefault') {
+                return (defaultValue) => createNode(storeApi, path, cache, extensions, value => withDefault(value, defaultValue, from), to);
+            }
+            if (isObjectMethod(prop)) {
+                const derivedValue = from(storeApi.value(path));
+                if (derivedValue !== undefined && typeof derivedValue !== 'object') {
+                    throw new Error(`Expected object at path ${path}, got ${typeof derivedValue}`);
+                }
+                if (prop === 'rename') {
+                    return (oldKey, newKey, notifyObject) => {
+                        storeApi.rename(path, oldKey, newKey, notifyObject);
+                    };
+                }
+            }
+            if (isArrayMethod(prop)) {
+                const derivedValue = from(storeApi.value(path));
+                if (derivedValue !== undefined && !Array.isArray(derivedValue)) {
+                    throw new Error(`Expected array at path ${path}, got ${typeof derivedValue}`);
+                }
+                const currentArray = derivedValue ? [...derivedValue] : [];
                 if (prop === 'at') {
                     return (index) => {
                         const nextPath = path ? `${path}.${index}` : String(index);
-                        return createNode(storeApi, nextPath, cache, extensions, from, to);
+                        return createNode(storeApi, nextPath, cache, extensions);
                     };
                 }
                 if (prop === 'length') {
-                    const value = from(storeApi.value(path));
-                    return Array.isArray(value) ? value.length : undefined;
+                    return currentArray.length;
                 }
                 // Array mutation methods
                 if (prop === 'push') {
                     return (...items) => {
-                        const currentArray = from(storeApi.value(path)) ?? [];
-                        const transformedItems = isDerived ? items.map(to) : items;
-                        const newArray = [...currentArray, ...transformedItems];
-                        storeApi.set(path, isDerived ? newArray.map(from) : newArray);
+                        const newArray = [...currentArray, ...items];
+                        storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return newArray.length;
                     };
                 }
                 if (prop === 'pop') {
                     return () => {
-                        const currentArray = from(storeApi.value(path)) ?? [];
                         if (currentArray.length === 0)
                             return undefined;
                         const newArray = currentArray.slice(0, -1);
                         const poppedItem = currentArray[currentArray.length - 1];
-                        storeApi.set(path, isDerived ? newArray.map(from) : newArray);
+                        storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return poppedItem;
                     };
                 }
                 if (prop === 'shift') {
                     return () => {
-                        const currentArray = from(storeApi.value(path)) ?? [];
                         if (currentArray.length === 0)
                             return undefined;
                         const newArray = currentArray.slice(1);
                         const shiftedItem = currentArray[0];
-                        storeApi.set(path, isDerived ? newArray.map(from) : newArray);
+                        storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return shiftedItem;
                     };
                 }
                 if (prop === 'unshift') {
                     return (...items) => {
-                        const currentArray = from(storeApi.value(path)) ?? [];
-                        const transformedItems = isDerived ? items.map(to) : items;
-                        const newArray = [...transformedItems, ...currentArray];
-                        storeApi.set(path, isDerived ? newArray.map(from) : newArray);
+                        const newArray = [...items, ...currentArray];
+                        storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return newArray.length;
                     };
                 }
                 if (prop === 'splice') {
                     return (start, deleteCount, ...items) => {
-                        const currentArray = from(storeApi.value(path)) ?? [];
-                        const newArray = [...currentArray];
-                        const transformedItems = isDerived ? items.map(to) : items;
-                        const deletedItems = newArray.splice(start, deleteCount ?? 0, ...transformedItems);
-                        storeApi.set(path, isDerived ? newArray.map(from) : newArray);
+                        const deletedItems = currentArray.splice(start, deleteCount ?? 0, ...items);
+                        storeApi.set(path, isDerived ? currentArray.map(to) : currentArray);
                         return deletedItems;
                     };
                 }
                 if (prop === 'reverse') {
                     return () => {
-                        const currentArray = from(storeApi.value(path)) ?? [];
                         if (!Array.isArray(currentArray))
                             return [];
-                        const newArray = [...currentArray].reverse();
-                        storeApi.set(path, isDerived ? newArray.map(from) : newArray);
-                        return newArray;
+                        currentArray.reverse();
+                        storeApi.set(path, isDerived ? currentArray.map(to) : currentArray);
+                        return currentArray;
                     };
                 }
                 if (prop === 'sort') {
                     return (compareFn) => {
-                        const currentArray = from(storeApi.value(path)) ?? [];
-                        const newArray = [...currentArray].sort(compareFn);
-                        storeApi.set(path, isDerived ? newArray.map(from) : newArray);
-                        return newArray;
+                        currentArray.sort(compareFn);
+                        storeApi.set(path, isDerived ? currentArray.map(to) : currentArray);
+                        return currentArray;
                     };
                 }
                 if (prop === 'fill') {
                     return (value, start, end) => {
-                        const currentArray = from(storeApi.value(path)) ?? [];
-                        const newArray = [...currentArray].fill(value, start, end);
-                        storeApi.set(path, isDerived ? newArray.map(from) : newArray);
-                        return newArray;
+                        currentArray.fill(value, start, end);
+                        storeApi.set(path, isDerived ? currentArray.map(to) : currentArray);
+                        return currentArray;
                     };
                 }
                 if (prop === 'copyWithin') {
                     return (target, start, end) => {
-                        const currentArray = from(storeApi.value(path)) ?? [];
-                        const newArray = [...currentArray].copyWithin(target, start, end);
-                        storeApi.set(path, isDerived ? newArray.map(from) : newArray);
-                        return newArray;
+                        currentArray.copyWithin(target, start, end);
+                        storeApi.set(path, isDerived ? currentArray.map(to) : currentArray);
+                        return currentArray;
                     };
                 }
                 if (prop === 'sortedInsert') {
                     return (cmp, ...items) => {
-                        const currentArray = from(storeApi.value(path)) ?? [];
                         if (typeof cmp !== 'function')
-                            return isDerived ? currentArray.map(from).length : currentArray.length;
-                        // Create a copy of the current array
-                        const newArray = isDerived ? currentArray.map(from) : [...currentArray];
-                        const transformedItems = isDerived ? items.map(to) : items;
-                        // Insert each item in sorted order using binary search
-                        for (const item of transformedItems) {
+                            return currentArray.length;
+                        const newArray = [...currentArray];
+                        for (const item of items) {
                             let left = 0;
                             let right = newArray.length;
                             // Binary search to find insertion point
@@ -200,7 +214,7 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
                             // Insert at the found position
                             newArray.splice(left, 0, item);
                         }
-                        storeApi.set(path, isDerived ? newArray.map(from) : newArray);
+                        storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return newArray.length;
                     };
                 }
@@ -210,8 +224,7 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
             }
             if (typeof prop === 'string' || typeof prop === 'number') {
                 const nextPath = path ? `${path}.${prop}` : String(prop);
-                // Always return a proxy
-                return createNode(storeApi, nextPath, cache, extensions, from, to);
+                return createNode(storeApi, nextPath, cache, extensions);
             }
             return undefined;
         },
@@ -220,7 +233,7 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
                 return extensions[prop]?.set(value);
             }
             if (typeof prop === 'string' || typeof prop === 'number') {
-                const nextPath = path ? `${path}.${prop}` : prop;
+                const nextPath = path ? `${path}.${prop}` : String(prop);
                 storeApi.set(nextPath, to(value));
                 return true;
             }
@@ -232,6 +245,46 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
     }
     return proxy;
 }
+function isArrayMethod(prop) {
+    return (prop === 'at' ||
+        prop === 'length' ||
+        prop === 'push' ||
+        prop === 'pop' ||
+        prop === 'shift' ||
+        prop === 'unshift' ||
+        prop === 'splice' ||
+        prop === 'reverse' ||
+        prop === 'sort' ||
+        prop === 'fill' ||
+        prop === 'copyWithin' ||
+        prop === 'sortedInsert');
+}
+function isObjectMethod(prop) {
+    return prop === 'rename';
+}
 function unchanged(value) {
     return value;
 }
+const EMPTY_ARRAY = [];
+const EMPTY_OBJECT = {};
+function ensureArray(value, from) {
+    if (value === undefined || value === null)
+        return EMPTY_ARRAY;
+    const array = from(value);
+    if (Array.isArray(array))
+        return array;
+    return EMPTY_ARRAY;
+}
+function ensureObject(value, from) {
+    if (value === undefined || value === null)
+        return EMPTY_OBJECT;
+    const obj = from(value);
+    if (typeof obj === 'object')
+        return obj;
+    return EMPTY_OBJECT;
+}
+function withDefault(value, defaultValue, from) {
+    if (value === undefined || value === null)
+        return defaultValue; // defaultValue should've already matched the type
+    return from(value);
+}

package/dist/root.js

@@ -1,5 +1,6 @@
-import { useCallback, useRef, useState } from 'react';
-import { getNestedValue, getSnapshot, isEqual, joinPath, notifyListeners, produce, setLeaf, useDebounce, useObject, useSubscribe } from './impl';
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+import { getNestedValue, getSnapshot, joinPath, notifyListeners, produce, rename, setLeaf, subscribe, useDebounce, useObject, useSubscribe } from './impl';
+import { createRootNode } from './node';
 export { createStoreRoot };
 /**
  * Creates the core store API with path-based methods.
@@ -20,6 +21,7 @@ function createStoreRoot(namespace, defaultValue, options = {}) {
     }
     produce(namespace, { ...defaultValue, ...(getSnapshot(namespace) ?? {}) }, true, true);
     const storeApi = {
+        state: (path) => createRootNode(storeApi, path),
         use: (path) => useObject(namespace, path),
         useDebounce: (path, delay) => useDebounce(namespace, path, delay),
         set: (path, value, skipUpdate = false) => {
@@ -31,24 +33,37 @@ function createStoreRoot(namespace, defaultValue, options = {}) {
         },
         value: (path) => getSnapshot(joinPath(namespace, path)),
         reset: (path) => produce(joinPath(namespace, path), undefined, false, memoryOnly),
+        rename: (path, oldKey, newKey, notifyObject = true) => rename(joinPath(namespace, path), oldKey, newKey, notifyObject),
         subscribe: (path, listener) => 
         // eslint-disable-next-line react-hooks/rules-of-hooks
         useSubscribe(joinPath(namespace, path), listener),
         useCompute: (path, fn) => {
             const fullPath = joinPath(namespace, path);
-            const initialValue = getSnapshot(fullPath);
-            const [computedValue, setComputedValue] = useState(() => fn(initialValue));
-            useSubscribe(fullPath, value => {
-                const newValue = fn(value);
-                if (!isEqual(computedValue, newValue)) {
-                    setComputedValue(newValue);
+            const fnRef = useRef(fn);
+            fnRef.current = fn;
+            // Cache to avoid infinite loops - only recompute when store value changes
+            const cacheRef = useRef(null);
+            const subscribeToPath = useCallback((onStoreChange) => subscribe(fullPath, onStoreChange), [fullPath]);
+            const getComputedSnapshot = useCallback(() => {
+                const storeValue = getSnapshot(fullPath);
+                // Return cached result if store value hasn't changed
+                if (cacheRef.current && cacheRef.current.storeValue === storeValue) {
+                    return cacheRef.current.computed;
                 }
-            });
-            return computedValue;
+                // Recompute and cache
+                const computed = fnRef.current(storeValue);
+                cacheRef.current = { storeValue, computed };
+                return computed;
+            }, [fullPath]);
+            return useSyncExternalStore(subscribeToPath, getComputedSnapshot, getComputedSnapshot);
         },
         notify: (path) => {
             const value = getNestedValue(getSnapshot(namespace), path);
-            return notifyListeners(joinPath(namespace, path), value, value, true, true);
+            return notifyListeners(joinPath(namespace, path), value, value, {
+                skipRoot: true,
+                skipChildren: true,
+                forceNotify: true
+            });
         },
         useState: (path) => {
             const fullPathRef = useRef(joinPath(namespace, path));

package/dist/store.d.ts

@@ -1,6 +1,6 @@
 import type { FieldValues } from './path';
 import { type StoreOptions } from './root';
-import type { DeepProxy, State, StoreRoot } from './types';
+import type { State, StoreRoot } from './types';
 export { createStore, type Store };
 /**
  * A persistent, hierarchical, cross-tab synchronized key-value store with React bindings.
@@ -14,7 +14,7 @@ export { createStore, type Store };
  * - Dynamic deep access via Proxy for ergonomic usage like `store.a.b.c.use()` and `store.a.b.c.set(v)`.
  */
 type Store<T extends FieldValues> = StoreRoot<T> & {
-    [K in keyof T]: NonNullable<T[K]> extends object ? DeepProxy<T[K]> : State<T[K]>;
+    [K in keyof T]-?: State<T[K]>;
 };
 /**
  * Creates a persistent, hierarchical store with localStorage backing and cross-tab synchronization.

package/dist/types.d.ts

@@ -1,17 +1,14 @@
-import type { FieldPath, FieldPathValue, FieldValues } from './path';
-export type { ArrayProxy, DeepProxy, DerivedStateProps, Prettify, State, StoreRenderProps, StoreRoot, StoreSetStateAction, StoreShowProps, StoreUse };
+import type { FieldPath, FieldPathValue, FieldValues, IsEqual } from './path';
+export type { AllowedKeys, ArrayProxy, ArrayState, DerivedStateProps, IsNullable, MaybeNullable, ObjectMutationMethods, ObjectState, Prettify, State, StoreRenderProps, StoreRoot, StoreSetStateAction, StoreShowProps, StoreUse, ValueState };
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
-/** Type for nested objects with proxy methods */
-type DeepProxy<T> = NonNullable<T> extends readonly (infer U)[] ? ArrayProxy<U> & State<T> : NonNullable<T> extends FieldValues ? {
-    [K in keyof NonNullable<T>]-?: NonNullable<NonNullable<T>[K]> extends object ? DeepProxy<NonNullable<T>[K]> : State<NonNullable<T>[K]>;
-} & State<T> : State<T>;
-type ArrayMutationMethods<T> = Pick<Array<T>, 'push' | 'pop' | 'shift' | 'unshift' | 'splice' | 'reverse' | 'sort' | 'fill' | 'copyWithin'>;
+type AllowedKeys<T> = Exclude<keyof T, keyof ValueState<unknown> | keyof ObjectMutationMethods>;
+type ArrayMutationMethods<T> = Prettify<Pick<Array<T>, 'push' | 'pop' | 'shift' | 'unshift' | 'splice' | 'reverse' | 'sort' | 'fill' | 'copyWithin'>>;
 /** Type for array proxy with index access */
-type ArrayProxy<T> = Prettify<ArrayMutationMethods<T>> & {
+type ArrayProxy<T, ElementState = State<T>> = ArrayMutationMethods<T> & {
     /** Read without subscribing. Returns array or undefined for missing paths. */
-    readonly value: T[] | undefined;
+    readonly value: T[];
     /**
      * Length of the underlying array. Runtime may return undefined when the
      * current value is not an array at the path. Prefer `Array.isArray(x) && x.length` when unsure.
@@ -20,42 +17,50 @@ type ArrayProxy<T> = Prettify<ArrayMutationMethods<T>> & {
     /** Numeric index access never returns undefined at the type level because
      * the proxy always returns another proxy object, even if the underlying value doesn't exist.
      */
-    [K: number]: T extends object ? DeepProxy<T> : State<T>;
+    [K: number]: ElementState;
     /** Safe accessor that never returns undefined at the type level */
-    at(index: number): T extends object ? DeepProxy<T> : State<T>;
+    at(index: number): ElementState;
     /** Insert items into the array in sorted order using the provided comparison function. */
     sortedInsert(cmp: (a: T, b: T) => number, ...items: T[]): number;
 };
+type ObjectMutationMethods = {
+    /** Rename a key in an object. */
+    rename: (oldKey: string, newKey: string, notifyObject?: boolean) => void;
+};
 /** Tuple returned by Store.use(path). */
 type StoreUse<T> = Readonly<[T | undefined, (value: T | undefined) => void]>;
 type StoreSetStateAction<T> = (value: T | undefined | ((prev: T) => T), skipUpdate?: boolean) => void;
 /** Public API returned by createStore(namespace, defaultValue). */
 type StoreRoot<T extends FieldValues> = {
+    /** Get the state object for a path. */
+    state: <P extends FieldPath<T>>(path: P) => State<FieldPathValue<T, P>>;
     /** Subscribe and read the value at path. Re-renders when the value changes. */
     use: <P extends FieldPath<T>>(path: P) => FieldPathValue<T, P> | undefined;
     /** Subscribe and read the debounced value at path. Re-renders when the value changes. */
     useDebounce: <P extends FieldPath<T>>(path: P, delay: number) => FieldPathValue<T, P> | undefined;
-    /** Set value at path (creates intermediate nodes as needed). */
-    set: <P extends FieldPath<T>>(path: P, value: FieldPathValue<T, P> | ((prev: FieldPathValue<T, P> | undefined) => FieldPathValue<T, P>), skipUpdate?: boolean) => void;
+    /** Convenience hook returning [value, setValue] for the path. */
+    useState: <P extends FieldPath<T>>(path: P) => StoreUse<FieldPathValue<T, P>>;
     /** Read without subscribing. */
     value: <P extends FieldPath<T>>(path: P) => FieldPathValue<T, P> | undefined;
+    /** Set value at path (creates intermediate nodes as needed). */
+    set: <P extends FieldPath<T>>(path: P, value: FieldPathValue<T, P> | ((prev: FieldPathValue<T, P> | undefined) => FieldPathValue<T, P>), skipUpdate?: boolean) => void;
     /** Delete value at path (for arrays, removes index; for objects, deletes key). */
     reset: <P extends FieldPath<T>>(path: P) => void;
+    /** Rename a key in an object. */
+    rename: <P extends FieldPath<T>>(path: P, oldKey: string, newKey: string, notifyObject?: boolean) => void;
     /** Subscribe to changes at path and invoke listener with the new value. */
     subscribe: <P extends FieldPath<T>>(path: P, listener: (value: FieldPathValue<T, P>) => void) => void;
     /** Compute a derived value from the current value, similar to useState + useMemo */
     useCompute: <P extends FieldPath<T>, R>(path: P, fn: (value: FieldPathValue<T, P>) => R) => R;
     /** Notify listeners at path. */
     notify: <P extends FieldPath<T>>(path: P) => void;
-    /** Convenience hook returning [value, setValue] for the path. */
-    useState: <P extends FieldPath<T>>(path: P) => StoreUse<FieldPathValue<T, P>>;
     /** Render-prop helper for inline usage. */
     Render: <P extends FieldPath<T>>(props: FieldPathValue<T, P> extends undefined ? never : StoreRenderProps<T, P>) => React.ReactNode;
     /** Show or hide children based on the value at the path. */
     Show: <P extends FieldPath<T>>(props: FieldPathValue<T, P> extends undefined ? never : StoreShowProps<T, P>) => React.ReactNode;
 };
 /** Common methods available on any deep proxy node */
-type State<T> = {
+type ValueState<T> = {
     /** Read without subscribing. */
     readonly value: T;
     /** The field name for the proxy. */
@@ -74,10 +79,27 @@ type State<T> = {
     subscribe(listener: (value: T) => void): void;
     /** Compute a derived value from the current value, similar to useState + useMemo */
     useCompute: <R>(fn: (value: T) => R) => R;
-    /** Virtual state derived from the current value. */
+    /** Ensure the value is an array. */
+    ensureArray(): NonNullable<T> extends (infer U)[] ? ArrayState<U> : never;
+    /** Ensure the value is an object. */
+    ensureObject(): NonNullable<T> extends FieldValues ? ObjectState<NonNullable<T>> : never;
+    /** Return a new state with a default value, and make the type non-nullable */
+    withDefault(defaultValue: T): State<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 }: {
-        from: (value: T | undefined) => R;
-        to: (value: R) => T | undefined;
+        from?: (value: T | undefined) => R;
+        to?: (value: R) => T | undefined;
     }) => State<R>;
     /** Notify listener of current value. */
     notify(): void;
@@ -102,7 +124,14 @@ type State<T> = {
         children: React.ReactNode;
         on: (value: T) => boolean;
     }) => React.ReactNode;
-} & (NonNullable<T> extends readonly (infer U)[] ? ArrayProxy<U> : unknown);
+};
+type MaybeNullable<T, Nullable extends boolean = false> = Nullable extends true ? T | undefined : T;
+type IsNullable<T> = T extends undefined | null ? true : false;
+type State<T> = IsEqual<T, unknown> extends true ? never : [NonNullable<T>] extends [readonly (infer U)[]] ? ArrayState<U, IsNullable<T>> : [NonNullable<T>] extends [FieldValues] ? ObjectState<NonNullable<T>, IsNullable<T>> : ValueState<T>;
+type ArrayState<T, Nullable extends boolean = false> = IsEqual<T, unknown> extends true ? never : ValueState<MaybeNullable<T[], Nullable>> & ArrayProxy<T>;
+type ObjectState<T extends FieldValues, Nullable extends boolean = false> = {
+    [K in keyof T]-?: State<T[K]>;
+} & ValueState<MaybeNullable<T, Nullable>> & ObjectMutationMethods;
 /** Props for Store.Render helper. */
 type StoreRenderProps<T extends FieldValues, P extends FieldPath<T>> = {
     path: P;
@@ -115,6 +144,6 @@ type StoreShowProps<T extends FieldValues, P extends FieldPath<T>> = {
     on: (value: FieldPathValue<T, P> | undefined) => boolean;
 };
 type DerivedStateProps<T, R> = {
-    from: (value: T | undefined) => R;
-    to: (value: R) => T | undefined;
+    from?: (value: T | undefined) => R;
+    to?: (value: R) => T | undefined;
 };

package/package.json

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