@signaltree/core 1.0.3 → 1.1.1

package/index.d.ts

@@ -1,71 +1,73 @@
-import { WritableSignal, Signal } from '@angular/core';
+import { Signal, WritableSignal } from '@angular/core';
 
 /**
- * @fileoverview Core types for SignalTree modular architecture
+ * SignalTree Core Types - Recursive Typing System
  *
- * Contains only the essential types needed for the basic signalTree functionality.
- * This keeps the core package minimal (~5KB) while other features are added via composition.
+ * COPYRIGHT NOTICE:
+ * This file contains proprietary recursive typing innovations protected under
+ * the SignalTree license. The DeepSignalify<T> recursive type system and
+ * related implementations are exclusive intellectual property of Jonathan D Borgia.
+ *
+ * Unauthorized extraction, copying, or reimplementation of these recursive typing
+ * concepts is strictly prohibited and constitutes copyright infringement.
+ *
+ * Licensed under Fair Source License - see LICENSE file for complete terms.
+ */
+
+/**
+ * NO MORE StateObject constraint!
+ * We don't need this at all - remove it or make it accept anything
+ */
+/**
+ * Primitive types for type checking
  */
-declare const __treeId: unique symbol;
-type TreeId = string & {
-    readonly [__treeId]: never;
-};
 type Primitive = string | number | boolean | null | undefined | bigint | symbol;
-type SerializableValue = unknown;
-type StateObject = Record<string | number | symbol, unknown>;
+/**
+ * Built-in object types that should be treated as primitive values
+ * Enhanced detection for better edge case handling
+ */
+type BuiltInObject = Date | RegExp | ((...args: unknown[]) => unknown) | Map<unknown, unknown> | Set<unknown> | WeakMap<object, unknown> | WeakSet<object> | ArrayBuffer | DataView | Error | Promise<unknown> | URL | URLSearchParams | FormData | Blob | File;
 type IsPrimitive<T> = T extends Primitive ? true : false;
-type DeepSignalify<T> = IsPrimitive<T> extends true ? WritableSignal<T> : T extends (infer U)[] ? WritableSignal<U[]> : T extends Record<string, unknown> ? T extends Signal<infer TSignal> ? WritableSignal<TSignal> : {
-    [K in keyof T]: DeepSignalify<T[K]>;
-} : WritableSignal<T>;
-type UnwrapSignalState<T> = T extends WritableSignal<infer U> ? U : T extends Record<string, unknown> ? {
-    [K in keyof T]: UnwrapSignalState<T[K]>;
-} : T;
+type IsBuiltInObject<T> = T extends BuiltInObject ? true : false;
 /**
- * Main signal tree type that preserves hierarchical structure
+ * Signal detection
  */
-type SignalState<T extends StateObject> = DeepSignalify<T>;
+type IsSignal<T> = T extends Signal<unknown> ? true : false;
+type IsWritableSignal<T> = T extends WritableSignal<unknown> ? true : false;
 /**
- * Core SignalTree interface with only essential functionality.
- * Additional features are added via composition using the .pipe() method.
+ * Enhanced DeepSignalify with better edge case handling
+ * Never double-wraps signals and properly handles functions and built-in objects
  */
-interface SignalTree<T extends StateObject> {
+type DeepSignalify<T> = IsSignal<T> extends true ? T : T extends Primitive ? WritableSignal<T> : T extends BuiltInObject ? WritableSignal<T> : T extends readonly (infer U)[] ? WritableSignal<U[]> : T extends (infer U)[] ? WritableSignal<U[]> : T extends object ? T extends (...args: unknown[]) => unknown ? WritableSignal<T> : {
+    [K in keyof T]: T[K] extends (infer U)[] ? WritableSignal<U[]> : T[K] extends BuiltInObject ? WritableSignal<T[K]> : T[K] extends object ? T[K] extends Signal<infer TK> ? WritableSignal<TK> : DeepSignalify<T[K]> : WritableSignal<T[K]>;
+} : WritableSignal<T>;
+/**
+ * SignalTree type - NO CONSTRAINTS on T
+ */
+type SignalTree<T> = {
     /**
-     * The reactive state object with deep signal conversion.
+     * The reactive state object with deep signal conversion
      */
-    state: SignalState<T>;
+    state: DeepSignalify<T>;
     /**
-     * Shorthand alias for `state`.
+     * Shorthand alias for state
      */
-    $: SignalState<T>;
+    $: DeepSignalify<T>;
     /**
-     * Extracts the current plain object value from the signal tree.
+     * Core methods
      */
     unwrap(): T;
-    /**
-     * Updates the tree state using a partial update function.
-     */
     update(updater: (current: T) => Partial<T>): void;
-    /**
-     * Creates a side effect that runs when the tree state changes.
-     */
     effect(fn: (tree: T) => void): void;
-    /**
-     * Subscribes to tree state changes with manual unsubscribe control.
-     */
     subscribe(fn: (tree: T) => void): () => void;
-    /**
-     * Completely destroys the tree and cleans up all resources.
-     */
     destroy(): void;
     /**
-     * Fluent API for composing features using function composition with strong typing
+     * Pipe method for composition
      */
     pipe(): SignalTree<T>;
     pipe<R1>(fn1: (tree: SignalTree<T>) => R1): R1;
     pipe<R1, R2>(fn1: (tree: SignalTree<T>) => R1, fn2: (arg: R1) => R2): R2;
     pipe<R1, R2, R3>(fn1: (tree: SignalTree<T>) => R1, fn2: (arg: R1) => R2, fn3: (arg: R2) => R3): R3;
-    pipe<R1, R2, R3, R4>(fn1: (tree: SignalTree<T>) => R1, fn2: (arg: R1) => R2, fn3: (arg: R2) => R3, fn4: (arg: R3) => R4): R4;
-    pipe<R1, R2, R3, R4, R5>(fn1: (tree: SignalTree<T>) => R1, fn2: (arg: R1) => R2, fn3: (arg: R2) => R3, fn4: (arg: R3) => R4, fn5: (arg: R4) => R5): R5;
     batchUpdate(updater: (current: T) => Partial<T>): void;
     memoize<R>(fn: (tree: T) => R, cacheKey?: string): Signal<R>;
     optimize(): void;
@@ -82,7 +84,7 @@ interface SignalTree<T extends StateObject> {
     redo(): void;
     getHistory(): TimeTravelEntry<T>[];
     resetHistory(): void;
-}
+};
 type TreePreset = 'basic' | 'performance' | 'development' | 'production';
 interface TreeConfig {
     batchUpdates?: boolean;
@@ -143,20 +145,45 @@ interface TimeTravelEntry<T> {
     payload: unknown;
 }
 
+/**
+ * SignalTree Core Implementation - Recursive Typing Engine
+ *
+ * COPYRIGHT NOTICE:
+ * This file contains the proprietary recursive typing implementation protected
+ * under the SignalTree license. The signal-store pattern, recursive type-runtime
+ * alignment, and "initiation defines structure" paradigm are exclusive intellectual
+ * property of Jonathan D Borgia.
+ *
+ * The createSignalStore and createLazySignalTree functions implement patented
+ * approaches to recursive type preservation that are strictly protected.
+ *
+ * Licensed under Fair Source License - see LICENSE file for complete terms.
+ */
+
 /**
  * Creates a reactive signal tree with smart progressive enhancement.
  *
+ * MAXIMUM FLEXIBILITY: Accepts ANY type T - no StateObject constraint!
+ * This is the key difference from constrained approaches.
+ *
  * Features auto-enable on first use. Uses intelligent defaults based on
- * environment (development vs production). No confusing warnings or
- * fake implementations - everything just works!
+ * environment (development vs production). Enhanced with safety features
+ * to prevent common issues like signal double-wrapping.
  *
- * @template T - The state object type, must extend Record<string, unknown>
+ * @template T - ANY type (no constraints for maximum flexibility)
  * @param obj - The initial state object to convert into a reactive tree
  * @returns A SignalTree with auto-enabling features
  *
  * @example
  * ```typescript
- * const tree = signalTree({ count: 0, users: [] });
+ * // Works with ANY object - no constraints!
+ * const tree = signalTree({
+ *   count: 0,
+ *   users: [],
+ *   metadata: new Map(),  // Non-plain objects work!
+ *   fn: () => 'hello',    // Functions work!
+ *   symbol: Symbol('id')  // Symbols work!
+ * });
  *
  * // Core functionality always works
  * tree.state.count.set(5);
@@ -170,7 +197,7 @@ interface TimeTravelEntry<T> {
  * );
  * ```
  */
-declare function signalTree<T extends StateObject>(obj: T): SignalTree<T>;
+declare function signalTree<T>(obj: T): SignalTree<T>;
 /**
  * Creates a reactive signal tree with preset configuration.
  *
@@ -194,22 +221,26 @@ declare function signalTree<T extends StateObject>(obj: T): SignalTree<T>;
  * const perfTree = signalTree(state, 'performance');
  * ```
  */
-declare function signalTree<T extends StateObject>(obj: T, preset: TreePreset): SignalTree<T>;
+declare function signalTree<T>(obj: T, preset: TreePreset): SignalTree<T>;
 /**
  * Creates a reactive signal tree with custom configuration.
  *
  * Provides full control over feature enablement while maintaining
- * auto-enabling behavior for unspecified features.
+ * auto-enabling behavior for unspecified features. Enhanced with safety features.
  *
- * @template T - The state object type, must extend Record<string, unknown>
+ * @template T - ANY type (no constraints for maximum flexibility)
  * @param obj - The initial state object to convert into a reactive tree
  * @param config - Custom configuration object
  * @returns A SignalTree configured with custom options
  *
  * @example
  * ```typescript
- * // Custom configuration
- * const customTree = signalTree(state, {
+ * // Custom configuration - works with ANY object!
+ * const customTree = signalTree({
+ *   data: state,
+ *   metadata: new Map(),  // Any object type
+ *   fn: () => 'custom'    // Even functions
+ * }, {
  *   batchUpdates: true,
  *   useMemoization: true,
  *   maxCacheSize: 500,
@@ -217,12 +248,37 @@ declare function signalTree<T extends StateObject>(obj: T, preset: TreePreset):
  * });
  * ```
  */
-declare function signalTree<T extends StateObject>(obj: T, config: TreeConfig): SignalTree<T>;
+declare function signalTree<T>(obj: T, config: TreeConfig): SignalTree<T>;
+/**
+ * Implementation of the signalTree factory function.
+ */
+/**
+ * Main SignalTree factory function with superior type inference
+ *
+ * Key improvements from signal-store.ts approach:
+ * 1. Uses Required<T> for better type inference when possible
+ * 2. Maintains complete type information through recursion
+ * 3. Proper handling of nested objects and arrays
+ * 4. No type constraints - maximum flexibility
+ */
+declare function signalTree<T extends Record<string, unknown>>(obj: Required<T>, configOrPreset?: TreeConfig | TreePreset): SignalTree<Required<T>>;
+declare function signalTree<T>(obj: T, configOrPreset?: TreeConfig | TreePreset): SignalTree<T>;
+
+/**
+ * SignalTree Utility Functions - Recursive Typing Implementation
+ *
+ * COPYRIGHT NOTICE:
+ * This file contains proprietary utility functions for the recursive typing system.
+ * The createLazySignalTree function and built-in object detection methods are
+ * protected intellectual property of Jonathan D Borgia.
+ *
+ * Licensed under Fair Source License - see LICENSE file for complete terms.
+ */
 
 /**
  * Enhanced equality function inspired by the monolithic implementation.
  * Uses deep equality for arrays and objects, === for primitives.
- * More efficient than lodash while maintaining compatibility.
+ * Optimized with early exits and type-specific comparisons.
  */
 declare function equal<T>(a: T, b: T): boolean;
 /**
@@ -234,8 +290,9 @@ declare function equal<T>(a: T, b: T): boolean;
  */
 declare function terminalSignal<T>(value: T, customEqual?: (a: T, b: T) => boolean): WritableSignal<T>;
 /**
- * Parses a dot-notation path into an array of keys with memoization.
+ * Parses a dot-notation path into an array of keys with LRU memoization.
  * Critical for performance when accessing nested properties frequently.
+ * Includes proper LRU cache management to prevent memory leaks.
  *
  * @example
  * ```typescript
@@ -248,13 +305,14 @@ declare function parsePath(path: string): string[];
  * Creates a lazy signal tree using Proxy for on-demand signal creation.
  * Only creates signals when properties are first accessed, providing
  * massive memory savings for large state objects.
+ * Uses WeakMap for memory-safe caching.
  *
  * @param obj - Source object to lazily signalify
  * @param equalityFn - Equality function for signal comparison
  * @param basePath - Base path for nested objects (internal use)
  * @returns Proxied object that creates signals on first access
  */
-declare function createLazySignalTree<T extends Record<string, unknown>>(obj: T, equalityFn: (a: unknown, b: unknown) => boolean, basePath?: string): DeepSignalify<T>;
+declare function createLazySignalTree<T extends object>(obj: T, equalityFn: (a: unknown, b: unknown) => boolean, basePath?: string): DeepSignalify<T>;
 /**
  * Native deep equality check for arrays and objects.
  * Handles all common cases that lodash.isEqual handles for our use cases.
@@ -266,4 +324,4 @@ declare function deepEqual<T>(a: T, b: T): boolean;
 declare function shallowEqual<T>(a: T, b: T): boolean;
 
 export { createLazySignalTree, deepEqual, equal, parsePath, shallowEqual, signalTree, terminalSignal };
-export type { AsyncAction, AsyncActionConfig, DeepSignalify, EntityHelpers, Middleware, PerformanceMetrics, SerializableValue, SignalState, SignalTree, StateObject, TimeTravelEntry, TreeConfig, TreeId, TreePreset, UnwrapSignalState };
+export type { AsyncAction, AsyncActionConfig, BuiltInObject, DeepSignalify, EntityHelpers, IsBuiltInObject, IsPrimitive, IsSignal, IsWritableSignal, Middleware, PerformanceMetrics, Primitive, SignalTree, TimeTravelEntry, TreeConfig, TreePreset };

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@signaltree/core",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "description": "Lightweight, type-safe signal-based state management for Angular. Core package providing hierarchical signal trees, basic entity management, and async actions.",
   "peerDependencies": {
-    "@angular/common": "^20.1.0",
     "@angular/core": "^20.1.0"
   },
   "sideEffects": false,