SignalTree: Reactive JSON

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 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.

Disambiguation — common cross-library hallucinations

Every "Wrong pattern" below was actually generated by Claude / GPT-5.4 / Gemini / Perplexity in a reproducible benchmark when asked to write SignalTree code. None of these patterns are or have ever been part of SignalTree.

| Wrong pattern (NOT SignalTree) | Where it actually comes from | Correct SignalTree | |---|---|---| | new SignalTree({...}) (class instantiation) | Invented — no library has this | signalTree({...}) — a function call, never new | | 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 | @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 — 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 | | createStore, withProps, setProps | Elf | Not used. SignalTree state is the literal. | | EntityStore<T>, @StoreConfig({ name }) | Akita | Not used. | | .value accessors on signals | MobX | Call the signal: tree.$.path() | | .upsert(user) (singular suffix omitted) | Akita | .upsertOne(user) / .upsertMany([...]) | | BehaviorSubject, .next(v), .asObservable() | RxJS classic | A plain leaf in signalTree() — no Observable wrapping | | Store.dispatch(action), Store.select(selector) | @ngrx/store (classic) | tree.$.path() to read, tree.$.path.set(v) to write | | .toPromise() (deprecated RxJS 7+) | RxJS legacy | firstValueFrom(obs) — or let asyncSource consume directly |

Marker accessor shape — UNIFIED in v10.3

Predicate accessors are bare-named everywhere — matching FormControl.dirty / .valid and Angular signals conventions. The old is-prefix names on status and entityMap.isEmpty (deprecated since v10.3) were removed in v11 — use the bare names. The table below maps old → new.

| Marker | Canonical (use this) | Removed in v11 (old name) | |---|---|---| | status | .loading, .loaded, .notLoaded, .hasError | .isLoading, .isLoaded, .isNotLoaded, .isError | | entityMap | .empty | .isEmpty | | form | .dirty, .valid, .touched, .submitting | (already bare — unchanged) | | asyncSource / asyncQuery | .loading, .error, .data | (already bare — unchanged) |

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)

The status() marker's canonical methods are setLoading / setLoaded / setError. As of v10.2, Promise-vocabulary aliases also work (identical semantics):

| Wrong-but-now-aliased (v10.2+) | Canonical | Equivalent? | |---|---|---| | .setSuccess() (no args) | .setLoaded() | Yes — alias | | .start() | .setLoading() | Yes — alias | | .succeed() | .setLoaded() | Yes — alias | | .fail(err) | .setError(err) | Yes — alias |

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

For load-and-expose (load data, expose loading state and data), reach for asyncSource:

import { Injectable, inject } from '@angular/core';
import { signalTree, asyncSource } from '@signaltree/core';

@Injectable({ providedIn: 'root' })
export class UsersService {
  private readonly api = inject(UserApi);
  private readonly tree = signalTree({
    users: asyncSource<User[]>({
      initial: [],
      load: () => this.api.list$(),
    }),
  });

  readonly users = this.tree.$.users;      // .users() → User[] | undefined, .users.loading(), .users.error()
  load = () => this.tree.$.users.refresh();
}

For input-driven queries (debounced search, filtered fetch), reach for asyncQuery — the debounce + dedup + switchMap pipeline is built in.

Canonical state-management pattern

import { Injectable, inject } from '@angular/core';
import { signalTree, entityMap, status, asyncSource, form } from '@signaltree/core';

@Injectable({ providedIn: 'root' })
export class AppService {
  // State is the literal — no with*() wrappers
  private readonly tree = signalTree({
    users: entityMap<User, number>(),
    saveStatus: status(),
    profile: form<{ firstName: string; lastName: string }>({
      initial: { firstName: '', lastName: '' },
    }),
    feed: asyncSource<Post[]>({ initial: [], load: () => api.feed$() }),
  });

  // Direct reads — call the signal
  readonly userCount = this.tree.$.users.count;
  readonly canSave = this.tree.$.profile.dirty;

  // Direct writes — call .set() / marker methods
  addUser = (u: User) => this.tree.$.users.addOne(u);
  startSave = () => this.tree.$.saveStatus.setLoading();
}

Where to read more

• Full priming surface (extended disambiguation, all markers, all patterns): signaltree.io/llms-full.txt
• Short priming surface (this content, slightly trimmed): signaltree.io/llms.txt — also shipped in this tarball at node_modules/@signaltree/core/llms.txt
• Myths and misconceptions catalogue: github.com/JBorgia/signaltree/blob/main/docs/myths-and-misconceptions.md
• Reproducible AI-codegen benchmark: github.com/JBorgia/signaltree/tree/main/scripts/ai-codegen-benchmark

What is @signaltree/core?

SignalTree treats application state as reactive JSON — a typed, dot-notation interface to plain JSON-like objects with fine-grained reactivity layered transparently on top.

You don't model state as actions, reducers, selectors, or classes — you model it as data.

When SignalTree earns its place (and when it doesn't)

SignalTree is not the right tool for every app — and saying so is part of the pitch. Its defensible niche is deeply structured state that needs batteries (entity CRUD, async status, forms, persistence, undo) attached at any node, at any depth:

import { signalTree, asyncSource, form, status } from '@signaltree/core';

const store = signalTree({
  workspace: {
    editor: {
      doc: asyncSource<Doc>({ initial: emptyDoc, load: () => api.doc$(id) }),
      draft: form<Doc>({ initial: emptyDoc }), // form marker — depth 3
      save: status<ApiError>(), //               status marker — depth 3
    },
    sidebar: { filters: form<Filters>({ initial: defaultFilters }) },
  },
});

store.$.workspace.editor.draft.dirty(); // each panel owns its state, addressed by path

Every behavior lives at the path it describes — not flattened to a store root, not hand-wired field by field. That structural locality, plus recursive typing and partial deep-merge writes, is the boilerplate SignalTree removes. It's the load-bearing difference from NgRx SignalStore (whose with* features compose at the store root only).

If your state is a handful of values or one flat object, use raw Angular signals (signal / computed / linkedSignal / resource) — they're zero-dependency and SignalTree would just be overhead. The honest decision boundary:

• Raw signals → simple/flat/component-local state, one async fetch. (when native signals are enough)
• SignalTree → structured/nested state needing batteries at depth, fully typed.
• NgRx SignalStore → you want Redux-style ergonomics or lean on its ecosystem. (comparison)

Core Philosophy

| Principle | What It Means | | ------------------------ | ---------------------------------------------------------------------------- | | State is Data | Your state shape looks like JSON. No ceremony, no abstractions. | | Dot-Notation Access | tree.$.user.profile.name() — fully type-safe, IDE-discoverable | | Invisible Reactivity | You think in data paths, not subscriptions. Reactivity emerges naturally. | | Lazy by Design | Signals created only where accessed. Types do heavy lifting at compile time. |

Technical Features

• Recursive typing with deep nesting and accurate type inference
• Fast operations with sub‑millisecond measurements at 5–20+ levels
• Strong TypeScript safety across nested structures
• Memory efficiency via structural sharing and lazy signals
• Small API surface with minimal runtime overhead
• Compact bundle size suited for production

Import guidance (tree-shaking)

Modern bundlers (Vite, esbuild, Rollup, webpack 5+) automatically tree-shake barrel imports from @signaltree/core. Unused enhancers and markers drop out of the bundle.

// Import only what you use — unused symbols are tree-shaken away
import { signalTree, batching } from '@signaltree/core';

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
• Core + batching: ~9.3 KB gzipped (barrel vs subpath: identical)
• Unused enhancers: automatically excluded by tree-shaking

Marker Tree-Shaking (Self-Registering)

Built-in markers (entityMap(), status(), stored()) are self-registering - they only add their processor code when you actually use them:

// ✅ Only status() code is bundled (entityMap and stored tree-shaken out)
import { signalTree, status } from '@signaltree/core';
const tree = signalTree({ loadState: status() });

// ✅ Minimal bundle - no marker code included
import { signalTree } from '@signaltree/core';
const tree = signalTree({ count: 0 });

How it works:

• Each marker factory (status(), stored(), entityMap()) registers its processor on first call
• If you never call a marker factory, its code is completely eliminated
• Zero import-time side effects - registration is lazy and automatic

When to use subpath imports:

• Older bundlers (webpack <5) with poor tree-shaking
• Explicit control over what gets included
• Personal/team preference for clarity

This repo's ESLint rule is disabled by default since testing confirms effective tree-shaking with barrel imports.

Callable shape — branches natively, leaves with the build transform

Branches are natively callable for reads AND writes at runtime — no transform required:

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:

// 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)

// 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: 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.

Measuring performance and size

Performance and bundle size vary by app shape, build tooling, device, and runtime. To get meaningful results for your environment:

• Use the Benchmark Orchestrator in the demo app to run calibrated, scenario-based benchmarks across supported libraries with real-world frequency weighting. It applies research-based multipliers derived from 40,000+ developer surveys and GitHub analysis, reports statistical summaries (median/p95/p99/stddev), alternates runs to reduce bias, and can export CSV/JSON. When available, memory usage is also reported.
• Use the bundle analysis scripts in scripts/ to measure your min+gz sizes. Sizes are approximate and depend on tree-shaking and configuration.

Best Practices (SignalTree-First)

📖 Production app structure: For anything beyond a single-component prototype, follow the Recommended Default Architecture — it wraps the patterns below in an AppStore facade with a $ + ops split, derived tiers, and an ESLint guard against direct tree mutation from components/services. The snippets in this README are deliberately minimal and use the low-level core API directly so they stay self-contained; in real apps the mutations shown here belong inside *Ops classes.

Follow these principles for idiomatic SignalTree code:

1. Expose signals directly (no computed wrappers)

const tree = signalTree(initialState);
const $ = tree.$; // Shorthand for state access

// ✅ SignalTree-first: Direct signal exposure
return {
  selectedUserId: $.selected.userId, // Direct from $ tree
  loadingState: $.loading.state,
  selectedUser, // Actual derived state (computed)
};

// ❌ Anti-pattern: Unnecessary computed wrappers
return {
  selectedUserId: computed(() => $.selected.userId()), // Adds indirection
};

2. Use ReturnType inference (SignalTree-first)

// Let SignalTree infer the type - no manual interface needed!
import type { createUserTree } from './user.tree';
export type UserTree = ReturnType<typeof createUserTree>;

// Factory function - no explicit return type needed
export function createUserTree() {
  const tree = signalTree(initialState); // entities() not needed in v7+
  return {
    selectedUserId: tree.$.selected.userId, // Type inferred automatically
    // ...
  };
}

3. Use computed() only for derived state

// ✅ Correct: Derived from multiple signals
const selectedUser = computed(() => {
  const id = $.selected.userId();
  return id ? $.users.byId(id)?.() ?? null : null;
});

// ❌ Wrong: Wrapping an existing signal
const selectedUserId = computed(() => $.selected.userId()); // Unnecessary!

4. Use EntitySignal API directly

// ✅ SignalTree-native
const user = $.users.byId(123)?.(); // EntityNode → User | undefined
const allUsers = $.users.all; // Get all
$.users.setAll(usersFromApi); // Replace all

// (NgRx Signal Store equivalent — for context, not SignalTree syntax)
// const user = usersStore.entityMap()[123];

Notification Batching

SignalTree automatically batches notification delivery to subscribers and change detection to the end of the current microtask. This prevents render thrashing when multiple values are updated together and preserves immediate read-after-write semantics (values update synchronously, notifications are deferred).

Example

// Multiple updates in the same microtask are coalesced into a single notification
tree.$.form.name.set('Alice');
tree.$.form.email.set('[email protected]');
tree.$.form.submitted.set(true);
// → Subscribers are notified once at the end of the microtask with final values

Testing

When tests need synchronous notification delivery, use flushSync():

import { getPathNotifier } from '@signaltree/core';

it('updates state', () => {
  tree.$.count.set(5);
  getPathNotifier().flushSync();
  expect(subscriber).toHaveBeenCalledWith(5, 0);
});

Alternatively, await a microtask (await Promise.resolve()) to allow the automatic flush to occur.

Opting out

To disable automatic microtask batching for a specific tree instance:

const tree = signalTree(initialState, { batchUpdates: false });

Use this only for rare cases that truly require synchronous notifications (most apps should keep batching enabled).

Quick start

Installation

npm install @signaltree/core

Deep nesting example

import { signalTree } from '@signaltree/core';

// Strong type inference at deep nesting levels
const tree = signalTree({
  enterprise: {
    divisions: {
      technology: {
        departments: {
          engineering: {
            teams: {
              frontend: {
                projects: {
                  signaltree: {
                    releases: {
                      v1: {
                        features: {
                          recursiveTyping: {
                            validation: {
                              tests: {
                                extreme: {
                                  depth: 15,
                                  typeInference: true,
                                },
                              },
                            },
                          },
                        },
                      },
                    },
                  },
                },
              },
            },
          },
        },
      },
    },
  },
});

// Type inference at deep nesting levels
const depth = tree.$.enterprise.divisions.technology.departments.engineering.teams.frontend.projects.signaltree.releases.v1.features.recursiveTyping.validation.tests.extreme.depth();
console.log(`Depth: ${depth}`);

// Type-safe updates at unlimited depth
tree.$.enterprise.divisions.technology.departments.engineering.teams.frontend.projects.signaltree.releases.v1.features.recursiveTyping.validation.tests.extreme.depth(25); // Perfect type safety!

Basic usage

import { signalTree } from '@signaltree/core';

// Create a simple tree
const tree = signalTree({
  count: 0,
  message: 'Hello World',
});

// Read values (these are Angular signals — always works)
console.log(tree.$.count()); // 0
console.log(tree.$.message()); // 'Hello World'

// ⚠️ CALLABLE SYNTAX REQUIRES BUILD TRANSFORM
// Lines below use tree.$.count(5) setter syntax. This requires the
// @signaltree/callable-syntax build-time transform (separate dev dependency).
// WITHOUT the transform, use .set()/.update() instead — these always work:
//   tree.$.count.set(5);
//   tree.$.message.set('Updated!');
//   tree.$.count.update((n) => n + 1);
// See: https://github.com/JBorgia/signaltree/blob/main/packages/callable-syntax/README.md
tree.$.count(5); // requires @signaltree/callable-syntax transform
tree.$.message('Updated!'); // requires @signaltree/callable-syntax transform

// Use in an Angular component
@Component({
  template: ` <div>Count: {{ tree.$.count() }}</div>
    <div>Message: {{ tree.$.message() }}</div>
    <button (click)="increment()">+1</button>`,
})
class SimpleComponent {
  tree = tree;

  increment() {
    this.tree.$.count((n) => n + 1);
  }
}

Intermediate usage (nested state)

// Create hierarchical state
const tree = signalTree({
  user: {
    name: 'John Doe',
    email: '[email protected]',
    preferences: {
      theme: 'dark',
      notifications: true,
    },
  },
  ui: {
    loading: false,
    errors: [] as string[],
  },
});

// Access nested signals with full type safety
// Requires @signaltree/callable-syntax. Without the transform, use:
// tree.$.user.name.set('Jane Doe');
// tree.$.user.preferences.theme.set('light');
// tree.$.ui.loading.set(true);
tree.$.user.name('Jane Doe');
tree.$.user.preferences.theme('light');
tree.$.ui.loading(true);

// Computed values from nested state
const userDisplayName = computed(() => {
  const user = tree.$.user();
  return `${user.name} (${user.email})`;
});

// Effects that respond to changes
effect(() => {
  if (tree.$.ui.loading()) {
    console.log('Loading started...');
  }
});

Reactive computations with computed()

SignalTree works seamlessly with Angular's computed() for creating efficient reactive computations. These computations automatically update when their dependencies change and are memoized for optimal performance.

import { computed, effect } from '@angular/core';
import { signalTree } from '@signaltree/core';

const tree = signalTree({
  users: [
    { id: '1', name: 'Alice', active: true, role: 'admin' },
    { id: '2', name: 'Bob', active: false, role: 'user' },
    { id: '3', name: 'Charlie', active: true, role: 'user' },
  ],
  filters: {
    showActive: true,
    role: 'all' as 'all' | 'admin' | 'user',
  },
});

// Basic computed - automatically memoized
const userCount = computed(() => tree.$.users().length);

// Complex filtering computation
const filteredUsers = computed(() => {
  const users = tree.$.users();
  const filters = tree.$.filters();

  return users.filter((user) => {
    if (filters.showActive && !user.active) return false;
    if (filters.role !== 'all' && user.role !== filters.role) return false;
    return true;
  });
});

// Derived computation from other computed values
const activeAdminCount = computed(() => filteredUsers().filter((user) => user.role === 'admin' && user.active).length);

// Performance-critical computation with complex logic
const userStatistics = computed(() => {
  const users = tree.$.users();

  return {
    total: users.length,
    active: users.filter((u) => u.active).length,
    admins: users.filter((u) => u.role === 'admin').length,
    averageNameLength: users.reduce((acc, u) => acc + u.name.length, 0) / users.length,
  };
});

// Dynamic computed functions (factory pattern)
const userById = (id: string) => computed(() => tree.$.users().find((user) => user.id === id));

// Usage in effects
effect(() => {
  console.log(`Filtered users: ${filteredUsers().length}`);
  console.log(`Statistics:`, userStatistics());
});

// Best Practices:
// 1. Use computed() for derived state that depends on signals
// 2. Keep computations pure - no side effects
// 3. Angular's computed() automatically caches results
// 4. Chain computed values for complex transformations
// 5. Use factory functions for parameterized computations

Performance optimization with computed()

Angular's built-in computed() provides automatic memoization — a result is cached until one of the signals it reads from changes. No additional enhancer is required:

import { computed } from '@angular/core';
import { signalTree } from '@signaltree/core';

const tree = signalTree({
  items: Array.from({ length: 10000 }, (_, i) => ({
    id: i,
    value: Math.random(),
    category: `cat-${i % 10}`,
  })),
});

// Expensive computation - automatically cached by Angular's computed()
const expensiveComputation = computed(() => {
  return tree.$.items()
    .filter((item) => item.value > 0.5)
    .reduce((acc, item) => acc + Math.sin(item.value * Math.PI), 0);
});

// The computation only runs when tree.$.items() actually changes
// Subsequent calls return the cached result

9.0.1 note: The memoization() enhancer was removed. Angular's computed() already memoizes; the enhancer added no value on top of it.

Advanced usage (full state tree)

interface AppState {
  auth: {
    user: User | null;
    token: string | null;
    isAuthenticated: boolean;
  };
  data: {
    users: User[];
    posts: Post[];
    cache: Record<string, unknown>;
  };
  ui: {
    theme: 'light' | 'dark';
    sidebar: {
      open: boolean;
      width: number;
    };
    notifications: Notification[];
  };
}

const tree = signalTree<AppState>({
  auth: {
    user: null,
    token: null,
    isAuthenticated: false,
  },
  data: {
    users: [],
    posts: [],
    cache: {},
  },
  ui: {
    theme: 'light',
    sidebar: { open: true, width: 250 },
    notifications: [],
  },
});

// 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,
    user: { id: '1', name: 'John' },
    isAuthenticated: true,
  },
  ui: {
    ...state.ui,
    notifications: [...state.ui.notifications, { id: '1', message: 'Welcome!', type: 'success' }],
  },
}));

// Get entire state as plain object
const currentState = tree();
console.log('Current app state:', currentState);

Core features

1) Hierarchical signal trees

Create deeply nested reactive state with automatic type inference:

const tree = signalTree({
  user: { name: '', email: '' },
  settings: { theme: 'dark', notifications: true },
  todos: [] as Todo[],
});

// Access nested signals with full type safety
tree.$.user.name(); // string signal
tree.$.settings.theme.set('light'); // type-checked value
tree.$.todos.update((todos) => [...todos, newTodo]); // array operations

2) TypeScript inference

SignalTree provides complete type inference without manual typing:

// Automatic inference from initial state
const tree = signalTree({
  count: 0, // Inferred as WritableSignal<number>
  name: 'John', // Inferred as WritableSignal<string>
  active: true, // Inferred as WritableSignal<boolean>
  items: [] as Item[], // Inferred as WritableSignal<Item[]>
  config: {
    theme: 'dark' as const, // Inferred as WritableSignal<'dark'>
    settings: {
      nested: true, // Deep nesting maintained
    },
  },
});

// Type-safe access and updates
tree.$.count.set(5); // ✅ number
tree.$.count.set('invalid'); // ❌ Type error
tree.$.config.theme.set('light'); // ❌ Type error ('dark' const)
tree.$.config.settings.nested.set(false); // ✅ boolean

3) Manual state management

Core provides basic state updates. For advanced entity management, use the built-in entities enhancer:

interface User {
  id: string;
  name: string;
  email: string;
  active: boolean;
}

const tree = signalTree({
  users: [] as User[],
});

// Entity CRUD operations using core methods
function addUser(user: User) {
  tree.$.users.update((users) => [...users, user]);
}

function updateUser(id: string, updates: Partial<User>) {
  tree.$.users.update((users) => users.map((user) => (user.id === id ? { ...user, ...updates } : user)));
}

function removeUser(id: string) {
  tree.$.users.update((users) => users.filter((user) => user.id !== id));
}

// Manual queries using computed signals
const userById = (id: string) => computed(() => tree.$.users().find((user) => user.id === id));
const activeUsers = computed(() => tree.$.users().filter((user) => user.active));

4) Manual async state management

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):

const tree = signalTree({
  users: [] as User[],
  loading: false,
  error: null as string | null,
});

// Manual async operation management
async function loadUsers() {
  tree.$.loading.set(true);
  tree.$.error.set(null);

  try {
    const users = await api.getUsers();
    tree.$.users.set(users);
  } catch (error) {
    tree.$.error.set(error instanceof Error ? error.message : 'Unknown error');
  } finally {
    tree.$.loading.set(false);
  }
}

// Usage in component
@Component({
  template: `
    @if (tree.$.loading()) {
    <div>Loading...</div>
    } @else if (tree.$.error()) {
    <div class="error">{{ tree.$.error() }}</div>
    } @else { @for (user of tree.$.users(); track user.id) {
    <user-card [user]="user" />
    } }
    <button (click)="loadUsers()">Refresh</button>
  `,
})
class UsersComponent {
  tree = tree;
  loadUsers = loadUsers;
}

5) Performance considerations

6) Enhancers and composition

SignalTree Core provides a complete set of built-in enhancers. Each enhancer is a focused, tree-shakeable extension that adds specific functionality.

Available Enhancers (All in @signaltree/core)

All enhancers are exported directly from @signaltree/core:

Performance Enhancers:

• batching() - Batch updates to reduce recomputation and rendering

9.0.1 note: The memoization() enhancer and all preset variants were removed. Use Angular's built-in computed() — it provides equivalent memoization with zero additional runtime cost.

Data Management:

• 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

Reactive Side Effects:

• effects() - Angular effect()-based subscriptions on tree state with cleanup

import { signalTree, effects } from '@signaltree/core';

const tree = signalTree({ count: 0, user: { name: 'Alice' } }).with(effects());

// Subscribe with automatic cleanup on destroy
const unsub = tree.subscribe((state) => {
  console.log('State changed:', state.count);
});

// Effect with cleanup callback
const cleanup = tree.effect((state) => {
  console.log('Count:', state.count);
  return () => console.log('Previous effect cleaned up');
});

Development Tools:

• devTools() - Redux DevTools auto-connect, path actions, and time-travel dispatch
• timeTravel() - Undo/redo functionality

Additional Packages

These are the only separate packages in the SignalTree ecosystem:

• @signaltree/ng-forms - Angular Forms integration (separate package)
• @signaltree/enterprise - Enterprise-scale optimizations for 500+ signals (separate package)
• @signaltree/callable-syntax - Build-time transform for callable syntax (dev dependency, separate package)

Composition Patterns

Basic Enhancement:

import { signalTree, batching, devTools } from '@signaltree/core';

// Apply enhancers by chaining — each .with() takes a single enhancer
const tree = signalTree({ count: 0 })
  .with(batching()) // Performance optimization
  .with(devTools()); // Development tools

Performance-Focused Stack:

import { signalTree, batching } from '@signaltree/core';

// entityMap() markers self-register — no entities() enhancer needed
const tree = signalTree({
  products: entityMap<Product>(),
  ui: { loading: false },
}).with(batching()); // Batch updates for optimal rendering

// Entity CRUD operations
tree.$.products.addOne(newProduct);
tree.$.products.setAll(productsFromApi);

// Entity queries
// 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:

import { signalTree, serialization, timeTravel } from '@signaltree/core';

const tree = signalTree({
  user: null as User | null,
  preferences: { theme: 'light' },
})
  .with(
    serialization({
      // Auto-save to localStorage
      autoSave: true,
      storage: 'localStorage',
    })
  )
  .with(timeTravel()); // Undo/redo support

// For async operations, use manual async or async helpers
async function fetchUser(id: string) {
  tree.$.loading.set(true);
  try {
    const user = await api.getUser(id);
    tree.$.user.set(user);
  } catch (error) {
    tree.$.loading.set(error.message);
  } finally {
    tree.$.loading.set(false);
  }
}

// Automatic state persistence
tree.$.preferences.theme('dark'); // Auto-saved

// Time travel
tree.undo(); // Revert changes

Enhancer Metadata & Ordering

Derived computed signals are preserved across .with() chaining, so enhancer composition does not recreate signal identities.

Enhancers can declare metadata for automatic dependency resolution:

// Chain enhancers — each .with() takes a single enhancer
const tree = signalTree(state)
  .with(batching()) // Requires: core, provides: batching
  .with(devTools()); // Requires: core, provides: debugging

Core Stubs

SignalTree Core includes all enhancer functionality built-in. No separate packages needed:

import { signalTree, entityMap } from '@signaltree/core';

// Without entityMap - use manual array updates
const basic = signalTree({ users: [] as User[] });
basic.$.users.update((users) => [...users, newUser]);

// With entityMap — entity helpers are automatically available (no enhancer needed)
const enhanced = signalTree({
  users: entityMap<User>(),
});

enhanced.$.users.addOne(newUser); // ✅ Advanced CRUD operations
enhanced.$.users.byId(123)?.(); // ✅ O(1) lookups (undefined if missing)
enhanced.$.users.all; // ✅ Get all as array

Core includes several performance optimizations:

// Lazy signal creation (default)
const tree = signalTree(
  {
    largeObject: {
      // Signals only created when accessed
      level1: { level2: { level3: { data: 'value' } } },
    },
  },
  {
    useLazySignals: true, // Default: true
  }
);

// Custom equality function
const tree2 = signalTree(
  {
    items: [] as Item[],
  },
  {
    useShallowComparison: false, // Deep equality (default)
  }
);

// Structural sharing for memory efficiency — update individual leaves directly
tree.$.newField.set('value'); // Only the changed leaf re-emits; siblings are unaffected

7) Extensibility: Custom Markers & Enhancers

SignalTree is designed for extensibility. Create your own markers (state placeholders that materialize into specialized signals) and enhancers (functions that augment trees with additional capabilities).

Custom Marker Example

import { signal, Signal } from '@angular/core';
import { registerMarkerProcessor, signalTree } from '@signaltree/core';

// 1. Define marker symbol and interface
const VALIDATED_MARKER = Symbol('VALIDATED_MARKER');

interface ValidatedMarker<T> {
  [VALIDATED_MARKER]: true;
  defaultValue: T;
  validator: (value: T) => string | null;
}

// 2. Create marker factory
function validated<T>(defaultValue: T, validator: (value: T) => string | null): ValidatedMarker<T> {
  return { [VALIDATED_MARKER]: true, defaultValue, validator };
}

// 3. Type guard
function isValidatedMarker(value: unknown): value is ValidatedMarker<unknown> {
  return Boolean(value && typeof value === 'object' && (value as any)[VALIDATED_MARKER] === true);
}

// 4. Register materializer (call once at app startup)
registerMarkerProcessor(isValidatedMarker, (marker) => {
  const valueSignal = signal(marker.defaultValue);
  const errorSignal = signal<string | null>(marker.validator(marker.defaultValue));
  return {
    get: () => valueSignal(),
    set: (v: any) => {
      valueSignal.set(v);
      errorSignal.set(marker.validator(v));
    },
    error: errorSignal.asReadonly(),
    isValid: () => errorSignal() === null,
  };
});

// 5. Usage
const tree = signalTree({
  email: validated('', (v) => (v.includes('@') ? null : 'Invalid email')),
});

Custom Enhancer Example

import { signal, Signal } from '@angular/core';
import type { ISignalTree } from '@signaltree/core';

interface WithLogger {
  log(message: string): void;
  history: Signal<string[]>;
}

function withLogger(config?: { maxHistory?: number }) {
  const maxHistory = config?.maxHistory ?? 100;
  return <T>(tree: ISignalTree<T>): ISignalTree<T> & WithLogger => {
    const historySignal = signal<string[]>([]);
    return Object.assign(tree, {
      log: (msg: string) => historySignal.update((h) => [...h, `[${new Date().toLocaleTimeString()}] ${msg}`].slice(-maxHistory)),
      history: historySignal.asReadonly(),
    });
  };
}

// Usage
const tree = signalTree({ count: 0 }).with(withLogger());
tree.log('Tree created');

📖 Full guide: Custom Markers & Enhancers

📱 Interactive demo: Demo App

8) Derived State Tiers

SignalTree supports derived state via the .derived() method, which allows you to add computed signals that build on base state or previous derived tiers.

Basic Usage (Inline Derived)

When derived functions are defined inline, TypeScript automatically infers all types:

import { signalTree, entityMap } from '@signaltree/core';
import { computed } from '@angular/core';

const tree = signalTree({
  users: entityMap<User, number>(),
  selectedUserId: null as number | null,
})
  .derived(($) => ({
    // Tier 1: Entity resolution
    selectedUser: computed(() => {
      const id = $.selectedUserId();
      return id != null ? $.users.byId(id)?.() ?? null : null;
    }),
  }))
  .derived(($) => ({
    // Tier 2: Complex logic (can access $.selectedUser from Tier 1)
    isAdmin: computed(() => $.selectedUser()?.role === 'admin'),
  }));

// Usage
tree.$.selectedUser(); // User | null (computed signal)
tree.$.isAdmin(); // boolean (computed signal)

External Derived Functions (Modular Architecture)

For larger applications, you may want to organize derived tiers into separate files. This requires explicit typing because TypeScript cannot infer types across file boundaries.

SignalTree provides two utilities for external derived functions:

• derivedFrom<TTree>() - Curried helper function that provides type context for your derived function
• WithDerived<TTree, TDerivedFn> - Type utility to build intermediate tree types

// app-tree.ts
import { signalTree, entityMap, WithDerived } from '@signaltree/core';
import { entityResolutionDerived } from './derived/tier-entity-resolution';
import { complexLogicDerived } from './derived/tier-complex-logic';

// Define base tree type
export type AppTreeBase = ReturnType<typeof signalTree<ReturnType<typeof createBaseState>>>;

// Build intermediate types using WithDerived
export type AppTreeWithTier1 = WithDerived<AppTreeBase, typeof entityResolutionDerived>;
export type AppTreeWithTier2 = WithDerived<AppTreeWithTier1, typeof complexLogicDerived>;

function createBaseState() {
  return {
    users: entityMap<User, number>(),
    selectedUserId: null as number | null,
  };
}

export function createAppTree() {
  return signalTree(createBaseState()).derived(entityResolutionDerived).derived(complexLogicDerived);
}

// derived/tier-entity-resolution.ts
import { computed } from '@angular/core';
import { derivedFrom } from '@signaltree/core';
import type { AppTreeBase } from '../app-tree';

// derivedFrom provides the type context for $ via curried syntax
export const entityResolutionDerived = derivedFrom<AppTreeBase>()(($) => ({
  selectedUser: computed(() => {
    const id = $.selectedUserId();
    return id != null ? $.users.byId(id)?.() ?? null : null;
  }),
}));

// derived/tier-complex-logic.ts
import { computed } from '@angular/core';
import { derivedFrom } from '@signaltree/core';
import type { AppTreeWithTier1 } from '../app-tree';

// This tier has access to $.selectedUser from Tier 1
export const complexLogicDerived = derivedFrom<AppTreeWithTier1>()(($) => ({
  isAdmin: computed(() => $.selectedUser()?.role === 'admin'),
  displayName: computed(() => {
    const user = $.selectedUser();
    return user ? `${user.firstName} ${user.lastName}` : 'No user selected';
  }),
}));

Why External Functions Need Typing

When a function is defined in a separate file, TypeScript analyzes it in isolation before knowing how it will be used. The type inference happens at the definition site, not the call site:

// ❌ TypeScript can't infer $ - this file is compiled before app-tree.ts uses it
export function myDerived($) {
  // $ is 'any'
  return { foo: computed(() => $.bar()) }; // Error: $ has no properties
}

// ✅ derivedFrom provides the type context (curried syntax)
export const myDerived = derivedFrom<AppTreeBase>()(($) => ({
  foo: computed(() => $.bar()), // $ is properly typed
}));

Key point: derivedFrom is only needed for functions defined in separate files. Inline functions automatically inherit types from the chain. Note the curried syntax: derivedFrom<TreeType>()(fn) - this allows TypeScript to infer the return type while you specify the tree type.

Built-in Markers

SignalTree provides four built-in markers that handle common state patterns Angular doesn't provide out of the box. All markers are self-registering and tree-shakeable - only the markers you use are included in your bundle.

9) entityMap<E, K>() - Normalized Collections

Creates a normalized entity collection with O(1) lookups by ID. Includes chainable .computed() for derived slices.

import { signalTree, entityMap } from '@signaltree/core';

interface Product {
  id: number;
  name: string;
  category: string;
  price: number;
  inStock: boolean;
}

const tree = signalTree({
  products: entityMap<Product, number>()
    .computed('electronics', (all) => all.filter((p) => p.category === 'electronics'))
    .computed('inStock', (all) => all.filter((p) => p.inStock))
    .computed('totalValue', (all) => all.reduce((sum, p) => sum + p.price, 0)),
});

// EntitySignal API
tree.$.products.setAll([
  { id: 1, name: 'Laptop', category: 'electronics', price: 999, inStock: true },
  { id: 2, name: 'Chair', category: 'furniture', price: 199, inStock: false },
]);

tree.$.products.all;                // Signal<Product[]> — getter, call as .all() to read
tree.$.products.all();              // Product[] — current value
tree.$.products.byId(1);           // EntityNode<Product> | undefined — cursor; call () to get value
tree.$.products.byId(1)?.();       // Product | undefined — unwrap the cursor

// Field-level reads and writes via EntityNode
// Field properties are computed signals: isSignal() returns true, toObservable() works
tree.$.products.byId(1)?.name();             // string — read field reactively
tree.$.products.byId(1)?.name.set('New');    // update single field (interceptors fire)
tree.$.products.byId(1)?.name.update(n => n.toUpperCase()); // updater
tree.$.products.byId(1)?.name.asReadonly();  // Signal<string> — read-only view

// Entity-level write via callable (replaces entire entity)
const node = tree.$.products.byId(1);
node?.({ id: 1, name: 'Updated', category: 'electronics', price: 899, inStock: true });

// Note: writes on a stale node (entity removed) throw "Entity with id X not found"
// This is consistent with updateOne() and the rest of the mutation API.
tree.$.products.ids;                // Signal<number[]> — getter
tree.$.products.ids();             // number[] — current value
tree.$.products.count;             // Signal<number> — getter
tree.$.products.count();           // number — current value

// Computed slices (reactive, type-safe)
tree.$.products.electronics();      // Signal<Product[]> - auto-updates
tree.$.products.inStock();          // Signal<Product[]>
tree.$.products.totalValue();       // Signal<number>

// CRUD operations
tree.$.products.upsertOne({ id: 1, name: 'Updated', category: 'electronics', price: 899, inStock: true });
tree.$.products.upsertMany([...]);
tree.$.products.removeOne(1);
tree.$.products.removeMany([1, 2]);
tree.$.products.clear();

Custom ID Selection

interface User {
  odataId: string; // Not named 'id'
  email: string;
}

const tree = signalTree({
  users: entityMap<User, string>(),
});

// Specify selectId when upserting
tree.$.users.upsertOne(user, { selectId: (u) => u.odataId });

10) status() - Manual Async State

Creates a status signal for manual async state management with type-safe error handling.

import { signalTree, status, LoadingState } from '@signaltree/core';

interface ApiError {
  code: number;
  message: string;
}

const tree = signalTree({
  users: {
    data: [] as User[],
    loadStatus: status<ApiError>(), // Generic error type
  },
});

// Status API
tree.$.users.loadStatus.state(); // Signal<LoadingState>
tree.$.users.loadStatus.error(); // Signal<ApiError | null>

// 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>

// Update methods (canonical)
tree.$.users.loadStatus.setLoading();
tree.$.users.loadStatus.setLoaded();
tree.$.users.loadStatus.setError({ code: 404, message: 'Not found' });
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'
LoadingState.Loading; // 'loading'
LoadingState.Loaded; // 'loaded'
LoadingState.Error; // 'error'

11) stored(key, default, options?) - localStorage Persistence

Auto-syncs state to localStorage with versioning and migration support.

⚠️ Read first: Persistence and Security covers the threat model and what stored() is — and isn't — appropriate for. Short version: fine for UI prefs, never for tokens, secrets, or PII.

import { signalTree, stored, createStorageKeys, clearStoragePrefix } from '@signaltree/core';

// Basic usage
const tree = signalTree({
  theme: stored('app-theme', 'light' as 'light' | 'dark'),
  lastViewedId: stored('last-viewed', null as number | null),
});

// Auto-loads from localStorage on init
// Auto-saves on every .set() or .update()
tree.$.theme.set('dark'); // Saved to localStorage immediately

// StoredSignal API
tree.$.theme(); // Get current value
tree.$.theme.set('light'); // Set and persist
tree.$.theme.clear(); // Remove from storage, reset to default
tree.$.theme.reload(); // Force reload from storage

Versioning and Migrations

interface SettingsV1 {
  darkMode: boolean;
}

interface SettingsV2 {
  theme: 'light' | 'dark' | 'system';
  fontSize: number;
}

const tree = signalTree({
  settings: stored<SettingsV2>(
    'user-settings',
    { theme: 'light', fontSize: 14 },
    {
      version: 2,
      migrate: (oldData, oldVersion) => {
        if (oldVersion === 1) {
          // Migrate from V1 to V2
          const v1 = oldData as SettingsV1;
          return {
            theme: v1.darkMode ? 'dark' : 'light',
            fontSize: 14, // New field with default
          };
        }
        return oldData as SettingsV2;
      },
      clearOnMigrationFailure: true, // Clear storage if migration fails
    }
  ),
});

Type-Safe Storage Keys

// Create namespaced storage keys
const STORAGE = createStorageKeys('myApp', {
  theme: 'theme',
  user: {
    settings: 'settings',
    preferences: 'prefs',
  },
} as const);

// STORAGE.theme = "myApp:theme"
// STORAGE.user.settings = "myApp:user:settings"

const tree = signalTree({
  theme: stored(STORAGE.theme, 'light'),
  settings: stored(STORAGE.user.settings, {}),
});

// Clear all app storage (e.g., on logout)
clearStoragePrefix('myApp');

Advanced Options

stored('key', defaultValue, {
  version: 1, // Schema version
  migrate: (old, ver) => migrated, // Migration function
  debounceMs: 100, // Write debounce (default: 100)
  storage: sessionStorage, // Custom storage backend
  serialize: (v) => JSON.stringify(v), // Custom serializer
  deserialize: (s) => JSON.parse(s), // Custom deserializer
  clearOnMigrationFailure: false, // Clear on failed migration
});

12) form(config) - Tree-Integrated Forms

Creates forms with validation, wizard navigation, and persistence that live inside SignalTree.

import { signalTree, form, validators } from '@signaltree/core';

interface ContactForm {
  name: string;
  email: string;
  phone: string;
  message: string;
}

const tree = signalTree({
  contact: form<ContactForm>({
    initial: { name: '', email: '', phone: '', message: '' },
    validators: {
      name: validators.required('Name is required'),
      email: [validators.required('Email is required'), validators.email('Invalid email format')],
      phone: validators.pattern(/^\+?[\d\s-]+$/, 'Invalid phone number'),
      message: validators.minLength(10, 'Message must be at least 10 characters'),
    },
  }),
});

// FormSignal API - Field access via $
tree.$.contact.$.name(); // Get field value
tree.$.contact.$.name.set('Jane'); // Set field value
tree.$.contact.$.email();

// Form-level operations
tree.$.contact(); // Get all values: ContactForm
tree.$.contact.set({ name: 'Jane', email: '[email protected]', phone: '', message: '' });
tree.$.contact.patch({ name: 'Updated' }); // Partial update
tree.$.contact.reset(); // Reset to initial values
tree.$.contact.clear(); // Clear all values

// Validation signals
tree.$.contact.valid(); // Signal<boolean>
tree.$.contact.dirty(); // Signal<boolean>
tree.$.contact.submitting(); // Signal<boolean>
tree.$.contact.touched(); // Signal<Record<keyof T, boolean>>
tree.$.contact.errors(); // Signal<Partial<Record<keyof T, string>>>
tree.$.contact.errorList(); // Signal<string[]>

// Validation methods
await tree.$.contact.validate(); // Validate all fields
await tree.$.contact.validateField('email');
tree.$.contact.touch('name'); // Mark field as touched
tree.$.contact.touchAll(); // Mark all fields as touched

Built-in Validators

import { validators } from '@signaltree/core';

validators.required('Field is required')
validators.minLength(5, 'Min 5 characters')
validators.maxLength(100, 'Max 100 characters')
validators.min(0, 'Must be positive')
validators.max(100, 'Max 100')
validators.email('Invalid email')
validators.pattern(/regex/, 'Invalid format')

// Compose multiple validators
validators: {
  password: [
    validators.required('Password is required'),
    validators.minLength(8, 'Min 8 characters'),
    validators.pattern(/[A-Z]/, 'Must contain uppercase'),
    validators.pattern(/[0-9]/, 'Must contain number'),
  ],
}

Wizard Navigation

const tree = signalTree({
  listing: form<ListingDraft>({
    initial: { title: '', description: '', photos: [], price: null, location: '' },
    validators: {
      title: validators.required('Title is required'),
      price: [validators.required('Price required'), validators.min(0, 'Must be positive')],
      location: validators.required('Location required'),
    },
    wizard: {
      steps: ['details', 'media', 'pricing', 'review'],
      stepFields: {
        details: ['title', 'description'],
        media: ['photos'],
        pricing: ['price'],
        review: ['location'],
      },
    },
  }),
});

// Wizard API
const wizard = tree.$.listing.wizard!;

wizard.currentStep(); // Signal<number> - 0-based index
wizard.stepName(); // Signal<string> - current step name
wizard.steps(); // Signal<string[]> - all step names
wizard.canNext(); // Signal<boolean>
wizard.canPrev(); // Signal<boolean>
wizard.isFirstStep(); // Signal<boolean>
wizard.isLastStep(); // Signal<boolean>

// Navigation (validates current step before proceeding)
await wizard.next(); // Returns false if validation fails
wizard.prev();
await wizard.goTo(2); // Jump to step by index
await wizard.goTo('pricing'); // Jump to step by name
wizard.reset(); // Go back to first step

Form Persistence

const tree = signalTree({
  draft: form<EmailDraft>({
    initial: { subject: '', body: '', to: '' },
    persist: 'email-draft', // localStorage key
    persistDebounceMs: 500, // Debounce writes (default: 500ms)
    validators: {
      subject: validators.required('Subject required'),
      to: validators.email('Invalid email'),
    },
  }),
});

// Form auto-saves to localStorage
// On page reload, draft is restored automatically

Async Validators

const tree = signalTree({
  registration: form<RegistrationForm>({
    initial: { username: '', email: '' },
    validators: {
      username: validators.minLength(3, 'Min 3 characters'),
    },
    asyncValidators: {
      username: async (value) => {
        const taken = await api.checkUsername(value);
        return taken ? 'Username already taken' : null;
      },
      email: async (value) => {
        const exists = await api.checkEmail(value);
        return exists ? 'Email already registered' : null;
      },
    },
  }),
});

Form Submission

async function handleSubmit() {
  const contactForm = tree.$.contact;

  // .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();
  });
}

Error handling examples

Manual async error handling

const tree = signalTree({
  data: null as ApiData | null,
  loading: false,
  error: null as Error | null,
  retryCount: 0,
});

async function loadDataWithRetry(attempt = 0) {
  tree.$.loading.set(true);
  tree.$.error.set(null);

  try {
    const data = await api.getData();
    tree.$.data.set(data);
    tree.$.loading.set(false);
    tree.$.retryCount.set(0);
  } catch (error) {
    if (attempt < 3) {
      // Retry logic
      await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
      return loadDataWithRetry(attempt + 1);
    }

    tree.$.loading.set(false);
    tree.$.error.set(error instanceof Error ? error : new Error('Unknown error'));
    tree.$.retryCount.update((count) => count + 1);
  }
}

// Error boundary component
@Component({
  template: `
    @if (tree.$.error()) {
    <div class="error-boundary">
      <h3>Something went wrong</h3>
      <p>{{ tree.$.error()?.message }}</p>
      <p>Attempts: {{ tree.$.retryCount() }}</p>
      <button (click)="retry()">Retry</button>
      <button (click)="clear()">Clear Error</button>
    </div>
    } @else {
    <!-- Normal content -->
    }
  `,
})
class ErrorHandlingComponent {
  tree = tree;

  retry() {
    loadDataWithRetry();
  }

  clear() {
    this.tree.$.error.set(null);
  }
}

State update error handling

const tree = signalTree({
  items: [] as Item[],
  validationErrors: [] as string[],
});

// Safe update with validation — read current state, transform, write back to leaves
function safeUpdateItem(id: string, updates: Partial<Item>) {
  try {
    const currentItems = tree.$.items();
    const itemIndex = currentItems.findIndex((item) => item.id === id);
    if (itemIndex === -1) {
      throw new Error(`Item with id ${id} not found`);
    }

    const updatedItem = { ...currentItems[itemIndex], ...updates };

    // Validation
    if (!updatedItem.name?.trim()) {
      throw new Error('Item name is required');
    }

    const newItems = [...currentItems];
    newItems[itemIndex] = updatedItem;

    tree.$.items.set(newItems);
    tree.$.validationErrors.set([]); // Clear errors on success
  } catch (error) {
    tree.$.validationErrors.update((errors) => [...errors, error instanceof Error ? error.message : 'Unknown error']);
  }
}

Package composition patterns

SignalTree Core is designed for modular composition. Start minimal and add features as needed.

Basic Composition

import { signalTree } from '@signaltree/core';

// Core provides the foundation
const tree = signalTree({
  users: [] as User[],
  ui: { loading: false },
});

// Basic operations included in core
tree.$.users.set([...users, newUser]);
tree.$.ui.loading.set(true);
// For reactive effects use Angular's built-in effect(): effect(() => console.log(tree.$.count()))

Performance-Enhanced Composition

import { signalTree, batching } from '@signaltree/core';

// Add performance optimizations
const tree = signalTree({
  products: [] as Product[],
  filters: { category: '', search: '' },
}).with(
  batching() // Batch updates for optimal rendering
);

// Now supports batched updates
tree.batchUpdate((state) => ({
  products: [...state.products, ...newProducts],
  filters: { category: 'electronics', search: '' },
}));

// Angular's computed() automatically caches derived values
const filteredProducts = computed(() => {
  return tree.$.products()
    .filter((p) => p.category.includes(tree.$.filters.category()))
    .filter((p) => p.name.includes(tree.$.filters.search()));
});

Data Management Composition

import { signalTree, entityMap } from '@signaltree/core';

// entityMap() markers self-register — entity operations available immediately
const tree = signalTree({
  users: entityMap<User>(),
  posts: entityMap<Post>(),
  ui: { loading: false, error: null as string | null },
});

// Advanced entity operations via tree.$ accessor
tree.$.users.addOne(newUser);
tree.$.users.where((u) => u.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
const appTree = signalTree({
  app: {
    data: {
      users: entityMap<User>(),
      products: entityMap<Product>(),
    },
  },
  admin: {
    data: {
      logs: entityMap<AuditLog>(),
      reports: entityMap<Report>(),
    },
  },
});

// Access nested entities using tree.$ accessor
appTree.$.app.data.users.where((u) => u.isAdmin); // Filtered signal
appTree.$.app.data.products.count(); // Count signal
appTree.$.admin.data.logs.all; // All items as array
appTree.$.admin.data.reports.ids(); // ID array signal

// For async operations, use manual async or async helpers
async function fetchUsers() {
  tree.$.ui.loading.set(true);
  try {
    const users = await api.getUsers();
    tree.$.users.setAll(users);
  } catch (error) {
    tree.$.ui.error.set(error.message);
  } finally {
    tree.$.ui.loading.set(false);
  }
}

Full-Featured Development Composition

import { signalTree, batching, serialization, timeTravel, devTools } from '@signaltree/core';

// Full development stack — chain each enhancer with a separate .with() call
// entityMap() markers self-register; no entities() enhancer needed
const tree = signalTree({
  app: {
    user: null as User | null,
    preferences: { theme: 'light' },
    data: { users: [], posts: [] },
  },
})
  .with(batching()) // Performance
  .with(
    serialization({
      // State persistence
      autoSave: true,
      storage: 'localStorage',
    })
  )
  .with(timeTravel({ maxHistorySize: 50 })) // Undo/redo
  .with(
    devTools({
      // Debug tools (dev only)
      name: 'MyApp',
      enableTimeTravel: true,
      includePaths: ['app.*', 'ui.*'],
      formatPath: (path) => path.replace(/\.(\d+)/g, '[$1]'),
    })
  );

// Rich feature set available
async function fetchUser(id: string) {
  return await api.getUser(id);
}
tree.$.app.data.users.byId(userId)?.(); // O(1) lookup (undefined if missing)
tree.undo(); // Time travel
tree.save(); // Persistence

Aggregated Redux DevTools Instance

When using multiple independent trees (e.g. per lazy-loaded feature module), each `devTools()` call creates a separate Redux DevTools instance by default. Use `aggregatedReduxInstance` to group multiple trees under a **single Redux DevTools instance**:

```typescript
import { signalTree, batching, entityMap, devTools } from '@signaltree/core';

const DEVTOOLS_GROUP_ID = 'my-app';
const DEVTOOLS_GROUP_NAME = 'MyApp SignalTree';

// Feature A tree
const ordersTree = signalTree({ orders: entityMap<Order>() })
  .with(batching())
  .with(devTools({
    treeName: 'orders-store',
    aggregatedReduxInstance: {
      id: DEVTOOLS_GROUP_ID,
      name: DEVTOOLS_GROUP_NAME,
    },
  }));

// Feature B tree (same group)
const productsTree = signalTree({ products: entityMap<Product>() })
  .with(batching())
  .with(devTools({
    treeName: 'products-store',
    aggregatedReduxInstance: {
      id: DEVTOOLS_GROUP_ID,
      name: DEVTOOLS_GROUP_NAME,
    },
  }));
```

In Redux DevTools you will see a single instance named `"MyApp SignalTree"` with state:

```json
{
  "orders-store": { "orders": { ... } },
  "products-store": { "products": { ... } }
}
```

**Key behaviors:**

- Trees sharing the same `aggregatedReduxInstance.id` are grouped together.
- The Redux DevTools `instanceId` is based on `aggregatedReduxInstance.id` to avoid collisions.
- Trees can be dynamically registered/unregistered as lazy-loaded modules come and go.
- The shared connection is created on first registration and cleaned up when the last tree disconnects.
- Trees that omit `aggregatedReduxInstance` work as standalone DevTools instances as before.
- You can mix aggregated and standalone trees in the same application.

**Logging:** DevTools internal logging is quiet by default. Set `enableLogging: true` on `devTools({ ... })` if you need console diagnostics.

**Cleanup:** Call `tree.disconnectDevTools()` when destroying a tree (e.g. in `DestroyRef.onDestroy`) to unregister it from the group and clean up its state in DevTools.

### Production-Ready Composition

```typescript
import { signalTree, batching, serialization } from '@signaltree/core';

// Production build (no dev tools)
const tree = signalTree(initialState)
  .with(batching())           // Performance optimization
  .with(serialization({       // User preferences
    autoSave: true,
    storage: 'localStorage',
    key: 'app-v1.2.3',
  }));

// Clean, efficient, production-ready
```

### Conditional Enhancement

```typescript
import { signalTree, batching, devTools, timeTravel } from '@signaltree/core';

const isDevelopment = process.env['NODE_ENV'] === 'development';

// Conditional enhancement based on environment
// entityMap() markers self-register; chain each enhancer with .with()
let tree = signalTree(state).with(batching()); // Always include performance
if (isDevelopment) {
  tree = tree.with(devTools()).with(timeTravel()); // Development-only features
}
```

### Preset-Based Composition

```typescript
import { signalTree, batching, devTools, timeTravel } from '@signaltree/core';

// Compose the enhancers you actually need
const devTree = signalTree({
  products: [],
  cart: { items: [], total: 0 },
  user: null,
})
  .with(batching())
  .with(devTools())
  .with(timeTravel());
```

> **9.0.1 note:** Preset factories (`createDevTr