@signaltree/core 4.1.7 → 4.2.0

package/README.md

@@ -594,11 +594,18 @@ const tree = signalTree({
   withTimeTravel() // Undo/redo support
 );
 
-// Advanced async operations
-const fetchUser = tree.asyncAction(async (id: string) => api.getUser(id), {
-  loadingKey: 'loading',
-  onSuccess: (user) => ({ user }),
-});
+// For async operations, use manual async or middleware 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
@@ -859,12 +866,47 @@ users.add(newUser);
 users.selectBy((u) => u.active);
 users.updateMany([{ id: '1', changes: { status: 'active' } }]);
 
-// Powerful async actions
-const fetchUsers = tree.asyncAction(async () => api.getUsers(), {
-  loadingKey: 'ui.loading',
-  errorKey: 'ui.error',
-  onSuccess: (users) => ({ users }),
+// Entity helpers support nested paths for organized state structures
+// Example: deeply nested entities in a domain-driven design pattern
+const appTree = signalTree({
+  app: {
+    data: {
+      users: [] as User[],
+      products: [] as Product[],
+    },
+  },
+  admin: {
+    data: {
+      logs: [] as AuditLog[],
+      reports: [] as Report[],
+    },
+  },
 });
+
+// Access deeply nested entities using dot notation
+const appUsers = appTree.entities<User>('app.data.users');
+const appProducts = appTree.entities<Product>('app.data.products');
+const adminLogs = appTree.entities<AuditLog>('admin.data.logs');
+const adminReports = appTree.entities<Report>('admin.data.reports');
+
+// All entity methods work seamlessly with nested paths
+appUsers.selectBy((u) => u.isAdmin); // Filtered signal
+appProducts.selectTotal(); // Count signal
+adminLogs.selectAll(); // All items signal
+adminReports.selectIds(); // ID array signal
+
+// For async operations, use manual async or middleware helpers
+async function fetchUsers() {
+  tree.$.ui.loading.set(true);
+  try {
+    const users = await api.getUsers();
+    tree.$.users.set(users);
+  } catch (error) {
+    tree.$.ui.error.set(error.message);
+  } finally {
+    tree.$.ui.loading.set(false);
+  }
+}
 ```
 
 ### Full-Featured Development Composition
@@ -901,7 +943,9 @@ const tree = signalTree({
 
 // Rich feature set available
 const users = tree.entities<User>('app.data.users');
-const fetchUser = tree.asyncAction(api.getUser);
+async function fetchUser(id: string) {
+  return await api.getUser(id);
+}
 tree.undo(); // Time travel
 tree.save(); // Persistence
 ```
@@ -1272,7 +1316,7 @@ tree.destroy(); // Cleanup resources
 
 // Extended features (built into @signaltree/core)
 tree.entities<T>(key); // Entity helpers (use withEntities enhancer)
-tree.asyncAction(fn, config?); // Async operations (use createAsyncOperation helper)
+// For async operations, use manual async or middleware helpers like createAsyncOperation or trackAsync
 ```
 
 ## Extending with enhancers
@@ -1355,10 +1399,18 @@ async loadUsers() {
   }
 }
 
-// Or use middleware helpers for async actions (createAsyncOperation / trackAsync)
-loadUsers = tree.asyncAction(() => api.getUsers(), {
-  onSuccess: (users) => ({ users }),
-});
+// Or use manual async patterns
+loadUsers = async () => {
+  tree.$.loading.set(true);
+  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);
+  }
+};
 ```
 
 ## Examples

package/dist/enhancers/entities/lib/entities.js

@@ -1,21 +1,45 @@
 import { computed } from '@angular/core';
 import { isAnySignal, isNodeAccessor } from '../../../lib/utils.js';
 
+function resolveNestedSignal(tree, path) {
+  const pathStr = String(path);
+  if (!pathStr.includes('.')) {
+    const signal = tree.state[pathStr];
+    if (!signal) {
+      throw new Error(`Entity key '${pathStr}' does not exist in the state. Available top-level keys: ${Object.keys(tree.state).join(', ')}`);
+    }
+    return signal;
+  }
+  const segments = pathStr.split('.');
+  let current = tree.state;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (isAnySignal(current)) {
+      current = current();
+    }
+    current = current[segment];
+    if (current === undefined) {
+      const attemptedPath = segments.slice(0, i + 1).join('.');
+      throw new Error(`Entity path '${pathStr}' is invalid: '${attemptedPath}' does not exist in the state`);
+    }
+  }
+  if (isAnySignal(current)) {
+    return current;
+  }
+  throw new Error(`Entity path '${pathStr}' does not resolve to a signal. Ensure all parent levels in the path are valid nested objects.`);
+}
 function createEntityHelpers(tree, entityKey) {
   const getEntitySignal = () => {
-    const stateProperty = tree.state[entityKey];
-    if (!stateProperty) {
-      throw new Error(`Entity key '${String(entityKey)}' does not exist in the state`);
-    }
-    if (!isAnySignal(stateProperty)) {
+    const signal = resolveNestedSignal(tree, entityKey);
+    if (!isAnySignal(signal)) {
       throw new Error(`Entity key '${String(entityKey)}' is not a signal. This should not happen with SignalTree.`);
     }
-    const signal = stateProperty;
-    const value = signal();
+    const castSignal = signal;
+    const value = castSignal();
     if (!Array.isArray(value)) {
       throw new Error(`Entity key '${String(entityKey)}' does not contain an array. Current type: ${typeof value}`);
     }
-    return signal;
+    return castSignal;
   };
   const setSignalValue = (signal, value) => {
     if (isNodeAccessor(signal)) {

package/dist/lib/constants.js

@@ -27,7 +27,6 @@ const DEV_MESSAGES = {
   MEMOIZE_NOT_ENABLED: 'memoize disabled',
   MIDDLEWARE_NOT_AVAILABLE: 'middleware missing',
   ENTITY_HELPERS_NOT_AVAILABLE: 'entity helpers missing',
-  ASYNC_ACTIONS_NOT_AVAILABLE: 'async actions missing',
   TIME_TRAVEL_NOT_AVAILABLE: 'time travel missing',
   OPTIMIZE_NOT_AVAILABLE: 'optimize missing',
   UPDATE_OPTIMIZED_NOT_AVAILABLE: 'update optimized missing',

package/dist/lib/signal-tree.js

@@ -464,12 +464,6 @@ function addStubMethods(tree, config) {
     }
     return {};
   };
-  tree.asyncAction = (operation, asyncConfig = {}) => {
-    if (config.debugMode) {
-      console.warn(SIGNAL_TREE_MESSAGES.ASYNC_ACTIONS_NOT_AVAILABLE);
-    }
-    return {};
-  };
   tree.undo = () => {
     if (config.debugMode) {
       console.warn(SIGNAL_TREE_MESSAGES.TIME_TRAVEL_NOT_AVAILABLE);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "4.1.7",
+  "version": "4.2.0",
   "description": "Lightweight, type-safe signal-based state management for Angular. Core package providing hierarchical signal trees, basic entity management, and async actions.",
   "type": "module",
   "sideEffects": false,

package/src/index.d.ts

@@ -1,5 +1,5 @@
 export { signalTree } from './lib/signal-tree';
-export type { SignalTree, TreeNode, RemoveSignalMethods, Primitive, BuiltInObject, NotFn, TreeConfig, TreePreset, Enhancer, EnhancerMeta, EnhancerWithMeta, ChainResult, WithMethod, Middleware, PerformanceMetrics, EntityHelpers, AsyncActionConfig, AsyncAction, TimeTravelEntry, } from './lib/types';
+export type { SignalTree, TreeNode, RemoveSignalMethods, Primitive, BuiltInObject, NotFn, DeepPath, DeepAccess, TreeConfig, TreePreset, Enhancer, EnhancerMeta, EnhancerWithMeta, ChainResult, WithMethod, Middleware, PerformanceMetrics, EntityHelpers, TimeTravelEntry, } from './lib/types';
 export { equal, deepEqual, isNodeAccessor, isAnySignal, toWritableSignal, parsePath, composeEnhancers, isBuiltInObject, createLazySignalTree, } from './lib/utils';
 export { SecurityValidator, SecurityPresets, type SecurityEvent, type SecurityEventType, type SecurityValidatorConfig, } from './lib/security/security-validator';
 export { createEnhancer, resolveEnhancerOrder } from './enhancers/index';

package/src/lib/constants.d.ts

@@ -25,7 +25,6 @@ export declare const SIGNAL_TREE_MESSAGES: Readonly<{
     readonly MEMOIZE_NOT_ENABLED: "memoize disabled";
     readonly MIDDLEWARE_NOT_AVAILABLE: "middleware missing";
     readonly ENTITY_HELPERS_NOT_AVAILABLE: "entity helpers missing";
-    readonly ASYNC_ACTIONS_NOT_AVAILABLE: "async actions missing";
     readonly TIME_TRAVEL_NOT_AVAILABLE: "time travel missing";
     readonly OPTIMIZE_NOT_AVAILABLE: "optimize missing";
     readonly UPDATE_OPTIMIZED_NOT_AVAILABLE: "update optimized missing";

package/src/lib/types.d.ts

@@ -26,6 +26,10 @@ export type TreeNode<T> = {
     [K in keyof T]: T[K] extends readonly unknown[] ? CallableWritableSignal<T[K]> : T[K] extends object ? T[K] extends Signal<unknown> ? T[K] : T[K] extends BuiltInObject ? CallableWritableSignal<T[K]> : T[K] extends (...args: unknown[]) => unknown ? CallableWritableSignal<T[K]> : AccessibleNode<T[K]> : CallableWritableSignal<T[K]>;
 };
 export type RemoveSignalMethods<T> = T extends infer U ? U : never;
+export type DeepPath<T, Prefix extends string = '', Depth extends readonly number[] = []> = Depth['length'] extends 5 ? never : {
+    [K in keyof T]: K extends string ? T[K] extends readonly unknown[] ? `${Prefix}${K}` : T[K] extends object ? T[K] extends Signal<unknown> ? never : T[K] extends BuiltInObject ? never : T[K] extends (...args: unknown[]) => unknown ? never : `${Prefix}${K}` | DeepPath<T[K], `${Prefix}${K}.`, [...Depth, 1]> : never : never;
+}[keyof T];
+export type DeepAccess<T, Path extends string> = Path extends `${infer First}.${infer Rest}` ? First extends keyof T ? DeepAccess<T[First] & object, Rest> : never : Path extends keyof T ? T[Path] : never;
 export interface EnhancerMeta {
     name?: string;
     requires?: string[];
@@ -91,7 +95,6 @@ export type SignalTree<T> = NodeAccessor<T> & {
     entities<E extends {
         id: string | number;
     }>(entityKey?: keyof T): EntityHelpers<E>;
-    asyncAction<TInput, TResult>(operation: (input: TInput) => Promise<TResult>, config?: AsyncActionConfig<T, TResult>): AsyncAction<TInput, TResult>;
     undo(): void;
     redo(): void;
     getHistory(): TimeTravelEntry<T>[];
@@ -143,18 +146,6 @@ export interface EntityHelpers<E extends {
     selectTotal(): Signal<number>;
     clear(): void;
 }
-export interface AsyncActionConfig<T, TResult> {
-    onStart?: (state: T) => Partial<T>;
-    onSuccess?: (result: TResult, state: T) => Partial<T>;
-    onError?: (error: Error, state: T) => Partial<T>;
-    onComplete?: (state: T) => Partial<T>;
-}
-export interface AsyncAction<TInput, TResult> {
-    execute(input: TInput): Promise<TResult>;
-    pending: Signal<boolean>;
-    error: Signal<Error | null>;
-    result: Signal<TResult | null>;
-}
 export interface TimeTravelEntry<T> {
     action: string;
     timestamp: number;