juststore 1.1.1 → 1.2.0

package/dist/src/store.d.ts

@@ -0,0 +1,42 @@
+import type { FieldValues } from "./path";
+import { type StoreOptions } from "./root";
+import type { State, StoreRoot } from "./types";
+export { createStore, type Store };
+/**
+ * A persistent, hierarchical, cross-tab synchronized key-value store with React bindings.
+ *
+ * - Dot-path addressing for nested values (e.g. "config.ui.theme").
+ * - Immutable partial updates with automatic object/array creation.
+ * - Persists root namespaces to localStorage with an in-memory mirror (no localStorage on SSR).
+ * - Cross-tab synchronization via BroadcastChannel (no-ops on SSR).
+ * - Fine-grained subscriptions built on useSyncExternalStore.
+ * - Type-safe paths using FieldPath.
+ * - Dynamic deep access via Proxy for ergonomic usage like `store.a.b.c.use()` and `store.a.b.c.set(v)`.
+ */
+type Store<T extends FieldValues> = StoreRoot<T> & {
+    [K in keyof T]-?: State<T[K]>;
+};
+/**
+ * Creates a persistent, hierarchical store with localStorage backing and cross-tab synchronization.
+ *
+ * @param namespace - Unique identifier for the store, used as the localStorage key prefix
+ * @param defaultValue - Initial state shape; merged with any existing persisted data
+ * @param options - Configuration options
+ * @param options.memoryOnly - When true, disables localStorage persistence (default: false)
+ * @returns A proxy object providing both path-based and dynamic property access to the store
+ *
+ * @example
+ * const store = createStore('app', {
+ *   user: { name: 'Guest' },
+ *   todos: []
+ * })
+ *
+ * // Dynamic access
+ * store.user.name.use()
+ * store.todos.push({ text: 'New todo' })
+ *
+ * // Path-based access
+ * store.use('user.name')
+ * store.set('user.name', 'Alice')
+ */
+declare function createStore<T extends FieldValues>(namespace: string, defaultValue: T, options?: StoreOptions): Store<T>;

package/dist/src/store.js

@@ -0,0 +1,40 @@
+import { createRootNode } from "./node";
+import { createStoreRoot } from "./root";
+export { createStore };
+/**
+ * Creates a persistent, hierarchical store with localStorage backing and cross-tab synchronization.
+ *
+ * @param namespace - Unique identifier for the store, used as the localStorage key prefix
+ * @param defaultValue - Initial state shape; merged with any existing persisted data
+ * @param options - Configuration options
+ * @param options.memoryOnly - When true, disables localStorage persistence (default: false)
+ * @returns A proxy object providing both path-based and dynamic property access to the store
+ *
+ * @example
+ * const store = createStore('app', {
+ *   user: { name: 'Guest' },
+ *   todos: []
+ * })
+ *
+ * // Dynamic access
+ * store.user.name.use()
+ * store.todos.push({ text: 'New todo' })
+ *
+ * // Path-based access
+ * store.use('user.name')
+ * store.set('user.name', 'Alice')
+ */
+function createStore(namespace, defaultValue, options = {}) {
+    const storeApi = createStoreRoot(namespace, defaultValue, options);
+    return new Proxy(storeApi, {
+        get(target, prop) {
+            if (prop in target) {
+                return target[prop];
+            }
+            if (typeof prop === "string" || typeof prop === "number") {
+                return createRootNode(target, prop);
+            }
+            return undefined;
+        },
+    });
+}

package/dist/src/types.d.ts

@@ -0,0 +1,143 @@
+import type { FieldPath, FieldPathValue, FieldValues, IsEqual } from "./path";
+export type { AllowedKeys, ArrayProxy, ArrayState, DerivedStateProps, ObjectMutationMethods, ObjectState, Prettify, ReadOnlyState, State, StoreRoot, StoreSetStateValue, StoreUseComputeFn, StoreUseState, ValueState, };
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type AllowedKeys<T> = Exclude<keyof T, keyof ValueState<unknown> | keyof ObjectMutationMethods>;
+type ArrayMutationMethods<T> = Prettify<Pick<Array<T>, "push" | "pop" | "shift" | "unshift" | "splice" | "reverse" | "sort" | "fill" | "copyWithin">>;
+/** Type for array proxy with index access */
+type ArrayProxy<T, ElementState = State<T>> = ArrayMutationMethods<NonNullable<T>> & {
+    /** Read without subscribing. Returns array or undefined for missing paths. */
+    readonly value: T[];
+    /**
+     * Length of the underlying array. Runtime may return undefined when the
+     * current value is not an array at the path. Prefer `Array.isArray(x) && x.length` when unsure.
+     */
+    readonly length: number;
+    /** Subscribe to array length changes without subscribing to individual element changes. */
+    useLength(): number;
+    /** Numeric index access never returns undefined at the type level because
+     * the proxy always returns another proxy object, even if the underlying value doesn't exist.
+     */
+    [K: number]: ElementState;
+    /** Safe accessor that never returns undefined at the type level */
+    at(index: number): ElementState;
+    /** Insert items into the array in sorted order using the provided comparison function. */
+    sortedInsert(cmp: (a: T, b: T) => number, ...items: T[]): number;
+};
+type 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) => void;
+};
+/** Tuple returned by Store.use(path). */
+type StoreUseState<T> = Readonly<[
+    T,
+    (value: StoreSetStateValue<T>, skipUpdate?: boolean) => void
+]>;
+/** Value type for set method. */
+type StoreSetStateValue<T> = T | ((prev: T) => T);
+/** Public API returned by createStore(namespace, defaultValue). */
+type StoreRoot<T extends FieldValues> = {
+    /** Get the state object for a path. */
+    state: <P extends FieldPath<T>>(path: P) => State<FieldPathValue<T, P>>;
+    /** Subscribe and read the value at path. Re-renders when the value changes. */
+    use: <P extends FieldPath<T>>(path: P) => FieldPathValue<T, P>;
+    /** Subscribe and read the debounced value at path. Re-renders when the value changes. */
+    useDebounce: <P extends FieldPath<T>>(path: P, delay: number) => FieldPathValue<T, P>;
+    /** Convenience hook returning [value, setValue] for the path. */
+    useState: <P extends FieldPath<T>>(path: P) => StoreUseState<FieldPathValue<T, P>>;
+    /** Read without subscribing. */
+    value: <P extends FieldPath<T>>(path: P) => FieldPathValue<T, P>;
+    /** Set value at path (creates intermediate nodes as needed). */
+    set: <P extends FieldPath<T>>(path: P, value: StoreSetStateValue<FieldPathValue<T, P>>, skipUpdate?: boolean) => void;
+    /** Delete value at path (for arrays, removes index; for objects, deletes key). */
+    reset: <P extends FieldPath<T>>(path: P) => void;
+    /** Rename a key in an object. */
+    rename: <P extends FieldPath<T>>(path: P, oldKey: string, newKey: string) => void;
+    /** Subscribe to changes at path and invoke listener with the new value
+     *
+     * @returns A function to unsubscribe from the path.
+     */
+    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: StoreUseComputeFn<T, P, R>, deps?: readonly unknown[]) => R;
+    /** Notify listeners at path. */
+    notify: <P extends FieldPath<T>>(path: P) => void;
+};
+/** Common methods available on any deep proxy node */
+type ValueState<T> = {
+    /** Read without subscribing. */
+    readonly value: T;
+    /** The field name for the proxy. */
+    readonly field: string;
+    /** The path for the proxy. */
+    readonly path: string;
+    /** Subscribe and read the value at path. Re-renders when the value changes. */
+    use(): T;
+    /** Subscribe and read the debounced value at path. Re-renders when the value changes. */
+    useDebounce(delay: number): T;
+    /** Convenience hook returning [value, setValue] for the path. */
+    useState(): StoreUseState<T>;
+    /** Set value at path (creates intermediate nodes as needed). */
+    set(value: T | ((prev: T) => T), skipUpdate?: boolean): void;
+    /** Delete value at path (for arrays, removes index; for objects, deletes key). */
+    reset(): void;
+    /** Subscribe to changes at path and invoke listener with the new value.
+     *
+     * @returns A function to unsubscribe.
+     * @example
+     *
+     * useEffect(() => {
+     *   const unsubscribe = store.a.b.c.subscribe(value => {
+     *     console.log(value)
+     *   })
+     *   return unsubscribe
+     * }, [])
+     */
+    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;
+    /** Ensure the value is an array. */
+    ensureArray(): NonNullable<T> extends (infer U)[] ? ArrayState<U> : never;
+    /** Ensure the value is an object. */
+    ensureObject(): NonNullable<T> extends FieldValues ? ObjectState<NonNullable<T>> : never;
+    /** Return a new state with a default value, and make the type non-nullable */
+    withDefault(defaultValue: T): State<NonNullable<T>>;
+    /** Virtual state derived from the current value.
+     *
+     * @returns ArrayState if the derived value is an array, ObjectState if the derived value is an object, otherwise State.
+     * @example
+     * const state = store.a.b.c.derived({
+     *   from: value => value + 1,
+     *   to: value => value - 1
+     * })
+     * state.use() // returns the derived value
+     * state.set(10) // sets the derived value
+     * state.reset() // resets the derived value
+     */
+    derived: <R>({ from, to }: DerivedStateProps<T, R>) => State<R>;
+    /** Notify listener of current value. */
+    notify(): void;
+};
+/**
+ * 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">>;
+type State<T> = IsEqual<T, unknown> extends true ? never : [NonNullable<T>] extends [readonly (infer U)[]] ? ArrayState<U, T> : [NonNullable<T>] extends [FieldValues] ? ObjectState<NonNullable<T>, T> : ValueState<T>;
+type ArrayState<TValue, TArray = TValue[]> = IsEqual<TValue, unknown> extends true ? never : ValueState<TArray> & ArrayProxy<TValue>;
+type ObjectState<TNonNullable extends FieldValues, TObject = TNonNullable> = ObjectProxy<TNonNullable> & ValueState<TObject> & ObjectMutationMethods;
+/** Type for useCompute function. */
+type StoreUseComputeFn<T extends FieldValues, P extends FieldPath<T>, R> = (value: FieldPathValue<T, P>) => R;
+type DerivedStateProps<T, R> = {
+    from?: (value: T) => R;
+    to?: (value: R) => T;
+};

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/utils.d.ts

@@ -0,0 +1,72 @@
+import type { Atom } from "./atom";
+import type { StoreSetStateValue, ValueState } from "./types";
+export { Conditional, ConditionalRender, Render, RenderWithUpdate };
+type AtomLike<T> = Pick<Atom<T> | ValueState<T>, "use" | "set" | "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;
+};
+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.
+ *
+ * @template T The type of the state value.
+ * @param props - The props object.
+ * @param props.state - The ValueState whose value will be passed to children.
+ * @param props.children - A render prop that receives the current value.
+ * @returns The result of calling children with the current value.
+ */
+declare function Render<State extends ReadOnlyAtomLike<unknown>>({ state, children, }: RenderProps<State>): import("react").ReactNode;
+/**
+ * Renders the provided children function with the current value and an update function.
+ *
+ * The update function can set the value directly or with an updater function.
+ *
+ * @template T The type of the state value.
+ * @template U The type allowed for updating the state (value or updater).
+ * @param props - The props object.
+ * @param props.state - The ValueState whose value will be passed to children.
+ * @param props.children - A render prop that receives the current value and update function.
+ * @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 - The render function that receives the value.
+ * @returns The result of children if the predicate returns true, otherwise null.
+ */
+declare function ConditionalRender<State extends ReadOnlyAtomLike<unknown>>({ state, on, children, }: ConditionalRenderProps<State>): import("react").ReactNode;

package/dist/src/utils.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Activity, useCallback } from "react";
+export { Conditional, ConditionalRender, Render, RenderWithUpdate };
+/**
+ * Renders the provided children function with the current value from the state.
+ *
+ * @template T The type of the state value.
+ * @param props - The props object.
+ * @param props.state - The ValueState whose value will be passed to children.
+ * @param props.children - A render prop that receives the current value.
+ * @returns The result of calling children with the current value.
+ */
+function Render({ state, children, }) {
+    const value = state.use();
+    return children(value);
+}
+/**
+ * Renders the provided children function with the current value and an update function.
+ *
+ * The update function can set the value directly or with an updater function.
+ *
+ * @template T The type of the state value.
+ * @template U The type allowed for updating the state (value or updater).
+ * @param props - The props object.
+ * @param props.state - The ValueState whose value will be passed to children.
+ * @param props.children - A render prop that receives the current value and update function.
+ * @returns The result of calling children with the current value and update function.
+ */
+function RenderWithUpdate({ state, children, }) {
+    const value = state.use();
+    const update = useCallback((value) => {
+        if (typeof value !== "function") {
+            state.set(value);
+        }
+        else {
+            state.set(value(state.value));
+        }
+    }, [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 - The render function that receives the value.
+ * @returns The result of children if the predicate returns true, otherwise null.
+ */
+function ConditionalRender({ state, on, children, }) {
+    const value = state.use();
+    const show = on(value);
+    if (!show) {
+        return null;
+    }
+    return children(value);
+}

package/dist/utils.d.ts

@@ -1,6 +1,6 @@
 import type { Atom } from './atom';
 import type { StoreSetStateValue, ValueState } from './types';
-export { Render, RenderWithUpdate, Conditional, ConditionalRender };
+export { Conditional, ConditionalRender, Render, RenderWithUpdate };
 type AtomLike<T> = Pick<Atom<T> | ValueState<T>, 'use' | 'set' | 'value'>;
 type ReadOnlyAtomLike<T> = Pick<Atom<T> | ValueState<T>, 'use' | 'useCompute' | 'value'>;
 type RenderProps<State extends ReadOnlyAtomLike<unknown>> = {

package/dist/utils.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Activity, useCallback } from 'react';
-export { Render, RenderWithUpdate, Conditional, ConditionalRender };
+export { Conditional, ConditionalRender, Render, RenderWithUpdate };
 /**
  * Renders the provided children function with the current value from the state.
  *

package/package.json

@@ -1,63 +1,63 @@
 {
-	"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"
-	}
+  "name": "juststore",
+  "version": "1.2.0",
+  "description": "A small, expressive, and type-safe state management library for React.",
+  "keywords": [
+    "hooks",
+    "react",
+    "react hooks",
+    "state",
+    "state management",
+    "store",
+    "typescript"
+  ],
+  "homepage": "https://github.com/yusing/juststore",
+  "bugs": {
+    "url": "https://github.com/yusing/juststore/issues"
+  },
+  "license": "AGPL-3.0-only",
+  "author": "Yusing",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yusing/juststore.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun --bun tsc",
+    "format": "oxfmt --write",
+    "format:check": "oxfmt",
+    "lint": "oxlint",
+    "prepare": "husky",
+    "prepublishOnly": "bun run build",
+    "typecheck": "bun --bun tsc --noEmit"
+  },
+  "dependencies": {
+    "change-case": "^5.4.4",
+    "react-fast-compare": "^3.2.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "husky": "^9.1.7",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
+    "react": "^19.2.4",
+    "typescript": "^6.0.2"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  }
 }