@signaltree/ng-forms 7.3.4 → 7.6.1

package/README.md

@@ -142,12 +142,6 @@ pnpm add @signaltree/core @signaltree/ng-forms
 import { Component } from '@angular/core';
 import { createFormTree, required, email } from '@signaltree/ng-forms';
 
-interface ProfileForm extends Record<string, unknown> {
-  name: string;
-  email: string;
-  marketing: boolean;
-}
-
 @Component({
   selector: 'app-profile-form',
   template: `
@@ -175,7 +169,8 @@ interface ProfileForm extends Record<string, unknown> {
 export class ProfileFormComponent {
   private storage = typeof window !== 'undefined' ? window.localStorage : undefined;
 
-  profile = createFormTree<ProfileForm>(
+  // Type is inferred from initial values - no interface needed!
+  profile = createFormTree(
     {
       name: '',
       email: '',
@@ -196,7 +191,7 @@ export class ProfileFormComponent {
 
   async save() {
     await this.profile.submit(async (values) => {
-      // Persist values to your API or service layer here
+      // values is typed as { name: string; email: string; marketing: boolean }
       console.log('Saving profile', values);
     });
   }
@@ -205,11 +200,64 @@ export class ProfileFormComponent {
 
 The returned `FormTree` exposes:
 
-- `form`: Angular `FormGroup` for templates and directives
+- `form`: Angular `TypedFormGroup<T>` for templates and directives (fully typed!)
 - `$` / `state`: signal-backed access to individual fields
 - `errors`, `asyncErrors`, `valid`, `dirty`, `submitting`: writable signals for UI state
 - Helpers such as `setValue`, `setValues`, `reset`, `validate`, and `submit`
 
+## Type Inference
+
+`createFormTree()` leverages recursive type inference—types flow from initial values:
+
+```typescript
+// ✅ Simple case: types inferred automatically
+const form = createFormTree({
+  name: '',           // string
+  age: 0,             // number
+  active: false,      // boolean
+});
+
+form.$.name();        // string
+form.$.age();         // number
+form.form.controls.name;  // FormControl<string>
+```
+
+### Union Types Need Assertions
+
+When a field can be one of several specific values, TypeScript widens the inferred type to `string`. Use inline type assertions to preserve narrowness:
+
+```typescript
+// ❌ Without assertion: resolution is inferred as string
+const form = createFormTree({
+  resolution: 'PENDING',  // Inferred as string, not the union
+});
+
+// ✅ With assertion: resolution is the exact union type
+const form = createFormTree({
+  resolution: 'PENDING' as 'PENDING' | 'APPROVED' | 'REJECTED',
+  category: null as CategoryType | null,
+  items: [] as string[],
+});
+```
+
+### TypedFormGroup
+
+The `form` property returns `TypedFormGroup<T>`, which recursively maps your form shape to Angular controls:
+
+```typescript
+type TypedFormGroup<T> = FormGroup<{
+  [K in keyof T]: T[K] extends unknown[]
+    ? FormArray<FormControl<T[K][number]>>
+    : T[K] extends object
+      ? FormGroup<...>  // Nested objects become nested FormGroups
+      : FormControl<T[K]>
+}>;
+
+// Result: full autocomplete and type checking
+const form = createFormTree({ user: { name: '', email: '' } });
+form.form.controls.user.controls.name.value;  // string
+```
+
 ## Core capabilities
 
 - **Signal-synced forms**: Bidirectional sync between Angular FormControls and SignalTree signals

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/ng-forms",
-  "version": "7.3.4",
+  "version": "7.6.1",
   "description": "Angular forms as reactive JSON. Seamless SignalTree integration with FormTree creation, validators, and form state tracking.",
   "license": "MIT",
   "type": "module",

package/dist/audit/audit.js

@@ -1,74 +0,0 @@
-import { getChanges } from '../get-changes.js';
-
-function createAuditTracker(tree, auditLog, config = {}) {
-  const {
-    getMetadata,
-    includePreviousValues = false,
-    filter,
-    maxEntries = 0
-  } = config;
-  let previousState = structuredClone(tree());
-  let isTracking = true;
-  const handleChange = () => {
-    if (!isTracking) return;
-    const currentState = tree();
-    const changes = getChanges(previousState, currentState);
-    if (Object.keys(changes).length > 0) {
-      if (filter && !filter(changes)) {
-        previousState = structuredClone(currentState);
-        return;
-      }
-      const entry = {
-        timestamp: Date.now(),
-        changes,
-        metadata: getMetadata?.()
-      };
-      if (includePreviousValues) {
-        const prevValues = {};
-        for (const key of Object.keys(changes)) {
-          prevValues[key] = previousState[key];
-        }
-        entry.previousValues = prevValues;
-      }
-      auditLog.push(entry);
-      if (maxEntries > 0 && auditLog.length > maxEntries) {
-        auditLog.splice(0, auditLog.length - maxEntries);
-      }
-    }
-    previousState = structuredClone(currentState);
-  };
-  let unsubscribe;
-  let pollingId;
-  if ('subscribe' in tree && typeof tree.subscribe === 'function') {
-    try {
-      unsubscribe = tree.subscribe(handleChange);
-    } catch {
-      pollingId = setInterval(handleChange, 100);
-    }
-  } else {
-    pollingId = setInterval(handleChange, 100);
-  }
-  return () => {
-    isTracking = false;
-    if (unsubscribe) {
-      unsubscribe();
-    }
-    if (pollingId) {
-      clearInterval(pollingId);
-    }
-  };
-}
-function createAuditCallback(auditLog, getMetadata) {
-  return (previousState, currentState) => {
-    const changes = getChanges(previousState, currentState);
-    if (Object.keys(changes).length > 0) {
-      auditLog.push({
-        timestamp: Date.now(),
-        changes,
-        metadata: getMetadata?.()
-      });
-    }
-  };
-}
-
-export { createAuditCallback, createAuditTracker };

package/dist/audit/index.js

@@ -1 +0,0 @@
-export { createAuditCallback, createAuditTracker } from './audit.js';

package/dist/constants.js

@@ -1,6 +0,0 @@
-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/core/async-validators.js

@@ -1,24 +0,0 @@
-import { isObservable, firstValueFrom } from 'rxjs';
-
-function unique(checkFn, message = 'Already exists') {
-  return async value => {
-    if (!value) return null;
-    const exists = await checkFn(value);
-    return exists ? message : null;
-  };
-}
-function debounce(validator, delayMs) {
-  let timeoutId;
-  return async value => {
-    return new Promise(resolve => {
-      clearTimeout(timeoutId);
-      timeoutId = setTimeout(async () => {
-        const maybeAsync = validator(value);
-        const result = isObservable(maybeAsync) ? await firstValueFrom(maybeAsync) : await maybeAsync;
-        resolve(result);
-      }, delayMs);
-    });
-  };
-}
-
-export { debounce, unique };