juststore 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,358 @@
+# juststore
+
+A small, expressive, and type-safe state management library for React.
+
+## Features
+
+- **Dot-path addressing** - Access nested values using paths like `store.user.profile.name`
+- **Type-safe paths** - Full TypeScript inference for nested property access
+- **Fine-grained subscriptions** - Components only re-render when their specific data changes
+- **localStorage persistence** - Automatic persistence with cross-tab synchronization via BroadcastChannel
+- **Memory-only stores** - Component-scoped state that doesn't persist
+- **Form handling** - Built-in validation and error management
+- **Array operations** - Native array methods (push, pop, splice, etc.) on array paths
+- **Derived state** - Transform values bidirectionally without extra storage
+- **SSR compatible** - Safe to use in server-side rendering environments
+
+## Installation
+
+```bash
+npm install juststore
+# or
+bun add juststore
+```
+
+## Quick Start
+
+```tsx
+import { createStore } from 'juststore'
+
+type AppState = {
+  user: {
+    name: string
+    preferences: {
+      theme: 'light' | 'dark'
+    }
+  }
+  todos: { id: number; text: string; done: boolean }[]
+}
+
+const store = createStore<AppState>('app', {
+  user: {
+    name: 'Guest',
+    preferences: { theme: 'light' }
+  },
+  todos: []
+})
+```
+
+## Usage
+
+### Reading State
+
+```tsx
+function UserName() {
+  // Subscribe to a specific path - re-renders only when this value changes
+  const name = store.user.name.use()
+  return <span>{name}</span>
+}
+
+function Theme() {
+  // Deep path access
+  const theme = store.user.preferences.theme.use()
+  return <span>Current theme: {theme}</span>
+}
+```
+
+### Writing State
+
+```tsx
+function Settings() {
+  return <button onClick={() => store.user.preferences.theme.set('dark')}>Dark Mode</button>
+}
+
+// Functional updates
+store.user.name.set(prev => prev.toUpperCase())
+
+// Read without subscribing
+const currentName = store.user.name.value
+```
+
+### useState-style Hook
+
+```tsx
+function EditableName() {
+  const [name, setName] = store.user.name.useState()
+  return <input value={name ?? ''} onChange={e => setName(e.target.value)} />
+}
+```
+
+### Debounced Values
+
+```tsx
+function SearchResults() {
+  // Value updates are debounced by 300ms
+  const query = store.search.query.useDebounce(300)
+  // fetch results based on debounced query...
+}
+```
+
+### Array Operations
+
+```tsx
+function TodoList() {
+  const todos = store.todos.use()
+
+  const addTodo = () => {
+    store.todos.push({ id: Date.now(), text: 'New todo', done: false })
+  }
+
+  const removeFirst = () => {
+    store.todos.shift()
+  }
+
+  const toggleTodo = (index: number) => {
+    store.todos.at(index).done.set(prev => !prev)
+  }
+
+  return (
+    <ul>
+      {todos?.map((todo, i) => (
+        <li key={todo.id} onClick={() => toggleTodo(i)}>
+          {todo.text}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+Available array methods: `push`, `pop`, `shift`, `unshift`, `splice`, `reverse`, `sort`, `fill`, `copyWithin`, `sortedInsert`.
+
+### Render Props
+
+```tsx
+function Counter() {
+  return (
+    <store.counter.Render>
+      {(value, update) => (
+        <button onClick={() => update((value ?? 0) + 1)}>Count: {value ?? 0}</button>
+      )}
+    </store.counter.Render>
+  )
+}
+```
+
+### Conditional Rendering
+
+```tsx
+function AdminPanel() {
+  return (
+    <store.user.role.Show on={role => role === 'admin'}>
+      <AdminDashboard />
+    </store.user.role.Show>
+  )
+}
+```
+
+### Derived State
+
+Transform values without storing the transformed version:
+
+```tsx
+function TemperatureInput() {
+  // Store holds Celsius, but we want to display/edit Fahrenheit
+  const fahrenheit = store.temperature.derived({
+    from: celsius => ((celsius ?? 0) * 9) / 5 + 32,
+    to: fahrenheit => ((fahrenheit - 32) * 5) / 9
+  })
+
+  const [temp, setTemp] = fahrenheit.useState()
+  return <input type="number" value={temp} onChange={e => setTemp(Number(e.target.value))} />
+}
+```
+
+### Computed Values
+
+```tsx
+function TotalPrice() {
+  const total = store.cart.items.compute(
+    items => items?.reduce((sum, item) => sum + item.price * item.qty, 0) ?? 0
+  )
+  return <span>Total: ${total}</span>
+}
+```
+
+### Memory-Only Stores
+
+For complex component-local state with nested structures. Useful when you need to pass state to child components without prop drilling:
+
+```tsx
+import { useMemoryStore, type MemoryStore } from 'juststore'
+
+type SearchState = {
+  query: string
+  filters: { category: string; minPrice: number }
+  results: { id: number; name: string }[]
+}
+
+function ProductSearch() {
+  const state = useMemoryStore<SearchState>({
+    query: '',
+    filters: { category: 'all', minPrice: 0 },
+    results: []
+  })
+
+  return (
+    <>
+      <SearchInput state={state} />
+      <FilterPanel state={state} />
+      <ResultsList state={state} />
+    </>
+  )
+}
+
+function SearchInput({ state }: { state: MemoryStore<SearchState> }) {
+  const query = state.query.use()
+  return <input value={query} onChange={e => state.query.set(e.target.value)} />
+}
+
+function FilterPanel({ state }: { state: MemoryStore<SearchState> }) {
+  const category = state.filters.category.use()
+  return (
+    <select value={category} onChange={e => state.filters.category.set(e.target.value)}>
+      <option value="all">All</option>
+      <option value="electronics">Electronics</option>
+    </select>
+  )
+}
+
+function ResultsList({ state }: { state: MemoryStore<SearchState> }) {
+  const results = state.results.use()
+  return (
+    <ul>
+      {results?.map(r => (
+        <li key={r.id}>{r.name}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### Form Handling
+
+```tsx
+import { useForm } from 'juststore'
+
+type LoginForm = {
+  email: string
+  password: string
+}
+
+function LoginPage() {
+  const form = useForm<LoginForm>(
+    { email: '', password: '' },
+    {
+      email: { validate: 'not-empty' },
+      password: {
+        validate: value => (value && value.length < 8 ? 'Password too short' : undefined)
+      }
+    }
+  )
+
+  return (
+    <form onSubmit={form.handleSubmit(values => console.log(values))}>
+      <input value={form.email.use() ?? ''} onChange={e => form.email.set(e.target.value)} />
+      {form.email.useError() && <span>{form.email.error}</span>}
+
+      <input
+        type="password"
+        value={form.password.use() ?? ''}
+        onChange={e => form.password.set(e.target.value)}
+      />
+      {form.password.useError() && <span>{form.password.error}</span>}
+
+      <button type="submit">Login</button>
+    </form>
+  )
+}
+```
+
+Validation options:
+
+- `'not-empty'` - Field must have a value
+- `RegExp` - Value must match the pattern
+- `(value, form) => string | undefined` - Custom validation function
+
+### Mixed State
+
+Combine multiple state values into a single subscription:
+
+```tsx
+import { createMixedState } from 'juststore'
+
+function LoadingOverlay() {
+  const loading = createMixedState(store.saving, store.fetching, store.uploading)
+
+  return (
+    <loading.Show on={([saving, fetching, uploading]) => saving || fetching || uploading}>
+      <Spinner />
+    </loading.Show>
+  )
+}
+```
+
+### Path-based API
+
+The store also exposes a path-based API for dynamic access:
+
+```tsx
+// Equivalent to store.user.name.use()
+const name = store.use('user.name')
+
+// Equivalent to store.user.name.set('Alice')
+store.set('user.name', 'Alice')
+
+// Equivalent to store.user.name.value
+const current = store.value('user.name')
+```
+
+## API Reference
+
+### createStore(namespace, defaultValue, options?)
+
+Creates a persistent store with localStorage backing and cross-tab sync.
+
+- `namespace` - Unique identifier for the store
+- `defaultValue` - Initial state shape
+- `options.memoryOnly` - Disable persistence (default: false)
+
+### useMemoryStore(defaultValue)
+
+Creates a component-scoped store that doesn't persist.
+
+### useForm(defaultValue, fieldConfigs?)
+
+Creates a form store with validation support.
+
+### 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)                      |
+| `.notify()`              | Manually trigger subscribers                            |
+| `.compute(fn)`           | Derive a computed value                                 |
+| `.derived({ from, to })` | Create bidirectional transform                          |
+| `.Render`                | Render prop component                                   |
+| `.Show`                  | Conditional render component                            |
+
+## License
+
+AGPL-3.0

package/dist/form.d.ts

@@ -1,12 +1,15 @@
 import type { FieldPath, FieldPathValue, FieldValues } from './path';
 import type { ArrayProxy, State } from './types';
 export { useForm, type CreateFormOptions, type DeepNonNullable, type FormArrayProxy, type FormDeepProxy, type FormState, type FormStore };
+/**
+ * Common form field methods available on every form state node.
+ */
 type FormCommon = {
-    /** Subscribe and read the error at path. Re-renders when the error changes. */
+    /** Subscribe and read the validation error. Re-renders when the error changes. */
     useError: () => string | undefined;
-    /** Read the error at path without subscribing. */
+    /** Read the validation error without subscribing. */
     readonly error: string | undefined;
-    /** Set the error at path. */
+    /** Manually set a validation error. */
     setError: (error: string | undefined) => void;
 };
 type FormArrayProxy<T> = ArrayProxy<T> & FormCommon;
@@ -19,8 +22,13 @@ type FormDeepProxy<T> = NonNullable<T> extends readonly (infer U)[] ? FormArrayP
 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.
+ */
 type FormStore<T extends FieldValues> = FormDeepProxy<T> & {
+    /** Clears all validation errors from the form. */
     clearErrors(): void;
+    /** Returns a form submit handler that validates and calls onSubmit with form values. */
     handleSubmit(onSubmit: (values: T) => void): (e: React.FormEvent) => void;
 };
 type NoEmptyValidator = 'not-empty';
@@ -31,4 +39,28 @@ type FieldConfig<T extends FieldValues> = {
     validate?: Validator<T>;
 };
 type CreateFormOptions<T extends FieldValues> = Partial<Record<FieldPath<T>, FieldConfig<T>>>;
+/**
+ * React hook that creates a form store with validation support.
+ *
+ * The form store extends the memory store with error handling and validation.
+ * Fields can be configured with validators that run on every change.
+ *
+ * @param defaultValue - Initial form values
+ * @param fieldConfigs - Optional validation configuration per field
+ * @returns A form store with validation and submission handling
+ *
+ * @example
+ * const form = useForm(
+ *   { email: '', password: '' },
+ *   {
+ *     email: { validate: 'not-empty' },
+ *     password: { validate: v => v && v.length < 8 ? 'Too short' : undefined }
+ *   }
+ * )
+ *
+ * <form onSubmit={form.handleSubmit(values => console.log(values))}>
+ *   <input value={form.email.use() ?? ''} onChange={e => form.email.set(e.target.value)} />
+ *   {form.email.useError() && <span>{form.email.error}</span>}
+ * </form>
+ */
 declare function useForm<T extends FieldValues>(defaultValue: T, fieldConfigs?: CreateFormOptions<T>): FormStore<T>;

package/dist/form.js

@@ -6,6 +6,30 @@ import { getSnapshot, produce } from './impl';
 import { createNode } from './node';
 import { createStoreRoot } from './root';
 export { useForm };
+/**
+ * React hook that creates a form store with validation support.
+ *
+ * The form store extends the memory store with error handling and validation.
+ * Fields can be configured with validators that run on every change.
+ *
+ * @param defaultValue - Initial form values
+ * @param fieldConfigs - Optional validation configuration per field
+ * @returns A form store with validation and submission handling
+ *
+ * @example
+ * const form = useForm(
+ *   { email: '', password: '' },
+ *   {
+ *     email: { validate: 'not-empty' },
+ *     password: { validate: v => v && v.length < 8 ? 'Too short' : undefined }
+ *   }
+ * )
+ *
+ * <form onSubmit={form.handleSubmit(values => console.log(values))}>
+ *   <input value={form.email.use() ?? ''} onChange={e => form.email.set(e.target.value)} />
+ *   {form.email.useError() && <span>{form.email.error}</span>}
+ * </form>
+ */
 function useForm(defaultValue, fieldConfigs = {}) {
     const formId = useId();
     const namespace = `form:${formId}`;
@@ -53,6 +77,14 @@ function useForm(defaultValue, fieldConfigs = {}) {
     }
     return store;
 }
+/**
+ * Creates a form proxy node that extends the base node with error handling.
+ *
+ * @param storeApi - The form's value store
+ * @param errorStore - The form's error store
+ * @param path - The field path
+ * @returns A proxy with both state methods and error methods
+ */
 const createFormProxy = (storeApi, errorStore, path) => {
     const proxyCache = new Map();
     const useError = () => errorStore.use(path);
@@ -73,6 +105,13 @@ const createFormProxy = (storeApi, errorStore, path) => {
         }
     });
 };
+/**
+ * Converts a validator configuration into a validation function.
+ *
+ * @param field - The field path (used for error messages)
+ * @param validator - The validator config ('not-empty', RegExp, or function)
+ * @returns A validation function, or undefined if no validator provided
+ */
 function getValidator(field, validator) {
     if (!validator) {
         return undefined;
@@ -85,18 +124,37 @@ function getValidator(field, validator) {
     }
     return validator;
 }
+/**
+ * Validates that a field has a non-empty value.
+ *
+ * @param field - The field path (used for error message)
+ * @param value - The value to validate
+ * @returns Error message if empty, undefined if valid
+ */
 function validateNoEmpty(field, value) {
     if (!stringValue(value)) {
         return `${pascalCase(field)} is required`;
     }
     return undefined;
 }
+/**
+ * Validates that a field matches a regular expression.
+ *
+ * @param field - The field path (used for error message)
+ * @param value - The value to validate
+ * @param regex - The pattern to match against
+ * @returns Error message if invalid, undefined if valid
+ */
 function validateRegex(field, value, regex) {
     if (!regex.test(stringValue(value))) {
         return `${pascalCase(field)} is invalid`;
     }
     return undefined;
 }
+/**
+ * Converts a value to a string for validation purposes.
+ * Returns empty string for non-primitive values.
+ */
 function stringValue(v) {
     if (typeof v === 'string') {
         return v;

package/dist/impl.d.ts

@@ -1,19 +1,82 @@
 import type { FieldPath, FieldPathValue, FieldValues } from './path';
 export { getNestedValue, getSnapshot, joinPath, notifyListeners, produce, setLeaf, useDebounce, useObject, useSubscribe };
+/**
+ * Joins a namespace and path into a full key string.
+ *
+ * @param namespace - The store namespace (root key)
+ * @param path - Optional dot-separated path within the namespace
+ * @returns Combined key string (e.g., "app.user.name")
+ */
 declare function joinPath(namespace: string, path?: string): string;
 /** Get a nested value from an object/array using a dot-separated path. */
 declare function getNestedValue(obj: unknown, path: string): unknown;
-/** Notify exact, root, and affected child listeners for a given key change. */
+/**
+ * Notifies all relevant listeners when a value changes.
+ *
+ * Handles three types of listeners:
+ * 1. Exact match - listeners subscribed to the exact changed path
+ * 2. Root listeners - listeners on the namespace root (for full-store subscriptions)
+ * 3. Child listeners - listeners on nested paths that may be affected by the change
+ *
+ * Child listeners are only notified if their specific value actually changed,
+ * determined by deep equality comparison.
+ */
 declare function notifyListeners(key: string, oldValue: unknown, newValue: unknown, skipRoot?: boolean, skipChildren?: boolean): void;
 /** Snapshot getter used by React's useSyncExternalStore. */
 declare function getSnapshot(key: string): unknown;
-/** Core mutation function that updates store and notifies listeners. */
+/**
+ * Core mutation function that updates the store and notifies listeners.
+ *
+ * Handles both setting and deleting values, with optimizations to skip
+ * unnecessary updates when the value hasn't changed.
+ *
+ * @param key - The full key path to update
+ * @param value - The new value, or undefined to delete
+ * @param skipUpdate - When true, skips notifying listeners
+ * @param memoryOnly - When true, skips localStorage persistence
+ */
 declare function produce(key: string, value: unknown, skipUpdate?: boolean, memoryOnly?: boolean): void;
-/** React hook: subscribe to and read a namespaced path value. */
+/**
+ * React hook that subscribes to and reads a value at a path.
+ *
+ * Uses useSyncExternalStore for tear-free reads and automatic re-rendering
+ * when the subscribed value changes.
+ *
+ * @param key - The namespace or full key
+ * @param path - Optional path within the namespace
+ * @returns The current value at the path, or undefined if not set
+ */
 declare function useObject<T extends FieldValues, P extends FieldPath<T>>(key: string, path?: P): FieldPathValue<T, P> | undefined;
-/** React hook: subscribe to and read a namespaced path debounced value. */
+/**
+ * React hook that subscribes to a value with debounced updates.
+ *
+ * The returned value only updates after the specified delay has passed
+ * since the last change, useful for expensive operations like search.
+ *
+ * @param key - The namespace or full key
+ * @param path - Path within the namespace
+ * @param delay - Debounce delay in milliseconds
+ * @returns The debounced value at the path
+ */
 declare function useDebounce<T extends FieldValues, P extends FieldPath<T>>(key: string, path: P, delay: number): FieldPathValue<T, P> | undefined;
-/** Effectful subscription helper that calls onChange with the latest value. */
+/**
+ * React hook for side effects when a value changes.
+ *
+ * Unlike `use()`, this doesn't cause re-renders. Instead, it calls the
+ * provided callback whenever the value changes, useful for syncing with
+ * external systems or triggering effects.
+ *
+ * @param key - The full key path to subscribe to
+ * @param onChange - Callback invoked with the new value on each change
+ */
 declare function useSubscribe<T>(key: string, onChange: (value: T) => void): void;
-/** Set a leaf value under namespace.path, optionally skipping notifications. */
+/**
+ * Sets a value at a specific path within a namespace.
+ *
+ * @param key - The namespace
+ * @param path - Path within the namespace
+ * @param value - The value to set, or undefined to delete
+ * @param skipUpdate - When true, skips notifying listeners
+ * @param memoryOnly - When true, skips localStorage persistence
+ */
 declare function setLeaf<T extends FieldValues, P extends FieldPath<T>>(key: string, path: P, value: FieldPathValue<T, P> | undefined, skipUpdate?: boolean, memoryOnly?: boolean): void;