ngx-signal-plus 2.6.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.44%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,10 +70,10 @@ 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`, `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`, `spMutation`, `QueryClient`, `setGlobalQueryClient`
+- Reactive queries: `spQuery`, `createDependentQuery`, `spInfiniteQuery`, `spMutation`, `QueryClient`, `setGlobalQueryClient`, `getGlobalQueryClient`
 - Transactions: `spTransaction`, `spBatch`
 - Schema validation: `spSchema`, `spSchemaValidator`
 - Middleware: `spUseMiddleware`, `spRemoveMiddleware`, `spLoggerMiddleware`, `spAnalyticsMiddleware`
@@ -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
 
@@ -118,3 +120,8 @@ export class CounterComponent {
 ## License
 
 MIT
+
+
+
+
+

package/fesm2022/ngx-signal-plus.mjs

@@ -264,7 +264,7 @@ function safeAddEventListener(event, handler) {
 }
 
 const states = new Map();
-let globalEnabled = true;
+let globalEnabled$1 = true;
 const ensureState = (name) => {
     const existing = states.get(name);
     if (existing) {
@@ -291,7 +291,7 @@ const spDebug = {
     recordUpdate(name, value) {
         const state = ensureState(name);
         state.lastValue = value;
-        if (!globalEnabled || !state.enabled) {
+        if (!globalEnabled$1 || !state.enabled) {
             return;
         }
         state.updates += 1;
@@ -304,10 +304,10 @@ const spDebug = {
         ensureState(name).enabled = false;
     },
     enableAll() {
-        globalEnabled = true;
+        globalEnabled$1 = true;
     },
     disableAll() {
-        globalEnabled = false;
+        globalEnabled$1 = false;
     },
     getActiveSignals() {
         return Array.from(states.values())
@@ -319,10 +319,142 @@ const spDebug = {
     },
     clear() {
         states.clear();
+        globalEnabled$1 = true;
+    },
+};
+
+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 {
@@ -4556,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 [];
@@ -5739,6 +5840,7 @@ function spMutation(options) {
     catch {
         // Not in injection context - cleanup will be manual via reset()
     }
+    const queryClient = getGlobalQueryClient();
     const dataSignal = signal(undefined, ...(ngDevMode ? [{ debugName: "dataSignal" }] : []));
     const errorSignal = signal(null, ...(ngDevMode ? [{ debugName: "errorSignal" }] : []));
     const isLoadingSignal = signal(false, ...(ngDevMode ? [{ debugName: "isLoadingSignal" }] : []));
@@ -5782,6 +5884,12 @@ function spMutation(options) {
         const { retry = 0, retryDelay = 10 } = options;
         let attempt = 0;
         let lastError = null;
+        let optimisticPreviousData;
+        const optimistic = options.optimisticUpdate;
+        if (optimistic) {
+            optimisticPreviousData = queryClient.getQueryData(optimistic.queryKey);
+            queryClient.setQueryData(optimistic.queryKey, (oldValue) => optimistic.updater(oldValue, variables));
+        }
         if (options.onMutate) {
             await options.onMutate(variables);
         }
@@ -5801,6 +5909,9 @@ function spMutation(options) {
                 if (options.onSettled) {
                     options.onSettled(result, null, variables);
                 }
+                if (optimistic?.invalidateOnSettled) {
+                    queryClient.invalidateQueries(optimistic.queryKey);
+                }
                 return result;
             }
             catch (error) {
@@ -5810,6 +5921,9 @@ function spMutation(options) {
                     ? retry(attempt, lastError)
                     : attempt <= retry;
                 if (!shouldRetry) {
+                    if (optimistic && optimistic.rollbackOnError !== false) {
+                        queryClient.setQueryData(optimistic.queryKey, optimisticPreviousData);
+                    }
                     updateState({
                         error: lastError,
                         isLoading: false,
@@ -5823,6 +5937,9 @@ function spMutation(options) {
                     if (options.onSettled) {
                         options.onSettled(undefined, lastError, variables);
                     }
+                    if (optimistic?.invalidateOnSettled) {
+                        queryClient.invalidateQueries(optimistic.queryKey);
+                    }
                     throw lastError;
                 }
                 const delay = typeof retryDelay === 'function'
@@ -6066,6 +6183,18 @@ function createQuery(queryKey, queryFn, options) {
         ...options,
     });
 }
+function createDependentQuery(queryKey, queryFn, dependencies, options) {
+    const enabled = computed(() => dependencies.every((dependency) => {
+        const value = dependency();
+        return value !== undefined && value !== null && value !== false;
+    }), ...(ngDevMode ? [{ debugName: "enabled" }] : []));
+    return spQuery({
+        queryKey,
+        queryFn,
+        ...options,
+        enabled,
+    });
+}
 
 /**
  * Reactive Queries Interfaces
@@ -6073,6 +6202,138 @@ function createQuery(queryKey, queryFn, options) {
  * This module exports all interface definitions for reactive queries
  */
 
+function spInfiniteQuery(options) {
+    const queryClient = getGlobalQueryClient();
+    let destroyRef = null;
+    try {
+        destroyRef = inject(DestroyRef, { optional: true });
+    }
+    catch {
+        // Not in injection context
+    }
+    const queryKey = Array.isArray(options.queryKey)
+        ? options.queryKey
+        : options.queryKey.key;
+    const pagesSignal = signal([], ...(ngDevMode ? [{ debugName: "pagesSignal" }] : []));
+    const errorSignal = signal(null, ...(ngDevMode ? [{ debugName: "errorSignal" }] : []));
+    const isLoadingSignal = signal(false, ...(ngDevMode ? [{ debugName: "isLoadingSignal" }] : []));
+    const isFetchingSignal = signal(false, ...(ngDevMode ? [{ debugName: "isFetchingSignal" }] : []));
+    const isFetchingNextPageSignal = signal(false, ...(ngDevMode ? [{ debugName: "isFetchingNextPageSignal" }] : []));
+    const hasNextPageSignal = signal(true, ...(ngDevMode ? [{ debugName: "hasNextPageSignal" }] : []));
+    const setPages = (pages) => {
+        untracked(() => {
+            pagesSignal.set(pages);
+            const lastPage = pages.length > 0 ? pages[pages.length - 1] : undefined;
+            hasNextPageSignal.set(lastPage !== undefined
+                ? options.getNextPageParam(lastPage, pages) !== undefined
+                : true);
+        });
+    };
+    const runPageFetch = async (pageParam) => {
+        isFetchingSignal.set(true);
+        errorSignal.set(null);
+        try {
+            return await options.queryFn(pageParam);
+        }
+        catch (error) {
+            errorSignal.set(error);
+            throw error;
+        }
+        finally {
+            isFetchingSignal.set(false);
+        }
+    };
+    const refetch = async () => {
+        isLoadingSignal.set(true);
+        try {
+            const firstPage = await runPageFetch(options.initialPageParam);
+            setPages([firstPage]);
+            queryClient.setQueryData(queryKey, [firstPage]);
+        }
+        finally {
+            isLoadingSignal.set(false);
+        }
+    };
+    const fetchNextPage = async () => {
+        const pages = pagesSignal();
+        const lastPage = pages[pages.length - 1];
+        const nextPageParam = pages.length === 0
+            ? options.initialPageParam
+            : options.getNextPageParam(lastPage, pages);
+        if (nextPageParam === undefined) {
+            hasNextPageSignal.set(false);
+            return;
+        }
+        isFetchingNextPageSignal.set(true);
+        try {
+            const page = await runPageFetch(nextPageParam);
+            const nextPages = [...pagesSignal(), page];
+            setPages(nextPages);
+            queryClient.setQueryData(queryKey, nextPages);
+        }
+        finally {
+            isFetchingNextPageSignal.set(false);
+        }
+    };
+    let enabledWatcher = null;
+    let previousEnabledState = false;
+    const getEnabled = () => {
+        if (typeof options.enabled === 'boolean') {
+            return options.enabled;
+        }
+        if (options.enabled) {
+            return options.enabled();
+        }
+        return true;
+    };
+    const runIfEnabled = () => {
+        const enabled = getEnabled();
+        if (!enabled) {
+            previousEnabledState = false;
+            return;
+        }
+        if (previousEnabledState) {
+            return;
+        }
+        previousEnabledState = true;
+        const cached = queryClient.getQueryData(queryKey);
+        if (cached && cached.length > 0) {
+            setPages(cached);
+            return;
+        }
+        refetch().catch(() => undefined);
+    };
+    runIfEnabled();
+    if (typeof options.enabled !== 'boolean' && options.enabled) {
+        enabledWatcher = setInterval(runIfEnabled, 100);
+    }
+    if (destroyRef) {
+        destroyRef.onDestroy(() => {
+            if (enabledWatcher) {
+                clearInterval(enabledWatcher);
+                enabledWatcher = null;
+            }
+        });
+    }
+    return {
+        pages: computed(() => pagesSignal()),
+        error: computed(() => errorSignal()),
+        isLoading: computed(() => isLoadingSignal()),
+        isFetching: computed(() => isFetchingSignal()),
+        isFetchingNextPage: computed(() => isFetchingNextPageSignal()),
+        hasNextPage: computed(() => hasNextPageSignal()),
+        refetch,
+        fetchNextPage,
+    };
+}
+function createInfiniteQuery(queryKey, queryFn, options) {
+    return spInfiniteQuery({
+        ...options,
+        queryKey,
+        queryFn,
+    });
+}
+
 /**
  * Public API Surface of ngx-signal-plus
  *
@@ -6085,5 +6346,5 @@ function createQuery(queryKey, queryFn, options) {
  * Generated bundle index. Do not edit.
  */
 
-export { QueryClient, SP_ERRORS, SpError, createMutation, createQuery, enhance, formatSpError, getGlobalQueryClient, setGlobalQueryClient, sp, spAll, spAnalyticsMiddleware, spAny, spAsync, spBatch, spClearMiddleware, spCollection, spCombine, combineLatest as spCombineLatest, spComputed, spCounter, spCreateError, debounceTime as spDebounceTime, spDebug, delay$1 as spDelay, distinctUntilChanged as spDistinctUntilChanged, spEffect, filter as spFilter, spForm, spFormGroup, spGetMiddlewareCount, spGetModifiedSignals, HistoryManager as spHistoryManager, spIsInBatch, spIsInTransaction, spIsTransactionActive, spLoggerMiddleware, map as spMap, merge as spMerge, spMutation, presets as spPresets, spQuery, spRemoveMiddleware, spSchema, spSchemaValidator, spSchemaWithErrors, SignalBuilder as spSignalBuilder, SignalPlusComponent as spSignalPlusComponent, SignalPlusService as spSignalPlusService, skip as spSkip, StorageManager as spStorageManager, take as spTake, throttleTime as spThrottleTime, spToggle, spTransaction, spUseMiddleware, validators as spValidators };
+export { QueryClient, SP_ERRORS, SpError, createDependentQuery, createInfiniteQuery, createMutation, createQuery, enhance, formatSpError, getGlobalQueryClient, setGlobalQueryClient, sp, spAll, spAnalyticsMiddleware, spAny, spAsync, spBatch, spClearMiddleware, spCollection, spCombine, combineLatest as spCombineLatest, spComputed, spCounter, spCreateError, debounceTime as spDebounceTime, spDebug, delay$1 as spDelay, distinctUntilChanged as spDistinctUntilChanged, spEffect, filter as spFilter, spForm, spFormGroup, spGetMiddlewareCount, spGetModifiedSignals, HistoryManager as spHistoryManager, spInfiniteQuery, spIsInBatch, spIsInTransaction, spIsTransactionActive, spLoggerMiddleware, map as spMap, merge as spMerge, spMonitor, spMutation, presets as spPresets, spQuery, spRemoveMiddleware, spSchema, spSchemaValidator, spSchemaWithErrors, SignalBuilder as spSignalBuilder, SignalPlusComponent as spSignalPlusComponent, SignalPlusService as spSignalPlusService, skip as spSkip, StorageManager as spStorageManager, take as spTake, throttleTime as spThrottleTime, spToggle, spTransaction, spUseMiddleware, validators as spValidators };
 //# sourceMappingURL=ngx-signal-plus.mjs.map