ngx-signal-plus 2.7.0 → 2.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![Angular 16-21](https://img.shields.io/badge/Angular-16--21-dd0031)](https://angular.dev/)
 [![npm version](https://img.shields.io/npm/v/ngx-signal-plus.svg)](https://www.npmjs.com/package/ngx-signal-plus)
-![Coverage](https://img.shields.io/badge/coverage-90.92%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-91.04%25-brightgreen)
 
 Bring validation, persistence, undo/redo, and reactive queries to Angular Signals on Angular 16+.
 
@@ -70,7 +70,7 @@ export class CounterComponent {
 - Signal creation: `sp`, `spCounter`, `spToggle`, `spForm`, `spComputed`
 - Signal enhancement: `enhance`
 - Operators: `spMap`, `spFilter`, `spDebounceTime`, `spThrottleTime`, `spDelay`, `spDistinctUntilChanged`
-- Developer experience: `spCombine`, `spAll`, `spAny`, `spEffect`, `spDebug`, `spMonitor`, `sp().debug(label)`
+- Developer experience: `spCombine`, `spAll`, `spAny`, `spEffect`, `spDebug`, `spMonitor`, `sp().debug(label)`, `sp().monitor(options)`
 - Forms and groups: `spForm`, `spFormGroup`
 - Async helpers: `spAsync`, `spCollection`
 - Reactive queries: `spQuery`, `createDependentQuery`, `spInfiniteQuery`, `spMutation`, `QueryClient`, `setGlobalQueryClient`, `getGlobalQueryClient`
@@ -82,6 +82,8 @@ export class CounterComponent {
 
 - `spComputed()` now exposes a read-only surface via `ReadonlySignalPlus<T>`.
 - `SignalPlus<T>` now includes `errors: Signal<string[]>` for consistent validation error access.
+- Builder monitoring is available via `sp().monitor(options)` and records updates through `spMonitor`.
+- Registered middleware now runs in normal `set`/`setValue`/`update` runtime paths for built signals.
 
 ## Comparisons
 
@@ -121,3 +123,5 @@ MIT
 
 
 
+
+

package/fesm2022/ngx-signal-plus.mjs

@@ -323,6 +323,138 @@ const spDebug = {
     },
 };
 
+const metrics = new Map();
+let globalEnabled = true;
+const ensureMetric = (name) => {
+    const existing = metrics.get(name);
+    if (existing) {
+        return existing;
+    }
+    const created = {
+        name,
+        updates: 0,
+        enabled: true,
+        totalDurationMs: 0,
+        averageDurationMs: 0,
+        maxDurationMs: 0,
+        lastDurationMs: 0,
+        lastUpdated: null,
+    };
+    metrics.set(name, created);
+    return created;
+};
+const spMonitor = {
+    trackSignal(name) {
+        ensureMetric(name);
+    },
+    recordUpdate(name, durationMs = 0) {
+        const metric = ensureMetric(name);
+        if (!globalEnabled || !metric.enabled) {
+            return;
+        }
+        metric.updates += 1;
+        metric.lastDurationMs = durationMs;
+        metric.totalDurationMs += durationMs;
+        metric.averageDurationMs = metric.totalDurationMs / metric.updates;
+        metric.maxDurationMs = Math.max(metric.maxDurationMs, durationMs);
+        metric.lastUpdated = Date.now();
+    },
+    enable(name) {
+        ensureMetric(name).enabled = true;
+    },
+    disable(name) {
+        ensureMetric(name).enabled = false;
+    },
+    enableAll() {
+        globalEnabled = true;
+    },
+    disableAll() {
+        globalEnabled = false;
+    },
+    getHotSignals(limit = 10) {
+        return Array.from(metrics.values())
+            .filter((metric) => metric.enabled)
+            .sort((a, b) => b.updates - a.updates)
+            .slice(0, limit)
+            .map((metric) => ({ ...metric }));
+    },
+    getSlowSignals(thresholdMs = 16) {
+        return Array.from(metrics.values())
+            .filter((metric) => metric.enabled && metric.averageDurationMs >= thresholdMs)
+            .sort((a, b) => b.averageDurationMs - a.averageDurationMs)
+            .map((metric) => ({ ...metric }));
+    },
+    exportMetrics(format = 'object') {
+        const exported = Array.from(metrics.values()).map((metric) => ({ ...metric }));
+        return format === 'json' ? JSON.stringify(exported) : exported;
+    },
+    clear() {
+        metrics.clear();
+        globalEnabled = true;
+    },
+};
+
+/**
+ * Middleware system for intercepting signal operations.
+ */
+const middlewareRegistry = [];
+function spUseMiddleware(middleware) {
+    if (!middlewareRegistry.some((m) => m.name === middleware.name)) {
+        middlewareRegistry.push(middleware);
+    }
+}
+function spRemoveMiddleware(name) {
+    const index = middlewareRegistry.findIndex((m) => m.name === name);
+    if (index === -1)
+        return false;
+    middlewareRegistry.splice(index, 1);
+    return true;
+}
+function spClearMiddleware() {
+    middlewareRegistry.length = 0;
+}
+function spGetMiddlewareCount() {
+    return middlewareRegistry.length;
+}
+function spRunMiddleware(context) {
+    for (const m of middlewareRegistry) {
+        try {
+            m.onSet?.(context);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+function spRunMiddlewareError(error, context) {
+    for (const m of middlewareRegistry) {
+        try {
+            m.onError?.(error, context);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+function spLoggerMiddleware(prefix = '[Signal]') {
+    return {
+        name: 'sp-logger',
+        onSet: (ctx) => console.log(`${prefix} ${ctx.signalName || 'signal'}: ${JSON.stringify(ctx.oldValue)} -> ${JSON.stringify(ctx.newValue)}`),
+        onError: (error, ctx) => console.error(`${prefix} Error in ${ctx.signalName || 'signal'}:`, error.message),
+    };
+}
+function spAnalyticsMiddleware(tracker) {
+    return {
+        name: 'sp-analytics',
+        onSet: (ctx) => tracker({
+            name: ctx.signalName || 'unknown',
+            oldValue: ctx.oldValue,
+            newValue: ctx.newValue,
+            timestamp: ctx.timestamp,
+        }),
+    };
+}
+
 /**
  * @fileoverview Builder class for creating enhanced Angular signals
  * Provides a fluent API for configuring signals with features like:
@@ -345,6 +477,7 @@ const spDebug = {
  */
 class SignalBuilder {
     options;
+    static monitorCounter = 0;
     /**
      * Creates a new SignalBuilder instance
      * @param initialValue Initial value for the signal
@@ -448,6 +581,10 @@ class SignalBuilder {
         this.options.debugLabel = label;
         return this;
     }
+    monitor(options = {}) {
+        this.options.monitorOptions = { ...options };
+        return this;
+    }
     /**
      * Transforms signal value to a different type
      * @param fn Transform function from T to R
@@ -479,6 +616,9 @@ class SignalBuilder {
         newBuilder.options.storageKey = this.options.storageKey;
         newBuilder.options.debounceTime = this.options.debounceTime;
         newBuilder.options.autoCleanup = this.options.autoCleanup;
+        newBuilder.options.monitorOptions = this.options.monitorOptions
+            ? { ...this.options.monitorOptions }
+            : undefined;
         return newBuilder;
     }
     /**
@@ -549,6 +689,20 @@ class SignalBuilder {
         const asyncErrorsSignal = signal([], ...(ngDevMode ? [{ debugName: "asyncErrorsSignal" }] : []));
         const enforceHistorySize = (histArray) => this.limitByHistorySize(histArray, this.options.historySize);
         const enforceRedoStackSize = (redoArray) => this.limitByHistorySize(redoArray, this.options.historySize);
+        const monitorOptions = this.options.monitorOptions;
+        const monitorEnabled = Boolean(monitorOptions &&
+            ((monitorOptions.trackUpdates ?? true) || monitorOptions.trackPerformance));
+        const trackPerformance = Boolean(monitorOptions?.trackPerformance);
+        const signalName = monitorOptions?.label ||
+            this.options.debugLabel ||
+            this.options.storageKey ||
+            `signal-${SignalBuilder.monitorCounter++}`;
+        const createMiddlewareContext = (oldValue, newValue) => ({
+            signalName,
+            oldValue,
+            newValue,
+            timestamp: Date.now(),
+        });
         /**
          * Helper function to run async validation with debouncing and cancellation
          * @param value The value to validate
@@ -803,21 +957,20 @@ class SignalBuilder {
                 }
                 // Only update if value has changed
                 if (hasChanged) {
-                    previousValue = conditionalClone(writable());
+                    const oldValue = conditionalClone(writable());
+                    spRunMiddleware(createMiddlewareContext(oldValue, conditionalClone(transformedValue)));
+                    const monitorStart = monitorEnabled && trackPerformance ? performance.now() : 0;
+                    previousValue = oldValue;
                     writable.set(transformedValue);
-                    // Update history if enabled and value has changed
                     if (this.options.enableHistory && !isProcessingDebounce) {
-                        // Clear redo stack when new value is set
                         redoStack = [];
                         const currentHistory = history();
                         const newHistory = [
                             ...currentHistory,
                             conditionalClone(transformedValue),
                         ];
-                        // Enforce history size limit using helper function
                         history.set(enforceHistorySize(newHistory));
                     }
-                    // Handle storage
                     if (this.options.storageKey && isBrowser()) {
                         try {
                             isProcessingStorage = true;
@@ -835,7 +988,10 @@ class SignalBuilder {
                             isProcessingStorage = false;
                         }
                     }
-                    // Only notify subscribers if not cleaned up
+                    if (monitorEnabled) {
+                        const duration = trackPerformance ? performance.now() - monitorStart : 0;
+                        spMonitor.recordUpdate(signalName, duration);
+                    }
                     if (!isCleanedUp) {
                         notifySubscribers(transformedValue);
                     }
@@ -851,6 +1007,9 @@ class SignalBuilder {
         if (this.options.debugLabel) {
             spDebug.trackSignal(this.options.debugLabel, writable());
         }
+        if (monitorEnabled) {
+            spMonitor.trackSignal(signalName);
+        }
         const processValue = (value) => {
             // Prevent setValue after destroy
             if (isCleanedUp) {
@@ -896,6 +1055,7 @@ class SignalBuilder {
                 }
             }
             catch (error) {
+                spRunMiddlewareError(error, createMiddlewareContext(conditionalClone(writable()), conditionalClone(value)));
                 this.handleError(error);
                 throw error;
             }
@@ -915,14 +1075,16 @@ class SignalBuilder {
             set: processValue,
             setValue: processValue,
             update: (fn) => {
+                let newValue;
                 try {
-                    const newValue = fn(writable());
-                    processValue(newValue);
+                    newValue = fn(writable());
                 }
                 catch (error) {
+                    spRunMiddlewareError(error, createMiddlewareContext(conditionalClone(writable()), conditionalClone(writable())));
                     this.handleError(error);
                     throw error;
                 }
+                processValue(newValue);
             },
             reset: () => {
                 try {
@@ -4180,77 +4342,6 @@ function spComputed(fn, options = {}) {
     };
 }
 
-const metrics = new Map();
-let globalEnabled = true;
-const ensureMetric = (name) => {
-    const existing = metrics.get(name);
-    if (existing) {
-        return existing;
-    }
-    const created = {
-        name,
-        updates: 0,
-        enabled: true,
-        totalDurationMs: 0,
-        averageDurationMs: 0,
-        maxDurationMs: 0,
-        lastDurationMs: 0,
-        lastUpdated: null,
-    };
-    metrics.set(name, created);
-    return created;
-};
-const spMonitor = {
-    trackSignal(name) {
-        ensureMetric(name);
-    },
-    recordUpdate(name, durationMs = 0) {
-        const metric = ensureMetric(name);
-        if (!globalEnabled || !metric.enabled) {
-            return;
-        }
-        metric.updates += 1;
-        metric.lastDurationMs = durationMs;
-        metric.totalDurationMs += durationMs;
-        metric.averageDurationMs = metric.totalDurationMs / metric.updates;
-        metric.maxDurationMs = Math.max(metric.maxDurationMs, durationMs);
-        metric.lastUpdated = Date.now();
-    },
-    enable(name) {
-        ensureMetric(name).enabled = true;
-    },
-    disable(name) {
-        ensureMetric(name).enabled = false;
-    },
-    enableAll() {
-        globalEnabled = true;
-    },
-    disableAll() {
-        globalEnabled = false;
-    },
-    getHotSignals(limit = 10) {
-        return Array.from(metrics.values())
-            .filter((metric) => metric.enabled)
-            .sort((a, b) => b.updates - a.updates)
-            .slice(0, limit)
-            .map((metric) => ({ ...metric }));
-    },
-    getSlowSignals(thresholdMs = 16) {
-        return Array.from(metrics.values())
-            .filter((metric) => metric.enabled && metric.averageDurationMs >= thresholdMs)
-            .sort((a, b) => b.averageDurationMs - a.averageDurationMs)
-            .map((metric) => ({ ...metric }));
-    },
-    exportMetrics(format = 'object') {
-        const exported = Array.from(metrics.values()).map((metric) => ({ ...metric }));
-        return format === 'json' ? JSON.stringify(exported) : exported;
-    },
-    clear() {
-        metrics.clear();
-        globalEnabled = true;
-    },
-};
-
 function spEffect(callback, options = {}) {
     const paused = signal(false, ...(ngDevMode ? [{ debugName: "paused" }] : []));
     let timeoutId = null;
@@ -4627,67 +4718,6 @@ function spFormGroup(config, options) {
     };
 }
 
-/**
- * Middleware system for intercepting signal operations.
- */
-const middlewareRegistry = [];
-function spUseMiddleware(middleware) {
-    if (!middlewareRegistry.some((m) => m.name === middleware.name)) {
-        middlewareRegistry.push(middleware);
-    }
-}
-function spRemoveMiddleware(name) {
-    const index = middlewareRegistry.findIndex((m) => m.name === name);
-    if (index === -1)
-        return false;
-    middlewareRegistry.splice(index, 1);
-    return true;
-}
-function spClearMiddleware() {
-    middlewareRegistry.length = 0;
-}
-function spGetMiddlewareCount() {
-    return middlewareRegistry.length;
-}
-function spRunMiddleware(context) {
-    for (const m of middlewareRegistry) {
-        try {
-            m.onSet?.(context);
-        }
-        catch {
-            /* ignore */
-        }
-    }
-}
-function spRunMiddlewareError(error, context) {
-    for (const m of middlewareRegistry) {
-        try {
-            m.onError?.(error, context);
-        }
-        catch {
-            /* ignore */
-        }
-    }
-}
-function spLoggerMiddleware(prefix = '[Signal]') {
-    return {
-        name: 'sp-logger',
-        onSet: (ctx) => console.log(`${prefix} ${ctx.signalName || 'signal'}: ${JSON.stringify(ctx.oldValue)} -> ${JSON.stringify(ctx.newValue)}`),
-        onError: (error, ctx) => console.error(`${prefix} Error in ${ctx.signalName || 'signal'}:`, error.message),
-    };
-}
-function spAnalyticsMiddleware(tracker) {
-    return {
-        name: 'sp-analytics',
-        onSet: (ctx) => tracker({
-            name: ctx.signalName || 'unknown',
-            oldValue: ctx.oldValue,
-            newValue: ctx.newValue,
-            timestamp: ctx.timestamp,
-        }),
-    };
-}
-
 function extractErrorMessages(error) {
     if (!error) {
         return [];