juststore 1.0.1 → 1.1.1

package/README.md

@@ -385,7 +385,7 @@ import { Conditional, Render, RenderWithUpdate } from "juststore";
 </RenderWithUpdate>;
 
 <Conditional state={store.user.role} on={(role) => role === "admin"}>
-  {(role) => <div>{role}</div>}
+  <AdminPage />
 </Conditional>;
 ```
 
@@ -400,7 +400,7 @@ import { Conditional, Render, RenderWithUpdate } from "juststore";
 - `useForm(defaultValue, fieldConfigs?)`
 - `createMixedState(...states)`
 - `createAtom(id, defaultValue, persistent?)`
-- `Render`, `RenderWithUpdate`, `Conditional`
+- `Render`, `RenderWithUpdate`, `Conditional`, `ConditionalRender`
 - `isEqual`
 - All public types from `path`, `types`, and `form`
 
@@ -429,7 +429,7 @@ Creates memory-only stores (no localStorage persistence).
 Creates a scalar atom-like state.
 
 - `persistent` defaults to `false`
-- methods: `.value`, `.use()`, `.set(value | updater)`, `.reset()`, `.subscribe(listener)`
+- methods: `.value`, `.use()`, `.set(value | updater)`, `.reset()`, `.subscribe(listener)`, `.useCompute(fn, deps?)`
 
 ### `createForm(namespace, defaultValue, fieldConfigs?)` / `useForm(defaultValue, fieldConfigs?)`
 
@@ -461,7 +461,8 @@ Combines multiple states into one read-only tuple-like state.
 
 - `Render` - render-prop helper for read-only usage
 - `RenderWithUpdate` - render-prop helper with updater callback
-- `Conditional` - conditional render helper based on predicate
+- `Conditional` - show/hide children based on predicate; uses `Activity` so children stay mounted when hidden (state preserved)
+- `ConditionalRender` - render only when predicate is true; children are a render prop receiving the value; returns `null` when false (unmounted)
 
 ## Store / State Methods
 

package/dist/atom.d.ts

@@ -16,6 +16,8 @@ type Atom<T> = {
     reset: () => void;
     /** Subscribe to the value.with a callback function. */
     subscribe: (listener: (value: T) => void) => () => void;
+    /** Compute a derived value from the current value, similar to useState + useMemo */
+    useCompute: <R>(fn: (value: T) => R, deps?: readonly unknown[]) => R;
 };
 type AtomSetState<T> = (value: T | ((prev: T) => T)) => void;
 /**

package/dist/atom.js

@@ -1,5 +1,5 @@
 import { useSyncExternalStore } from 'react';
-import { getSnapshot, updateSnapshot } from './impl';
+import { getSnapshot, updateSnapshot, useCompute } from './impl';
 export { createAtom };
 /**
  * Creates an atom with a given id and default value.
@@ -53,6 +53,9 @@ function createAtom(id, defaultValue, persistent = false) {
             if (prop === 'subscribe') {
                 return (target._subscribe ??= (listener) => subscribeAtom(key, memoryOnly, listener));
             }
+            if (prop === 'useCompute') {
+                return (target._useCompute ??= (fn, deps) => useCompute(key, undefined, fn, deps, memoryOnly));
+            }
             return undefined;
         }
     });

package/dist/impl.d.ts

@@ -1,6 +1,6 @@
 import type { FieldPath, FieldPathValue, FieldValues } from './path';
 import { getStableKeys, setExternalKeyOrder } from './stable_keys';
-export { getNestedValue, getSnapshot, getStableKeys, isClass, isEqual, isRecord, joinPath, notifyListeners, produce, rename, setExternalKeyOrder, setLeaf, setNestedValue, subscribe, testReset, updateSnapshot, useDebounce, useObject };
+export { getNestedValue, getSnapshot, getStableKeys, isClass, isEqual, isRecord, joinPath, notifyListeners, produce, rename, setExternalKeyOrder, setLeaf, setNestedValue, subscribe, testReset, updateSnapshot, useDebounce, useObject, useCompute };
 declare function testReset(): void;
 declare function isClass(value: unknown): boolean;
 declare function isRecord(value: unknown): boolean;
@@ -64,6 +64,7 @@ declare function notifyListeners(key: string, oldValue: unknown, newValue: unkno
  * @returns An unsubscribe function to remove the listener
  */
 declare function subscribe(key: string, listener: () => void): () => void;
+declare function useCompute<T = unknown, R = unknown>(namespace: string, path: string | undefined, fn: (value: T) => R, deps?: readonly unknown[], memoryOnly?: boolean): R;
 /**
  * Core mutation function that updates the store and notifies listeners.
  *

package/dist/impl.js

@@ -1,8 +1,8 @@
-import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react';
 import rfcIsEqual from 'react-fast-compare';
 import { KVStore } from './kv_store';
 import { getExternalKeyOrder, getStableKeys, setExternalKeyOrder } from './stable_keys';
-export { getNestedValue, getSnapshot, getStableKeys, isClass, isEqual, isRecord, joinPath, notifyListeners, produce, rename, setExternalKeyOrder, setLeaf, setNestedValue, subscribe, testReset, updateSnapshot, useDebounce, useObject };
+export { getNestedValue, getSnapshot, getStableKeys, isClass, isEqual, isRecord, joinPath, notifyListeners, produce, rename, setExternalKeyOrder, setLeaf, setNestedValue, subscribe, testReset, updateSnapshot, useDebounce, useObject, useCompute };
 const inMemStorage = new Map();
 const listeners = new Map();
 const descendantListenerKeysByPrefix = new Map();
@@ -434,6 +434,42 @@ function subscribe(key, listener) {
         }
     };
 }
+function useCompute(namespace, path, fn, deps, memoryOnly = false) {
+    const fullPath = joinPath(namespace, path);
+    const fnRef = useRef(fn);
+    fnRef.current = fn;
+    const cacheRef = useRef(null);
+    const depsRef = useRef(deps);
+    // Invalidate cached compute when hook inputs change.
+    if (!isEqual(depsRef.current, deps)) {
+        depsRef.current = deps;
+        cacheRef.current = null;
+    }
+    const pathRef = useRef(fullPath);
+    if (pathRef.current !== fullPath) {
+        pathRef.current = fullPath;
+        cacheRef.current = null;
+    }
+    const subscribeToPath = useCallback((onStoreChange) => subscribe(fullPath, onStoreChange), [fullPath]);
+    const getComputedSnapshot = useCallback(() => {
+        const storeValue = getSnapshot(fullPath, memoryOnly);
+        if (cacheRef.current && Object.is(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;
+        }
+        cacheRef.current = { storeValue, computed: computedNext };
+        return computedNext;
+    }, [fullPath, memoryOnly]);
+    return useSyncExternalStore(subscribeToPath, getComputedSnapshot, getComputedSnapshot);
+}
 /**
  * Core mutation function that updates the store and notifies listeners.
  *

package/dist/root.js

@@ -1,5 +1,5 @@
-import { useCallback, useRef, useSyncExternalStore } from 'react';
-import { getNestedValue, getSnapshot, isEqual, joinPath, notifyListeners, produce, rename, setLeaf, subscribe, useDebounce, useObject } from './impl';
+import { useCallback } from 'react';
+import { getNestedValue, getSnapshot, isRecord, joinPath, notifyListeners, produce, rename, setLeaf, subscribe, useCompute, useDebounce, useObject } from './impl';
 import { createRootNode } from './node';
 export { createStoreRoot };
 /**
@@ -18,7 +18,7 @@ function createStoreRoot(namespace, defaultValue, options = {}) {
     'use memo';
     const memoryOnly = options?.memoryOnly ?? false;
     // merge with default value and save in memory only
-    produce(namespace, { ...defaultValue, ...(getSnapshot(namespace, memoryOnly) ?? {}) }, true, true);
+    produce(namespace, mergeWithDefaults(defaultValue, getSnapshot(namespace, memoryOnly)), true, true);
     const storeApi = {
         state: (path) => createRootNode(storeApi, path),
         use: (path) => useObject(namespace, path, memoryOnly),
@@ -42,40 +42,7 @@ function createStoreRoot(namespace, defaultValue, options = {}) {
             return unsubscribe;
         },
         useCompute: (path, fn, deps) => {
-            const fullPath = joinPath(namespace, path);
-            const fnRef = useRef(fn);
-            fnRef.current = fn;
-            const cacheRef = useRef(null);
-            const depsRef = useRef(deps);
-            // Invalidate cached compute when hook inputs change.
-            if (!isEqual(depsRef.current, deps)) {
-                depsRef.current = deps;
-                cacheRef.current = null;
-            }
-            const pathRef = useRef(fullPath);
-            if (pathRef.current !== fullPath) {
-                pathRef.current = fullPath;
-                cacheRef.current = null;
-            }
-            const subscribeToPath = useCallback((onStoreChange) => subscribe(fullPath, onStoreChange), [fullPath]);
-            const getComputedSnapshot = useCallback(() => {
-                const storeValue = getSnapshot(fullPath, memoryOnly);
-                if (cacheRef.current && Object.is(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;
-                }
-                cacheRef.current = { storeValue, computed: computedNext };
-                return computedNext;
-            }, [fullPath]);
-            return useSyncExternalStore(subscribeToPath, getComputedSnapshot, getComputedSnapshot);
+            return useCompute(namespace, path, fn, deps, memoryOnly);
         },
         notify: (path) => {
             const value = getNestedValue(getSnapshot(namespace, memoryOnly), path);
@@ -97,3 +64,18 @@ function createStoreRoot(namespace, defaultValue, options = {}) {
     };
     return storeApi;
 }
+function mergeWithDefaults(defaultValue, existingValue) {
+    if (existingValue === undefined) {
+        return defaultValue;
+    }
+    if (!isRecord(defaultValue) || !isRecord(existingValue)) {
+        return existingValue;
+    }
+    const defaults = defaultValue;
+    const existing = existingValue;
+    const merged = { ...existing };
+    for (const key of Object.keys(defaults)) {
+        merged[key] = mergeWithDefaults(defaults[key], existing[key]);
+    }
+    return merged;
+}

package/dist/utils.d.ts

@@ -1,8 +1,8 @@
 import type { Atom } from './atom';
 import type { StoreSetStateValue, ValueState } from './types';
-export { Render, RenderWithUpdate, Conditional };
+export { Render, RenderWithUpdate, Conditional, ConditionalRender };
 type AtomLike<T> = Pick<Atom<T> | ValueState<T>, 'use' | 'set' | 'value'>;
-type ReadOnlyAtomLike<T> = Pick<Atom<T> | ValueState<T>, 'use' | 'value'>;
+type ReadOnlyAtomLike<T> = Pick<Atom<T> | ValueState<T>, 'use' | 'useCompute' | 'value'>;
 type RenderProps<State extends ReadOnlyAtomLike<unknown>> = {
     state: State;
     children: (value: State['value']) => React.ReactNode;
@@ -11,6 +11,16 @@ type RenderWithUpdateProps<State extends AtomLike<unknown>> = {
     state: State;
     children: (value: State['value'], update: (value: StoreSetStateValue<State['value']>) => void) => React.ReactNode;
 };
+type ConditionalProps<State extends ReadOnlyAtomLike<unknown>> = {
+    state: State;
+    on: (value: State['value']) => boolean;
+    children: React.ReactNode;
+};
+type ConditionalRenderProps<State extends ReadOnlyAtomLike<unknown>> = {
+    state: State;
+    on: (value: State['value']) => boolean;
+    children: (value: State['value']) => React.ReactNode;
+};
 /**
  * Renders the provided children function with the current value from the state.
  *
@@ -34,18 +44,29 @@ declare function Render<State extends ReadOnlyAtomLike<unknown>>({ state, childr
  * @returns The result of calling children with the current value and update function.
  */
 declare function RenderWithUpdate<State extends AtomLike<unknown>>({ state, children }: RenderWithUpdateProps<State>): import("react").ReactNode;
+/**
+ * Conditionally shows or hides the children based on the result of the `on` predicate.
+ *
+ * It uses the Activity component to keep component states even when hidden.
+ *
+ * @template T The type of the state value.
+ * @param props - The props object.
+ * @param props.state - The ValueState whose value will be used.
+ * @param props.on - A predicate that receives the value and returns whether to show children.
+ * @param props.children - The component to render if the predicate returns true.
+ * @returns The Activity component with the children.
+ */
+declare function Conditional<State extends ReadOnlyAtomLike<unknown>>({ state, on, children }: ConditionalProps<State>): import("react/jsx-runtime").JSX.Element;
 /**
  * Conditionally renders the children function based on the result of the `on` predicate.
  *
+ * It returns null if the predicate returns false.
+ *
  * @template T The type of the state value.
  * @param props - The props object.
  * @param props.state - The ValueState whose value will be used.
  * @param props.on - A predicate that receives the value and returns whether to show children.
- * @param props.children - A render prop that receives the current value for rendering if visible.
+ * @param props.children - The render function that receives the value.
  * @returns The result of children if the predicate returns true, otherwise null.
  */
-declare function Conditional<State extends ReadOnlyAtomLike<unknown>>({ state, on, children }: {
-    state: State;
-    on: (value: State['value']) => boolean;
-    children: (value: State['value']) => React.ReactNode;
-}): import("react").ReactNode;
+declare function ConditionalRender<State extends ReadOnlyAtomLike<unknown>>({ state, on, children }: ConditionalRenderProps<State>): import("react").ReactNode;

package/dist/utils.js

@@ -1,5 +1,6 @@
-import { useCallback } from 'react';
-export { Render, RenderWithUpdate, Conditional };
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Activity, useCallback } from 'react';
+export { Render, RenderWithUpdate, Conditional, ConditionalRender };
 /**
  * Renders the provided children function with the current value from the state.
  *
@@ -37,19 +38,37 @@ function RenderWithUpdate({ state, children }) {
     }, [state]);
     return children(value, update);
 }
+/**
+ * Conditionally shows or hides the children based on the result of the `on` predicate.
+ *
+ * It uses the Activity component to keep component states even when hidden.
+ *
+ * @template T The type of the state value.
+ * @param props - The props object.
+ * @param props.state - The ValueState whose value will be used.
+ * @param props.on - A predicate that receives the value and returns whether to show children.
+ * @param props.children - The component to render if the predicate returns true.
+ * @returns The Activity component with the children.
+ */
+function Conditional({ state, on, children }) {
+    const show = state.useCompute(on);
+    return _jsx(Activity, { mode: show ? 'visible' : 'hidden', children: children });
+}
 /**
  * Conditionally renders the children function based on the result of the `on` predicate.
  *
+ * It returns null if the predicate returns false.
+ *
  * @template T The type of the state value.
  * @param props - The props object.
  * @param props.state - The ValueState whose value will be used.
  * @param props.on - A predicate that receives the value and returns whether to show children.
- * @param props.children - A render prop that receives the current value for rendering if visible.
+ * @param props.children - The render function that receives the value.
  * @returns The result of children if the predicate returns true, otherwise null.
  */
-function Conditional({ state, on, children }) {
+function ConditionalRender({ state, on, children }) {
     const value = state.use();
-    const show = on(value); // on should not be expensive, memorizing just adds overhead
+    const show = on(value);
     if (!show) {
         return null;
     }

package/package.json

@@ -1,53 +1,63 @@
 {
-  "name": "juststore",
-  "version": "1.0.1",
-  "description": "A small, expressive, and type-safe state management library for React.",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "author": "Yusing",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/yusing/juststore.git"
-  },
-  "homepage": "https://github.com/yusing/juststore",
-  "bugs": {
-    "url": "https://github.com/yusing/juststore/issues"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "sideEffects": false,
-  "files": ["dist"],
-  "license": "AGPL-3.0-only",
-  "keywords": ["state", "react", "typescript", "hooks", "store", "state management", "react hooks"],
-  "scripts": {
-    "build": "bun --bun tsc",
-    "typecheck": "bun --bun tsc --noEmit",
-    "lint": "bun --bun biome check",
-    "format": "bun --bun biome format --write",
-    "format:check": "bun --bun biome format",
-    "prepublishOnly": "bun run build",
-    "publish": "npm publish --access public",
-    "prepare": "husky"
-  },
-  "peerDependencies": {
-    "react": ">=18.0.0"
-  },
-  "dependencies": {
-    "change-case": "^5.4.4",
-    "react-fast-compare": "^3.2.2"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.2",
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^25.3.0",
-    "@types/react": "^19.2.14",
-    "husky": "^9.1.7",
-    "react": "^19.2.4",
-    "typescript": "^5.9.3"
-  }
+	"name": "juststore",
+	"version": "1.1.1",
+	"description": "A small, expressive, and type-safe state management library for React.",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"author": "Yusing",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/yusing/juststore.git"
+	},
+	"homepage": "https://github.com/yusing/juststore",
+	"bugs": {
+		"url": "https://github.com/yusing/juststore/issues"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"sideEffects": false,
+	"files": [
+		"dist"
+	],
+	"license": "AGPL-3.0-only",
+	"keywords": [
+		"state",
+		"react",
+		"typescript",
+		"hooks",
+		"store",
+		"state management",
+		"react hooks"
+	],
+	"scripts": {
+		"build": "bun --bun tsc",
+		"typecheck": "bun --bun tsc --noEmit",
+		"lint": "biome check",
+		"format": "biome format --write",
+		"format:check": "biome format",
+		"prepublishOnly": "bun run build",
+		"publish": "npm publish --access public",
+		"prepare": "husky"
+	},
+	"peerDependencies": {
+		"react": ">=18.0.0"
+	},
+	"dependencies": {
+		"change-case": "^5.4.4",
+		"react-fast-compare": "^3.2.2"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.6",
+		"@eslint/js": "^10.0.1",
+		"@types/node": "^25.4.0",
+		"@types/react": "^19.2.14",
+		"husky": "^9.1.7",
+		"react": "^19.2.4",
+		"typescript": "^5.9.3"
+	}
 }