juststore 0.3.2 → 0.3.4

package/README.md

@@ -454,44 +454,46 @@ Creates a form store with validation support.
 
 The store root provides path-based methods for dynamic access:
 
-| 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                            |
+| 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)` | Rename a key in an object                               |
+| `.keys(path)`                   | Get the readonly state of keys of 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)                                      |
-| `.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                                            |
+| 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)`    | Rename a key in an object                                               |
+| `.keys()`                    | Get the readonly state of keys of 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/impl.d.ts

@@ -1,5 +1,7 @@
 import type { FieldPath, FieldPathValue, FieldValues } from './path';
-export { getNestedValue, getSnapshot, isClass, isEqual, joinPath, notifyListeners, produce, rename, setLeaf, subscribe, useDebounce, useObject, useSubscribe };
+export { getNestedValue, getSnapshot, getStableKeys, isClass, isEqual, joinPath, notifyListeners, produce, rename, setExternalKeyOrder, setLeaf, subscribe, useDebounce, useObject, useSubscribe };
+declare function setExternalKeyOrder(target: object, keys: string[]): void;
+declare function getStableKeys(value: unknown): string[];
 declare function isClass(value: unknown): boolean;
 /** Compare two values for equality
  * @description
@@ -70,9 +72,8 @@ declare function produce(key: string, value: unknown, skipUpdate?: boolean, memo
  * @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;
+declare function rename(path: string, oldKey: string, newKey: string): void;
 /**
  * React hook that subscribes to and reads a value at a path.
  *

package/dist/impl.js

@@ -1,10 +1,43 @@
 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, rename, setLeaf, subscribe, useDebounce, useObject, useSubscribe };
+export { getNestedValue, getSnapshot, getStableKeys, isClass, isEqual, joinPath, notifyListeners, produce, rename, setExternalKeyOrder, setLeaf, subscribe, useDebounce, useObject, useSubscribe };
 const memoryStore = new Map();
 const listeners = new Map();
 const descendantListenerKeysByPrefix = new Map();
+const virtualRevisions = new Map();
+const externalKeyOrder = new WeakMap();
+function isVirtualKey(key) {
+    return key.endsWith('.__juststore_keys') || key === '__juststore_keys';
+}
+function setExternalKeyOrder(target, keys) {
+    externalKeyOrder.set(target, keys);
+}
+function hasOwn(target, key) {
+    return Object.prototype.hasOwnProperty.call(target, key);
+}
+function getStableKeys(value) {
+    if (!isRecord(value))
+        return [];
+    const target = value;
+    const existing = externalKeyOrder.get(target);
+    if (existing) {
+        const next = existing.filter(k => hasOwn(target, k));
+        const nextSet = new Set(next);
+        for (const k of Object.keys(target)) {
+            if (nextSet.has(k))
+                continue;
+            next.push(k);
+        }
+        if (next.length !== existing.length) {
+            setExternalKeyOrder(target, next);
+        }
+        return next;
+    }
+    const keys = Object.keys(target);
+    setExternalKeyOrder(target, keys);
+    return keys;
+}
 // check if the value is a class instance
 function isClass(value) {
     if (value === null || value === undefined)
@@ -21,6 +54,13 @@ function isClass(value) {
     }
     return false;
 }
+function isRecord(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value !== 'object')
+        return false;
+    return !Array.isArray(value) && !isClass(value);
+}
 /** Compare two values for equality
  * @description
  * - react-fast-compare for non-class instances
@@ -95,7 +135,14 @@ function setNestedValue(obj, path, value) {
         ? {}
         : Array.isArray(obj)
             ? [...obj]
-            : { ...obj };
+            : (() => {
+                const existing = obj;
+                const next = { ...existing };
+                const order = externalKeyOrder.get(existing);
+                if (order)
+                    setExternalKeyOrder(next, order);
+                return next;
+            })();
     let current = result;
     for (let i = 0; i < segments.length - 1; i++) {
         const segment = segments[i];
@@ -136,7 +183,11 @@ function setNestedValue(obj, path, value) {
                 next = [...existing];
             }
             else {
-                next = { ...existing };
+                const existingObj = existing;
+                next = { ...existingObj };
+                const order = externalKeyOrder.get(existingObj);
+                if (order)
+                    setExternalKeyOrder(next, order);
             }
             currentObj[segment] = next;
             current = next;
@@ -156,11 +207,22 @@ function setNestedValue(obj, path, value) {
     }
     else if (typeof current === 'object' && current !== null) {
         const currentObj = current;
+        const hadKey = hasOwn(currentObj, lastSegment);
         if (value === undefined) {
             delete currentObj[lastSegment];
+            if (hadKey) {
+                const order = externalKeyOrder.get(currentObj);
+                if (order)
+                    setExternalKeyOrder(currentObj, order.filter(k => k !== lastSegment));
+            }
         }
         else {
             currentObj[lastSegment] = value;
+            if (!hadKey) {
+                const order = externalKeyOrder.get(currentObj);
+                if (order)
+                    setExternalKeyOrder(currentObj, [...order, lastSegment]);
+            }
         }
     }
     return result;
@@ -209,6 +271,9 @@ function getKeyPrefixes(key) {
     prefixes.unshift(parts[0]);
     return prefixes;
 }
+function joinChildKey(parent, child) {
+    return parent ? `${parent}.${child}` : child;
+}
 /**
  * Notifies all relevant listeners when a value changes.
  *
@@ -221,6 +286,23 @@ function getKeyPrefixes(key) {
  * determined by deep equality comparison.
  */
 function notifyListeners(key, oldValue, newValue, { skipRoot = false, skipChildren = false, forceNotify = false } = {}) {
+    // Keep `state.xxx.keys()` in sync: any mutation under a path can change the set of
+    // keys for that path (or its ancestors). Keys are represented as virtual nodes at
+    // `${path}.__juststore_keys`, so we bump those virtual nodes here.
+    //
+    // Important: avoid recursion when *we* are notifying a virtual key.
+    if (!isVirtualKey(key)) {
+        const paths = [...getKeyPrefixes(key), key];
+        for (const p of paths) {
+            const virtualKey = joinChildKey(p, '__juststore_keys');
+            const listenerSet = listeners.get(virtualKey);
+            if (listenerSet && listenerSet.size > 0) {
+                // Only notify the virtual key subscribers; the current call will handle
+                // ancestors/children for the real key.
+                notifyVirtualKey(virtualKey);
+            }
+        }
+    }
     if (skipRoot && skipChildren) {
         if (!forceNotify && isEqual(oldValue, newValue)) {
             return;
@@ -260,6 +342,21 @@ function notifyListeners(key, oldValue, newValue, { skipRoot = false, skipChildr
         const childKeys = descendantListenerKeysByPrefix.get(key);
         if (childKeys) {
             for (const childKey of childKeys) {
+                if (isVirtualKey(childKey)) {
+                    const childPath = childKey.slice(key.length + 1);
+                    const suffix = '.__juststore_keys';
+                    const objectPath = childPath.endsWith(suffix) ? childPath.slice(0, -suffix.length) : '';
+                    const getKeys = (root) => {
+                        const obj = objectPath ? getNestedValue(root, objectPath) : root;
+                        return getStableKeys(obj);
+                    };
+                    const oldKeys = getKeys(oldValue);
+                    const newKeys = getKeys(newValue);
+                    if (forceNotify || !isEqual(oldKeys, newKeys)) {
+                        notifyVirtualKey(childKey);
+                    }
+                    continue;
+                }
                 const childPath = childKey.slice(key.length + 1);
                 const oldChildValue = getNestedValue(oldValue, childPath);
                 const newChildValue = getNestedValue(newValue, childPath);
@@ -273,8 +370,13 @@ function notifyListeners(key, oldValue, newValue, { skipRoot = false, skipChildr
         }
     }
 }
-function forceNotifyListeners(key, options = {}) {
-    notifyListeners(key, undefined, undefined, { ...options, forceNotify: true });
+function notifyVirtualKey(key) {
+    virtualRevisions.set(key, (virtualRevisions.get(key) ?? 0) + 1);
+    notifyListeners(key, undefined, undefined, {
+        skipRoot: true,
+        skipChildren: true,
+        forceNotify: true
+    });
 }
 // BroadcastChannel for cross-tab synchronization
 const broadcastChannel = typeof window !== 'undefined' ? new BroadcastChannel('juststore') : null;
@@ -367,6 +469,9 @@ const store = {
 };
 /** Snapshot getter used by React's useSyncExternalStore. */
 function getSnapshot(key) {
+    if (isVirtualKey(key)) {
+        return virtualRevisions.get(key) ?? 0;
+    }
     return store.get(key);
 }
 // Cross-tab synchronization: keep memoryStore in sync with BroadcastChannel events
@@ -413,14 +518,14 @@ function subscribe(key, listener) {
             keyListeners.delete(listener);
             if (keyListeners.size === 0) {
                 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);
+                for (const prefix of prefixes) {
+                    const prefixKeys = descendantListenerKeysByPrefix.get(prefix);
+                    if (prefixKeys) {
+                        prefixKeys.delete(key);
+                        if (prefixKeys.size === 0) {
+                            descendantListenerKeysByPrefix.delete(prefix);
+                        }
+                    }
                 }
             }
         }
@@ -459,29 +564,37 @@ function produce(key, value, skipUpdate = false, memoryOnly = false) {
  * @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) {
+function rename(path, oldKey, newKey) {
     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 });
-        }
+        const next = { [newKey]: undefined };
+        store.set(path, next);
+        setExternalKeyOrder(next, [newKey]);
+        notifyListeners(path, current, next);
         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 });
+    const obj = current;
+    if (oldKey === newKey)
+        return;
+    if (!hasOwn(obj, oldKey))
+        return;
+    const keyOrder = getStableKeys(obj);
+    const entries = [];
+    for (const key of keyOrder) {
+        if (!hasOwn(obj, key))
+            continue;
+        if (key === oldKey) {
+            entries.push([newKey, obj[oldKey]]);
+            continue;
+        }
+        entries.push([key, obj[key]]);
     }
+    const newObject = Object.fromEntries(entries);
+    store.set(path, newObject);
+    setExternalKeyOrder(newObject, Array.from(new Set(entries.map(([k]) => k))));
+    notifyListeners(path, current, newObject);
 }
 /**
  * React hook that subscribes to and reads a value at a path.

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export type * from './form';
 export { useForm } from './form';
 export { useMemoryStore, type MemoryStore } from './memory';
-export { createMixedState, type MixedState } from './mixed_state';
+export { createMixedState } from './mixed_state';
 export type * from './path';
 export { createStore, type Store } from './store';
 export type * from './types';

package/dist/mixed_state.d.ts

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

package/dist/mixed_state.js

@@ -21,6 +21,9 @@ function createMixedState(...states) {
             return states.map(state => state.value);
         },
         use,
+        useCompute(fn) {
+            return states.map(state => state.useCompute(value => fn(value)));
+        },
         Render({ children }) {
             const value = use();
             return children(value);

package/dist/node.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { getStableKeys } from './impl';
 export { createNode, createRootNode };
 /**
  * Creates the root proxy node for dynamic path access.
@@ -40,60 +42,80 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
                 return fieldName;
             }
             if (prop === 'use') {
-                return () => from(storeApi.use(path));
+                return (_target._use ??= () => from(storeApi.use(path)));
             }
             if (prop === 'useDebounce') {
-                return (delay) => from(storeApi.useDebounce(path, delay));
+                return (_target._useDebounce ??= (delay) => from(storeApi.useDebounce(path, delay)));
             }
             if (prop === 'useState') {
-                return () => {
+                return (_target._useState ??= () => {
                     const value = storeApi.use(path);
                     return [from(value), (next) => storeApi.set(path, to(next))];
-                };
+                });
             }
             if (prop === 'value') {
                 return from(storeApi.value(path));
             }
             if (prop === 'set') {
-                return (value, skipUpdate) => storeApi.set(path, to(value), skipUpdate);
+                return (_target._set ??= (value, skipUpdate) => storeApi.set(path, to(value), skipUpdate));
             }
             if (prop === 'reset') {
-                return () => storeApi.reset(path);
+                return (_target._reset ??= () => storeApi.reset(path));
             }
             if (prop === 'subscribe') {
-                return (listener) => storeApi.subscribe(path, value => listener(to(value)));
+                return (_target._subscribe ??= (listener) => storeApi.subscribe(path, value => listener(to(value))));
             }
             if (prop === 'Render') {
-                return ({ children }) => storeApi.Render({
+                return (_target._Render ??= ({ children }) => storeApi.Render({
                     path,
                     children: (value, update) => children(from(value), value => update(to(value)))
-                });
+                }));
             }
             if (prop === 'Show') {
-                return ({ children, on }) => storeApi.Show({ path, children, on: value => on(from(value)) });
+                return (_target._Show ??= ({ children, on }) => storeApi.Show({ path, children, on: value => on(from(value)) }));
             }
             if (prop === 'useCompute') {
-                return (fn) => {
+                return (_target._useCompute ??= (fn) => {
                     return storeApi.useCompute(path, value => fn(from(value)));
-                };
+                });
             }
             if (prop === 'derived') {
                 if (isDerived) {
                     throw new Error(`Derived method cannot be called on a derived node: ${path}`);
                 }
-                return ({ from, to }) => createNode(storeApi, path, cache, extensions, from, to);
+                return (_target._derived ??= ({ from, to }) => createNode(storeApi, path, cache, extensions, from, to));
             }
             if (prop === 'notify') {
-                return () => storeApi.notify(path);
+                return (_target._notify ??= () => storeApi.notify(path));
             }
             if (prop === 'ensureArray') {
-                return () => createNode(storeApi, path, cache, extensions, value => ensureArray(value, from), unchanged);
+                return (_target._ensureArray ??= () => {
+                    const cacheKey = `${path}.__juststore_ensureArray`;
+                    if (!isDerived && cache.has(cacheKey)) {
+                        return cache.get(cacheKey);
+                    }
+                    const node = createNode(storeApi, path, cache, extensions, value => ensureArray(value, from), unchanged);
+                    if (!isDerived) {
+                        cache.set(cacheKey, node);
+                    }
+                    return node;
+                });
             }
             if (prop === 'ensureObject') {
-                return () => createNode(storeApi, path, cache, extensions, value => ensureObject(value, from), to);
+                return (_target._ensureObject ??= () => {
+                    const cacheKey = `${path}.__juststore_ensureObject`;
+                    if (!isDerived && cache.has(cacheKey)) {
+                        return cache.get(cacheKey);
+                    }
+                    const node = createNode(storeApi, path, cache, extensions, value => ensureObject(value, from), to);
+                    if (!isDerived) {
+                        cache.set(cacheKey, node);
+                    }
+                    return node;
+                });
             }
             if (prop === 'withDefault') {
-                return (defaultValue) => createNode(storeApi, path, cache, extensions, value => withDefault(value, defaultValue, from), to);
+                return (_target._withDefault ??= (defaultValue) => createNode(storeApi, path, cache, extensions, value => withDefault(value, defaultValue, from), to));
             }
             if (isObjectMethod(prop)) {
                 const derivedValue = from(storeApi.value(path));
@@ -101,9 +123,18 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
                     throw new Error(`Expected object at path ${path}, got ${typeof derivedValue}`);
                 }
                 if (prop === 'rename') {
-                    return (oldKey, newKey, notifyObject) => {
-                        storeApi.rename(path, oldKey, newKey, notifyObject);
-                    };
+                    return (_target._rename ??= (oldKey, newKey) => storeApi.rename(path, oldKey, newKey));
+                }
+                if (prop === 'keys') {
+                    const cacheKey = `${path}.__juststore_keys`;
+                    if (!isDerived && cache.has(cacheKey)) {
+                        return cache.get(cacheKey);
+                    }
+                    const keysNode = createKeysNode(storeApi, path, value => ensureObject(value, from));
+                    if (!isDerived) {
+                        cache.set(cacheKey, keysNode);
+                    }
+                    return keysNode;
                 }
             }
             if (isArrayMethod(prop)) {
@@ -113,91 +144,115 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
                 }
                 const currentArray = derivedValue ? [...derivedValue] : [];
                 if (prop === 'at') {
-                    return (index) => {
+                    return (_target._at ??= (index) => {
                         const nextPath = path ? `${path}.${index}` : String(index);
                         return createNode(storeApi, nextPath, cache, extensions);
-                    };
+                    });
                 }
                 if (prop === 'length') {
                     return currentArray.length;
                 }
                 // Array mutation methods
                 if (prop === 'push') {
-                    return (...items) => {
-                        const newArray = [...currentArray, ...items];
+                    return (_target._push ??= (...items) => {
+                        // We need to fetch the current array at call time, not bind time
+                        const arr = from(storeApi.value(path)) ?? [];
+                        const newArray = [...arr, ...items];
                         storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return newArray.length;
-                    };
+                    });
                 }
                 if (prop === 'pop') {
-                    return () => {
-                        if (currentArray.length === 0)
+                    return (_target._pop ??= () => {
+                        const arr = from(storeApi.value(path)) ?? [];
+                        if (arr.length === 0)
                             return undefined;
-                        const newArray = currentArray.slice(0, -1);
-                        const poppedItem = currentArray[currentArray.length - 1];
+                        const newArray = arr.slice(0, -1);
+                        const poppedItem = arr[arr.length - 1];
                         storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return poppedItem;
-                    };
+                    });
                 }
                 if (prop === 'shift') {
-                    return () => {
-                        if (currentArray.length === 0)
+                    return (_target._shift ??= () => {
+                        const arr = from(storeApi.value(path)) ?? [];
+                        if (arr.length === 0)
                             return undefined;
-                        const newArray = currentArray.slice(1);
-                        const shiftedItem = currentArray[0];
+                        const newArray = arr.slice(1);
+                        const shiftedItem = arr[0];
                         storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return shiftedItem;
-                    };
+                    });
                 }
                 if (prop === 'unshift') {
-                    return (...items) => {
-                        const newArray = [...items, ...currentArray];
+                    return (_target._unshift ??= (...items) => {
+                        const arr = from(storeApi.value(path)) ?? [];
+                        const newArray = [...items, ...arr];
                         storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return newArray.length;
-                    };
+                    });
                 }
                 if (prop === 'splice') {
-                    return (start, deleteCount, ...items) => {
-                        const deletedItems = currentArray.splice(start, deleteCount ?? 0, ...items);
-                        storeApi.set(path, isDerived ? currentArray.map(to) : currentArray);
+                    return (_target._splice ??= (start, deleteCount, ...items) => {
+                        const arr = from(storeApi.value(path)) ?? [];
+                        const newArray = [...arr];
+                        const deletedItems = newArray.splice(start, deleteCount ?? 0, ...items);
+                        storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return deletedItems;
-                    };
+                    });
                 }
                 if (prop === 'reverse') {
-                    return () => {
-                        if (!Array.isArray(currentArray))
+                    return (_target._reverse ??= () => {
+                        const arr = from(storeApi.value(path));
+                        if (!Array.isArray(arr))
                             return [];
-                        currentArray.reverse();
-                        storeApi.set(path, isDerived ? currentArray.map(to) : currentArray);
-                        return currentArray;
-                    };
+                        const newArray = [...arr];
+                        newArray.reverse();
+                        storeApi.set(path, isDerived ? newArray.map(to) : newArray);
+                        return newArray;
+                    });
                 }
                 if (prop === 'sort') {
-                    return (compareFn) => {
-                        currentArray.sort(compareFn);
-                        storeApi.set(path, isDerived ? currentArray.map(to) : currentArray);
-                        return currentArray;
-                    };
+                    return (_target._sort ??= (compareFn) => {
+                        const arr = from(storeApi.value(path));
+                        if (!Array.isArray(arr))
+                            return [];
+                        const newArray = [...arr];
+                        newArray.sort(compareFn);
+                        storeApi.set(path, isDerived ? newArray.map(to) : newArray);
+                        return newArray;
+                    });
                 }
                 if (prop === 'fill') {
-                    return (value, start, end) => {
-                        currentArray.fill(value, start, end);
-                        storeApi.set(path, isDerived ? currentArray.map(to) : currentArray);
-                        return currentArray;
-                    };
+                    return (_target._fill ??= (value, start, end) => {
+                        const arr = from(storeApi.value(path));
+                        if (!Array.isArray(arr))
+                            return [];
+                        const newArray = [...arr];
+                        newArray.fill(value, start, end);
+                        storeApi.set(path, isDerived ? newArray.map(to) : newArray);
+                        return newArray;
+                    });
                 }
                 if (prop === 'copyWithin') {
-                    return (target, start, end) => {
-                        currentArray.copyWithin(target, start, end);
-                        storeApi.set(path, isDerived ? currentArray.map(to) : currentArray);
-                        return currentArray;
-                    };
+                    return (_target._copyWithin ??= (target, start, end) => {
+                        const arr = from(storeApi.value(path));
+                        if (!Array.isArray(arr))
+                            return [];
+                        const newArray = [...arr];
+                        newArray.copyWithin(target, start, end);
+                        storeApi.set(path, isDerived ? newArray.map(to) : newArray);
+                        return newArray;
+                    });
                 }
                 if (prop === 'sortedInsert') {
-                    return (cmp, ...items) => {
+                    return (_target._sortedInsert ??= (cmp, ...items) => {
+                        const arr = from(storeApi.value(path));
+                        if (!Array.isArray(arr))
+                            return [];
                         if (typeof cmp !== 'function')
-                            return currentArray.length;
-                        const newArray = [...currentArray];
+                            return arr.length;
+                        const newArray = [...arr];
                         for (const item of items) {
                             let left = 0;
                             let right = newArray.length;
@@ -216,7 +271,7 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
                         }
                         storeApi.set(path, isDerived ? newArray.map(to) : newArray);
                         return newArray.length;
-                    };
+                    });
                 }
             }
             if (extensions?.[prop]?.get) {
@@ -260,13 +315,44 @@ function isArrayMethod(prop) {
         prop === 'sortedInsert');
 }
 function isObjectMethod(prop) {
-    return prop === 'rename';
+    return prop === 'rename' || prop === 'keys';
 }
 function unchanged(value) {
     return value;
 }
 const EMPTY_ARRAY = [];
 const EMPTY_OBJECT = {};
+function createKeysNode(storeApi, path, getObjectValue) {
+    const signalPath = path ? `${path}.__juststore_keys` : '__juststore_keys';
+    const computeKeys = () => {
+        return getStableKeys(getObjectValue(storeApi.value(path)));
+    };
+    return new Proxy({}, {
+        get(_target, prop) {
+            if (prop === 'use') {
+                return (_target._use ??= () => storeApi.useCompute(signalPath, computeKeys));
+            }
+            if (prop === 'value')
+                return computeKeys();
+            if (prop === 'useCompute') {
+                return (_target._useCompute ??= (fn) => {
+                    return storeApi.useCompute(signalPath, () => fn(computeKeys()));
+                });
+            }
+            if (prop === 'Render') {
+                return (_target._Render ??= ({ children }) => children(storeApi.useCompute(signalPath, computeKeys), () => { }));
+            }
+            if (prop === 'Show') {
+                // eslint-disable-next-line react/display-name
+                return (_target._Show ??= ({ children, on }) => {
+                    const show = storeApi.useCompute(signalPath, () => on(computeKeys()), [on]);
+                    return show ? children : null;
+                });
+            }
+            return undefined;
+        }
+    });
+}
 function ensureArray(value, from) {
     if (value === undefined || value === null)
         return EMPTY_ARRAY;
@@ -279,7 +365,7 @@ function ensureObject(value, from) {
     if (value === undefined || value === null)
         return EMPTY_OBJECT;
     const obj = from(value);
-    if (typeof obj === 'object')
+    if (obj && typeof obj === 'object' && !Array.isArray(obj))
         return obj;
     return EMPTY_OBJECT;
 }

package/dist/root.js

@@ -1,5 +1,5 @@
 import { useCallback, useRef, useSyncExternalStore } from 'react';
-import { getNestedValue, getSnapshot, joinPath, notifyListeners, produce, rename, setLeaf, subscribe, useDebounce, useObject, useSubscribe } from './impl';
+import { getNestedValue, getSnapshot, isEqual, joinPath, notifyListeners, produce, rename, setLeaf, subscribe, useDebounce, useObject, useSubscribe } from './impl';
 import { createRootNode } from './node';
 export { createStoreRoot };
 /**
@@ -33,28 +33,39 @@ 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),
+        rename: (path, oldKey, newKey) => rename(joinPath(namespace, path), oldKey, newKey),
         subscribe: (path, listener) => 
         // eslint-disable-next-line react-hooks/rules-of-hooks
         useSubscribe(joinPath(namespace, path), listener),
-        useCompute: (path, fn) => {
+        useCompute: (path, fn, deps) => {
             const fullPath = joinPath(namespace, path);
             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(() => {
+                if (cacheRef.current && cacheRef.current.path !== fullPath) {
+                    cacheRef.current = null;
+                }
+                if (cacheRef.current && !isEqual(cacheRef.current.deps, deps)) {
+                    cacheRef.current = null;
+                }
                 const storeValue = getSnapshot(fullPath);
-                // Return cached result if store value hasn't changed
-                if (cacheRef.current && cacheRef.current.storeValue === storeValue) {
+                if (cacheRef.current && isEqual(cacheRef.current.storeValue, storeValue)) {
+                    // same store value, return the same computed value
+                    return cacheRef.current.computed;
+                }
+                const computedNext = fnRef.current(storeValue);
+                // Important: even if storeValue changed, we should avoid forcing a re-render
+                // when the computed result is logically unchanged. `useSyncExternalStore`
+                // uses `Object.is` on the snapshot; returning the same reference will bail out.
+                if (cacheRef.current && isEqual(cacheRef.current.computed, computedNext)) {
+                    cacheRef.current.storeValue = storeValue;
                     return cacheRef.current.computed;
                 }
-                // Recompute and cache
-                const computed = fnRef.current(storeValue);
-                cacheRef.current = { storeValue, computed };
-                return computed;
-            }, [fullPath]);
+                cacheRef.current = { path: fullPath, storeValue, computed: computedNext, deps };
+                return computedNext;
+            }, [fullPath, deps]);
             return useSyncExternalStore(subscribeToPath, getComputedSnapshot, getComputedSnapshot);
         },
         notify: (path) => {
@@ -66,28 +77,28 @@ function createStoreRoot(namespace, defaultValue, options = {}) {
             });
         },
         useState: (path) => {
-            const fullPathRef = useRef(joinPath(namespace, path));
+            const fullPath = joinPath(namespace, path);
             const setValue = useCallback((value) => {
                 if (typeof value === 'function') {
-                    const currentValue = getSnapshot(fullPathRef.current);
+                    const currentValue = getSnapshot(fullPath);
                     const newValue = value(currentValue);
                     return setLeaf(namespace, path, newValue, false, memoryOnly);
                 }
                 return setLeaf(namespace, path, value, false, memoryOnly);
-            }, [path]);
-            return [useObject(fullPathRef.current), setValue];
+            }, [fullPath, path]);
+            return [useObject(namespace, path), setValue];
         },
         Render: ({ path, children }) => {
-            const fullPathRef = useRef(joinPath(namespace, path));
-            const value = useObject(fullPathRef.current);
+            const fullPath = joinPath(namespace, path);
+            const value = useObject(namespace, path);
             const update = useCallback((value) => {
                 if (typeof value === 'function') {
-                    const currentValue = getSnapshot(fullPathRef.current);
+                    const currentValue = getSnapshot(fullPath);
                     const newValue = value(currentValue);
                     return setLeaf(namespace, path, newValue, false, memoryOnly);
                 }
                 return setLeaf(namespace, path, value, false, memoryOnly);
-            }, [path]);
+            }, [fullPath, path]);
             return children(value, update);
         },
         Show: ({ path, children, on }) => {

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 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 };
+export type { AllowedKeys, ArrayProxy, ArrayState, DerivedStateProps, IsNullable, MaybeNullable, ObjectMutationMethods, ObjectState, Prettify, ReadOnlyState, State, StoreRenderProps, StoreRoot, StoreSetStateAction, StoreShowProps, StoreUse, ValueState };
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
@@ -23,9 +23,18 @@ type ArrayProxy<T, ElementState = State<T>> = ArrayMutationMethods<T> & {
     /** Insert items into the array in sorted order using the provided comparison function. */
     sortedInsert(cmp: (a: T, b: T) => number, ...items: T[]): number;
 };
+type ObjectProxy<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: ReadOnlyState<FieldPath<T>[]>;
+} & {
+    [K in keyof T]-?: State<T[K]>;
+};
 type ObjectMutationMethods = {
     /** Rename a key in an object. */
-    rename: (oldKey: string, newKey: string, notifyObject?: boolean) => void;
+    rename: (oldKey: string, newKey: string) => void;
 };
 /** Tuple returned by Store.use(path). */
 type StoreUse<T> = Readonly<[T | undefined, (value: T | undefined) => void]>;
@@ -47,11 +56,11 @@ type StoreRoot<T extends FieldValues> = {
     /** 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;
+    rename: <P extends FieldPath<T>>(path: P, oldKey: string, newKey: string) => 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;
+    useCompute: <P extends FieldPath<T>, R>(path: P, fn: (value: FieldPathValue<T, P>) => R, deps?: readonly unknown[]) => R;
     /** Notify listeners at path. */
     notify: <P extends FieldPath<T>>(path: P) => void;
     /** Render-prop helper for inline usage. */
@@ -78,7 +87,7 @@ type ValueState<T> = {
     /** Subscribe to changes at path and invoke listener with the new value. */
     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;
+    useCompute: <R>(fn: (value: T) => R, deps?: readonly unknown[]) => R;
     /** Ensure the value is an array. */
     ensureArray(): NonNullable<T> extends (infer U)[] ? ArrayState<U> : never;
     /** Ensure the value is an object. */
@@ -125,13 +134,15 @@ type ValueState<T> = {
         on: (value: T) => boolean;
     }) => React.ReactNode;
 };
+/**
+ * A read-only state that provides access to the value, use, Render, and Show methods.
+ */
+type ReadOnlyState<T> = Prettify<Pick<ValueState<Readonly<Required<T>>>, 'value' | 'use' | 'useCompute' | 'Render' | 'Show'>>;
 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;
+type ObjectState<T extends FieldValues, Nullable extends boolean = false> = ObjectProxy<T> & ValueState<MaybeNullable<T, Nullable>> & ObjectMutationMethods;
 /** Props for Store.Render helper. */
 type StoreRenderProps<T extends FieldValues, P extends FieldPath<T>> = {
     path: P;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "juststore",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "A small, expressive, and type-safe state management library for React.",
   "type": "module",
   "main": "dist/index.js",
@@ -52,19 +52,19 @@
     "react-fast-compare": "^3.2.2"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^24.10.2",
-    "@types/react": "^19.2.1",
-    "@typescript-eslint/eslint-plugin": "^8.49.0",
-    "@typescript-eslint/parser": "^8.49.0",
-    "eslint": "^9.39.1",
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^24.10.4",
+    "@types/react": "^19.2.7",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "eslint": "^9.39.2",
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.4.24",
+    "eslint-plugin-react-refresh": "^0.4.26",
     "husky": "^9.1.7",
     "prettier": "^3.7.4",
-    "react": "^19.2.1",
+    "react": "^19.2.3",
     "typescript": "^5.9.3"
   }
 }