@signaltree/core 7.1.6 → 7.3.0

package/README.md

@@ -1029,6 +1029,398 @@ export const myDerived = derivedFrom<AppTreeBase>()(($) => ({
 
 **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.
+
+```typescript
+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.setMany([
+  { 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[]> - all entities
+tree.$.products.byId(1);            // Signal<Product> | undefined
+tree.$.products.ids();              // Signal<number[]>
+tree.$.products.count();            // Signal<number>
+
+// 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
+
+```typescript
+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.
+
+```typescript
+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
+tree.$.users.loadStatus.isNotLoaded(); // Signal<boolean>
+tree.$.users.loadStatus.isLoading(); // Signal<boolean>
+tree.$.users.loadStatus.isLoaded(); // Signal<boolean>
+tree.$.users.loadStatus.isError(); // Signal<boolean>
+
+// Update methods
+tree.$.users.loadStatus.setLoading();
+tree.$.users.loadStatus.setLoaded();
+tree.$.users.loadStatus.setError({ code: 404, message: 'Not found' });
+tree.$.users.loadStatus.reset();
+
+// 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.
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+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.
+
+```typescript
+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: 'jane@example.com', 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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+async function handleSubmit() {
+  const contactForm = tree.$.contact;
+
+  // Validate all fields first
+  contactForm.touchAll();
+  const isValid = await contactForm.validate();
+
+  if (!isValid) return;
+
+  // Set submitting state
+  contactForm.setSubmitting(true);
+
+  try {
+    await api.submit(contactForm());
+    contactForm.reset();
+  } catch (error) {
+    // Handle error
+  } finally {
+    contactForm.setSubmitting(false);
+  }
+}
+```
+
 ## Error handling examples
 
 ### Manual async error handling

package/dist/index.js

@@ -3,7 +3,8 @@ export { ENHANCER_META } from './lib/types.js';
 export { derivedFrom, externalDerived } from './lib/internals/derived-types.js';
 export { isDerivedMarker } from './lib/markers/derived.js';
 export { LoadingState, isStatusMarker, status } from './lib/markers/status.js';
-export { isStoredMarker, stored } from './lib/markers/stored.js';
+export { clearStoragePrefix, createStorageKeys, isStoredMarker, stored } from './lib/markers/stored.js';
+export { FORM_MARKER, createFormSignal, form, isFormMarker, validators } from './lib/markers/form.js';
 export { registerMarkerProcessor } from './lib/internals/materialize-markers.js';
 export { composeEnhancers, createLazySignalTree, isAnySignal, isNodeAccessor, toWritableSignal } from './lib/utils.js';
 export { createEditSession } from './lib/edit-session.js';

package/dist/lib/markers/entity-map.js

@@ -1,3 +1,4 @@
+import { computed } from '@angular/core';
 import { createEntitySignal } from '../entity-signal.js';
 import { registerMarkerProcessor } from '../internals/materialize-markers.js';
 import { isEntityMapMarker } from '../utils.js';
@@ -8,13 +9,33 @@ function entityMap(config) {
     entityMapRegistered = true;
     registerMarkerProcessor(isEntityMapMarker, (marker, notifier, path) => {
       const cfg = marker.__entityMapConfig ?? {};
-      return createEntitySignal(cfg, notifier, path);
+      const entitySignal = createEntitySignal(cfg, notifier, path);
+      const slices = marker.__computedSlices;
+      if (slices) {
+        for (const [name, sliceConfig] of Object.entries(slices)) {
+          const computedSignal = computed(() => sliceConfig.compute(entitySignal.all()));
+          entitySignal[name] = computedSignal;
+        }
+      }
+      return entitySignal;
     });
   }
-  return {
+  const slices = {};
+  const combined = {
     __isEntityMap: true,
-    __entityMapConfig: config ?? {}
+    __entityMapConfig: config ?? {},
+    __computedSlices: slices,
+    computed(name, compute) {
+      slices[name] = {
+        compute: compute
+      };
+      return combined;
+    },
+    build() {
+      return combined;
+    }
   };
+  return combined;
 }
 
-export { entityMap };
+export { entityMap, isEntityMapMarker };

package/dist/lib/markers/form.js

@@ -0,0 +1,310 @@
+import { signal, computed } from '@angular/core';
+import { registerMarkerProcessor } from '../internals/materialize-markers.js';
+
+const FORM_MARKER = Symbol('FORM_MARKER');
+let formRegistered = false;
+function form(config) {
+  if (!formRegistered) {
+    formRegistered = true;
+    registerMarkerProcessor(isFormMarker, createFormSignal);
+  }
+  return {
+    [FORM_MARKER]: true,
+    config
+  };
+}
+function isFormMarker(value) {
+  return value !== null && typeof value === 'object' && FORM_MARKER in value && value[FORM_MARKER] === true;
+}
+function createFormSignal(marker) {
+  const config = marker.config;
+  const initial = config.initial;
+  const valuesSignal = signal({
+    ...initial
+  });
+  const touchedSignal = signal(Object.keys(initial).reduce((acc, key) => {
+    acc[key] = false;
+    return acc;
+  }, {}));
+  const errorsSignal = signal({});
+  const submittingSignal = signal(false);
+  const dirty = computed(() => {
+    const current = valuesSignal();
+    const eq = config.equalityFn ?? defaultEquality;
+    return Object.keys(initial).some(key => !eq(current[key], initial[key]));
+  });
+  const valid = computed(() => {
+    const errs = errorsSignal();
+    return Object.values(errs).every(e => e === null || e === undefined);
+  });
+  const errorList = computed(() => {
+    const errs = errorsSignal();
+    return Object.values(errs).filter(e => e !== null && e !== undefined);
+  });
+  let persistTimeout = null;
+  const storage = config.storage !== undefined ? config.storage : typeof window !== 'undefined' ? window.localStorage : null;
+  function loadFromStorage() {
+    if (!config.persist || !storage) return;
+    try {
+      const stored = storage.getItem(config.persist);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        valuesSignal.set({
+          ...initial,
+          ...parsed
+        });
+      }
+    } catch {}
+  }
+  function saveToStorage() {
+    if (!config.persist || !storage) return;
+    try {
+      storage.setItem(config.persist, JSON.stringify(valuesSignal()));
+    } catch {}
+  }
+  function schedulePersist() {
+    if (!config.persist) return;
+    if (persistTimeout) clearTimeout(persistTimeout);
+    persistTimeout = setTimeout(saveToStorage, config.persistDebounceMs ?? 500);
+  }
+  loadFromStorage();
+  function createFieldAccessor(path, getValue, setValue) {
+    const accessor = () => getValue();
+    accessor.set = v => {
+      setValue(v);
+      schedulePersist();
+    };
+    accessor.update = fn => {
+      setValue(fn(getValue()));
+      schedulePersist();
+    };
+    return accessor;
+  }
+  function createFieldsProxy(values) {
+    const proxy = {};
+    for (const key of Object.keys(values)) {
+      const k = key;
+      const fieldAccessor = createFieldAccessor(key, () => valuesSignal()[k], v => valuesSignal.update(curr => ({
+        ...curr,
+        [k]: v
+      })));
+      const value = values[k];
+      if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        const nested = createFieldsProxy(value);
+        Object.assign(fieldAccessor, nested);
+      }
+      proxy[key] = fieldAccessor;
+    }
+    return proxy;
+  }
+  const fieldsProxy = createFieldsProxy(initial);
+  async function validateField(field) {
+    const value = valuesSignal()[field];
+    const validators = config.validators?.[field];
+    const asyncValidator = config.asyncValidators?.[field];
+    let error = null;
+    if (validators) {
+      const validatorArray = Array.isArray(validators) ? validators : [validators];
+      for (const validator of validatorArray) {
+        error = validator(value);
+        if (error) break;
+      }
+    }
+    if (!error && asyncValidator) {
+      error = await asyncValidator(value);
+    }
+    errorsSignal.update(errs => ({
+      ...errs,
+      [field]: error
+    }));
+    return error === null;
+  }
+  async function validateAll() {
+    const fields = Object.keys(initial);
+    const results = await Promise.all(fields.map(validateField));
+    return results.every(Boolean);
+  }
+  let wizard;
+  if (config.wizard) {
+    const wizardConfig = config.wizard;
+    const currentStepSignal = signal(0);
+    const stepName = computed(() => wizardConfig.steps[currentStepSignal()] ?? '');
+    const canNext = computed(() => currentStepSignal() < wizardConfig.steps.length - 1);
+    const canPrev = computed(() => currentStepSignal() > 0);
+    const isLastStep = computed(() => currentStepSignal() === wizardConfig.steps.length - 1);
+    const isFirstStep = computed(() => currentStepSignal() === 0);
+    async function validateCurrentStep() {
+      const stepIdx = currentStepSignal();
+      const stepNameStr = wizardConfig.steps[stepIdx];
+      const stepCfg = wizardConfig.stepConfig?.[stepNameStr];
+      if (stepCfg?.validate) {
+        const result = await stepCfg.validate();
+        if (!result) return false;
+      }
+      const stepFields = wizardConfig.stepFields?.[stepNameStr] ?? stepCfg?.fields ?? [];
+      for (const field of stepFields) {
+        const isValid = await validateField(field);
+        if (!isValid) return false;
+      }
+      return true;
+    }
+    wizard = {
+      currentStep: currentStepSignal.asReadonly(),
+      stepName,
+      steps: signal(wizardConfig.steps).asReadonly(),
+      canNext,
+      canPrev,
+      isLastStep,
+      isFirstStep,
+      async next() {
+        const valid = await validateCurrentStep();
+        if (!valid) return false;
+        const current = currentStepSignal();
+        if (current < wizardConfig.steps.length - 1) {
+          currentStepSignal.set(current + 1);
+          return true;
+        }
+        return false;
+      },
+      prev() {
+        const current = currentStepSignal();
+        if (current > 0) {
+          currentStepSignal.set(current - 1);
+        }
+      },
+      async goTo(step) {
+        const targetIdx = typeof step === 'number' ? step : wizardConfig.steps.indexOf(step);
+        if (targetIdx < 0 || targetIdx >= wizardConfig.steps.length) {
+          return false;
+        }
+        if (targetIdx > currentStepSignal()) {
+          const valid = await validateCurrentStep();
+          if (!valid) return false;
+        }
+        currentStepSignal.set(targetIdx);
+        return true;
+      },
+      reset() {
+        currentStepSignal.set(0);
+      }
+    };
+  }
+  const formSignalFn = () => valuesSignal();
+  formSignalFn.$ = fieldsProxy;
+  formSignalFn.set = values => {
+    valuesSignal.update(curr => ({
+      ...curr,
+      ...values
+    }));
+    schedulePersist();
+  };
+  formSignalFn.patch = values => {
+    valuesSignal.update(curr => ({
+      ...curr,
+      ...values
+    }));
+    schedulePersist();
+  };
+  formSignalFn.reset = () => {
+    valuesSignal.set({
+      ...initial
+    });
+    touchedSignal.set(Object.keys(initial).reduce((acc, key) => {
+      acc[key] = false;
+      return acc;
+    }, {}));
+    errorsSignal.set({});
+    wizard?.reset();
+    schedulePersist();
+  };
+  formSignalFn.clear = () => {
+    const empty = Object.keys(initial).reduce((acc, key) => {
+      const val = initial[key];
+      acc[key] = typeof val === 'string' ? '' : typeof val === 'number' ? 0 : Array.isArray(val) ? [] : val === null ? null : typeof val === 'object' ? {} : val;
+      return acc;
+    }, {});
+    valuesSignal.set(empty);
+    schedulePersist();
+  };
+  formSignalFn.valid = valid;
+  formSignalFn.dirty = dirty;
+  formSignalFn.submitting = submittingSignal.asReadonly();
+  formSignalFn.touched = touchedSignal.asReadonly();
+  formSignalFn.errors = errorsSignal.asReadonly();
+  formSignalFn.errorList = errorList;
+  formSignalFn.validate = validateAll;
+  formSignalFn.validateField = validateField;
+  formSignalFn.touch = field => {
+    touchedSignal.update(t => ({
+      ...t,
+      [field]: true
+    }));
+  };
+  formSignalFn.touchAll = () => {
+    touchedSignal.update(t => {
+      const updated = {
+        ...t
+      };
+      for (const key of Object.keys(t)) {
+        updated[key] = true;
+      }
+      return updated;
+    });
+  };
+  formSignalFn.submit = async handler => {
+    submittingSignal.set(true);
+    try {
+      const isValid = await validateAll();
+      if (!isValid) {
+        return null;
+      }
+      const result = await handler(valuesSignal());
+      return result;
+    } finally {
+      submittingSignal.set(false);
+    }
+  };
+  formSignalFn.wizard = wizard;
+  formSignalFn.persistNow = () => {
+    if (persistTimeout) clearTimeout(persistTimeout);
+    saveToStorage();
+  };
+  formSignalFn.reload = () => {
+    loadFromStorage();
+  };
+  formSignalFn.clearStorage = () => {
+    if (config.persist && storage) {
+      storage.removeItem(config.persist);
+    }
+  };
+  return formSignalFn;
+}
+function defaultEquality(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a === 'object') {
+    return JSON.stringify(a) === JSON.stringify(b);
+  }
+  return false;
+}
+const validators = {
+  required: (message = 'This field is required') => value => value === null || value === undefined || value === '' ? message : null,
+  minLength: (min, message) => value => typeof value === 'string' && value.length < min ? message ?? `Must be at least ${min} characters` : null,
+  maxLength: (max, message) => value => typeof value === 'string' && value.length > max ? message ?? `Must be at most ${max} characters` : null,
+  min: (min, message) => value => typeof value === 'number' && value < min ? message ?? `Must be at least ${min}` : null,
+  max: (max, message) => value => typeof value === 'number' && value > max ? message ?? `Must be at most ${max}` : null,
+  email: (message = 'Invalid email address') => value => typeof value === 'string' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) ? message : null,
+  pattern: (regex, message = 'Invalid format') => value => typeof value === 'string' && !regex.test(value) ? message : null,
+  when: (condition, validator) => (value, form) => {
+    if (!form) {
+      return null;
+    }
+    if (condition(form)) {
+      return validator(value);
+    }
+    return null;
+  }
+};
+
+export { FORM_MARKER, createFormSignal, form, isFormMarker, validators };

package/dist/lib/markers/stored.js

@@ -2,6 +2,31 @@ import { signal } from '@angular/core';
 import { registerMarkerProcessor } from '../internals/materialize-markers.js';
 
 const STORED_MARKER = Symbol('STORED_MARKER');
+function isVersionedData(value) {
+  return value !== null && typeof value === 'object' && '__v' in value && typeof value.__v === 'number' && 'data' in value;
+}
+function createStorageKeys(prefix, keys) {
+  const result = {};
+  for (const [key, value] of Object.entries(keys)) {
+    if (typeof value === 'string') {
+      result[key] = `${prefix}:${value}`;
+    } else if (typeof value === 'object' && value !== null) {
+      result[key] = createStorageKeys(`${prefix}:${key}`, value);
+    }
+  }
+  return result;
+}
+function clearStoragePrefix(prefix, storage = typeof localStorage !== 'undefined' ? localStorage : null) {
+  if (!storage) return;
+  const keysToRemove = [];
+  for (let i = 0; i < storage.length; i++) {
+    const key = storage.key(i);
+    if (key && key.startsWith(`${prefix}:`)) {
+      keysToRemove.push(key);
+    }
+  }
+  keysToRemove.forEach(key => storage.removeItem(key));
+}
 let storedRegistered = false;
 function stored(key, defaultValue, options = {}) {
   if (!storedRegistered) {
@@ -25,16 +50,71 @@ function createStoredSignal(marker) {
     options: {
       serialize = JSON.stringify,
       deserialize = JSON.parse,
-      debounceMs = 100
+      debounceMs = 100,
+      version = 1,
+      migrate,
+      clearOnMigrationFailure = false
     }
   } = marker;
   const storage = marker.options.storage !== undefined ? marker.options.storage : typeof localStorage !== 'undefined' ? localStorage : null;
   let initialValue = defaultValue;
   if (storage) {
     try {
-      const storedValue = storage.getItem(key);
-      if (storedValue !== null) {
-        initialValue = deserialize(storedValue);
+      const storedRaw = storage.getItem(key);
+      if (storedRaw !== null) {
+        const parsed = deserialize(storedRaw);
+        if (isVersionedData(parsed)) {
+          const storedVersion = parsed.__v;
+          let data = parsed.data;
+          if (storedVersion !== version && migrate) {
+            try {
+              data = migrate(data, storedVersion);
+              queueMicrotask(() => {
+                try {
+                  const versionedData = {
+                    __v: version,
+                    data
+                  };
+                  storage.setItem(key, serialize(versionedData));
+                } catch {}
+              });
+            } catch (e) {
+              if (typeof ngDevMode === 'undefined' || ngDevMode) {
+                console.warn(`SignalTree: Migration failed for "${key}" from v${storedVersion} to v${version}`, e);
+              }
+              if (clearOnMigrationFailure) {
+                storage.removeItem(key);
+              }
+              data = defaultValue;
+            }
+          }
+          initialValue = data;
+        } else {
+          if (migrate && version > 0) {
+            try {
+              initialValue = migrate(parsed, 0);
+              queueMicrotask(() => {
+                try {
+                  const versionedData = {
+                    __v: version,
+                    data: initialValue
+                  };
+                  storage.setItem(key, serialize(versionedData));
+                } catch {}
+              });
+            } catch (e) {
+              if (typeof ngDevMode === 'undefined' || ngDevMode) {
+                console.warn(`SignalTree: Migration failed for "${key}" from legacy to v${version}`, e);
+              }
+              if (clearOnMigrationFailure) {
+                storage.removeItem(key);
+              }
+              initialValue = defaultValue;
+            }
+          } else {
+            initialValue = parsed;
+          }
+        }
       }
     } catch (e) {
       if (typeof ngDevMode === 'undefined' || ngDevMode) {
@@ -43,14 +123,19 @@ function createStoredSignal(marker) {
     }
   }
   const sig = signal(initialValue);
+  const currentVersion = version;
   let pendingWrite = null;
   let pendingValue;
   const saveToStorage = value => {
     if (!storage) return;
+    const versionedData = {
+      __v: currentVersion,
+      data: value
+    };
     if (debounceMs === 0) {
       queueMicrotask(() => {
         try {
-          storage.setItem(key, serialize(value));
+          storage.setItem(key, serialize(versionedData));
         } catch (e) {
           if (typeof ngDevMode === 'undefined' || ngDevMode) {
             console.warn(`SignalTree: Failed to save "${key}" to storage`, e);
@@ -67,7 +152,11 @@ function createStoredSignal(marker) {
       pendingWrite = null;
       queueMicrotask(() => {
         try {
-          storage.setItem(key, serialize(pendingValue));
+          const finalData = {
+            __v: currentVersion,
+            data: pendingValue
+          };
+          storage.setItem(key, serialize(finalData));
         } catch (e) {
           if (typeof ngDevMode === 'undefined' || ngDevMode) {
             console.warn(`SignalTree: Failed to save "${key}" to storage`, e);
@@ -95,9 +184,14 @@ function createStoredSignal(marker) {
   storedSignal.reload = () => {
     if (!storage) return;
     try {
-      const storedValue = storage.getItem(key);
-      if (storedValue !== null) {
-        sig.set(deserialize(storedValue));
+      const storedRaw = storage.getItem(key);
+      if (storedRaw !== null) {
+        const parsed = deserialize(storedRaw);
+        if (isVersionedData(parsed)) {
+          sig.set(parsed.data);
+        } else {
+          sig.set(parsed);
+        }
       } else {
         sig.set(defaultValue);
       }
@@ -105,7 +199,15 @@ function createStoredSignal(marker) {
       sig.set(defaultValue);
     }
   };
+  Object.defineProperty(storedSignal, 'key', {
+    value: key,
+    writable: false
+  });
+  Object.defineProperty(storedSignal, 'version', {
+    value: currentVersion,
+    writable: false
+  });
   return storedSignal;
 }
 
-export { STORED_MARKER, createStoredSignal, isStoredMarker, stored };
+export { STORED_MARKER, clearStoragePrefix, createStorageKeys, createStoredSignal, isStoredMarker, stored };

package/dist/lib/signal-tree.js

@@ -349,6 +349,7 @@ function createBuilder(baseTree) {
   });
   Object.defineProperty(builder, 'with', {
     value: function (enhancer) {
+      finalize();
       const enhanced = baseTree.with(enhancer);
       const newBuilder = createBuilder(enhanced);
       for (const key of Object.keys(enhanced)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "7.1.6",
+  "version": "7.3.0",
   "description": "Reactive JSON for Angular. JSON branches, reactive leaves. No actions. No reducers. No selectors.",
   "license": "MIT",
   "type": "module",

package/src/index.d.ts

@@ -6,7 +6,8 @@ export { derivedFrom, externalDerived } from './lib/internals/derived-types';
 export type { SignalTreeBuilder } from './lib/internals/builder-types';
 export { isDerivedMarker, type DerivedMarker, type DerivedType, } from './lib/markers/derived';
 export { status, isStatusMarker, LoadingState, type StatusMarker, type StatusSignal, type StatusConfig, } from './lib/markers/status';
-export { stored, isStoredMarker, type StoredMarker, type StoredSignal, type StoredOptions, } from './lib/markers/stored';
+export { stored, isStoredMarker, createStorageKeys, clearStoragePrefix, type StoredMarker, type StoredSignal, type StoredOptions, } from './lib/markers/stored';
+export { form, isFormMarker, createFormSignal, validators, FORM_MARKER, type FormMarker, type FormSignal, type FormConfig, type FormFields, type FormWizard, type WizardConfig, type WizardStepConfig, type Validator, type AsyncValidator, } from './lib/markers/form';
 export { registerMarkerProcessor } from './lib/internals/materialize-markers';
 export { equal, deepEqual, isNodeAccessor, isAnySignal, toWritableSignal, parsePath, composeEnhancers, isBuiltInObject, createLazySignalTree, } from './lib/utils';
 export { createEditSession, type EditSession, type UndoRedoHistory, } from './lib/edit-session';

package/src/lib/markers/entity-map.d.ts

@@ -1,4 +1,19 @@
-import type { EntityConfig, EntityMapMarker } from '../types';
+import { Signal } from '@angular/core';
+import { isEntityMapMarker } from '../utils';
+export { isEntityMapMarker };
+import type { EntityConfig, EntityMapMarker, EntitySignal } from '../types';
+export interface ComputedSliceConfig<E, R> {
+    compute: (entities: E[]) => R;
+}
+export type EntitySignalWithSlices<E, K extends string | number, Slices extends Record<string, unknown>> = EntitySignal<E, K> & {
+    [P in keyof Slices]: Signal<Slices[P]>;
+};
+export interface EntityMapBuilder<E, K extends string | number, Slices extends Record<string, unknown> = Record<string, never>> extends EntityMapMarker<E, K> {
+    __computedSlices?: EntityMapComputedSlices<E>;
+    __sliceTypes?: Slices;
+    computed<N extends string, R>(name: N, compute: (entities: E[]) => R): EntityMapBuilder<E, K, Slices & Record<N, R>>;
+    build(): EntityMapMarkerWithSlices<E, K, Slices>;
+}
 export declare function entityMap<E, K extends string | number = E extends {
     id: infer I extends string | number;
-} ? I : string>(config?: EntityConfig<E, K>): EntityMapMarker<E, K>;
+} ? I : string>(config?: EntityConfig<E, K>): EntityMapBuilder<E, K, Record<string, never>>;

package/src/lib/markers/form.d.ts

@@ -0,0 +1,86 @@
+import { Signal } from '@angular/core';
+export declare const FORM_MARKER: unique symbol;
+export type Validator<T> = (value: T) => string | null;
+export type AsyncValidator<T> = (value: T) => Promise<string | null>;
+export interface WizardStepConfig {
+    fields?: string[];
+    validate?: () => Promise<boolean> | boolean;
+    canSkip?: boolean;
+}
+export interface WizardConfig {
+    steps: string[];
+    stepConfig?: Record<string, WizardStepConfig>;
+    stepFields?: Record<string, string[]>;
+}
+export interface FormConfig<T extends Record<string, unknown>> {
+    initial: T;
+    persist?: string;
+    storage?: Storage | null;
+    persistDebounceMs?: number;
+    validators?: Partial<Record<keyof T, Validator<unknown> | Validator<unknown>[]>>;
+    asyncValidators?: Partial<Record<keyof T, AsyncValidator<unknown>>>;
+    wizard?: WizardConfig;
+    equalityFn?: (a: unknown, b: unknown) => boolean;
+}
+export interface FormMarker<T extends Record<string, unknown>> {
+    [FORM_MARKER]: true;
+    config: FormConfig<T>;
+}
+export interface FormWizard {
+    currentStep: Signal<number>;
+    stepName: Signal<string>;
+    steps: Signal<string[]>;
+    canNext: Signal<boolean>;
+    canPrev: Signal<boolean>;
+    isLastStep: Signal<boolean>;
+    isFirstStep: Signal<boolean>;
+    next(): Promise<boolean>;
+    prev(): void;
+    goTo(step: number | string): Promise<boolean>;
+    reset(): void;
+}
+export type FormFields<T> = {
+    [K in keyof T]: T[K] extends Record<string, unknown> ? FormFields<T[K]> & {
+        (): T[K];
+        set(value: T[K]): void;
+    } : {
+        (): T[K];
+        set(value: T[K]): void;
+        update(fn: (current: T[K]) => T[K]): void;
+    };
+};
+export interface FormSignal<T extends Record<string, unknown>> {
+    $: FormFields<T>;
+    (): T;
+    set(values: Partial<T>): void;
+    patch(values: Partial<T>): void;
+    reset(): void;
+    clear(): void;
+    valid: Signal<boolean>;
+    dirty: Signal<boolean>;
+    submitting: Signal<boolean>;
+    touched: Signal<Record<keyof T, boolean>>;
+    errors: Signal<Partial<Record<keyof T, string | null>>>;
+    errorList: Signal<string[]>;
+    validate(): Promise<boolean>;
+    validateField(field: keyof T): Promise<boolean>;
+    touch(field: keyof T): void;
+    touchAll(): void;
+    submit<R>(handler: (values: T) => Promise<R>): Promise<R | null>;
+    wizard?: FormWizard;
+    persistNow(): void;
+    reload(): void;
+    clearStorage(): void;
+}
+export declare function form<T extends Record<string, unknown>>(config: FormConfig<T>): FormMarker<T>;
+export declare function isFormMarker(value: unknown): value is FormMarker<Record<string, unknown>>;
+export declare const validators: {
+    required: (message?: string) => (value: unknown) => string | null;
+    minLength: (min: number, message?: string) => (value: unknown) => string | null;
+    maxLength: (max: number, message?: string) => (value: unknown) => string | null;
+    min: (min: number, message?: string) => (value: unknown) => string | null;
+    max: (max: number, message?: string) => (value: unknown) => string | null;
+    email: (message?: string) => (value: unknown) => string | null;
+    pattern: (regex: RegExp, message?: string) => (value: unknown) => string | null;
+    when: <T>(condition: (form: T) => boolean, validator: Validator<unknown>) => (value: unknown, form?: T) => string | null;
+};

package/src/lib/markers/index.d.ts

@@ -1,3 +1,4 @@
 export { isDerivedMarker, getDerivedMarkerSymbol, type DerivedMarker, type DerivedType, } from './derived';
 export { status, isStatusMarker, createStatusSignal, LoadingState, STATUS_MARKER, type StatusMarker, type StatusSignal, type StatusConfig, } from './status';
-export { stored, isStoredMarker, createStoredSignal, STORED_MARKER, type StoredMarker, type StoredSignal, type StoredOptions, } from './stored';
+export { stored, isStoredMarker, createStoredSignal, createStorageKeys, clearStoragePrefix, STORED_MARKER, type StoredMarker, type StoredSignal, type StoredOptions, type MigrationFn, } from './stored';
+export { form, isFormMarker, createFormSignal, validators, FORM_MARKER, type FormMarker, type FormSignal, type FormConfig, type FormFields, type FormWizard, type WizardConfig, type WizardStepConfig, type Validator, type AsyncValidator, } from './form';

package/src/lib/markers/stored.d.ts

@@ -1,10 +1,19 @@
 export declare const STORED_MARKER: unique symbol;
+export type MigrationFn<T> = (oldData: unknown, oldVersion: number) => T;
 export interface StoredOptions<T> {
     serialize?: (value: T) => string;
     deserialize?: (stored: string) => T;
     storage?: Storage | null;
     debounceMs?: number;
+    version?: number;
+    migrate?: MigrationFn<T>;
+    clearOnMigrationFailure?: boolean;
 }
+type StorageKeyMap<T, Prefix extends string> = {
+    [K in keyof T]: T[K] extends string ? `${Prefix}:${T[K] & string}` : T[K] extends object ? StorageKeyMap<T[K], `${Prefix}:${K & string}`> : never;
+};
+export declare function createStorageKeys<T extends object, P extends string>(prefix: P, keys: T): StorageKeyMap<T, P>;
+export declare function clearStoragePrefix(prefix: string, storage?: Storage): void;
 export interface StoredMarker<T> {
     [STORED_MARKER]: true;
     key: string;
@@ -17,7 +26,10 @@ export interface StoredSignal<T> {
     update(fn: (current: T) => T): void;
     clear(): void;
     reload(): void;
+    readonly key: string;
+    readonly version: number;
 }
 export declare function stored<T>(key: string, defaultValue: T, options?: StoredOptions<T>): StoredMarker<T>;
 export declare function isStoredMarker(value: unknown): value is StoredMarker<unknown>;
 export declare function createStoredSignal<T>(marker: StoredMarker<T>): StoredSignal<T>;
+export {};

package/src/lib/types.d.ts

@@ -1,4 +1,5 @@
 import { Signal, WritableSignal } from '@angular/core';
+import { FormMarker, FormSignal } from './markers/form';
 import { StatusMarker, StatusSignal } from './markers/status';
 import { StoredMarker, StoredSignal } from './markers/stored';
 import { SecurityValidatorConfig } from './security/security-validator';
@@ -34,7 +35,7 @@ export interface NodeAccessor<T> {
     (updater: (current: T) => T): void;
 }
 export type TreeNode<T> = {
-    [K in keyof T]: T[K] extends EntityMapMarker<infer E, infer Key> ? EntitySignal<E, Key> : T[K] extends StatusMarker<infer Err> ? StatusSignal<Err> : T[K] extends StoredMarker<infer V> ? StoredSignal<V> : T[K] extends Primitive ? CallableWritableSignal<T[K]> : T[K] extends readonly unknown[] ? CallableWritableSignal<T[K]> : T[K] extends Date | RegExp | Map<any, any> | Set<any> | Error | ((...args: unknown[]) => unknown) ? CallableWritableSignal<T[K]> : T[K] extends object ? NodeAccessor<T[K]> & TreeNode<T[K]> : CallableWritableSignal<T[K]>;
+    [K in keyof T]: T[K] extends EntityMapMarker<infer E, infer Key> ? EntitySignal<E, Key> : T[K] extends StatusMarker<infer Err> ? StatusSignal<Err> : T[K] extends StoredMarker<infer V> ? StoredSignal<V> : T[K] extends FormMarker<infer F> ? FormSignal<F> : T[K] extends Primitive ? CallableWritableSignal<T[K]> : T[K] extends readonly unknown[] ? CallableWritableSignal<T[K]> : T[K] extends Date | RegExp | Map<any, any> | Set<any> | Error | ((...args: unknown[]) => unknown) ? CallableWritableSignal<T[K]> : T[K] extends object ? NodeAccessor<T[K]> & TreeNode<T[K]> : CallableWritableSignal<T[K]>;
 };
 export interface ISignalTree<T> extends NodeAccessor<T> {
     readonly state: TreeNode<T>;