@signaltree/core 7.1.0 → 7.1.2

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,7 +1,8 @@
 {
   "name": "@signaltree/core",
-  "version": "7.1.0",
+  "version": "7.1.2",
   "description": "Lightweight, type-safe signal-based state management for Angular. Core package providing hierarchical signal trees, basic entity management, and async actions.",
+  "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -13,51 +14,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",

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/types.d.ts

@@ -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 {};