@sladg/apex-state 3.0.1 → 3.0.3

package/README.md

@@ -0,0 +1,228 @@
+# @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).
+
+```bash
+npm install @sladg/apex-state valtio zod react
+```
+
+## Example
+
+```tsx
+import { createGenericStore } from '@sladg/apex-state'
+import { z } from 'zod'
+
+type OrderState = {
+  product: { name: string; quantity: number; price: number }
+  shipping: { address: string; express: boolean }
+  payment: { method: 'card' | 'cash'; cardNumber: string }
+  status: 'draft' | 'submitted'
+}
+
+const store = createGenericStore<OrderState>()
+
+const OrderForm = () => {
+  // Declare side effects
+  store.useSideEffects('order', {
+    syncPaths: [['product.price', 'shipping.basePrice']],
+    flipPaths: [['shipping.express', 'shipping.standard']],
+  })
+
+  // Declare concerns — just data, no logic to test
+  store.useConcerns('order', {
+    'product.quantity': {
+      validationState: { schema: z.number().min(1).max(100) },
+      disabledWhen: { condition: { IS_EQUAL: ['status', 'submitted'] } },
+    },
+    'payment.cardNumber': {
+      validationState: { schema: z.string().regex(/^\d{16}$/) },
+      visibleWhen: { condition: { IS_EQUAL: ['payment.method', 'card'] } },
+    },
+  })
+
+  const { value, setValue, validationState, disabledWhen } =
+    store.useFieldStore('product.quantity')
+
+  return (
+    <input
+      type="number"
+      value={value}
+      onChange={(e) => setValue(Number(e.target.value))}
+      disabled={disabledWhen}
+      className={validationState?.isError ? 'error' : ''}
+    />
+  )
+}
+
+const App = () => (
+  <store.Provider initialState={{
+    product: { name: 'Widget', quantity: 1, price: 29.99 },
+    shipping: { address: '', express: false },
+    payment: { method: 'card', cardNumber: '' },
+    status: 'draft',
+  }}>
+    <OrderForm />
+  </store.Provider>
+)
+```
+
+## Features
+
+| Feature | Description | Details |
+|---|---|---|
+| **Type-safe paths** | `DeepKey<T>` / `DeepValue<T, P>` — compile-time path safety | |
+| **Concerns** | Validation, BoolLogic conditions, 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 | [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 `[*]` wildcard paths | [Wildcard Guide](docs/WILD_FUNCTION_GUIDE.md) |
+
+## Architecture
+
+```
+setValue("email", "alice@example.com")
+  │
+  ├─[Legacy JS]──▶ sync → flip → listeners → applyBatch
+  │
+  └─[WASM/Rust]──▶ shadow state + sync + flip + BoolLogic (Rust)
+                      │
+                      ▼
+                    execute listeners + Zod validators (JS)
+                      │
+                      ▼
+                    pipelineFinalize → diff → final changes (Rust)
+  │
+  ▼
+valtio proxy → 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.
+
+See [docs/WASM_ARCHITECTURE.md](docs/WASM_ARCHITECTURE.md) for the full specification.
+
+## WASM Mode
+
+WASM is the default. Pass `{ useLegacyImplementation: true }` for pure JS:
+
+```tsx
+const store = createGenericStore<MyState>()                                // WASM (default)
+const store = createGenericStore<MyState>({ useLegacyImplementation: true }) // Legacy JS
+```
+
+### Performance
+
+Benchmarked with 60 variants across 3 Record layers, 75 syncs, 40 flips, 100 BoolLogic conditions, 85 listeners:
+
+| Operation | Legacy | WASM | Winner |
+|---|---|---|---|
+| Single field edit | **0.5us** | 1.4us | Legacy 2.6x |
+| 7 changes + cascading listeners | 41.8ms | **0.11ms** | WASM 367x |
+| 60 bulk price changes | 596ms | **2.9ms** | WASM 207x |
+| 135 changes (full catalog refresh) | 621ms | **2.99ms** | WASM 208x |
+
+Both modes produce **identical state** — verified across all 16 benchmark scenarios. See [docs/BENCHMARK_COMPARISON.md](docs/BENCHMARK_COMPARISON.md) for the full analysis.
+
+### Why WASM is faster
+
+- **Pre-computed topic routing** — listener dispatch is O(1) lookup vs O(changes x listeners) string matching
+- **Shadow state diffing** — fast Rust HashMap vs valtio Proxy trap overhead
+- **Single-pass pipeline** — aggregation + sync + flip + BoolLogic in one Rust call
+- **BoolLogic in pipeline** — evaluated in Rust before listeners fire; Legacy defers to async `effect()`
+
+### Why Legacy is faster for small ops
+
+Every WASM call pays a fixed cost: JSON serialization, wasm-bindgen marshalling, and two round trips (`processChanges` + `pipelineFinalize`). When the actual work is trivial, this ~1us overhead dominates.
+
+## API Quick Reference
+
+### Store
+
+```tsx
+const {
+  Provider,        // React context — accepts initialState
+  useFieldStore,   // { value, setValue, ...concerns } for a path
+  useStore,        // [value, setValue] tuple for a path
+  useJitStore,     // { proxyValue, setChanges, getState } for bulk ops
+  useSideEffects,  // register sync/flip/aggregation/listeners
+  useConcerns,     // register validation/BoolLogic/custom concerns
+  withConcerns,    // typed concern selection
+} = createGenericStore<MyState>(config?)
+```
+
+### Concerns
+
+```tsx
+useConcerns('id', {
+  'user.email': {
+    validationState: { schema: z.string().email() },
+    disabledWhen:    { condition: { IS_EQUAL: ['tosAccepted', false] } },
+    visibleWhen:     { condition: { AND: [{ EXISTS: 'user.name' }, { IS_EQUAL: ['step', 2] }] } },
+  },
+})
+```
+
+Built-in concerns: `validationState`, `disabledWhen`, `readonlyWhen`, `visibleWhen`, `dynamicLabel`, `dynamicTooltip`, `dynamicPlaceholder`.
+
+BoolLogic operators: `IS_EQUAL`, `EXISTS`, `IS_EMPTY`, `GT`, `LT`, `GTE`, `LTE`, `IN`, `AND`, `OR`, `NOT`.
+
+See [Concerns Guide](docs/guides/CONCERNS_GUIDE.md) for lifecycle, custom concerns, and testing.
+
+### Side Effects
+
+```tsx
+useSideEffects('id', {
+  syncPaths:    [['source', 'target']],
+  flipPaths:    [['active', 'inactive']],
+  // Aggregation: target reflects the common value when all sources agree, null otherwise.
+  // Multiple pairs with the same target form a group.
+  // Currently supports consensus (all-equal) mode only — SUM, AVG, COUNT planned (see Roadmap).
+  aggregations: [['summary.price', 'legs.0.price'], ['summary.price', 'legs.1.price']],
+  listeners:    [{ path: 'orders', scope: 'orders', fn: handler }],
+})
+```
+
+See [Side Effects Guide](docs/SIDE_EFFECTS_GUIDE.md) for the full API.
+
+## Development
+
+```bash
+npm install            # Install dependencies
+npm run wasm:build     # Compile Rust -> WASM
+npm run build          # Bundle TypeScript + WASM
+npm run test           # Run tests
+npm run code:check     # Lint + type check
+npm run wasm:check     # Rust lint + check
+```
+
+### WASM Prerequisites
+
+```bash
+# Rust toolchain
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+rustup target add wasm32-unknown-unknown
+cargo install wasm-pack
+```
+
+## Documentation
+
+| Document | Covers |
+|---|---|
+| [WASM Architecture](docs/WASM_ARCHITECTURE.md) | JS/WASM boundary, data flow, ownership model |
+| [Benchmark Comparison](docs/BENCHMARK_COMPARISON.md) | Legacy vs WASM performance with 16 scenarios |
+| [Concerns Guide](docs/guides/CONCERNS_GUIDE.md) | Concern lifecycle, built-ins, custom concerns |
+| [Side Effects Guide](docs/SIDE_EFFECTS_GUIDE.md) | Sync, flip, aggregation, listener API |
+| [Store & Hooks](docs/guides/STORE_HOOKS.md) | Hook reference and patterns |
+| [Debug Timing](docs/DEBUG_TIMING.md) | Performance debugging utilities |
+| [Wildcard Paths](docs/WILD_FUNCTION_GUIDE.md) | `Wild()` template utility for Record types |
+| [Record Migration](docs/RECORD_MIGRATION.md) | Migration patterns for dynamic Record types |
+| [Full Index](docs/README.md) | Complete documentation index |
+
+## Roadmap
+
+- **Aggregation modes** — Aggregations currently use consensus (all-equal) mode. Planned: `SUM`, `AVG`, `COUNT`, `MIN`, `MAX`, and custom reducer functions, declared per-target alongside the source pairs.
+- **Nested sub-stores** — Allow a parent store to contain child stores, enabling component-level state that participates in the parent's pipeline (concerns, listeners, sync).
+- **Technical debt resolution** — See [TECHNICAL_DEBT.md](TECHNICAL_DEBT.md) for tracked items.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -223,6 +223,40 @@ type ArrayOfChanges<DATA, META extends GenericMeta = GenericMeta> = {
  * their return types for proper type-safe concern registration and reading.
  */
 
+/**
+ * Config type for the validationState concern at a specific path.
+ *
+ * Defined here (not in concerns/prebuilts/validation-state.ts) to avoid
+ * circular imports when used in ConcernRegistrationMap.
+ *
+ * Can be a schema for the path's own value type, or a scoped schema
+ * targeting a different path in the same state.
+ */
+type ValidationStateInput<DATA, PATH extends DeepKey<DATA>> = {
+    schema: z.ZodSchema<DeepValue<DATA, PATH>>;
+} | {
+    [SCOPE in DeepKey<DATA>]: {
+        scope: SCOPE;
+        schema: z.ZodSchema<DeepValue<DATA, SCOPE>>;
+    };
+}[DeepKey<DATA>];
+/**
+ * Get the appropriate registration config type for a concern at a given path.
+ *
+ * - validationState: schema must match DeepValue<DATA, PATH> — path-dependent
+ * - BoolLogic-based concerns: boolLogic paths are typed against DATA
+ * - Template-based concerns: fixed { template: string }
+ * - Custom concerns: fall back to Record<string, unknown>
+ */
+type ConcernConfigFor<C, DATA extends object, PATH extends DeepKey<DATA>> = C extends {
+    name: 'validationState';
+} ? ValidationStateInput<DATA, PATH> : C extends {
+    evaluate: (props: infer P) => any;
+} ? P extends {
+    boolLogic: any;
+} ? {
+    boolLogic: BoolLogic<DATA>;
+} : Omit<P, 'state' | 'path' | 'value'> : Record<string, unknown>;
 /**
  * Extract the return type from a concern's evaluate function
  *
@@ -261,8 +295,12 @@ type EvaluatedConcerns<CONCERNS extends readonly any[]> = {
 /**
  * Maps field paths to per-concern config objects.
  *
- * Used as the `registration` parameter for `useConcerns` / `registerConcernEffects`.
- * Each key is a `DeepKey<DATA>` path, and the value maps concern names to their config.
+ * When CONCERNS is provided (e.g., from createGenericStore's CONCERNS generic),
+ * each concern config is type-checked against:
+ * - The concern's own EXTRA_PROPS (e.g., `{ boolLogic: ... }` for disabledWhen)
+ * - The path's value type for validationState (schema must match DeepValue<DATA, PATH>)
+ *
+ * Without CONCERNS (standalone usage), falls back to loose typing for backward compatibility.
  *
  * @example
  * ```typescript
@@ -272,7 +310,13 @@ type EvaluatedConcerns<CONCERNS extends readonly any[]> = {
  * }
  * ```
  */
-type ConcernRegistrationMap<DATA extends object> = Partial<Record<DeepKey<DATA>, Partial<Record<string, unknown>>>>;
+type ConcernRegistrationMap<DATA extends object, CONCERNS extends readonly any[] = readonly any[]> = Partial<{
+    [PATH in DeepKey<DATA>]: Partial<{
+        [C in CONCERNS[number] as C extends {
+            name: string;
+        } ? C['name'] : never]: ConcernConfigFor<C, DATA, PATH>;
+    }>;
+}>;
 
 /**
  * DeepKeyFiltered - Filters paths by their resolved value type
@@ -384,8 +428,8 @@ interface BaseConcernProps<STATE, PATH extends string> {
     path: PATH;
     value: unknown;
 }
-interface ConcernType<EXTRA_PROPS = Record<string, unknown>, RETURN_TYPE = unknown> {
-    name: string;
+interface ConcernType<NAME extends string = string, EXTRA_PROPS = Record<string, unknown>, RETURN_TYPE = unknown> {
+    name: NAME;
     description: string;
     /** Evaluated inside effect() - all state accesses are tracked */
     evaluate: (props: BaseConcernProps<Record<string, unknown>, string> & EXTRA_PROPS) => RETURN_TYPE;
@@ -770,14 +814,6 @@ interface ValidationStateResult {
     isError: boolean;
     errors: ValidationError[];
 }
-type ValidationStateInput<SUB_STATE, PATH extends DeepKey<SUB_STATE>> = {
-    schema: z.ZodSchema<DeepValue<SUB_STATE, PATH>>;
-} | {
-    [SCOPE in DeepKey<SUB_STATE>]: {
-        scope: SCOPE;
-        schema: z.ZodSchema<DeepValue<SUB_STATE, SCOPE>>;
-    };
-}[DeepKey<SUB_STATE>];
 interface ValidationStateConcern {
     name: 'validationState';
     description: string;
@@ -796,21 +832,21 @@ declare const findConcern: (name: string, concerns?: readonly any[]) => ConcernT
 /**
  * Default concerns provided by apex-state
  */
-declare const defaultConcerns: readonly [ValidationStateConcern, ConcernType<{
+declare const defaultConcerns: readonly [ValidationStateConcern, ConcernType<"disabledWhen", {
     boolLogic: BoolLogic<any>;
-}, boolean>, ConcernType<{
+}, boolean>, ConcernType<"readonlyWhen", {
     boolLogic: BoolLogic<any>;
-}, boolean>, ConcernType<{
+}, boolean>, ConcernType<"visibleWhen", {
     boolLogic: BoolLogic<any>;
-}, boolean>, ConcernType<{
+}, boolean>, ConcernType<"dynamicTooltip", {
     template: string;
-}, string>, ConcernType<{
+}, string>, ConcernType<"dynamicLabel", {
     template: string;
-}, string>, ConcernType<{
+}, string>, ConcernType<"dynamicPlaceholder", {
     template: string;
 }, string>];
 
-declare const disabledWhen: ConcernType<{
+declare const disabledWhen: ConcernType<'disabledWhen', {
     boolLogic: BoolLogic<any>;
 }, boolean>;
 
@@ -833,7 +869,7 @@ declare const disabledWhen: ConcernType<{
  * ```
  */
 
-declare const readonlyWhen: ConcernType<{
+declare const readonlyWhen: ConcernType<'readonlyWhen', {
     boolLogic: BoolLogic<any>;
 }, boolean>;
 
@@ -856,7 +892,7 @@ declare const readonlyWhen: ConcernType<{
  * ```
  */
 
-declare const visibleWhen: ConcernType<{
+declare const visibleWhen: ConcernType<'visibleWhen', {
     boolLogic: BoolLogic<any>;
 }, boolean>;
 
@@ -879,7 +915,7 @@ declare const visibleWhen: ConcernType<{
  * ```
  */
 
-declare const dynamicLabel: ConcernType<{
+declare const dynamicLabel: ConcernType<'dynamicLabel', {
     template: string;
 }, string>;
 
@@ -902,7 +938,7 @@ declare const dynamicLabel: ConcernType<{
  * ```
  */
 
-declare const dynamicPlaceholder: ConcernType<{
+declare const dynamicPlaceholder: ConcernType<'dynamicPlaceholder', {
     template: string;
 }, string>;
 
@@ -925,24 +961,24 @@ declare const dynamicPlaceholder: ConcernType<{
  * ```
  */
 
-declare const dynamicTooltip: ConcernType<{
+declare const dynamicTooltip: ConcernType<'dynamicTooltip', {
     template: string;
 }, string>;
 
 /**
  * All pre-built concerns as a tuple (for use with findConcern)
  */
-declare const prebuilts: readonly [ValidationStateConcern, ConcernType<{
+declare const prebuilts: readonly [ValidationStateConcern, ConcernType<"disabledWhen", {
     boolLogic: BoolLogic<any>;
-}, boolean>, ConcernType<{
+}, boolean>, ConcernType<"readonlyWhen", {
     boolLogic: BoolLogic<any>;
-}, boolean>, ConcernType<{
+}, boolean>, ConcernType<"visibleWhen", {
     boolLogic: BoolLogic<any>;
-}, boolean>, ConcernType<{
+}, boolean>, ConcernType<"dynamicTooltip", {
     template: string;
-}, string>, ConcernType<{
+}, string>, ConcernType<"dynamicLabel", {
     template: string;
-}, string>, ConcernType<{
+}, string>, ConcernType<"dynamicPlaceholder", {
     template: string;
 }, string>];
 /**
@@ -950,22 +986,22 @@ declare const prebuilts: readonly [ValidationStateConcern, ConcernType<{
  */
 declare const prebuiltsNamespace: {
     validationState: ValidationStateConcern;
-    disabledWhen: ConcernType<{
+    disabledWhen: ConcernType<"disabledWhen", {
         boolLogic: BoolLogic<any>;
     }, boolean>;
-    readonlyWhen: ConcernType<{
+    readonlyWhen: ConcernType<"readonlyWhen", {
         boolLogic: BoolLogic<any>;
     }, boolean>;
-    visibleWhen: ConcernType<{
+    visibleWhen: ConcernType<"visibleWhen", {
         boolLogic: BoolLogic<any>;
     }, boolean>;
-    dynamicTooltip: ConcernType<{
+    dynamicTooltip: ConcernType<"dynamicTooltip", {
         template: string;
     }, string>;
-    dynamicLabel: ConcernType<{
+    dynamicLabel: ConcernType<"dynamicLabel", {
         template: string;
     }, string>;
-    dynamicPlaceholder: ConcernType<{
+    dynamicPlaceholder: ConcernType<"dynamicPlaceholder", {
         template: string;
     }, string>;
 };
@@ -1085,7 +1121,7 @@ interface SideEffects<DATA extends object, META extends GenericMeta = GenericMet
     listeners?: ListenerRegistration<DATA, META>[];
 }
 
-declare const createGenericStore: <DATA extends object, META extends GenericMeta = GenericMeta, CONCERNS extends readonly any[] = typeof defaultConcerns>(config?: StoreConfig) => {
+declare const createGenericStore: <DATA extends object, META extends GenericMeta = GenericMeta, CONCERNS extends readonly ConcernType<string, any, any>[] = typeof defaultConcerns>(config?: StoreConfig) => {
     Provider: {
         ({ initialState: rawInitialState, children, }: ProviderProps<DATA>): react_jsx_runtime.JSX.Element | null;
         displayName: string;
@@ -1101,12 +1137,14 @@ declare const createGenericStore: <DATA extends object, META extends GenericMeta
         getState: () => DATA;
     };
     useSideEffects: (id: string, effects: SideEffects<DATA, META>) => void;
-    useConcerns: (id: string, registration: ConcernRegistrationMap<DATA>, customConcerns?: readonly ConcernType<any, any>[]) => void;
-    withConcerns: <SELECTION extends Partial<Record<string, boolean>>>(selection: SELECTION) => {
+    useConcerns: <CUSTOM extends readonly ConcernType<string, any, any>[] = readonly []>(id: string, registration: ConcernRegistrationMap<DATA, readonly [...CONCERNS, ...CUSTOM]>, customConcerns?: CUSTOM) => void;
+    withConcerns: <SELECTION extends Partial<Record<Extract<CONCERNS[number], {
+        name: string;
+    }>["name"], boolean>>>(selection: SELECTION) => {
         useFieldStore: <P extends DeepKey<DATA>>(path: P) => {
             value: DATA extends readonly any[] ? DATA[number] : P extends `${infer First}.${infer Rest}` ? First extends keyof DATA ? DeepValue<DATA[First], Rest> : string extends keyof DATA ? First extends "[*]" ? DeepValue<DATA[keyof DATA & string], Rest> : unknown : unknown : P extends "[*]" ? string extends keyof DATA ? DATA[keyof DATA & string] : unknown : P extends keyof DATA ? DATA[P] : unknown;
             setValue: (newValue: DATA extends readonly any[] ? DATA[number] : P extends `${infer First}.${infer Rest}` ? First extends keyof DATA ? DeepValue<DATA[First], Rest> : string extends keyof DATA ? First extends "[*]" ? DeepValue<DATA[keyof DATA & string], Rest> : unknown : unknown : P extends "[*]" ? string extends keyof DATA ? DATA[keyof DATA & string] : unknown : P extends keyof DATA ? DATA[P] : unknown, meta?: META) => void;
-        } & { [K in keyof SELECTION as SELECTION[K] extends true ? K : never]?: K extends CONCERNS[number]["name"] ? EvaluatedConcerns<CONCERNS>[K] : never; };
+        } & { [K in keyof SELECTION as SELECTION[K] extends true ? K : never]?: K extends keyof EvaluatedConcerns<CONCERNS> ? EvaluatedConcerns<CONCERNS>[K] : never; };
     };
 };