ngx-signal-plus 2.5.0 → 2.7.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-90.92%25-brightgreen)
 
 Bring validation, persistence, undo/redo, and reactive queries to Angular Signals on Angular 16+.
 
@@ -70,9 +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`, `spMonitor`, `sp().debug(label)`
 - 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`
@@ -117,3 +118,6 @@ export class CounterComponent {
 ## License
 
 MIT
+
+
+

package/fesm2022/ngx-signal-plus.mjs

@@ -263,6 +263,66 @@ function safeAddEventListener(event, handler) {
     };
 }
 
+const states = new Map();
+let globalEnabled$1 = true;
+const ensureState = (name) => {
+    const existing = states.get(name);
+    if (existing) {
+        return existing;
+    }
+    const created = {
+        name,
+        updates: 0,
+        enabled: true,
+        lastValue: undefined,
+        lastUpdated: null,
+    };
+    states.set(name, created);
+    return created;
+};
+const spDebug = {
+    trackSignal(name, initialValue) {
+        const state = ensureState(name);
+        state.lastValue = initialValue;
+        if (state.lastUpdated === null) {
+            state.lastUpdated = Date.now();
+        }
+    },
+    recordUpdate(name, value) {
+        const state = ensureState(name);
+        state.lastValue = value;
+        if (!globalEnabled$1 || !state.enabled) {
+            return;
+        }
+        state.updates += 1;
+        state.lastUpdated = Date.now();
+    },
+    enable(name) {
+        ensureState(name).enabled = true;
+    },
+    disable(name) {
+        ensureState(name).enabled = false;
+    },
+    enableAll() {
+        globalEnabled$1 = true;
+    },
+    disableAll() {
+        globalEnabled$1 = false;
+    },
+    getActiveSignals() {
+        return Array.from(states.values())
+            .filter((state) => state.enabled)
+            .map((state) => state.name);
+    },
+    exportState() {
+        return Array.from(states.values()).map((state) => ({ ...state }));
+    },
+    clear() {
+        states.clear();
+        globalEnabled$1 = true;
+    },
+};
+
 /**
  * @fileoverview Builder class for creating enhanced Angular signals
  * Provides a fluent API for configuring signals with features like:
@@ -379,6 +439,15 @@ class SignalBuilder {
         this.options.errorHandlers.push(handler);
         return this;
     }
+    /**
+     * Enables debug tracking for this signal instance.
+     * @param label Human-readable identifier used by spDebug state exports
+     * @returns Builder instance for chaining
+     */
+    debug(label) {
+        this.options.debugLabel = label;
+        return this;
+    }
     /**
      * Transforms signal value to a different type
      * @param fn Transform function from T to R
@@ -648,6 +717,9 @@ class SignalBuilder {
         const notifySubscribers = (value) => {
             if (isCleanedUp)
                 return;
+            if (this.options.debugLabel) {
+                spDebug.recordUpdate(this.options.debugLabel, value);
+            }
             subscribers.forEach((callback) => {
                 try {
                     callback(value);
@@ -776,6 +848,9 @@ class SignalBuilder {
         };
         // Set initial value without applying transforms
         writable.set(initialValue);
+        if (this.options.debugLabel) {
+            spDebug.trackSignal(this.options.debugLabel, writable());
+        }
         const processValue = (value) => {
             // Prevent setValue after destroy
             if (isCleanedUp) {
@@ -3705,6 +3780,19 @@ function spAsync(options) {
     };
 }
 
+function spCombine(signals, combiner) {
+    return computed(() => {
+        const values = signals.map((source) => source());
+        return combiner(...values);
+    });
+}
+function spAll(signals) {
+    return computed(() => signals.every((source) => source()));
+}
+function spAny(signals) {
+    return computed(() => signals.some((source) => source()));
+}
+
 function spCollection(options) {
     const idField = options.idField;
     const persistKey = options.persist;
@@ -4092,6 +4180,131 @@ 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;
+    const runCallback = () => {
+        if (paused()) {
+            return;
+        }
+        if (options.condition && !options.condition()) {
+            return;
+        }
+        const debounce = options.debounce ?? 0;
+        if (debounce > 0) {
+            if (timeoutId !== null) {
+                safeClearTimeout(timeoutId);
+            }
+            timeoutId = safeSetTimeout(() => {
+                timeoutId = null;
+                if (paused()) {
+                    return;
+                }
+                if (options.condition && !options.condition()) {
+                    return;
+                }
+                callback();
+            }, debounce);
+            return;
+        }
+        callback();
+    };
+    const effectRef = effect(() => {
+        runCallback();
+    }, ...(ngDevMode ? [{ debugName: "effectRef" }] : []));
+    return {
+        pause: () => {
+            paused.set(true);
+            if (timeoutId !== null) {
+                safeClearTimeout(timeoutId);
+                timeoutId = null;
+            }
+        },
+        resume: () => {
+            paused.set(false);
+        },
+        destroy: () => {
+            if (timeoutId !== null) {
+                safeClearTimeout(timeoutId);
+                timeoutId = null;
+            }
+            effectRef.destroy();
+        },
+        isPaused: computed(() => paused()),
+    };
+}
+
 function isFormGroup(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 control) {
@@ -5597,6 +5810,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" }] : []));
@@ -5640,6 +5854,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);
         }
@@ -5659,6 +5879,9 @@ function spMutation(options) {
                 if (options.onSettled) {
                     options.onSettled(result, null, variables);
                 }
+                if (optimistic?.invalidateOnSettled) {
+                    queryClient.invalidateQueries(optimistic.queryKey);
+                }
                 return result;
             }
             catch (error) {
@@ -5668,6 +5891,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,
@@ -5681,6 +5907,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'
@@ -5924,6 +6153,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
@@ -5931,6 +6172,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
  *
@@ -5943,5 +6316,5 @@ function createQuery(queryKey, queryFn, options) {
  * Generated bundle index. Do not edit.
  */
 
-export { QueryClient, SP_ERRORS, SpError, createMutation, createQuery, enhance, formatSpError, getGlobalQueryClient, setGlobalQueryClient, sp, spAnalyticsMiddleware, spAsync, spBatch, spClearMiddleware, spCollection, combineLatest as spCombineLatest, spComputed, spCounter, spCreateError, debounceTime as spDebounceTime, delay$1 as spDelay, distinctUntilChanged as spDistinctUntilChanged, 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