juststore 0.3.0 → 0.3.2

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/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.2",
   "description": "A small, expressive, and type-safe state management library for React.",
   "type": "module",
   "main": "dist/index.js",