juststore 0.3.0 → 0.3.3

package/README.md

@@ -473,22 +473,25 @@ The store root provides path-based methods for dynamic access:
 
 ### 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                          |
-| `.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,5 +1,5 @@
-import type { FieldPath, FieldPathValue, FieldValues, Primitive } from './path';
-import type { ArrayProxy, ExcludeNullUndefined, ObjectMutationMethods, ValueState } from './types';
+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,19 +12,35 @@ type FormCommon = {
     /** Manually set a validation error. */
     setError: (error: string | undefined) => void;
 };
-type FormState<T> = [ExcludeNullUndefined<T>] extends [readonly (infer U)[]] ? FormArrayState<U> : [T] extends [FieldValues] ? FormObjectState<T> : [ExcludeNullUndefined<T>] extends [FieldValues] ? FormObjectState<ExcludeNullUndefined<T>> : FormValueState<T>;
-interface FormValueState<T> extends ValueState<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 FormArrayElementState<T> = T extends Primitive ? FormValueState<T> : FormState<T>;
-interface FormArrayState<T> extends FormValueState<T[]>, ArrayProxy<T, FormArrayElementState<T>> {
-}
-type FormObjectState<T extends FieldValues> = {
+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<T> & ObjectMutationMethods;
+} & FormValueState<MaybeNullable<T, Nullable>> & ObjectMutationMethods;
 /** Type for nested objects with proxy methods */
-type DeepNonNullable<T> = [ExcludeNullUndefined<T>] extends [readonly (infer U)[]] ? U[] : [ExcludeNullUndefined<T>] extends [FieldValues] ? {
-    [K in keyof ExcludeNullUndefined<T>]-?: DeepNonNullable<ExcludeNullUndefined<T>[K]>;
-} : ExcludeNullUndefined<T>;
+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.
  */

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 { State } from './types';
+import type { State, ValueState } from './types';
 export { useMemoryStore, type MemoryStore };
 /**
  * A component local store with React bindings.
@@ -10,7 +10,7 @@ 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> & {
+type MemoryStore<T extends FieldValues> = ValueState<T> & {
     [K in keyof T]-?: State<T[K]>;
 };
 /**

package/dist/mixed_state.d.ts

@@ -1,4 +1,4 @@
-import type { Prettify, State, ValueState } from './types';
+import type { Prettify, ValueState } from './types';
 export { createMixedState, type MixedState };
 /**
  * A combined state that aggregates multiple independent states into a tuple.
@@ -21,5 +21,5 @@ type MixedState<T extends readonly unknown[]> = Prettify<Pick<ValueState<Readonl
  * </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.js

@@ -87,10 +87,13 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
                 return () => storeApi.notify(path);
             }
             if (prop === 'ensureArray') {
-                return () => createNode(storeApi, path, cache, extensions, ensureArray, unchanged);
+                return () => createNode(storeApi, path, cache, extensions, value => ensureArray(value, from), unchanged);
             }
             if (prop === 'ensureObject') {
-                return () => createNode(storeApi, path, cache, extensions, ensureObject, unchanged);
+                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));
@@ -112,7 +115,7 @@ function createNode(storeApi, path, cache, extensions, from = unchanged, to = un
                 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') {
@@ -221,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;
         },
@@ -263,17 +265,26 @@ function isObjectMethod(prop) {
 function unchanged(value) {
     return value;
 }
-function ensureArray(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 [];
-    if (Array.isArray(value))
-        return value;
-    return [];
+        return EMPTY_OBJECT;
+    const obj = from(value);
+    if (typeof obj === 'object')
+        return obj;
+    return EMPTY_OBJECT;
 }
-function ensureObject(value) {
+function withDefault(value, defaultValue, from) {
     if (value === undefined || value === null)
-        return {};
-    if (typeof value === 'object')
-        return value;
-    return {};
+        return defaultValue; // defaultValue should've already matched the type
+    return from(value);
 }

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 };
 /**
@@ -41,19 +41,27 @@ function createStoreRoot(namespace, defaultValue, options = {}) {
             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;
+                }
                 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;
+                cacheRef.current = { path: fullPath, storeValue, computed: computedNext };
+                return computedNext;
             }, [fullPath]);
             return useSyncExternalStore(subscribeToPath, getComputedSnapshot, getComputedSnapshot);
         },
@@ -66,28 +74,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,12 +1,12 @@
-import type { FieldPath, FieldPathValue, FieldValues, Primitive } from './path';
-export type { AllowedKeys, ArrayElementState, ArrayProxy, ArrayState, DerivedStateProps, ExcludeNullUndefined, ObjectMutationMethods, ObjectState, Prettify, State, StoreRenderProps, StoreRoot, StoreSetStateAction, StoreShowProps, StoreUse, ValueState };
+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 AllowedKeys<T> = Exclude<keyof T, keyof ValueState<unknown> | keyof ObjectMutationMethods>;
-type ArrayMutationMethods<T> = Pick<Array<T>, 'push' | 'pop' | 'shift' | 'unshift' | 'splice' | 'reverse' | 'sort' | 'fill' | 'copyWithin'>;
+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, ElementState = ArrayElementState<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[];
     /**
@@ -80,9 +80,11 @@ type ValueState<T> = {
     /** Compute a derived value from the current value, similar to useState + useMemo */
     useCompute: <R>(fn: (value: T) => R) => R;
     /** Ensure the value is an array. */
-    ensureArray<U>(): ArrayState<U>;
+    ensureArray(): NonNullable<T> extends (infer U)[] ? ArrayState<U> : never;
     /** Ensure the value is an object. */
-    ensureObject<U extends FieldValues>(): ObjectState<U>;
+    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.
@@ -123,14 +125,13 @@ type ValueState<T> = {
         on: (value: T) => boolean;
     }) => React.ReactNode;
 };
-type ExcludeNullUndefined<T> = Exclude<T, undefined | null>;
-type ArrayElementState<T> = T extends Primitive ? ValueState<T> : State<T>;
-type State<T> = [ExcludeNullUndefined<T>] extends [readonly (infer U)[]] ? ArrayState<U> : [T] extends [FieldValues] ? ObjectState<T> : [ExcludeNullUndefined<T>] extends [FieldValues] ? ObjectState<ExcludeNullUndefined<T>> : ValueState<T>;
-interface ArrayState<T> extends ValueState<T[]>, ArrayProxy<T> {
-}
-type ObjectState<T extends FieldValues> = {
+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<T> & ObjectMutationMethods;
+} & 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.0",
+  "version": "0.3.3",
   "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"
   }
 }