@sladg/apex-state 4.0.0 → 4.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @sladg/apex-state
 
-Reactive state management for React built on [Valtio](https://github.com/pmndrs/valtio). Declare what your fields need — validation, conditional UI, sync, listeners — and the store handles the rest. Optional Rust/WASM accelerator for complex workloads (up to 367x faster).
+Reactive state management for React built on [Valtio](https://github.com/pmndrs/valtio). Declare what your fields need — validation, conditional UI, sync, listeners — and the store handles the rest. Rust/WASM pipeline handles all heavy computation: graph traversal, expression evaluation, listener dispatch.
 
 ## Quick Start
 
@@ -59,13 +59,17 @@ const UserForm = () => {
 | Feature | Description | Details |
 |---|---|---|
 | **Type-safe paths** | `DeepKey<T>` / `DeepValue<T, P>` — compile-time path safety with configurable depth | |
-| **Concerns** | Validation (Zod), BoolLogic conditions, dynamic text | [Concerns Guide](docs/guides/CONCERNS_GUIDE.md) |
+| **Concerns** | Validation (Zod), BoolLogic conditions, ValueLogic conditional values, dynamic text | [Concerns Guide](docs/guides/CONCERNS_GUIDE.md) |
 | **Side effects** | Sync paths, flip paths, aggregations, listeners | [Side Effects Guide](docs/SIDE_EFFECTS_GUIDE.md) |
-| **WASM mode** | Rust-powered pipeline for bulk operations (up to 367x faster) | [Architecture](docs/WASM_ARCHITECTURE.md) |
+| **WASM mode** | Rust-powered pipeline for bulk operations (full catalog refresh in 7.4ms) | [Architecture](docs/WASM_ARCHITECTURE.md) |
 | **Composable hooks** | Buffered, throttled, transformed field wrappers | [Store & Hooks](docs/guides/STORE_HOOKS.md) |
 | **Record/wildcard** | `Record<string, V>` with `_()` hash key paths | [Wildcard Guide](docs/WILD_FUNCTION_GUIDE.md) |
 | **Testing mock** | Drop-in `vi.mock` replacement with call tracking | [Testing Mock](docs/TESTING_MOCK.md) |
 
+**Side effects** enforce data invariants — when X changes, Y must follow (sync, flip, aggregate, listen). **Concerns** annotate fields with UI meaning — given settled state, is this field valid, disabled, visible? They run at different times and write to different proxies; neither drives the other.
+
+Side effects and declarative concerns (`boolLogic`, `valueLogic`, `validationState`) are evaluated **synchronously inside the WASM pipeline** — results are available immediately after the state change. Custom `evaluate()` concerns use valtio's `effect()` and are **not guaranteed synchronous** — valtio may batch or defer their evaluation to the next microtask.
+
 ## Full Example
 
 ```tsx
@@ -125,214 +129,101 @@ const App = () => (
 )
 ```
 
-## Reading and Writing State
-
-```tsx
-const store = createGenericStore<MyState>()
-
-// useStore — simple [value, setter] tuple (like useState)
-const NameInput = () => {
-  const [name, setName] = store.useStore('user.name')
-  return <input value={name} onChange={(e) => setName(e.target.value)} />
-}
-
-// useFieldStore — object API with concerns merged in
-const EmailInput = () => {
-  const { value, setValue, validationState, disabledWhen } =
-    store.useFieldStore('user.email')
-  return (
-    <input
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-      disabled={disabledWhen}
-      className={validationState?.isError ? 'error' : ''}
-    />
-  )
-}
-
-// useJitStore — bulk operations and non-reactive reads
-const ImportButton = () => {
-  const { setChanges, getState } = store.useJitStore()
-
-  const handleImport = (data: Record<string, unknown>) => {
-    setChanges([
-      ['user.name', data.name, {}],
-      ['user.email', data.email, {}],
-      ['user.age', data.age, {}],
-    ])
-  }
-
-  return <button onClick={() => handleImport({ name: 'Alice', email: 'a@b.com', age: 30 })}>Import</button>
-}
-```
-
-## Validation with Zod
-
-```tsx
-import { createGenericStore } from '@sladg/apex-state'
-import { z } from 'zod'
-
-type ProfileState = {
-  user: { name: string; email: string; age: number; bio: string }
-}
-
-const store = createGenericStore<ProfileState>()
-
-const ProfileForm = () => {
-  // Register validation schemas for multiple fields at once
-  store.useConcerns('profile-validation', {
-    'user.name': {
-      validationState: { schema: z.string().min(2, 'Name too short').max(50) },
-    },
-    'user.email': {
-      validationState: { schema: z.string().email('Enter a valid email') },
-    },
-    'user.age': {
-      validationState: { schema: z.number().min(18, 'Must be 18+').max(120) },
-    },
-    'user.bio': {
-      validationState: { schema: z.string().max(500, 'Bio too long') },
-    },
-  })
-
-  const email = store.useFieldStore('user.email')
-  const age = store.useFieldStore('user.age')
-
-  return (
-    <form>
-      <div>
-        <input value={email.value} onChange={(e) => email.setValue(e.target.value)} />
-        {email.validationState?.isError && (
-          <ul>{email.validationState.errors.map((err, i) => <li key={i}>{err.message}</li>)}</ul>
-        )}
-      </div>
-      <div>
-        <input
-          type="number"
-          value={age.value}
-          onChange={(e) => age.setValue(Number(e.target.value))}
-        />
-        {age.validationState?.isError && <span>{age.validationState.errors[0]?.message}</span>}
-      </div>
-    </form>
-  )
-}
-```
+## Concerns
 
-## Conditional UI with BoolLogic
+Concerns describe *what a field means* for the UI given the current state — valid, disabled, visible, what label to show. They run after state settles and write to a separate `_concerns` proxy, never to `state` itself.
 
 ```tsx
-store.useConcerns('conditional-ui', {
-  // Disable when another field has a specific value
+store.useConcerns('checkout', {
+  // Zod validation
   'user.email': {
+    validationState: { schema: z.string().email('Enter a valid email') },
     disabledWhen: { boolLogic: { IS_EQUAL: ['status', 'submitted'] } },
+    dynamicTooltip: { template: 'Sending confirmation to {{user.email}}' },
   },
 
-  // Show only when multiple conditions are true
+  // Card number: validate + show only when paying by card
   'payment.cardNumber': {
-    visibleWhen: {
-      boolLogic: {
-        AND: [
-          { IS_EQUAL: ['payment.method', 'card'] },
-          { EXISTS: 'user.email' },
-        ],
-      },
-    },
+    validationState: { schema: z.string().regex(/^\d{16}$/, 'Must be 16 digits') },
+    visibleWhen: { boolLogic: { IS_EQUAL: ['payment.method', 'card'] } },
   },
 
-  // Make readonly when value exceeds threshold
+  // Lock order total above threshold
   'order.total': {
     readonlyWhen: { boolLogic: { GT: ['order.total', 10000] } },
   },
 
-  // Complex nested logic with OR, NOT
-  'shipping.express': {
-    disabledWhen: {
-      boolLogic: {
-        OR: [
-          { IS_EQUAL: ['status', 'shipped'] },
-          { NOT: { EXISTS: 'shipping.address' } },
-        ],
+  // ValueLogic: label adapts to stock level
+  'product.quantity': {
+    dynamicLabel: {
+      valueLogic: {
+        IF: { LTE: ['product.quantity', 5] },
+        THEN: 'Quantity (low stock)',
+        ELSE: 'Quantity',
       },
     },
   },
 })
 
+// Read all concerns for a field via useFieldStore
+const { value, setValue, validationState, disabledWhen, dynamicTooltip } =
+  store.useFieldStore('user.email')
+
 // Available BoolLogic operators:
 // IS_EQUAL, EXISTS, IS_EMPTY, GT, LT, GTE, LTE, IN, AND, OR, NOT
 ```
 
 ## Side Effects
 
-### Sync Paths
+Side effects describe *what must change* when state changes — enforcing invariants, keeping related fields in sync, reacting to mutations. They run inside the pipeline and can write back to `state`.
 
 ```tsx
-store.useSideEffects('sync', {
+store.useSideEffects('checkout', {
+  // Sync billing ↔ shipping contact details bidirectionally
   syncPaths: [
-    ['billing.email', 'shipping.email'],   // changing one updates the other
+    ['billing.email', 'shipping.email'],
     ['billing.phone', 'shipping.phone'],
   ],
-})
-// When user types in billing.email, shipping.email updates automatically
-```
-
-### Flip Paths
 
-```tsx
-store.useSideEffects('flips', {
+  // Express and standard shipping are mutually exclusive
   flipPaths: [
-    ['isActive', 'isInactive'],       // setting isActive=true -> isInactive=false
-    ['isExpanded', 'isCollapsed'],
+    ['shipping.express', 'shipping.standard'],
   ],
-})
-```
 
-### Aggregations
-
-```tsx
-store.useSideEffects('agg', {
+  // Order total = consensus across items (undefined if they differ)
   aggregations: [
-    // Target is ALWAYS first. Multiple pairs with same target form a group.
-    ['summary.price', 'legs.0.price'],
-    ['summary.price', 'legs.1.price'],
-    ['summary.price', 'legs.2.price'],
+    ['order.total', 'items.0.price'],
+    ['order.total', 'items.1.price'],
+    ['order.total', 'items.2.price'],
   ],
-})
-// summary.price = leg price if ALL legs match, undefined if they differ
-```
-
-### Listeners
 
-```tsx
-store.useSideEffects('listeners', {
+  // Stamp audit trail on any profile change
   listeners: [
     {
-      path: 'user.profile',       // watch changes under this path
-      scope: 'user.profile',      // receive scoped state and relative paths
-      fn: (changes, state) => {
-        // changes: [['name', 'Alice', {}]] — paths relative to scope
-        // state: { name: 'Alice', email: '...' } — user.profile sub-object
-        return [['audit.lastEdit', Date.now(), {}]] // return FULL paths for new changes
-      },
+      path: 'user',
+      scope: 'user',
+      fn: (_changes, _state) => [['audit.lastModified', Date.now(), {}]],
     },
   ],
 })
 ```
 
-## Dynamic Text
+## Reading and Writing State
 
 ```tsx
-store.useConcerns('dynamic-text', {
-  'legs.0.strike': {
-    dynamicTooltip: { template: 'Current strike: {{legs.0.strike}}' },
-    dynamicLabel: { template: 'Strike for {{legs.0.product}}' },
-    dynamicPlaceholder: { template: 'Enter value (min {{legs.0.minStrike}})' },
-  },
-})
-
-const { dynamicTooltip, dynamicLabel } = store.useFieldStore('legs.0.strike')
-// dynamicTooltip -> "Current strike: 105"
-// dynamicLabel -> "Strike for AAPL"
+// useStore — simple [value, setter] tuple (like useState)
+const [name, setName] = store.useStore('user.name')
+
+// useFieldStore — object API with all concerns merged in
+const { value, setValue, validationState, disabledWhen } =
+  store.useFieldStore('user.email')
+
+// useJitStore — bulk updates and non-reactive reads
+const { setChanges } = store.useJitStore()
+setChanges([
+  ['user.name', 'Alice', {}],
+  ['user.email', 'alice@example.com', {}],
+])
 ```
 
 ## Composable Field Hooks
@@ -341,44 +232,24 @@ const { dynamicTooltip, dynamicLabel } = store.useFieldStore('legs.0.strike')
 import { useBufferedField, useThrottledField, useTransformedField } from '@sladg/apex-state'
 
 // Buffer edits locally, commit/cancel explicitly
-const PriceEditor = () => {
-  const raw = store.useFieldStore('product.price')
-  const buffered = useBufferedField(raw)
-
-  return (
-    <div>
-      <input value={buffered.value} onChange={(e) => buffered.setValue(Number(e.target.value))} />
-      <button onClick={buffered.commit} disabled={!buffered.isDirty}>Save</button>
-      <button onClick={buffered.cancel}>Cancel</button>
-    </div>
-  )
-}
+const raw = store.useFieldStore('product.price')
+const buffered = useBufferedField(raw)
+// buffered.value, buffered.setValue, buffered.commit(), buffered.cancel(), buffered.isDirty
 
-// Throttle rapid setValue calls (e.g., slider input)
-const VolumeSlider = () => {
-  const raw = store.useFieldStore('audio.volume')
-  const throttled = useThrottledField(raw, { ms: 100 })
-  return <input type="range" value={throttled.value} onChange={(e) => throttled.setValue(Number(e.target.value))} />
-}
+// Throttle rapid updates (e.g. range sliders)
+const throttled = useThrottledField(raw, { ms: 100 })
 
-// Transform display format (cents <-> dollars)
-const CurrencyInput = () => {
-  const raw = store.useFieldStore('price')
-  const formatted = useTransformedField(raw, {
-    to: (cents: number) => (cents / 100).toFixed(2),    // store -> display
-    from: (dollars: string) => Math.round(parseFloat(dollars) * 100), // display -> store
-  })
-  return <input value={formatted.value} onChange={(e) => formatted.setValue(e.target.value)} />
-}
+// Transform display format (cents ↔ dollars)
+const formatted = useTransformedField(raw, {
+  to: (cents: number) => (cents / 100).toFixed(2),
+  from: (dollars: string) => Math.round(parseFloat(dollars) * 100),
+})
 
-// Chain them: buffered + transformed
-const raw = store.useFieldStore('price')
-const buffered = useBufferedField(raw)
-const display = useTransformedField(buffered, {
+// Chain: buffered + transformed
+const display = useTransformedField(useBufferedField(raw), {
   to: (cents) => (cents / 100).toFixed(2),
   from: (dollars) => Math.round(parseFloat(dollars) * 100),
 })
-// display has: value, setValue, commit, cancel, isDirty
 ```
 
 ## Hash Key Paths for Record Types
@@ -387,19 +258,19 @@ const display = useTransformedField(buffered, {
 import { _ } from '@sladg/apex-state'
 
 // _() marks a segment as a hash key for Record-typed paths
-const strikePath = `portfolio.legs.${_('l1')}.strike`
+const itemPath = `catalog.categories.${_('c1')}.items`
 // -> typed string containing HASH_KEY marker
 
 // Use with concerns — applies to ALL keys in the Record
 store.useConcerns('wildcards', {
-  [strikePath]: {
+  [itemPath]: {
     validationState: { schema: z.number().min(0) },
     disabledWhen: { boolLogic: { IS_EQUAL: ['status', 'locked'] } },
   },
 })
 
 // Multiple hash keys for deeply nested Records
-const nestedPath = `books.${_('b1')}.products.${_('p1')}.legs.${_('l1')}.notional`
+const nestedPath = `catalog.${_('c1')}.products.${_('p1')}.variants.${_('v1')}.price`
 ```
 
 ## Type-Safe Paths with Configurable Depth
@@ -512,14 +383,23 @@ it('tracks concern and side effect registrations', () => {
 
 ## Performance
 
-Benchmarked with 60 variants across 3 Record layers, 75 syncs, 40 flips, 100 BoolLogic conditions, 85 listeners:
+Benchmarks run on Apple M4 Pro against a full e-commerce pipeline: 75 sync pairs, 40 flip pairs, 100 BoolLogic expressions, 85 listeners with real JS handlers.
 
-| Operation | Duration |
-|---|---|
-| Single field edit | 1.4µs |
-| 7 changes + cascading listeners | 0.11ms |
-| 60 bulk price changes | 2.9ms |
-| 135 changes (full catalog refresh) | 2.99ms |
+| Scenario | Changes | Duration |
+|---|---|---|
+| Single field change | 1 | 1.4µs |
+| Order confirmation | 1 | 40µs |
+| Dashboard aggregation (10 orders) | 10 | 295µs |
+| Bulk price update (3 Record levels deep) | 60 | 7.2ms |
+| Full catalog refresh (everything fires) | 135 | 7.4ms |
+
+Typical interactions are sub-millisecond. The stress case — 135 changes triggering cascading sync, flip, BoolLogic, and 85 listener callbacks across 3 Record levels — completes in **7.4ms**.
+
+**Bundle:** ~105 KB JS + ~697 KB WASM, loaded separately and cached by the browser. For eager loading:
+
+```ts
+import '@sladg/apex-state/preload'
+```
 
 See [Benchmark Comparison](docs/BENCHMARK_COMPARISON.md) for the full analysis.
 
@@ -562,21 +442,32 @@ See [Benchmark Comparison](docs/BENCHMARK_COMPARISON.md) for the full analysis.
 setValue("email", "alice@example.com")
   |
   v
-[WASM/Rust] shadow state + sync + flip + BoolLogic evaluation
+[WASM/Rust] single processChanges() call:
+  - shadow state update
+  - aggregation → sync → flip
+  - expression evaluation (BoolLogic + ValueLogic, unified)
+  - listener waves + validator dispatch (via externref — no JS round-trips)
   |
   v
-[JS] execute listeners + Zod validators
+[JS] partition result changes by meta flag (state vs _concerns)
   |
-  v
-[WASM/Rust] diff -> compute final changes
+  ├── applyBatch(stateChanges) → valtio state proxy
+  └── applyConcernChanges(concernChanges) → valtio _concerns proxy
   |
   v
-valtio proxy -> React re-render
+React re-render
 ```
 
-**Dual-layer design:** JS/React owns reactivity and rendering. Rust/WASM owns heavy computation (graphs, diffing, pipeline orchestration). The boundary is thin: paths cross as strings, values as JSON. WASM decides the execution plan, JS executes user functions.
+**Dual-layer design:** JS/React owns reactivity and rendering. Rust/WASM owns the full pipeline — shadow state, sync/flip graphs, expression evaluation, and listener dispatch (via externref callbacks). The JS layer normalizes inputs, calls one WASM function, and applies the result. The boundary is thin: paths as strings, values as JSON.
+
+**Side effects vs. concerns:** These are two distinct systems with different authority and different timing.
+
+- **Side effects** model *causality* — because X changed, Y must change. They enforce invariants in the data model (sync, flip, aggregate, listen). They run *during* the pipeline and can write to `state`.
+- **Concerns** model *interpretation* — given settled state, what does this field mean for the UI? They annotate fields with metadata (valid, disabled, visible, label). They run *after* the pipeline and can only write to `_concerns`.
+
+Both use the same expression language (`BoolLogic`, `ValueLogic`) — that's just a shared way to write declarative conditions. What those conditions *drive* is determined by the registration context, not the expression itself.
 
-See [WASM Architecture](docs/WASM_ARCHITECTURE.md) for the full specification.
+See [Architecture Guide](docs/guides/ARCHITECTURE.md) and [WASM Architecture](docs/WASM_ARCHITECTURE.md) for the full specification.
 
 ## Development
 
@@ -609,7 +500,7 @@ cargo install wasm-pack
 | [Wildcard Paths](docs/WILD_FUNCTION_GUIDE.md) | `_()` hash key utility for Record types |
 | [String Interpolation](docs/INTERPOLATION.md) | Template helpers for dynamic text concerns |
 | [Testing Mock](docs/TESTING_MOCK.md) | Mock module for consumer tests (`vi.mock`) |
-| [Debug Timing](docs/DEBUG_TIMING.md) | Performance debugging utilities |
+| [Debug Logging](docs/DEBUG_LOGGING.md) | Pipeline trace, console output, debug configuration |
 | [Full Index](docs/README.md) | Complete documentation index |
 
 ## Roadmap