@signaltree/core 7.1.5 → 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/constants.js

@@ -0,0 +1,6 @@
+const SHARED_DEFAULTS = Object.freeze({
+  PATH_CACHE_SIZE: 1000
+});
+const DEFAULT_PATH_CACHE_SIZE = SHARED_DEFAULTS.PATH_CACHE_SIZE;
+
+export { DEFAULT_PATH_CACHE_SIZE, SHARED_DEFAULTS };

package/dist/deep-equal.js

@@ -0,0 +1,41 @@
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a == null || b == null) return a === b;
+  const typeA = typeof a;
+  const typeB = typeof b;
+  if (typeA !== typeB) return false;
+  if (typeA !== 'object') return false;
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() === b.getTime();
+  }
+  if (a instanceof RegExp && b instanceof RegExp) {
+    return a.source === b.source && a.flags === b.flags;
+  }
+  if (a instanceof Map && b instanceof Map) {
+    if (a.size !== b.size) return false;
+    for (const [key, value] of a) {
+      if (!b.has(key) || !deepEqual(value, b.get(key))) return false;
+    }
+    return true;
+  }
+  if (a instanceof Set && b instanceof Set) {
+    if (a.size !== b.size) return false;
+    for (const value of a) {
+      if (!b.has(value)) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+  if (Array.isArray(b)) return false;
+  const objA = a;
+  const objB = b;
+  const keysA = Object.keys(objA);
+  const keysB = Object.keys(objB);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every(key => key in objB && deepEqual(objA[key], objB[key]));
+}
+
+export { deepEqual };

package/dist/enhancers/batching/batching.js

@@ -0,0 +1,230 @@
+import { copyTreeProperties } from '../utils/copy-tree-properties.js';
+
+function batching(config = {}) {
+  const enabled = config.enabled ?? true;
+  const notificationDelayMs = config.notificationDelayMs ?? 0;
+  return tree => {
+    if (!enabled) {
+      const passthrough = {
+        batch: fn => fn(),
+        coalesce: fn => fn(),
+        hasPendingNotifications: () => false,
+        flushNotifications: () => {}
+      };
+      const enhanced = tree;
+      Object.assign(enhanced, passthrough);
+      enhanced.batchUpdate = updater => {
+        if (typeof tree.batchUpdate === 'function') {
+          tree.batchUpdate(updater);
+        } else {
+          updater(tree());
+        }
+      };
+      return enhanced;
+    }
+    let notificationPending = false;
+    let notificationTimeoutId;
+    let inBatch = false;
+    let inCoalesce = false;
+    const coalescedUpdates = new Map();
+    const scheduleNotification = () => {
+      if (notificationPending) return;
+      notificationPending = true;
+      if (notificationDelayMs > 0) {
+        notificationTimeoutId = setTimeout(flushNotificationsInternal, notificationDelayMs);
+      } else {
+        queueMicrotask(flushNotificationsInternal);
+      }
+    };
+    const flushNotificationsInternal = () => {
+      if (!notificationPending) return;
+      notificationPending = false;
+      if (notificationTimeoutId !== undefined) {
+        clearTimeout(notificationTimeoutId);
+        notificationTimeoutId = undefined;
+      }
+      if (tree.__notifyChangeDetection) {
+        tree.__notifyChangeDetection();
+      }
+    };
+    const flushCoalescedUpdates = () => {
+      const updates = Array.from(coalescedUpdates.values());
+      coalescedUpdates.clear();
+      updates.forEach(fn => {
+        try {
+          fn();
+        } catch (e) {
+          console.error('[SignalTree] Error in coalesced update:', e);
+        }
+      });
+    };
+    const wrapSignalSetters = (node, path = '') => {
+      if (!node || typeof node !== 'object') return;
+      if (typeof node.set === 'function' && !node.__batchingWrapped) {
+        const originalSet = node.set.bind(node);
+        node.set = value => {
+          if (inCoalesce) {
+            coalescedUpdates.set(path, () => originalSet(value));
+          } else {
+            originalSet(value);
+          }
+          if (!inBatch) {
+            scheduleNotification();
+          }
+        };
+        node.__batchingWrapped = true;
+      }
+      if (typeof node.update === 'function' && !node.__batchingUpdateWrapped) {
+        const originalUpdate = node.update.bind(node);
+        node.update = updater => {
+          if (inCoalesce) {
+            coalescedUpdates.set(`${path}:update:${Date.now()}`, () => originalUpdate(updater));
+          } else {
+            originalUpdate(updater);
+          }
+          if (!inBatch) {
+            scheduleNotification();
+          }
+        };
+        node.__batchingUpdateWrapped = true;
+      }
+      for (const key of Object.keys(node)) {
+        if (key.startsWith('_') || key === 'set' || key === 'update') continue;
+        const child = node[key];
+        if (child && typeof child === 'object') {
+          wrapSignalSetters(child, path ? `${path}.${key}` : key);
+        }
+      }
+    };
+    if (tree.$) {
+      wrapSignalSetters(tree.$);
+    }
+    const batchingMethods = {
+      batch(fn) {
+        const wasBatching = inBatch;
+        inBatch = true;
+        try {
+          fn();
+        } finally {
+          inBatch = wasBatching;
+          if (!inBatch) {
+            scheduleNotification();
+          }
+        }
+      },
+      coalesce(fn) {
+        const wasCoalescing = inCoalesce;
+        const wasBatching = inBatch;
+        inCoalesce = true;
+        inBatch = true;
+        try {
+          fn();
+        } finally {
+          inCoalesce = wasCoalescing;
+          inBatch = wasBatching;
+          if (!wasCoalescing) {
+            flushCoalescedUpdates();
+          }
+          if (!inBatch) {
+            scheduleNotification();
+          }
+        }
+      },
+      hasPendingNotifications() {
+        return notificationPending;
+      },
+      flushNotifications() {
+        flushNotificationsInternal();
+      }
+    };
+    const originalTreeCall = tree.bind(tree);
+    const enhancedTree = function (...args) {
+      if (args.length === 0) {
+        return originalTreeCall();
+      } else {
+        if (args.length === 1) {
+          const arg = args[0];
+          if (typeof arg === 'function') {
+            originalTreeCall(arg);
+          } else {
+            originalTreeCall(arg);
+          }
+        }
+        if (!inBatch) {
+          scheduleNotification();
+        }
+      }
+    };
+    Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
+    Object.assign(enhancedTree, tree);
+    try {
+      copyTreeProperties(tree, enhancedTree);
+    } catch {}
+    Object.defineProperty(enhancedTree, 'with', {
+      value: function (enhancer) {
+        if (typeof enhancer !== 'function') {
+          throw new Error('Enhancer must be a function');
+        }
+        return enhancer(enhancedTree);
+      },
+      writable: false,
+      enumerable: false,
+      configurable: true
+    });
+    if ('state' in tree) {
+      Object.defineProperty(enhancedTree, 'state', {
+        value: tree.state,
+        enumerable: false,
+        configurable: true
+      });
+    }
+    if ('$' in tree) {
+      Object.defineProperty(enhancedTree, '$', {
+        value: tree.$,
+        enumerable: false,
+        configurable: true
+      });
+    }
+    Object.assign(enhancedTree, batchingMethods);
+    enhancedTree.batchUpdate = updater => {
+      enhancedTree.batch(() => {
+        const current = originalTreeCall();
+        const updates = updater(current);
+        Object.entries(updates).forEach(([key, value]) => {
+          const property = enhancedTree.state[key];
+          if (property && typeof property.set === 'function') {
+            property.set(value);
+          } else if (typeof property === 'function') {
+            property(value);
+          }
+        });
+      });
+    };
+    return enhancedTree;
+  };
+}
+function highPerformanceBatching() {
+  return batching({
+    enabled: true,
+    notificationDelayMs: 0
+  });
+}
+function batchingWithConfig(config = {}) {
+  return batching(config);
+}
+function flushBatchedUpdates() {
+  console.warn('[SignalTree] flushBatchedUpdates() is deprecated. Use tree.flushNotifications() instead.');
+}
+function hasPendingUpdates() {
+  console.warn('[SignalTree] hasPendingUpdates() is deprecated. Use tree.hasPendingNotifications() instead.');
+  return false;
+}
+function getBatchQueueSize() {
+  console.warn('[SignalTree] getBatchQueueSize() is deprecated. Signal writes are now synchronous.');
+  return 0;
+}
+Object.assign((config = {}) => batching(config), {
+  highPerformance: highPerformanceBatching
+});
+
+export { batching, batchingWithConfig, flushBatchedUpdates, getBatchQueueSize, hasPendingUpdates, highPerformanceBatching };