@signaltree/core 7.0.1 → 7.1.1

package/README.md

@@ -36,6 +36,26 @@ import { batching } from '@signaltree/core/enhancers/batching';
 - Core + batching: ~9.3 KB gzipped (barrel vs subpath: identical)
 - Unused enhancers: **automatically excluded** by tree-shaking
 
+### Marker Tree-Shaking (Self-Registering)
+
+Built-in markers (`entityMap()`, `status()`, `stored()`) are **self-registering** - they only add their processor code when you actually use them:
+
+```ts
+// ✅ Only status() code is bundled (entityMap and stored tree-shaken out)
+import { signalTree, status } from '@signaltree/core';
+const tree = signalTree({ loadState: status() });
+
+// ✅ Minimal bundle - no marker code included
+import { signalTree } from '@signaltree/core';
+const tree = signalTree({ count: 0 });
+```
+
+**How it works:**
+
+- Each marker factory (`status()`, `stored()`, `entityMap()`) registers its processor on first call
+- If you never call a marker factory, its code is completely eliminated
+- Zero import-time side effects - registration is lazy and automatic
+
 **When to use subpath imports:**
 
 - Older bundlers (webpack <5) with poor tree-shaking
@@ -796,6 +816,87 @@ tree.update((state) => ({
 }));
 ```
 
+### 7) Extensibility: Custom Markers & Enhancers
+
+SignalTree is designed for extensibility. Create your own **markers** (state placeholders that materialize into specialized signals) and **enhancers** (functions that augment trees with additional capabilities).
+
+#### Custom Marker Example
+
+```typescript
+import { signal, Signal } from '@angular/core';
+import { registerMarkerProcessor, signalTree } from '@signaltree/core';
+
+// 1. Define marker symbol and interface
+const VALIDATED_MARKER = Symbol('VALIDATED_MARKER');
+
+interface ValidatedMarker<T> {
+  [VALIDATED_MARKER]: true;
+  defaultValue: T;
+  validator: (value: T) => string | null;
+}
+
+// 2. Create marker factory
+function validated<T>(defaultValue: T, validator: (value: T) => string | null): ValidatedMarker<T> {
+  return { [VALIDATED_MARKER]: true, defaultValue, validator };
+}
+
+// 3. Type guard
+function isValidatedMarker(value: unknown): value is ValidatedMarker<unknown> {
+  return Boolean(value && typeof value === 'object' && (value as any)[VALIDATED_MARKER] === true);
+}
+
+// 4. Register materializer (call once at app startup)
+registerMarkerProcessor(isValidatedMarker, (marker) => {
+  const valueSignal = signal(marker.defaultValue);
+  const errorSignal = signal<string | null>(marker.validator(marker.defaultValue));
+  return {
+    get: () => valueSignal(),
+    set: (v: any) => {
+      valueSignal.set(v);
+      errorSignal.set(marker.validator(v));
+    },
+    error: errorSignal.asReadonly(),
+    isValid: () => errorSignal() === null,
+  };
+});
+
+// 5. Usage
+const tree = signalTree({
+  email: validated('', (v) => (v.includes('@') ? null : 'Invalid email')),
+});
+```
+
+#### Custom Enhancer Example
+
+```typescript
+import { signal, Signal } from '@angular/core';
+import type { ISignalTree } from '@signaltree/core';
+
+interface WithLogger {
+  log(message: string): void;
+  history: Signal<string[]>;
+}
+
+function withLogger(config?: { maxHistory?: number }) {
+  const maxHistory = config?.maxHistory ?? 100;
+  return <T>(tree: ISignalTree<T>): ISignalTree<T> & WithLogger => {
+    const historySignal = signal<string[]>([]);
+    return Object.assign(tree, {
+      log: (msg: string) => historySignal.update((h) => [...h, `[${new Date().toLocaleTimeString()}] ${msg}`].slice(-maxHistory)),
+      history: historySignal.asReadonly(),
+    });
+  };
+}
+
+// Usage
+const tree = signalTree({ count: 0 }).with(withLogger());
+tree.log('Tree created');
+```
+
+> 📖 **Full guide**: [Custom Markers & Enhancers](https://github.com/JBorgia/signaltree/blob/main/docs/custom-markers-enhancers.md)
+>
+> 📱 **Interactive demo**: [Demo App](/custom-extensions)
+
 ## Error handling examples
 
 ### Manual async error handling

package/dist/index.js

@@ -1,5 +1,5 @@
 export { signalTree } from './lib/signal-tree.js';
-export { ENHANCER_META, entityMap } from './lib/types.js';
+export { ENHANCER_META } from './lib/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';
@@ -18,6 +18,7 @@ export { devTools, enableDevTools, fullDevTools, productionDevTools } from './en
 export { createAsyncOperation, trackAsync } from './lib/async-helpers.js';
 export { TREE_PRESETS, combinePresets, createPresetConfig, getAvailablePresets, validatePreset } from './enhancers/presets/lib/presets.js';
 export { SIGNAL_TREE_CONSTANTS, SIGNAL_TREE_MESSAGES } from './lib/constants.js';
+export { entityMap } from './lib/markers/entity-map.js';
 export { deepEqual, deepEqual as equal } from './deep-equal.js';
 export { parsePath } from './parse-path.js';
 export { isBuiltInObject } from './is-built-in-object.js';

package/dist/lib/internals/materialize-markers.js

@@ -1,26 +1,32 @@
 import { isSignal } from '@angular/core';
-import { createEntitySignal } from '../entity-signal.js';
-import { createStatusSignal, isStatusMarker } from '../markers/status.js';
-import { createStoredSignal, isStoredMarker } from '../markers/stored.js';
 import { getPathNotifier } from '../path-notifier.js';
 import { isNodeAccessor } from '../utils.js';
 
-function isEntityMapMarker(value) {
-  return Boolean(value && typeof value === 'object' && value['__isEntityMap'] === true);
-}
 const MARKER_PROCESSORS = [];
+function isRegisteredMarker(value) {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  if (Object.getOwnPropertySymbols(value).length === 0) {
+    return false;
+  }
+  for (const processor of MARKER_PROCESSORS) {
+    if (processor.check(value)) {
+      return true;
+    }
+  }
+  return false;
+}
 function registerMarkerProcessor(check, create) {
+  const alreadyRegistered = MARKER_PROCESSORS.some(p => p.check === check);
+  if (alreadyRegistered) {
+    return;
+  }
   MARKER_PROCESSORS.push({
     check,
     create: create
   });
 }
-registerMarkerProcessor(isEntityMapMarker, (marker, notifier, path) => {
-  const cfg = marker.__entityMapConfig ?? {};
-  return createEntitySignal(cfg, notifier, path);
-});
-registerMarkerProcessor(isStatusMarker, marker => createStatusSignal(marker));
-registerMarkerProcessor(isStoredMarker, marker => createStoredSignal(marker));
 function materializeMarkers(node, notifier, path = []) {
   if (node == null) return;
   if (typeof node !== 'object' && typeof node !== 'function') return;
@@ -63,4 +69,4 @@ function materializeMarkers(node, notifier, path = []) {
   }
 }
 
-export { materializeMarkers, registerMarkerProcessor };
+export { isRegisteredMarker, materializeMarkers, registerMarkerProcessor };

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

@@ -0,0 +1,20 @@
+import { createEntitySignal } from '../entity-signal.js';
+import { registerMarkerProcessor } from '../internals/materialize-markers.js';
+import { isEntityMapMarker } from '../utils.js';
+
+let entityMapRegistered = false;
+function entityMap(config) {
+  if (!entityMapRegistered) {
+    entityMapRegistered = true;
+    registerMarkerProcessor(isEntityMapMarker, (marker, notifier, path) => {
+      const cfg = marker.__entityMapConfig ?? {};
+      return createEntitySignal(cfg, notifier, path);
+    });
+  }
+  return {
+    __isEntityMap: true,
+    __entityMapConfig: config ?? {}
+  };
+}
+
+export { entityMap };

package/dist/lib/markers/status.js

@@ -1,4 +1,5 @@
 import { signal, computed } from '@angular/core';
+import { registerMarkerProcessor } from '../internals/materialize-markers.js';
 
 const STATUS_MARKER = Symbol('STATUS_MARKER');
 var LoadingState;
@@ -8,7 +9,12 @@ var LoadingState;
   LoadingState["Loaded"] = "LOADED";
   LoadingState["Error"] = "ERROR";
 })(LoadingState || (LoadingState = {}));
+let statusRegistered = false;
 function status(initialState = LoadingState.NotLoaded) {
+  if (!statusRegistered) {
+    statusRegistered = true;
+    registerMarkerProcessor(isStatusMarker, createStatusSignal);
+  }
   return {
     [STATUS_MARKER]: true,
     initialState

package/dist/lib/markers/stored.js

@@ -1,7 +1,13 @@
 import { signal } from '@angular/core';
+import { registerMarkerProcessor } from '../internals/materialize-markers.js';
 
 const STORED_MARKER = Symbol('STORED_MARKER');
+let storedRegistered = false;
 function stored(key, defaultValue, options = {}) {
+  if (!storedRegistered) {
+    storedRegistered = true;
+    registerMarkerProcessor(isStoredMarker, createStoredSignal);
+  }
   return {
     [STORED_MARKER]: true,
     key,

package/dist/lib/signal-tree.js

@@ -1,7 +1,7 @@
 import { signal, isSignal } from '@angular/core';
 import { SIGNAL_TREE_MESSAGES, SIGNAL_TREE_CONSTANTS } from './constants.js';
 import { batchScope } from './internals/batch-scope.js';
-import { materializeMarkers } from './internals/materialize-markers.js';
+import { isRegisteredMarker, materializeMarkers } from './internals/materialize-markers.js';
 import { applyDerivedFactories } from './internals/merge-derived.js';
 import { isStatusMarker } from './markers/status.js';
 import { isStoredMarker } from './markers/stored.js';
@@ -160,6 +160,15 @@ function createSignalStore(obj, equalityFn) {
       store[key] = value;
       continue;
     }
+    if (isRegisteredMarker(value)) {
+      store[key] = value;
+      continue;
+    }
+    if (typeof ngDevMode === 'undefined' || ngDevMode) {
+      if (value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getOwnPropertySymbols(value).length > 0) {
+        console.warn(`SignalTree: Object at "${key}" has Symbol keys but doesn't match any ` + `registered marker processor. If this is a custom marker, ensure ` + `registerMarkerProcessor() is called BEFORE creating the tree.`);
+      }
+    }
     if (isSignal(value)) {
       store[key] = value;
       continue;

package/dist/lib/types.js

@@ -1,9 +1,3 @@
-function entityMap(config) {
-  return {
-    __isEntityMap: true,
-    __entityMapConfig: config ?? {}
-  };
-}
 const ENHANCER_META = Symbol('signaltree:enhancer:meta');
 
-export { ENHANCER_META, entityMap };
+export { ENHANCER_META };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signaltree/core",
-  "version": "7.0.1",
+  "version": "7.1.1",
   "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,
@@ -13,51 +13,7 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./enhancers": {
-      "types": "./src/enhancers/index.d.ts",
-      "import": "./dist/enhancers/index.js",
-      "default": "./dist/enhancers/index.js"
-    },
-    "./enhancers/batching": {
-      "types": "./src/enhancers/batching/index.d.ts",
-      "import": "./dist/enhancers/batching/index.js",
-      "default": "./dist/enhancers/batching/index.js"
-    },
-    "./enhancers/middleware": {
-      "types": "./src/enhancers/middleware/index.d.ts",
-      "import": "./dist/enhancers/middleware/index.js",
-      "default": "./dist/enhancers/middleware/index.js"
-    },
-    "./enhancers/memoization": {
-      "types": "./src/enhancers/memoization/index.d.ts",
-      "import": "./dist/enhancers/memoization/index.js",
-      "default": "./dist/enhancers/memoization/index.js"
-    },
-    "./enhancers/time-travel": {
-      "types": "./src/enhancers/time-travel/index.d.ts",
-      "import": "./dist/enhancers/time-travel/index.js",
-      "default": "./dist/enhancers/time-travel/index.js"
-    },
-    "./enhancers/devtools": {
-      "types": "./src/enhancers/devtools/index.d.ts",
-      "import": "./dist/enhancers/devtools/index.js",
-      "default": "./dist/enhancers/devtools/index.js"
-    },
-    "./enhancers/presets": {
-      "types": "./src/enhancers/presets/index.d.ts",
-      "import": "./dist/enhancers/presets/index.js",
-      "default": "./dist/enhancers/presets/index.js"
-    },
-    "./enhancers/entities": {
-      "types": "./src/enhancers/entities/index.d.ts",
-      "import": "./dist/enhancers/entities/index.js",
-      "default": "./dist/enhancers/entities/index.js"
-    },
-    "./enhancers/serialization": {
-      "types": "./src/enhancers/serialization/index.d.ts",
-      "import": "./dist/enhancers/serialization/index.js",
-      "default": "./dist/enhancers/serialization/index.js"
-    }
+    "./package.json": "./package.json"
   },
   "peerDependencies": {
     "@angular/core": "^20.0.0",
@@ -89,4 +45,4 @@
     "src/**/*.d.ts",
     "README.md"
   ]
-}
+}

package/src/lib/internals/materialize-markers.d.ts

@@ -1,4 +1,5 @@
 import { PathNotifier } from '../path-notifier';
+export declare function isRegisteredMarker(value: unknown): boolean;
 export declare function registerMarkerProcessor<T, R>(check: (value: unknown) => value is T, create: (marker: T, notifier: PathNotifier, path: string) => R): void;
 export declare function materializeMarkers(node: unknown, notifier?: PathNotifier, path?: string[]): void;
 export declare function hasMarkers(node: unknown, visited?: WeakSet<object>): boolean;

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

@@ -0,0 +1,4 @@
+import type { EntityConfig, EntityMapMarker } from '../types';
+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>;

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

@@ -9,13 +9,14 @@ export declare enum LoadingState {
 export interface StatusConfig {
     initialState?: LoadingState;
 }
-export interface StatusMarker {
+export interface StatusMarker<E = Error> {
     [STATUS_MARKER]: true;
     initialState: LoadingState;
+    readonly __errorType?: E;
 }
-export interface StatusSignal {
+export interface StatusSignal<E = Error> {
     state: WritableSignal<LoadingState>;
-    error: WritableSignal<Error | null>;
+    error: WritableSignal<E | null>;
     isNotLoaded: Signal<boolean>;
     isLoading: Signal<boolean>;
     isLoaded: Signal<boolean>;
@@ -23,9 +24,9 @@ export interface StatusSignal {
     setNotLoaded(): void;
     setLoading(): void;
     setLoaded(): void;
-    setError(error: Error): void;
+    setError(error: E): void;
     reset(): void;
 }
-export declare function status(initialState?: LoadingState): StatusMarker;
+export declare function status<E = Error>(initialState?: LoadingState): StatusMarker<E>;
 export declare function isStatusMarker(value: unknown): value is StatusMarker;
-export declare function createStatusSignal(marker: StatusMarker): StatusSignal;
+export declare function createStatusSignal<E = Error>(marker: StatusMarker<E>): StatusSignal<E>;

package/src/lib/types.d.ts

@@ -34,7 +34,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 ? StatusSignal : 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 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>;
@@ -153,9 +153,7 @@ export interface EntityMapMarker<E, K extends string | number> {
     readonly __isEntityMap: true;
     readonly __entityMapConfig?: EntityConfig<E, K>;
 }
-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>;
+export { entityMap } from './markers/entity-map';
 export interface MutationOptions {
     onError?: (error: Error) => void;
 }
@@ -300,4 +298,3 @@ export type MinimalSignalTree<T> = ISignalTree<T> & EffectsMethods<T>;
 export type SignalTree<T> = ISignalTree<T> & TreeNode<T>;
 export type SignalTreeBase<T> = ISignalTree<T> & TreeNode<T>;
 export declare function isSignalTree<T>(value: unknown): value is ISignalTree<T>;
-export {};

package/src/lib/utils.d.ts

@@ -1,4 +1,5 @@
 import { WritableSignal } from '@angular/core';
+import { deepEqual, isBuiltInObject, parsePath } from '@signaltree/shared';
 export { deepEqual };
 export { deepEqual as equal };
 export { isBuiltInObject };
@@ -10,22 +11,6 @@ export interface MemoryManager {
     dispose(): void;
 }
 import type { NodeAccessor, TreeNode } from './types';
-
-// Inlined from @signaltree/shared (internal package)
-declare function deepEqual<T>(a: T, b: T): boolean;
-declare function deepClone<T>(obj: T): T;
-declare function isBuiltInObject(value: unknown): boolean;
-declare function parsePath(path: string): string[];
-declare class LRUCache<K, V> {
-  constructor(maxSize: number);
-  get(key: K): V | undefined;
-  set(key: K, value: V): void;
-  has(key: K): boolean;
-  delete(key: K): boolean;
-  clear(): void;
-  get size(): number;
-}
-declare const DEFAULT_PATH_CACHE_SIZE: number;
 export declare function isNodeAccessor(value: unknown): value is NodeAccessor<unknown>;
 export declare function isAnySignal(value: unknown): boolean;
 export declare function toWritableSignal<T>(node: NodeAccessor<T>, injector?: unknown): WritableSignal<T>;

package/LICENSE

@@ -1,54 +0,0 @@
-BUSINESS SOURCE LICENSE 1.1
-
-Copyright (c) 2025 Jonathan D Borgia
-
-This Business Source License 1.1 ("License") governs the use of the software and associated documentation files (the "Software"). You are granted a limited license to use the Software under the terms of this License.
-
-1. Definitions
-
-"Change Date" means the date on which the Change License set out in section 6 will apply to the Software. The Change Date for this release is 2028-09-05.
-
-"Change License" means the open source license that will apply to the Software on and after the Change Date. The Change License for this release is the MIT License.
-
-"Licensor" means the copyright owner granting rights under this License (Jonathan D Borgia).
-
-"You" ("Licensee") means an individual or legal entity exercising rights under this License who has not violated the terms of this License or had their rights terminated.
-
-2. License Grant
-
-Subject to the terms and conditions of this License, Licensor hereby grants You a non-exclusive, non-transferable, worldwide license to use, reproduce, display, perform, and distribute the Software, and to make modifications and derivative works for internal use, until the Change Date.
-
-3. Commercial Use
-
-You may use the Software in commercial applications, including for providing services, selling products that include the Software, or otherwise exploiting the Software commercially, subject to the other terms of this License.
-
-4. Limitations and Conditions
-
-a. You may not remove or alter this License, the copyright notice, or notices of the Change Date.
-
-b. You may not publicly offer a modified version of the Software that would directly compete with Licensor's public offering of the Software if doing so would circumvent the intent of this License.
-
-c. Except as expressly provided in this License, no rights are granted to You under any patent or trademark of Licensor.
-
-5. Disclaimer and Limitation of Liability
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. TO THE FULLEST EXTENT PERMITTED BY LAW, LICENSOR WILL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM OR RELATING TO THE SOFTWARE.
-
-6. Change License
-
-On and after the Change Date specified above, the Software will be licensed under the Change License (MIT License) on the same terms and conditions as set forth by that Change License.
-
-7. Governing Law
-
-This License will be governed by and construed in accordance with the laws of the State of New York, USA, without regard to conflict of law principles.
-
-8. Accepting this License
-
-You accept this License by copying, modifying, or distributing the Software or any portion thereof.
-
----
-
-LICENSE NOTE
-
-- Original license file replaced on 2025-09-05 to Business Source License 1.1. Change Date: 2028-09-05. Change License: MIT.
-  or standard modifications for your own applications.