@signaltree/enterprise 13.1.1 → 13.2.0

package/skills/using-signaltree/reference/core.md

@@ -0,0 +1,398 @@
+# Core reference: `@signaltree/core`
+
+Authoritative reference for the surface area an agent uses day-to-day. Signatures are simplified for readability — the source under `packages/core/src/` is the tiebreaker when generics or advanced overloads matter.
+
+## `signalTree(initialState, configOrDerived?)`
+
+Factory that turns a plain state object into a reactive tree.
+
+```ts
+import { signalTree } from '@signaltree/core';
+
+interface AppState {
+  counter: number;
+  user: { name: string; email: string };
+}
+
+const tree = signalTree<AppState>({
+  counter: 0,
+  user: { name: 'Ada', email: 'ada@example.com' },
+});
+
+tree.$.counter(); // read → 0
+tree.$.user.name.set('Grace');
+```
+
+Two overloads:
+
+- `signalTree<T>(initialState: T, config?: TreeConfig)` — standard path.
+- `signalTree<T, D>(initialState: T, derivedFactory: ($: TreeNode<T>) => D)` — attach derived state declared alongside the tree. The returned tree has `tree.$` augmented with the derived keys.
+
+Both overloads return a **builder** whose `.with(enhancer)` chain composes enhancers in application order.
+
+## The `$` proxy
+
+`tree.$` is a typed proxy mirroring the shape of your state.
+
+- Leaf access (`tree.$.counter`) returns a `WritableSignal<T>`-compatible accessor. Call it to read (`tree.$.counter()`), call `.set(v)` to assign, `.update(fn)` to update.
+- Branch access (`tree.$.user`) returns a group accessor. You can:
+  - Dot further into it: `tree.$.user.name`.
+  - Read the whole subtree as an object: `tree.$.user()`.
+  - Replace the subtree: `tree.$.user({ name, email })` (call the branch accessor).
+  - Patch the subtree with an updater: `tree.$.user((u) => ({ ...u, name }))`.
+  - `@signaltree/callable-syntax` adds the same callable shorthand for leaves (`tree.$.counter(5)` → `.set(5)`).
+
+**What's a leaf vs a branch?** It's a property of the *value's type*, not its position in the tree:
+
+- **Leaves** (have `.set()` / `.update()`): primitives (`string`, `number`, `boolean`, `null`, `undefined`, `bigint`, `symbol`), arrays, `Date`, `Map`, `Set`, `Error`, `RegExp`, `Promise`, functions, and class instances.
+- **Branches** (call form, no `.set()`): plain objects (records, interfaces, type aliases for object literals).
+
+A property typed `currentFilter: PlantFilter` where `PlantFilter` is `{ isArchived: boolean; sortBy: string }` is a **branch**, even though it lives next to primitive siblings. Writing `tree.$.currentFilter.set(merged)` will fail with `Property 'set' does not exist on type 'NodeAccessor<PlantFilter> & TreeNode<PlantFilter>'`. The correct form is the call form: `tree.$.currentFilter(merged)` or `tree.$.currentFilter((c) => ({ ...c, ...changes }))`.
+
+The `$` proxy is fully typed — dotting through `tree.$` gives you accurate autocomplete all the way down.
+
+## Reads and writes
+
+```ts
+import { signalTree } from '@signaltree/core';
+
+const tree = signalTree({
+  counter: 0,
+  user: { name: 'Ada', email: 'ada@example.com' },
+  ui: { theme: 'light' as 'light' | 'dark', sidebarOpen: false },
+});
+
+// read a leaf
+const n = tree.$.counter();
+
+// read a whole subtree
+const user = tree.$.user();
+
+// write a leaf
+tree.$.counter.set(1);
+tree.$.counter.update((n) => n + 1);
+
+// replace a subtree (call the branch accessor with a new object)
+tree.$.user({ name: 'Grace', email: 'grace@example.com' });
+
+// patch a subtree immutably (call the branch accessor with an updater fn)
+tree.$.user((u) => ({ ...u, name: 'Grace' }));
+
+// write multiple leaves at the root by calling the tree itself with an updater
+tree((s) => ({ ...s, counter: 99, ui: { ...s.ui, theme: 'dark' } }));
+```
+
+Reads inside `computed()` and `effect()` register reactive dependencies exactly like bare signals.
+
+**Branch and root writes auto-batch.** When you call a branch accessor or the
+root tree with an object or updater, every child signal write that results from
+the merge is coalesced into a single change-detection notification. This
+replaces the `patchState(store, { a, b, c })` idiom from `@ngrx/signals` —
+there's no need to add the `batching()` enhancer just to group a multi-field
+update, because branch/root writes are already batched by construction. Reach
+for `batching()` only when you want to coalesce multiple _separate_ writes
+(different call sites) within a tick.
+
+## Markers
+
+Markers are typed placeholders you put in the initial state. `signalTree()` replaces them at that path with the real runtime API.
+
+### `entityMap<E, K>(config?)`
+
+Normalized collection with O(1) CRUD.
+
+```ts
+import { signalTree, entityMap } from '@signaltree/core';
+
+interface User {
+  id: number;
+  name: string;
+}
+
+const store = signalTree({
+  users: entityMap<User, number>(),
+});
+
+store.$.users.addOne({ id: 1, name: 'Ada' });
+store.$.users.upsertOne({ id: 1, name: 'Ada Lovelace' });
+store.$.users.removeOne(1);
+store.$.users.setAll([{ id: 2, name: 'Grace' }]);
+
+const all = store.$.users.all(); // Signal<User[]> → User[]
+const userNode = store.$.users.byId(2); // EntityNode<User> | undefined — callable accessor with per-field signals
+const one = userNode?.(); // User | undefined
+const nameSignal = userNode?.name; // Signal<string> | undefined (field-level)
+```
+
+Key options live on `EntityConfig<E, K>`: `selectId: (entity) => entity.someKey` for a custom id key (e.g., `selectId: (p) => p.sku`); `sortComparer: (a, b) => …` (v10.5+, `@ngrx/entity` parity) to keep `all()` / `ids()` in a stable sorted order (`map()` stays insertion-order); plus optional `beforeAdd` / `beforeUpdate` / `beforeRemove` lifecycle hooks.
+
+**Full mutation surface:** `addOne`, `addMany`, `upsertOne`, `upsertMany`, `updateOne`, `updateMany(ids: K[], changes: Partial<E>)` (NOT NgRx-style `[{id, changes}]`), `updateWhere(pred, changes)`, `removeOne`, `removeMany`, `removeWhere`, `clear`, `setAll`.
+**Full read surface (Signals — invoke with `()`):** `all`, `count`, `ids`, `map`, `has(id)`, `where(pred)`, `find(pred)`, `empty` (the `.isEmpty` alias was removed in v11).
+**Node access:** `byId(id) → EntityNode<E> | undefined`. **Per-entity reads are body-granular** — `byId(id).field()` re-runs only when *that* entity changes (fan-out 1), not on every collection mutation.
+**Computed slices:** `entityMap<User>().computed('active', all => all.filter(u => u.active))` materializes `store.$.users.active()` as a `Signal<User[]>` — **fully typed on `tree.$` since v13.2** (no cast; chain `.computed()` more than once and every name is typed independently). The `compute` fn receives only that collection's `E[]`, so a projection that needs other state (another collection, an external id signal) stays a normal `computed`/`.derived()`.
+
+### `status()`
+
+Async operation state (`NotLoaded` | `Loading` | `Loaded` | `Error`), surfaced as a signal-backed object.
+
+```ts
+import { signalTree, status, LoadingState } from '@signaltree/core';
+
+// status() defaults to Error type; pass a type parameter for a custom error shape.
+const tree = signalTree({
+  load: status<string>(),
+});
+
+// Setters
+tree.$.load.setLoading();
+tree.$.load.setLoaded();
+tree.$.load.setError('network failure');
+tree.$.load.setNotLoaded(); // resets to initial NotLoaded state, clears error
+
+// Boolean reader signals — v10.3 canonical (bare names). Use these in templates and computed().
+tree.$.load.loading(); // boolean
+tree.$.load.loaded(); // boolean
+tree.$.load.hasError(); // boolean
+tree.$.load.notLoaded(); // boolean
+// (The is-prefix aliases .isLoading/.isLoaded/.isError/.isNotLoaded were removed in v11.)
+// — same Signal instance, both work; canonical preferred in new code.
+
+// v10.2+ Promise-vocabulary aliases (identical semantics, no args for booleans)
+tree.$.load.start();                       // === setLoading()
+tree.$.load.setSuccess();                  // === setLoaded() — NO ARGS
+tree.$.load.succeed();                     // === setLoaded()
+tree.$.load.fail('network failure');       // === setError('network failure')
+
+// Raw state and error if you need them
+tree.$.load.state();  // LoadingState (state is WritableSignal<LoadingState>)
+tree.$.load.error();  // E | null (error is WritableSignal<E | null> — write via .error.set(e))
+
+// When comparing raw state, always use the LoadingState enum — never string literals
+const loading = tree.$.load.state() === LoadingState.Loading; // ✓
+// tree.$.load.state() === 'loading'                              // ✗ TypeScript error
+```
+
+### `stored(key, default)`
+
+A single signal whose value is persisted to `localStorage` under `key`.
+
+```ts
+import { signalTree, stored } from '@signaltree/core';
+
+const tree = signalTree({
+  theme: stored<'light' | 'dark'>('app.theme', 'light'),
+});
+
+tree.$.theme.set('dark'); // writes through to localStorage
+```
+
+For full-tree persistence instead of a single leaf, use the `persistence()` enhancer.
+
+### `form(fields)`
+
+Tree-integrated form state (values, errors, dirty/touched, validity). For Angular `FormGroup` interop, pair with `formBridge()` from `@signaltree/ng-forms`.
+
+```ts
+import { signalTree, form } from '@signaltree/core';
+
+// form() takes a FormConfig — pass initial values under `initial`.
+const tree = signalTree({
+  profile: form({
+    initial: { username: '', email: '' },
+  }),
+});
+```
+
+See [`../ng-forms/SKILL.md`](../ng-forms/SKILL.md) for full form guidance.
+
+### `asyncSource<T>(config)`
+
+Load-and-expose async primitive. Materializes into an accessor with `data`, `loading`, `error` signals plus `refresh` / `set` / `update` / `reset` methods. Accepts `Observable<T>` or `Promise<T>` from the loader.
+
+```ts
+import { signalTree, asyncSource } from '@signaltree/core';
+import type { Observable } from 'rxjs';
+
+interface User { id: number; name: string; }
+interface Report { id: string; rows: number; }
+declare const api: {
+  list$(): Observable<User[]>;
+  generateReport$(): Observable<Report>;
+};
+
+const store = signalTree({
+  users: asyncSource<User[]>({
+    initial: [],
+    load: () => api.list$(),   // auto-loads on materialization
+  }),
+  report: asyncSource<Report>({
+    load: () => api.generateReport$(),
+    lazy: true,                // skip auto-load; caller invokes .refresh()
+  }),
+});
+
+store.$.users();          // current value (User[] | undefined)
+store.$.users.loading();  // Signal<boolean>
+store.$.users.error();    // Signal<unknown | null>
+store.$.users.refresh();  // reload (cancels in-flight)
+store.$.users.set([{ id: 1, name: 'Override' }]); // manual override
+store.$.users.reset();    // clear data/loading/error
+```
+
+Auto-cleans on the surrounding `DestroyRef`. **No manual `setLoading()` / `setLoaded()` wiring.**
+
+### `asyncQuery<TInput, TResult>(config)`
+
+Input-driven debounced query. A writable `input` signal drives a built-in `debounce → filter → distinctUntilChanged → switchMap(query)` pipeline. Race conditions, cancellation, dedup all handled.
+
+```ts
+import { signalTree, asyncQuery } from '@signaltree/core';
+import type { Observable } from 'rxjs';
+
+interface User { id: number; name: string; }
+declare const api: { search$(q: string): Observable<User[]>; };
+
+const store = signalTree({
+  search: asyncQuery<string, User[]>({
+    initialResult: [],
+    debounce: 300,
+    filter: (q) => q.length > 0,
+    query: (q) => api.search$(q),
+  }),
+});
+
+// Either two-way bind in a template:
+//   <input [(ngModel)]="store.$.search.input">
+// Or set imperatively:
+store.$.search.input.set('alice');
+
+store.$.search();          // current results
+store.$.search.loading();
+store.$.search.error();
+store.$.search.rerun();    // rerun current input, skip dedup
+store.$.search.reset();
+```
+
+### Custom markers
+
+`registerMarkerProcessor(processor)` extends the marker system. **Call it before any `signalTree()` that uses the custom marker.**
+
+## Enhancer composition
+
+`.with(enhancer)` chains enhancers in application order.
+
+```ts
+import { signalTree, batching, timeTravel, devTools, persistence } from '@signaltree/core';
+
+const tree = signalTree({ count: 0 })
+  .with(batching())
+  .with(
+    timeTravel({
+      // Customize the labels that show up in the DevTools action list.
+      actionNames: { update: 'x/update', set: 'x/set' },
+    })
+  )
+  .with(devTools({ treeName: 'Counter' }))
+  .with(
+    persistence({
+      key: 'counter.v1',
+      autoSave: true,
+      autoLoad: true,
+      debounceMs: 500,
+    })
+  );
+```
+
+SignalTree does **not** support per-call action names — there is no
+`store.$.count.set(5, 'incrementClicked')` signature. The `actionNames` block
+above (on `TimeTravelConfig`) rewrites the category labels (`update`, `set`,
+`batch`) globally. If you need finer-grained DevTools labels, use an Angular
+`effect()` to emit a tagged action as state mirrors the interesting change, or
+split hot domains into separately-labeled trees with their own
+`devTools({ treeName })`.
+
+Built-in enhancers exported from `@signaltree/core`:
+
+- `batching(config?: BatchingConfig)` — coalesce change-detection notifications.
+- `timeTravel(config?)` — undo / redo history.
+- `devTools(config?)` — Redux DevTools integration.
+- `serialization(config?)` / `persistence(config?)` — snapshot and auto-persist.
+
+> The `memoization` enhancer was removed in 9.0.1. Use Angular's built-in `computed()` for memoization — it provides equivalent caching at zero runtime cost.
+
+Utilities you may need when composing enhancers yourself:
+
+- `composeEnhancers(...enhancers)` — combine multiple enhancers into one.
+- `createEnhancer(metadata, fn)` — author a third-party enhancer with metadata.
+- `resolveEnhancerOrder(list)` — dependency-aware ordering.
+- `ENHANCER_META` — symbol used by third parties to attach metadata.
+
+## Derived state helpers
+
+One helper for declaring derived functions in separate files without losing type inference:
+
+- `derivedFrom<TTree>()` — returns a function that accepts `($) => derived`. Explicitly types `TTree` while inferring the return.
+
+```ts
+import { derivedFrom } from '@signaltree/core';
+import type { SignalTree } from '@signaltree/core';
+
+interface AppState {
+  counter: number;
+}
+type AppTree = SignalTree<AppState>;
+
+export const counterDerived = derivedFrom<AppTree>()(($) => ({
+  doubled: $.counter() * 2,
+}));
+```
+
+Prefer plain Angular `computed()` for inline derivations. Reach for `derivedFrom` only when you need to declare derived logic in a separate file and still get typed `$`.
+
+### `linked()` — derived-but-writable
+
+`.derived()` values are read-only `computed`s. When you need a value derived from a source that is *also writable* (and re-derives when the source changes), return `linked()` — comparable to NgRx `withLinkedState`, wrapping Angular's `linkedSignal`. The merged path is a real `WritableSignal`, so `.set()`/`.update()` type-check.
+
+```ts
+import { signalTree, linked } from '@signaltree/core';
+
+interface Option {
+  id: number;
+  label: string;
+}
+
+const tree = signalTree({ options: [] as Option[] }).derived(($) => ({
+  // Sticky selection: derive from options, keep the chosen item across refreshes.
+  // Annotate the computation's return type — like Angular's linkedSignal, TS
+  // can't infer it from the body when `prev.value` is referenced.
+  selected: linked({
+    source: () => $.options(),
+    computation: (opts, prev): Option | undefined =>
+      opts.find((o) => o.id === prev?.value?.id) ?? opts[0],
+  }),
+  // Simple form — re-derives when its reads change (return type inferred):
+  count: linked(() => $.options().length),
+}));
+
+const current: Option | undefined = tree.$.selected(); // read (derived)
+tree.$.selected.set({ id: 9, label: 'manual' }); // write (override) — type-checks
+tree.$.count.update((n) => n + 1); // writable too
+```
+
+Use `linked()` only when you need the writable part; for pure projections use `computed()`. The `source` reads tree state, so `linked()` belongs in `.derived(...)` where `$` is available.
+
+## Other utilities
+
+- `equal(a, b)` / `deepEqual(a, b)` — equality helpers used internally and safe to consume.
+- `parsePath('a.b.c')` — split a dot path into segments for dynamic access.
+- `isNodeAccessor(x)`, `isAnySignal(x)`, `toWritableSignal(x)` — runtime type guards / coercions.
+
+## Subpath exports
+
+`@signaltree/core` ships additional entry points (not re-exported from the root) to keep the main bundle small:
+
+- `@signaltree/core/edit-session` — value-level (`createEditSession`) and path-bound (`createTreeEditSession`, v10.1+) draft / undo / commit primitives.
+- `@signaltree/core/security` — security-oriented helpers (`SecurityValidator`, `SecurityPresets`).
+- `@signaltree/core/storage` — storage adapter primitives (`createStorageAdapter`, `createIndexedDBAdapter`).
+
+Import from the subpath when you need these — do not expect them on the main barrel.

package/skills/using-signaltree/reference/install.md

@@ -0,0 +1,110 @@
+# Install
+
+Version and install steps derived from each package's `peerDependencies` in `packages/<pkg>/package.json` (tiebreaker: `package.json` itself).
+
+## Required runtime
+
+- **Angular 20, 21, or 22** — every Angular-consuming package declares
+  `@angular/core: ^20.0.0 || ^21.0.0 || ^22.0.0` in `peerDependencies`.
+  SignalTree runs on Angular 20, 21, and 22 unchanged.
+- **TypeScript** — whatever your Angular project already pins.
+- **Node / package manager** — your normal Angular toolchain.
+
+Never instruct consumers to install `@signaltree/shared`, `@signaltree/types`, or `@signaltree/utils`. These are **private** packages bundled into the public `@signaltree/*` packages at build time.
+
+## Core
+
+```bash
+npm install @signaltree/core
+# yarn:  yarn add @signaltree/core
+# pnpm:  pnpm add @signaltree/core            # in a single-package repo
+#        pnpm add -w @signaltree/core         # in a pnpm workspace, install at the workspace root
+#        pnpm --filter <pkg> add @signaltree/core   # in a pnpm workspace, install in one package only
+```
+
+> **pnpm workspaces:** plain `pnpm add @signaltree/core` from the workspace root fails with `ERR_PNPM_ADDING_TO_ROOT`. Use `-w` for the workspace root, or `--filter <pkg>` to scope to one workspace package.
+
+Required peer deps (from `packages/core/package.json`):
+`@angular/core ^20.0.0 || ^21.0.0 || ^22.0.0`, `tslib ^2.0.0`. `@angular/compiler`, `@angular/platform-browser-dynamic`, and `zone.js` are declared optional peers.
+
+## Optional packages
+
+Install only what you need. Each package declares `@signaltree/core` as a peer.
+
+### `@signaltree/ng-forms`
+
+```bash
+npm install @signaltree/ng-forms
+```
+
+Adds `@angular/forms ^20.0.0 || ^21.0.0 || ^22.0.0` and `rxjs ^7.0.0` as peers. Read [`../ng-forms/SKILL.md`](../ng-forms/SKILL.md).
+
+### `@signaltree/enterprise`
+
+```bash
+npm install @signaltree/enterprise
+```
+
+Licensed under BSL-1.1 (see the package `package.json`). Peers: `@angular/core ^20.0.0 || ^21.0.0 || ^22.0.0`, `@signaltree/core`. Read [`../enterprise/SKILL.md`](../enterprise/SKILL.md).
+
+### `@signaltree/callable-syntax`
+
+```bash
+npm install --save-dev @signaltree/callable-syntax
+```
+
+Build-time-only transform — **install as a dev dependency**. Zero bytes at runtime. Wire into your build via the Vite plugin (`@signaltree/callable-syntax/vite`) or the Webpack plugin (`@signaltree/callable-syntax/webpack`). Detailed setup lives in [`../callable-syntax/SKILL.md`](../callable-syntax/SKILL.md).
+
+**TypeScript augmentation (≥ 9.2.0):** `@signaltree/callable-syntax` owns the `declare module '@angular/core'` augmentation that adds callable overloads to `WritableSignal<T>`. Prior to `@signaltree/core@9.2.0` the same augmentation also lived in `core` and activated globally on any import from core; that was removed because it broke type-checking in projects coexisting with `@ngrx/signals`. If you want the callable form on raw Angular signals, opt in explicitly via either:
+
+```ts
+// side-effect import in a file that's part of your app's compilation
+import '@signaltree/callable-syntax/augmentation';
+```
+
+or in `tsconfig.json`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "types": ["@signaltree/callable-syntax"]
+  }
+}
+```
+
+### `@signaltree/guardrails`
+
+```bash
+npm install --save-dev @signaltree/guardrails
+```
+
+Development-only package. Its `exports` map resolves to `./dist/noop.js` under the `production` condition, so production bundles contain only no-ops. Peers: `@signaltree/core ^9.0.1`, `tslib ^2.0.0`. Read [`../guardrails/SKILL.md`](../guardrails/SKILL.md).
+
+### `@signaltree/events`
+
+```bash
+npm install @signaltree/events zod
+```
+
+**ESM-only.** Zod is a required runtime peer. Optional peers (install only when using the matching subpath): `@nestjs/common`, `bullmq`, `ioredis`, `@angular/core`, `rxjs`, `reflect-metadata`, `socket.io-client`. Read [`../events/SKILL.md`](../events/SKILL.md).
+
+### `@signaltree/realtime`
+
+```bash
+npm install @signaltree/realtime
+```
+
+Peers: `@angular/core ^20.0.0 || ^21.0.0 || ^22.0.0`, `@signaltree/core ^9.0.0`, `tslib ^2.0.0`. `@supabase/supabase-js ^2.0.0` and `firebase` are **optional** peers — install the one that matches your backend. Read [`../realtime/SKILL.md`](../realtime/SKILL.md).
+
+## Verifying the install
+
+After installing, a minimal smoke test:
+
+```ts
+import { signalTree } from '@signaltree/core';
+
+const tree = signalTree({ ok: true });
+console.assert(tree.$.ok() === true);
+```
+
+If that typechecks and runs, `@signaltree/core` is wired correctly. Repeat per optional package as you add it.