@signaltree/core 10.3.1 → 10.3.3

package/llms-full.txt

@@ -38,9 +38,9 @@ const store = signalTree({
 
 // With config:
 const store2 = signalTree(initialState, {
-  batchUpdates: true,      // default — microtask-level notification batching
-  equalityFn: Object.is,   // custom signal equality
-  treeName: 'AppStore',    // for devtools labeling
+  batchUpdates: true,         // default — microtask-level notification batching
+  useShallowComparison: true, // switch leaf signal equality from deepEqual to Object.is
+  treeName: 'AppStore',       // for devtools labeling
 });
 ```
 
@@ -59,14 +59,15 @@ Both `store.$` and `store.state` point to the same TreeNode. Use whichever reads
 ```typescript
 store.$.user.name.set('Bob');
 store.$.user.age.update((n) => n + 1);
-store.$.user({ name: 'Carol', age: 25 });   // replace a whole branch
-store({ user: { name: 'Dave', age: 40 }, settings: { theme: 'dark' } }); // replace full state
+store.$.user({ name: 'Carol', age: 25 });   // partial deep-merge update; sibling keys preserved
+store({ user: { name: 'Dave', age: 40 }, settings: { theme: 'dark' } }); // partial deep-merge of root; keys not in payload preserved
+store();                                    // no-arg call returns the current snapshot
 ```
 
 ### Lifecycle
 
 ```typescript
-store.destroy();                       // tears down all enhancer resources in reverse order
+store.destroy();                       // runs registered cleanup hooks in registration order
 store.destroyed();                     // Signal<boolean>
 store.registerCleanup(() => ws.close()); // custom hook called during destroy
 ```
@@ -95,7 +96,7 @@ store.$.users.setAll(users);
 store.$.users.upsertOne(user);
 store.$.users.upsertMany(users);
 store.$.users.updateOne(id, changes);
-store.$.users.updateMany([{ id, changes }, ...]);
+store.$.users.updateMany([id1, id2, id3], { active: false }); // shared Partial<E> applied to every id — NOT NgRx-style [{id, changes}]
 store.$.users.updateWhere(pred, changes);
 store.$.users.removeOne(id);
 store.$.users.removeMany(ids);
@@ -104,7 +105,7 @@ store.$.users.clear();
 
 // Queries (all return signals)
 store.$.users.all();              // Signal<User[]>
-store.$.users.byId(id);           // Signal<User | undefined>
+store.$.users.byId(id);           // EntityNode<User> | undefined — invoke: .byId(id)?.() → User | undefined
 store.$.users.count();            // Signal<number>
 store.$.users.has(id);            // Signal<boolean>
 store.$.users.ids();              // Signal<number[]>
@@ -128,20 +129,28 @@ const store = signalTree({
   },
 });
 
-// Read
-store.$.users.loading.state();      // Signal<LoadingState>
-store.$.users.loading.error();      // Signal<ApiError | null>
-store.$.users.loading.isLoading();  // Signal<boolean>
-store.$.users.loading.isLoaded();
-store.$.users.loading.isError();
-store.$.users.loading.isNotLoaded();
-
-// Mutate
+// Read — v10.3 canonical (bare names)
+store.$.users.loading.state();      // LoadingState (calling Signal<LoadingState>)
+store.$.users.loading.error();      // ApiError | null
+store.$.users.loading.loading();    // boolean
+store.$.users.loading.loaded();     // boolean
+store.$.users.loading.hasError();   // boolean
+store.$.users.loading.notLoaded();  // boolean
+// Deprecated through v10.x, removed v11: .isLoading, .isLoaded, .isError, .isNotLoaded
+// (same Signal instance — both work; canonical preferred in new code)
+
+// Mutate — canonical methods
 store.$.users.loading.setLoading();
 store.$.users.loading.setLoaded();
 store.$.users.loading.setError(err);
 store.$.users.loading.setNotLoaded();
 store.$.users.loading.reset();
+
+// v10.2+ Promise-vocabulary aliases (identical semantics, no args)
+store.$.users.loading.start();      // === setLoading()
+store.$.users.loading.setSuccess(); // === setLoaded() — NO ARGS
+store.$.users.loading.succeed();    // === setLoaded()
+store.$.users.loading.fail(err);    // === setError(err)
 ```
 
 ### `stored(key, defaultValue, options?)`
@@ -166,9 +175,9 @@ store.$.settings.theme.reload();  // re-read from localStorage
 
 Supports versioning and migration functions via the third argument. Use for individual per-leaf persistence; use the `persistence()` enhancer for tree-wide persistence with storage adapters.
 
-### `form<T>(config)` (from `@signaltree/ng-forms` integration)
+### `form<T>(config: FormConfig<T>)`
 
-Tree-integrated form with validation, wizard, and persistence. Materializes into a form signal exposing field state, validation status, and submit/reset helpers. See `@signaltree/ng-forms` documentation for full config schema.
+Tree-integrated form marker, **exported from `@signaltree/core`** (not from `@signaltree/ng-forms`). Materializes into a form signal exposing field state, validation status, and submit/reset helpers. Requires `{ initial: T, validators?, asyncValidators?, wizard? }`. `@signaltree/ng-forms` is a separate **bridge** that binds these markers to Angular `FormGroup` — useful but not required.
 
 ### Custom markers via `registerMarkerProcessor(spec)`
 
@@ -278,7 +287,7 @@ const store = signalTree({ count: 0, items: [] })
 
 store.batch(() => {
   store.$.count.set(10);
-  store.$.items.push({ id: 1 });
+  store.$.items.update((arr) => [...arr, { id: 1 }]); // .push() doesn't exist — arrays live in a WritableSignal
 });
 
 store.undo();
@@ -303,6 +312,8 @@ store.$.count((n) => n + 1);            // → store.$.count.update((n) => n + 1
 
 **This is not a runtime proxy.** The transform runs at build time and disappears in production — there is no wrapper function, no `Proxy` object, no runtime overhead. Install as a dev dependency, register the Vite or Webpack plugin, and the transform compiles away.
 
+> **Configure `rootIdentifiers`**: the plugin's default is `['tree']`. If your tree variable is named `store` or `state` (common in service facades), pass `{ rootIdentifiers: ['tree', 'store', 'state'] }` to the plugin options — variables not in this list are silently skipped.
+
 ---
 
 ## Subpath imports
@@ -310,12 +321,13 @@ store.$.count((n) => n + 1);            // → store.$.count.update((n) => n + 1
 Specialized APIs live in subpaths to keep the main barrel small:
 
 ```typescript
-import { TREE_PRESETS, createDevTree, createProdTree } from '@signaltree/core/presets';
 import { SecurityValidator, SecurityPresets } from '@signaltree/core/security';
-import { createEditSession } from '@signaltree/core/edit-session';
+import { createEditSession, createTreeEditSession } from '@signaltree/core/edit-session';
 import { createStorageAdapter, createIndexedDBAdapter } from '@signaltree/core/storage';
 ```
 
+The only published subpaths in `@signaltree/core` are `./security`, `./edit-session`, and `./storage`. The main barrel (`@signaltree/core`) re-exports everything; modern bundlers tree-shake unused symbols regardless.
+
 ### Async — `asyncSource` and `asyncQuery` markers (canonical, v9.5+)
 
 Async state belongs **at the tree path it describes**. Two markers cover the two main async patterns and compose with the rest of the marker family:
@@ -531,7 +543,7 @@ This is the pattern enforced in production migrations. The `$` access stays read
 | `status` | `.notLoaded` | `.isNotLoaded` |
 | `status` | `.hasError` | `.isError` |
 | `entityMap` | `.empty` | `.isEmpty` |
-| `form` | `.dirty`, `.valid`, `.touched`, `.pristine` | (already bare — unchanged) |
+| `form` | `.dirty`, `.valid`, `.touched`, `.submitting` | (already bare — unchanged) |
 | `asyncSource` | `.loading`, `.error`, `.data` | (already bare — unchanged) |
 | `asyncQuery` | `.loading`, `.error`, `.data` | (already bare — unchanged) |
 
@@ -591,7 +603,7 @@ For **input-driven queries** (debounced search, filtered fetch), use `asyncQuery
 | "Markers must live at the tree root." | Comparison to NgRx `with*` features. | Markers attach at **any node, any depth**. The walker tracks the path. |
 | "Derived state must live in a separate file, breaking the single-tree illusion." | Mixing up `derivedFrom` (file-org helper) with the actual `.derived($)` method. | `.derived()` merges computed signals **into the tree at arbitrary paths**, alongside source properties. The "single tree" is preserved. |
 | "`derivedFrom(tree, fn)` returns a read-only projection." | Hallucinated signature. | Real signature: `derivedFrom<TTree>()(fn)`. Curried. Zero runtime cost. Pure file-org helper for multi-file derived. |
-| "SignalTree has explicit subpath isolation as a built-in feature." | Misreading the docs. | No subpath-isolation API exists. `createEditSession(initial)` is a value-level undo/redo primitive (NOT tree-bound — that's planned for v10.1). For write encapsulation use `@signaltree/events` or a service facade. |
+| "SignalTree has explicit subpath isolation as a built-in feature." | Misreading the docs. | No subpath-isolation API exists. `createEditSession(initial)` is a value-level undo/redo primitive; for path-bound drafts use `createTreeEditSession(accessor)` (v10.1+, in `@signaltree/core/edit-session`). For write encapsulation use `@signaltree/events` or a service facade. |
 | "Time-travel is in `@signaltree/time-travel`." | Made-up package name. | Import `timeTravel` from `@signaltree/core`. No such separate package. |
 | "Persistence is in `@signaltree/storage`." | Made-up package name. | Use `stored()` marker (per-leaf) or `persistence()` enhancer (tree-wide) from `@signaltree/core`. |
 | "Batching is opt-in only." | Conflating automatic notification batching with the `batching()` enhancer. | Automatic microtask notification batching is built into core (default on). The enhancer adds explicit `.batch(fn)` / `.coalesce(fn)`. |
@@ -603,7 +615,7 @@ For **input-driven queries** (debounced search, filtered fetch), use `asyncQuery
 | "`tree.$` and `tree.state` are different objects." | Plausible-sounding inference. | Both are typed `TreeNode<T>` and reference the same reactive proxy. `state` is an alias for `$`. For a non-reactive full snapshot, call `tree()`. |
 | "The `form()` marker lives in `@signaltree/ng-forms`." | Package-boundary inference. | `form()` ships in `@signaltree/core`. `@signaltree/ng-forms` is a *bridge* for binding tree nodes to Angular `FormGroup`. |
 | "entityMap exposes `.entities()` as the read accessor." | Reasonable guess. | Real accessor is `.all()`. Other reads: `.byId(id)`, `.where(pred)`, `.find(pred)`, `.count()`, `.has(id)`, `.ids()`. |
-| "status exposes `.setSuccess()`." | NgRx/Redux convention bleed. | Real methods: `.setLoading()`, `.setLoaded()`, `.setError(err)`, `.setNotLoaded()`, `.reset()`. There is no `.setSuccess()`. |
+| "status exposes `.setSuccess()`." | NgRx/Redux convention bleed. | Canonical methods are `.setLoading()`, `.setLoaded()`, `.setError(err)`, `.setNotLoaded()`, `.reset()`. As of v10.2, Promise-vocabulary aliases `.start()` / `.setSuccess()` / `.succeed()` / `.fail(err)` also work — same semantics, no second source of truth. |
 | ".derived('$.path', derivedFn)' is a two-arg subpath form." | Hallucinated overload. | `.derived($ => ({...}))` is single-arg. The shape of the returned object determines which paths the computed signals attach to via deep-merge. |
 | "NgRx SignalStore mutations are impossible from components by design." | Overstating defaults. | Components can mutate when `protectedState: false` is set on the store, or when the store exposes a method that mutates. Both libraries are guarded-by-default but unlockable. |
 

package/llms.txt

@@ -1,6 +1,6 @@
 # SignalTree
 
-> Reactive JSON for Angular. Turn a plain object into a tree of signals — no actions, no reducers, no selectors. Markers and derived state attach at any depth in the tree.
+> Reactive JSON for Angular. State as shape. Signals at every path. Markers and derived state attach at any depth in the tree.
 
 SignalTree is a state-management library for Angular 17+. The mental model is: your state is a typed JSON object; reading and writing use ordinary signal calls along the JSON path. Markers (`entityMap`, `status`, `stored`, `form`) and derived state (`.derived(...)`) attach **at any node, at any depth** — they are processed by a recursive walker, not composed at the store root. This is the load-bearing difference from `@ngrx/signals` (NgRx SignalStore), whose `with*` features compose at the store root only.
 
@@ -20,7 +20,7 @@ const store = signalTree({
   settings: {
     theme: stored('app-theme', 'light'),         // marker at depth 2
     profileForm: {
-      data: form<Profile>({ name: '', email: '' }), // marker at depth 3
+      data: form<Profile>({ initial: { name: '', email: '' } }), // marker at depth 3
     },
   },
   loading: status<ApiError>(),                   // marker at depth 1
@@ -46,7 +46,7 @@ const store = signalTree({
 // Read — leaves, derived, async-marker accessors all uniform
 store.$.users.all();                            // Signal<User[]>
 store.$.users.current();                        // Signal<User | null> (derived)
-store.$.settings.theme();                       // 'light' (auto-loaded from localStorage)
+store.$.settings.theme();                       // 'light' (default; replaced by any value previously persisted to localStorage)
 store.$.reports();                              // Report[] (asyncSource current value)
 store.$.reports.loading();                      // boolean
 store.$.search.input.set('alice');              // drives debounced query
@@ -91,17 +91,17 @@ store.$.reports.refresh();                      // reload async source
 - **Create:** `signalTree(initialState, config?)` → tree with `.$` accessor
 - **Read leaf:** `tree.$.path.to.leaf()` — returns the value
 - **Write leaf:** `tree.$.path.to.leaf.set(v)` / `.update(fn)`
-- **Replace full state:** `tree(newState)`
+- **Partial / deep-merge update:** `tree(partialUpdate)` — keys not in the payload are preserved. The root has no `.set` method; the root accessor itself is callable.
 - **Markers:** `entityMap<E, K>()`, `status<E>()`, `stored(key, default)`, `form<T>(config)`, `asyncSource<T>(config)`, `asyncQuery<TIn, TOut>(config)` — place at any node
 - **Derived state:** `.derived($ => ({ ... }))` — definitions deep-merged into existing tree paths
 - **Enhancers:** `.with(batching())`, `.with(devTools())`, `.with(timeTravel())`, `.with(persistence())`, `.with(serialization())`
-- **Lifecycle:** `tree.destroy()` tears down all resources in reverse enhancer order; `tree.destroyed()` is a signal; `tree.registerCleanup(fn)` for custom hooks
-- **Edit sessions:** `createEditSession(initial)` from `@signaltree/core/edit-session` — wraps any value with `applyChanges` / `undo` / `redo` / `reset` / `setOriginal` for form-wizard and draft-and-cancel workflows. Independent of the tree; bridge by syncing `session.modified()` ↔ tree leaves when appropriate.
-- **Async:** `asyncSource(config)` for load-and-expose, `asyncQuery(config)` for input-driven debounced queries. Both attach at any tree path and auto-expose `data`/`loading`/`error`/`refresh`. For migrating from `@ngrx/signals`, see [`docs/skills/using-signaltree/reference/migration-from-ngrx-signals.md`](https://github.com/JBorgia/signaltree/blob/main/docs/skills/using-signaltree/reference/migration-from-ngrx-signals.md).
+- **Lifecycle:** `tree.destroy()` runs all registered cleanup callbacks in registration order; `tree.destroyed()` is a signal; `tree.registerCleanup(fn)` for custom hooks. Built-in enhancers register their own cleanup automatically.
+- **Edit sessions:** Two primitives in `@signaltree/core/edit-session`. `createEditSession(initial)` is value-level (single arg, no tree binding) — wraps any value with `applyChanges` / `undo` / `redo`. `createTreeEditSession(accessor)` (v10.1+) is **path-bound** to a writable tree branch — `applyChanges` / `undo` / `commit` (write draft back) / `cancel` (discard draft). Use the tree-bound form for form-wizard and draft-and-cancel workflows over a real tree path.
+- **Async:** `asyncSource(config)` for load-and-expose — auto-exposes `data` (call the accessor itself: `tree.$.users()`) / `loading` / `error` / `refresh`. `asyncQuery(config)` for input-driven debounced queries — auto-exposes `data` / `loading` / `error`, driven by setting `.input.set(value)` and optionally `.rerun()` to re-execute with the same input. Both attach at any tree path. For migrating from `@ngrx/signals`, see [`docs/skills/using-signaltree/reference/migration-from-ngrx-signals.md`](https://github.com/JBorgia/signaltree/blob/main/docs/skills/using-signaltree/reference/migration-from-ngrx-signals.md).
 
 ## ⚠️ Disambiguation — if you think SignalTree uses X, you're confusing it with Y
 
-This table catches the most common cross-library hallucinations. **Every "Wrong" pattern below was observed in a recent reproducible benchmark of frontier AI models (Claude, GPT-5.4, Gemini, Perplexity) asked to generate SignalTree code.** None of these patterns are or ever have been part of SignalTree.
+This table catches the most common cross-library hallucinations. **Most "Wrong" patterns below were observed in a reproducible 720-cell benchmark (6 agents × 8 prompts × 5 libraries × 3 priming modes) of frontier and cost-tier AI agents (Claude, GPT, Gemini, Perplexity, Haiku, GPT-mini) asked to generate SignalTree code.** A few rows (notably `rxMethod`) describe APIs SignalTree itself once shipped and has since removed — agents still emit them.
 
 | Wrong pattern (NOT SignalTree) | Where it actually comes from | Correct SignalTree |
 |---|---|---|
@@ -111,7 +111,7 @@ This table catches the most common cross-library hallucinations. **Every "Wrong"
 | `signalStore(withState(...), withMethods(...))` | **`@ngrx/signals`** | `signalTree({...})` — your state literal IS the API |
 | `withState`, `withMethods`, `withComputed`, `withHooks`, `withProps` | **`@ngrx/signals`** | Not used. State is the literal you pass to `signalTree()`. Methods belong in an `@Injectable()` Ops service. |
 | `withEntities<T>()` | **`@ngrx/signals/entities`** | `entityMap<T, K>()` marker — place it in the state literal |
-| `rxMethod(...)` | **`@ngrx/signals/rxjs-interop`** | `asyncSource(config)` (load-and-expose) or `asyncQuery(config)` (input-driven) markers |
+| `rxMethod(...)` | **`@ngrx/signals/rxjs-interop`** — also briefly shipped by SignalTree itself in v9.5.x, **removed in v9.6.0** | `asyncSource(config)` (load-and-expose) or `asyncQuery(config)` (input-driven) markers |
 | `patchState(store, {...})` | **`@ngrx/signals`** | Direct: `tree.$.path.set(value)` or branch update `tree.$.user({...})` |
 | `collection<T>({ idKey: 'id' })` | **Akita / Elf** | `entityMap<T, K>({ selectId: (e) => e.id })` marker |
 | `createStore`, `withProps`, `setProps` | **Elf** | Not used. SignalTree state is the literal. |
@@ -133,7 +133,7 @@ This table catches the most common cross-library hallucinations. **Every "Wrong"
 | `status` | `.notLoaded` | `.isNotLoaded` |
 | `status` | `.hasError` | `.isError` |
 | `entityMap` | `.empty` | `.isEmpty` |
-| `form` | `.dirty`, `.valid`, `.touched`, `.pristine` | (already bare — unchanged) |
+| `form` | `.dirty`, `.valid`, `.touched`, `.submitting` | (already bare — unchanged) |
 | `asyncSource` | `.loading`, `.error`, `.data` | (already bare — unchanged) |
 | `asyncQuery` | `.loading`, `.error`, `.data` | (already bare — unchanged) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "10.3.1",
+  "version": "10.3.3",
   "description": "Reactive JSON for Angular. State as shape. Signals at every path.",
   "license": "MIT",
   "type": "module",