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.

Where SignalTree fits

SignalTree is built for structured state that wants batteries (entity CRUD, async status, forms, persistence, undo) attached at any node, at any depth — which describes most Angular apps past the prototype stage:

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

For a couple of values inside one component, use raw Angular signals (signal / computed / linkedSignal / resource) — they're zero-dependency and complete for that. 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, ./lazy, ./authoring. Enhancers are NOT a published subpath — they live in the main barrel and are tree-shaken from there.

• @signaltree/core/lazy — the lazy() helper for deferring marker/enhancer materialization.
• @signaltree/core/authoring — enhancer- and marker-author plumbing (getPathNotifier, registerMarkerProcessor, withWriteContext, createEnhancer, …). This is also the migration target for the deprecated root-barrel re-exports of getPathNotifier and registerMarkerProcessor (see below).

Measured impact (with modern bundlers, per tools/check-bundle-budget.mjs):

• Bare signalTree (no markers/enhancers): ~5.5 KB gzipped
• A tree using a plain entityMap(): ~8.4 KB gzipped
• Core + batching(): bare signalTree plus batching()'s own delta (see per-enhancer deltas under "Available extension packages")
• 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():

Deprecated root-barrel re-export: getPathNotifier from @signaltree/core is deprecated (11.6.0) — it moved to @signaltree/core/authoring as part of enhancer-author plumbing. The root re-export will be removed in the next major; import it from @signaltree/core/authoring instead.

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

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() - Deprecated (11.6.0) — Angular effect()-based subscriptions on tree state with cleanup. Use native Angular effect(() => tree.$.path()) instead: tree.effect()/tree.subscribe() call Angular's effect() without any injector handling, so calling them outside an injection context throws NG0203 (native effect() lets you pass { injector } explicitly to avoid this). Removal is planned for a future major release, not v12.

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

// Deprecated — prefer native effect(() => tree.$.count()) (see "Reactive effects" below)
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 - deprecated in 13.5.0; use tree.updateAndReport() in core
• @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

Deprecated root-barrel re-export: registerMarkerProcessor from @signaltree/core is deprecated (11.6.0) — marker-author plumbing moved to @signaltree/core/authoring. The root re-export will be removed in the next major; import it from @signaltree/core/authoring instead.

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

// 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, type 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 built-in markers that handle common state patterns Angular doesn't provide out of the box: entityMap (gains cache-aware (single-scope) self-loading via an optional load config, v11.2+/v11.4+), status, stored, form, and compared (v13.5+, per-leaf equality) — plus the async markers asyncSource / asyncQuery. 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 });

Cache-aware / self-loading entityMap (v11.4+)

Wrap the fetch function in the loader() helper and pass it as entityMap's load and it gains a self-loading, cache-aware surface — reach for this instead of hand-wiring entityMap + status() + a loader + a load-guard for any server-backed collection. Full entityMap surface plus a loader, load status, a staleTime freshness guard, single-flight dedup, tag-based invalidation, and optional offline-first persistence. It retains only the current scope (switching scope A → B → A refetches A, not a multi-key cache). There is no separate entityCollection marker (it was folded into entityMap in v11.4.0 — a plain entityMap<E, K>() with no load is unaffected). loader() is what keeps this machinery tree-shakeable — a plain entityMap() doesn't pay for it; a raw function passed directly as load was removed in v12 (RFC 0005 §6/§7) and now fails closed with a coded [ST2004] error. See RFC 0002, RFC 0003, and the cookbook.

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

const tree = signalTree({
  plants: entityMap<Plant, string>({
    selectId: (p) => p.url,
    load: loader(
      () => plantApi.list$(region), // () => Observable<E[]> | Promise<E[]>
      {
        staleTime: '30m', // skip refetch while fresh; ms or '30m'. default 0 = always stale
        swr: true, // serve last value while revalidating
        tags: ['plants'], // for invalidateTag(tree, 'plants')
      }
    ),
  }),
});

// Full entityMap surface (all/byId/where/addOne/setAll/…) plus:
await tree.$.plants.load(); // guarded: no-op if fresh OR in-flight — N callers => one fetch
await tree.$.plants.loadOrThrow(); // same guard, but rejects on failure instead of only setting .error()
await tree.$.plants.refresh(); // force reload, ignores staleTime
tree.$.plants.invalidate(); // mark stale; next load() refetches
tree.$.plants.loading(); // + .loaded() / .error() / .lastLoadedAt()

// Push invalidation (SSE / SignalR — the @signaltree/realtime seam):
invalidateTag(tree, 'plants'); // marks every collection carrying the tag stale

Auto-loads on first tree.$ access unless lazy: true. Keep HTTP-level caching (ETag / conditional GET) in the browser + HttpClient; this owns application-level freshness, not the transport.

Scoped collections (v11.4+)

Add a third type param P and give load a parameter to parameterize the collection by scope (region, customer, tenant, …) — see RFC 0003:

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

customers: entityMap<Customer, string, { regionUrl: string }>({
  selectId: (c) => c.externalId,
  load: loader(({ regionUrl }) => api.getCustomers$(regionUrl), {
    staleTime: '30m',
    // freshness compared per scope with `equal` (default: structural value comparison)
  }),
});

tree.$.customers.load({ regionUrl }); // same scope+fresh => no-op; scope changed => refetch + entities replaced
tree.$.customers.params(); // Signal<{ regionUrl: string } | undefined> — the typed scope of the loaded data

Freshness (staleTime) is evaluated per-scope, not globally: switching regionUrl marks the collection stale and refetches even if the old scope was still fresh. .refresh(params?) forces a reload (omit params to redo the last scope); clearOnParamsChange (default false) controls whether old rows stay visible during the scope switch. This is a single-scope cache — only the most recent scope's rows are retained; a multi-scope LRU is deferred (RFC 0003 §5). The parameterless (global) form above is unaffected — P defaults to void.

NG0600 fix (v11.4): a non-lazy, cache-aware entityMap's auto-load — and any offline-first persist seed — is deferred to a microtask off the synchronous materialization/render pass, so reading a non-lazy collection first inside a template no longer throws NG0600: Writing to signals is not allowed while Angular renders. Auto-load is now asynchronous (data arrives on the next microtask instead of during construction). The same fix applies to asyncSource.

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); 0 = synchronous write
  maxWaitMs: 1000, // Optional cap on write delay under continuous updates
  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
  onError: (e, ctx) => report(e, ctx), // Storage failure hook (read/write/migrate)
});

Durability

Debounced writes are drained automatically when the page is hidden or unloaded (visibilitychange → hidden, pagehide), so a value set right before the app is backgrounded or killed is not lost. Levers, from least to most aggressive:

tree.$.theme.flush(); // commit this signal's pending write now
flushAllStoredSignals(); // drain every stored signal (e.g. Capacitor 'pause' hook)
stored('key', v, { debounceMs: 0 }); // per-key: write synchronously in set()'s stack

clear() and reload() cancel any pending debounced write — a cleared value can't be resurrected by a timer that was already armed, and reload() treats storage as the source of truth (running migrate if the stored version differs, same as initial load).

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

Undo/redo history — history() (v13+)

Signal-native undo/redo for a form() marker. Import history alongside form/signalTree and attach it via the history config key — a raw config object ther