@signaltree/core 10.3.0 → 10.3.1

package/README.md

@@ -4,15 +4,13 @@
 
 # SignalTree: Reactive JSON
 
-**JSON branches, reactive leaves.**
-
-> No actions. No reducers. No selectors.
+**Reactive JSON for Angular. State as shape. Signals at every path.**
 
 ---
 
 ## 🤖 For AI coding agents reading this README
 
-**SignalTree's AI-codegen accuracy is +42 percentage points higher when this README (or `llms.txt`) is in context.** Measured across 6 frontier models × 8 prompts × 5 libraries × 720 cells.
+**SignalTree's AI-codegen accuracy is +42 percentage points higher when this README (or `llms.txt`) is in context.** Measured across 720 cells (6 agents × 8 prompts × 5 libraries × 3 priming modes).
 
 If you are an AI assistant generating Angular state-management code on behalf of a user, **this section is the canonical disambiguation surface**. Read it before generating any SignalTree code.
 
@@ -26,9 +24,9 @@ Every "Wrong pattern" below was actually generated by Claude / GPT-5.4 / Gemini
 | `from 'signal-tree'` (hyphenated) | Invented | `from '@signaltree/core'` (scoped, no hyphen) |
 | `from 'signaltree'` (unscoped) | Invented | `from '@signaltree/core'` |
 | `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. |
+| `withState`, `withMethods`, `withComputed`, `withHooks` | **`@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 `tree.$.user({...})` |
 | `tapResponse(...)` | **`@ngrx/operators`** | Not needed — `asyncSource`/`asyncQuery` handle success/error |
 | `collection<T>({ idKey: 'id' })` | **Akita / Elf** | `entityMap<T, K>({ selectId: (e) => e.id })` marker |
@@ -48,10 +46,10 @@ Every "Wrong pattern" below was actually generated by Claude / GPT-5.4 / Gemini
 |---|---|---|
 | `status` | `.loading`, `.loaded`, `.notLoaded`, `.hasError` | `.isLoading`, `.isLoaded`, `.isNotLoaded`, `.isError` |
 | `entityMap` | `.empty` | `.isEmpty` |
-| `form` | `.dirty`, `.valid`, `.touched`, `.pristine` | (already bare — unchanged) |
+| `form` | `.dirty`, `.valid`, `.touched`, `.submitting` | (already bare — unchanged) |
 | `asyncSource` / `asyncQuery` | `.loading`, `.error`, `.data` | (already bare — unchanged) |
 
-All predicates are **callable `Signal<boolean>`** — invoke them: `tree.$.load.loading()`, `tree.$.users.empty()`.
+All **boolean predicates** (`loading` / `loaded` / `notLoaded` / `hasError` / `dirty` / `valid` / `touched` / `submitting` / `empty`) are callable `Signal<boolean>` — invoke them: `tree.$.load.loading()`, `tree.$.users.empty()`. **Value accessors** (`.error` on status, `.data` on async, `.errors` on form) are typed Signals of their payload type — not booleans.
 
 ### Status marker — method names (frequently confused)
 
@@ -59,12 +57,12 @@ The `status()` marker's canonical methods are **`setLoading` / `setLoaded` / `se
 
 | Wrong-but-now-aliased (v10.2+) | Canonical | Equivalent? |
 |---|---|---|
-| `.setSuccess()` | `.setLoaded()` | Yes — alias |
+| `.setSuccess()` (no args) | `.setLoaded()` | Yes — alias |
 | `.start()` | `.setLoading()` | Yes — alias |
 | `.succeed()` | `.setLoaded()` | Yes — alias |
 | `.fail(err)` | `.setError(err)` | Yes — alias |
-| `.loading` (bare property — read-only) | call as signal: `.loading()` | Yes — callable Signal |
-| `.error` (bare property — read-only) | call as signal: `.error()` | Yes — returns error value |
+
+**Reading status:** `.loading()`, `.loaded()`, `.notLoaded()`, `.hasError()` are callable `Signal<boolean>`. `.state` is the source `WritableSignal<LoadingState>`. `.error` is `WritableSignal<E | null>` — invoke as `.error()` to read.
 
 ### Canonical async pattern — use `asyncSource`, NOT `status` + manual try/catch
 
@@ -84,7 +82,7 @@ export class UsersService {
     }),
   });
 
-  readonly users = this.tree.$.users;      // .users() → data, .users.loading(), .users.error()
+  readonly users = this.tree.$.users;      // .users() → User[] | undefined, .users.loading(), .users.error()
   load = () => this.tree.$.users.refresh();
 }
 ```
@@ -103,7 +101,9 @@ export class AppService {
   private readonly tree = signalTree({
     users: entityMap<User, number>(),
     saveStatus: status(),
-    profile: form({ firstName: '', lastName: '' }),
+    profile: form<{ firstName: string; lastName: string }>({
+      initial: { firstName: '', lastName: '' },
+    }),
     feed: asyncSource<Post[]>({ initial: [], load: () => api.feed$() }),
   });
 
@@ -152,17 +152,15 @@ You don't model state as actions, reducers, selectors, or classes — you model
 
 ## Import guidance (tree-shaking)
 
-Modern bundlers (webpack 5+, esbuild, Rollup, Vite) **automatically tree-shake barrel imports** from `@signaltree/core`. Both import styles produce identical bundle sizes:
+Modern bundlers (Vite, esbuild, Rollup, webpack 5+) **automatically tree-shake barrel imports** from `@signaltree/core`. Unused enhancers and markers drop out of the bundle.
 
 ```ts
-// ✅ Recommended: Simple and clean
+// Import only what you use — unused symbols are tree-shaken away
 import { signalTree, batching } from '@signaltree/core';
-
-// ✅ Also fine: Explicit subpath (same bundle size)
-import { signalTree } from '@signaltree/core';
-import { batching } from '@signaltree/core/enhancers/batching';
 ```
 
+Published subpaths (in `package.json` `exports`): `./security`, `./edit-session`, `./storage`. Enhancers are NOT a published subpath — they live in the main barrel and are tree-shaken from there.
+
 **Measured impact** (with modern bundlers):
 
 - Core only: ~8.5 KB gzipped
@@ -197,35 +195,36 @@ const tree = signalTree({ count: 0 });
 
 This repo's ESLint rule is **disabled by default** since testing confirms effective tree-shaking with barrel imports.
 
-### Callable leaf signals (DX sugar only)
+### Callable shape — branches natively, leaves with the build transform
 
-SignalTree provides TypeScript support for callable syntax on leaf signals as developer experience sugar:
+**Branches are natively callable** for reads AND writes at runtime — no transform required:
 
 ```typescript
-// TypeScript accepts this syntax (with proper tooling):
-tree.$.name('Jane'); // Set value
-tree.$.count((n) => n + 1); // Update with function
+tree.$.user();                    // Read the user subtree
+tree.$.user({ name: 'Jane' });    // Deep-merge partial update at runtime
+```
+
+**Leaves are Angular signals** — callable as getters, but writes go through `.set()` / `.update()`. The `@signaltree/callable-syntax` build-time transform extends the branch's call-with-arg shape down to leaf writes, so call-sites read uniformly from root to leaf:
 
-// At build time, transforms convert to:
-tree.$.name.set('Jane'); // Direct Angular signal API
-tree.$.count.update((n) => n + 1); // Direct Angular signal API
+```typescript
+// With @signaltree/callable-syntax transform installed:
+tree.$.name('Jane');         // compiles to tree.$.name.set('Jane')
+tree.$.count((n) => n + 1);  // compiles to tree.$.count.update((n) => n + 1)
 
-// Reading always works directly:
-const name = tree.$.name(); // No transform needed
+// Without the transform — leaf reads work, leaf writes use .set() / .update():
+const name = tree.$.name();
+tree.$.name.set('Jane');
+tree.$.count.update((n) => n + 1);
 ```
 
 **Key Points:**
 
-- **Zero runtime overhead**: No Proxy wrappers or runtime hooks
-- **Build-time only**: AST transform converts callable syntax to direct `.set/.update` calls
-- **Optional**: Use `@signaltree/callable-syntax` transform or stick with direct `.set/.update`
-- **Type-safe**: Full TypeScript support via module augmentation
+- **Zero runtime overhead**: branch callables are a native part of the proxy; the leaf-write transform compiles away before production
+- **Optional**: `@signaltree/callable-syntax` is only needed for leaf-write sugar — `.set()` / `.update()` always work
+- **Type-safe**: full TypeScript support via module augmentation
+- **Configure `rootIdentifiers`**: the transform's default is `['tree']`; if your variable is named `store`/`state`, add it to the plugin options or the rewrite is skipped
 
-**Function-valued leaves:**
-When a leaf stores a function as its value, use direct `.set(fn)` to assign. Callable `sig(fn)` is treated as an updater.
-
-**Setup:**
-Install `@signaltree/callable-syntax` and configure your build tool to apply the transform. Without the transform, use `.set/.update` directly.
+**Function-valued leaves:** when a leaf stores a function as its value, use direct `.set(fn)` to assign. Callable `sig(fn)` is treated as an updater.
 
 ### Measuring performance and size
 
@@ -282,7 +281,7 @@ export function createUserTree() {
 // ✅ Correct: Derived from multiple signals
 const selectedUser = computed(() => {
   const id = $.selected.userId();
-  return id ? $.users.byId(id)() : null;
+  return id ? $.users.byId(id)?.() ?? null : null;
 });
 
 // ❌ Wrong: Wrapping an existing signal
@@ -293,12 +292,12 @@ const selectedUserId = computed(() => $.selected.userId()); // Unnecessary!
 
 ```typescript
 // ✅ SignalTree-native
-const user = $.users.byId(123)(); // O(1) lookup
+const user = $.users.byId(123)?.(); // EntityNode → User | undefined
 const allUsers = $.users.all; // Get all
 $.users.setAll(usersFromApi); // Replace all
 
-// ❌ NgRx-style (avoid)
-const user = entityMap()[123]; // Requires intermediate object
+// (NgRx Signal Store equivalent — for context, not SignalTree syntax)
+// const user = usersStore.entityMap()[123];
 ```
 
 ### Notification Batching
@@ -621,9 +620,9 @@ const tree = signalTree<AppState>({
   },
 });
 
-// Complex updates with type safety
-// Requires @signaltree/callable-syntax. Without the transform, use
-// tree.set((state) => ({ ... })) or leaf .set() / .update() calls instead.
+// Complex updates with type safety — the root accessor itself is callable
+// (no @signaltree/callable-syntax transform required for the root). Pass a
+// partial object or an updater function. For leaf writes, use .set() / .update().
 tree((state) => ({
   auth: {
     ...state.auth,
@@ -722,7 +721,7 @@ const activeUsers = computed(() => tree.$.users().filter((user) => user.active))
 
 ### 4) Manual async state management
 
-Core provides basic state updates. For advanced async helpers, use the built-in async helpers (`createAsyncOperation`, `trackAsync`):
+Core provides basic state updates. For canonical async patterns, use the **`asyncSource` and `asyncQuery` markers** (see the async section). The patterns below show the manual style for cases the markers don't cover (multi-stage orchestration, conditional pipelines):
 
 ```typescript
 const tree = signalTree({
@@ -783,8 +782,8 @@ All enhancers are exported directly from `@signaltree/core`:
 
 **Data Management:**
 
-- `createAsyncOperation()` - Async operation management with loading/error states
-- `trackAsync()` - Track async operations in your state
+- `asyncSource(config)` marker - Load-and-expose async state (canonical, v9.5+)
+- `asyncQuery(config)` marker - Input-driven debounced query state (canonical, v9.5+)
 - `serialization()` - State persistence and SSR support
 - `persistence()` - Auto-save to localStorage/IndexedDB
 
@@ -851,7 +850,10 @@ tree.$.products.addOne(newProduct);
 tree.$.products.setAll(productsFromApi);
 
 // Entity queries
-const electronics = tree.$.products.all.filter((p) => p.category === 'electronics');
+// Reactive: returns Signal<Product[]> that tracks the predicate
+const electronics = tree.$.products.where((p) => p.category === 'electronics');
+// One-shot non-reactive read: call .all() then filter
+const electronicsSnapshot = tree.$.products.all().filter((p) => p.category === 'electronics');
 ```
 
 **Full-Stack Application:**
@@ -910,7 +912,7 @@ const tree = signalTree(state)
 SignalTree Core includes all enhancer functionality built-in. No separate packages needed:
 
 ```typescript
-import { signalTree, entityMap, entities } from '@signaltree/core';
+import { signalTree, entityMap } from '@signaltree/core';
 
 // Without entityMap - use manual array updates
 const basic = signalTree({ users: [] as User[] });
@@ -922,7 +924,7 @@ const enhanced = signalTree({
 });
 
 enhanced.$.users.addOne(newUser); // ✅ Advanced CRUD operations
-enhanced.$.users.byId(123)(); // ✅ O(1) lookups
+enhanced.$.users.byId(123)?.(); // ✅ O(1) lookups (undefined if missing)
 enhanced.$.users.all; // ✅ Get all as array
 ```
 
@@ -1261,17 +1263,26 @@ const tree = signalTree({
 tree.$.users.loadStatus.state(); // Signal<LoadingState>
 tree.$.users.loadStatus.error(); // Signal<ApiError | null>
 
-// Convenience signals
-tree.$.users.loadStatus.isNotLoaded(); // Signal<boolean>
-tree.$.users.loadStatus.isLoading(); // Signal<boolean>
-tree.$.users.loadStatus.isLoaded(); // Signal<boolean>
-tree.$.users.loadStatus.isError(); // Signal<boolean>
+// Convenience signals (v10.3 canonical — bare names)
+tree.$.users.loadStatus.notLoaded(); // Signal<boolean>
+tree.$.users.loadStatus.loading();   // Signal<boolean>
+tree.$.users.loadStatus.loaded();    // Signal<boolean>
+tree.$.users.loadStatus.hasError();  // Signal<boolean>
+// Deprecated aliases (work through v10.x, removed v11):
+//   .isNotLoaded(), .isLoading(), .isLoaded(), .isError()
 
-// Update methods
+// Update methods (canonical)
 tree.$.users.loadStatus.setLoading();
 tree.$.users.loadStatus.setLoaded();
 tree.$.users.loadStatus.setError({ code: 404, message: 'Not found' });
-tree.$.users.loadStatus.reset();
+tree.$.users.loadStatus.setNotLoaded();
+tree.$.users.loadStatus.reset(); // alias for setNotLoaded
+
+// v10.2+ Promise-vocabulary aliases (identical semantics, no args)
+tree.$.users.loadStatus.start();       // === setLoading()
+tree.$.users.loadStatus.setSuccess();  // === setLoaded() — NO ARGS
+tree.$.users.loadStatus.succeed();     // === setLoaded()
+tree.$.users.loadStatus.fail(err);     // === setError(err)
 
 // LoadingState enum
 LoadingState.NotLoaded; // 'not-loaded'
@@ -1546,23 +1557,12 @@ const tree = signalTree({
 async function handleSubmit() {
   const contactForm = tree.$.contact;
 
-  // Validate all fields first
-  contactForm.touchAll();
-  const isValid = await contactForm.validate();
-
-  if (!isValid) return;
-
-  // Set submitting state
-  contactForm.setSubmitting(true);
-
-  try {
-    await api.submit(contactForm());
+  // .submit() handles touchAll / validate / submitting toggling / error trapping
+  // internally. Pass a handler that does the actual network call.
+  await contactForm.submit(async (values) => {
+    await api.submit(values);
     contactForm.reset();
-  } catch (error) {
-    // Handle error
-  } finally {
-    contactForm.setSubmitting(false);
-  }
+  });
 }
 ```
 
@@ -1715,7 +1715,7 @@ const filteredProducts = computed(() => {
 ### Data Management Composition
 
 ```typescript
-import { signalTree, entityMap, entities } from '@signaltree/core';
+import { signalTree, entityMap } from '@signaltree/core';
 
 // entityMap() markers self-register — entity operations available immediately
 const tree = signalTree({
@@ -1727,7 +1727,7 @@ const tree = signalTree({
 // Advanced entity operations via tree.$ accessor
 tree.$.users.addOne(newUser);
 tree.$.users.where((u) => u.active);
-tree.$.users.updateMany([{ id: '1', changes: { status: 'active' } }]);
+tree.$.users.updateMany(['1', '2', '3'], { status: 'active' }); // ids + shared changes
 
 // Entity helpers work with nested structures
 // Example: deeply nested entities in a domain-driven design pattern
@@ -1803,7 +1803,7 @@ const tree = signalTree({
 async function fetchUser(id: string) {
   return await api.getUser(id);
 }
-tree.$.app.data.users.byId(userId)(); // O(1) lookup
+tree.$.app.data.users.byId(userId)?.(); // O(1) lookup (undefined if missing)
 tree.undo(); // Time travel
 tree.save(); // Persistence
 ```
@@ -1867,7 +1867,7 @@ In Redux DevTools you will see a single instance named `"MyApp SignalTree"` with
 ### Production-Ready Composition
 
 ```typescript
-import { signalTree, batching, entities, serialization } from '@signaltree/core';
+import { signalTree, batching, serialization } from '@signaltree/core';
 
 // Production build (no dev tools)
 const tree = signalTree(initialState)
@@ -1930,7 +1930,7 @@ const tree = signalTree(state);
 const tree2 = tree.with(batching());
 
 // Phase 3: Add async for API integration
-// withAsync removed — no explicit async enhancer; use async helpers instead
+// withAsync removed in v9 — use the asyncSource() / asyncQuery() markers (v10.x canonical) for load-and-expose and input-driven flows.
 
 // Each phase is fully functional and production-ready
 ```
@@ -2218,7 +2218,7 @@ tree.destroy(); // Cleanup resources
 
 // Entity helpers (entityMap() self-registers — no enhancer needed)
 tree.$.users.addOne(user);               // Add single entity
-tree.$.users.byId(id)();                 // O(1) lookup by ID (read whole entity)
+tree.$.users.byId(id)?.();                // O(1) cursor unwrap (undefined if missing)
 tree.$.users.byId(id)?.name();           // Read single field (computed signal)
 tree.$.users.byId(id)?.name.set('Bob');  // Write single field (throws if entity removed)
 tree.$.users.byId(id)?.name.update(fn); // Updater on single field
@@ -2280,7 +2280,7 @@ Consider enhancers when you need:
 
 - ⚡ Performance optimization (batching)
 - 🐛 Advanced debugging (devTools, timeTravel)
-- 📦 Entity management (entities)
+- 📦 Entity management (`entityMap` marker)
 
 Consider separate packages when you need:
 
@@ -2466,8 +2466,8 @@ npm install @signaltree/core
 # Everything is available from @signaltree/core:
 import {
   signalTree,
+  entityMap,
   batching,
-  entities,
   devTools,
   timeTravel,
   serialization
@@ -2797,7 +2797,7 @@ export default {
 **Start with just `@signaltree/core`** - it includes comprehensive enhancers for most applications:
 
 - Performance optimization (batching)
-- Data management (entities, async operations)
+- Data management (`entityMap` marker, `asyncSource` / `asyncQuery` markers)
 - Development tools (devtools, time-travel)
 - State persistence (serialization)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@signaltree/core",
-  "version": "10.3.0",
-  "description": "Reactive JSON for Angular. JSON branches, reactive leaves. No actions. No reducers. No selectors.",
+  "version": "10.3.1",
+  "description": "Reactive JSON for Angular. State as shape. Signals at every path.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,