ngx-signal-query 1.5.0 → 1.5.1-dev.2

package/fesm2022/ngx-signal-query.mjs

@@ -1,8 +1,20 @@
 import * as i0 from '@angular/core';
 import { inject, PLATFORM_ID, signal, Injectable, InjectionToken, EnvironmentInjector, DestroyRef, untracked, runInInjectionContext, makeEnvironmentProviders, assertInInjectionContext, effect, computed, Injector } from '@angular/core';
-import { DOCUMENT, isPlatformBrowser } from '@angular/common';
+import { isPlatformBrowser, DOCUMENT } from '@angular/common';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
-import { fromEvent, filter, defer, from, take, retry, timer, throwIfEmpty, map, tap, concatMap, catchError, of, endWith, concat, ignoreElements, EMPTY } from 'rxjs';
+import { fromEvent, filter, Subscription, defer, isObservable, from, take, retry, timer, tap, throwIfEmpty, map, concatMap, catchError, of, endWith, concat, ignoreElements, EMPTY } from 'rxjs';
+
+/**
+ * Whether the app runs in the browser rather than on the server. On the
+ * server, DOCUMENT is an emulated document that has listeners, a window and
+ * no visibilityState: only the platform tells. Must run in an injection
+ * context.
+ *
+ * @internal
+ */
+function inBrowser() {
+    return isPlatformBrowser(inject(PLATFORM_ID));
+}
 
 /**
  * Calls `listener` whenever the user comes back to the page, as the tab or
@@ -44,11 +56,6 @@ function onReconnect(listener) {
         .pipe(takeUntilDestroyed())
         .subscribe(() => listener());
 }
-// On the server, DOCUMENT is an emulated document that has listeners,
-// a window and no visibilityState: only the platform tells.
-function inBrowser() {
-    return isPlatformBrowser(inject(PLATFORM_ID));
-}
 
 /** @internal */
 class Cache {
@@ -252,9 +259,10 @@ function deferred() {
 /**
  * The error a promise of a query's data rejects with when the fetch stops
  * with no data to give: it was cancelled before the query had any
- * (`cancelQueries()`, or the last component showing the query went away), or
- * the query was removed (`removeQueries()`, e.g. on sign-out). The request
- * didn't fail, so tell the two apart with `instanceof CancelledError`.
+ * (`cancelQueries()`, or the last component showing the query went away
+ * during an `Observable` fetch), or the query was removed
+ * (`removeQueries()`, e.g. on sign-out). The request didn't fail, so tell
+ * the two apart with `instanceof CancelledError`.
  *
  * A mutation's `mutateAsync()` rejects with one too, when the mutation cache
  * is cleared while its run is in flight.
@@ -286,7 +294,6 @@ function resolveRetryDelay(retryDelay, failureCount, error) {
         : retryDelay;
 }
 
-const DEFAULT_GC_TIME = 5 * 60 * 1000;
 /** @internal */
 class Query {
     key;
@@ -305,30 +312,32 @@ class Query {
     // field it reads during initialization (field init order).
     // eslint-disable-next-line @typescript-eslint/member-ordering
     state = this.#state.asReadonly();
-    #subscription = null;
-    // The promise of the fetch in flight, which every caller that joins the
-    // fetch shares, and how to settle it; null while nothing is in flight.
-    #outcome = null;
-    // The state the fetch in flight started from, or the last write made
-    // during it: stopping the fetch with nothing in its place goes back to it
-    // (see #stop). null while nothing is in flight.
-    #beforeFetch = null;
+    // The fetch in flight; null while nothing is.
+    #inFlight = null;
     // The structuralSharing of the fetch whose response the query holds.
     #fetchedStructuralSharing;
     #observers = new Set();
-    #gcTime = DEFAULT_GC_TIME;
+    #gcTime = 0;
     #gcTimer = null;
     #cache;
-    constructor(key, queryHash, cache) {
+    constructor({ key, queryHash, cache, gcTime }) {
         this.key = key;
         this.queryHash = queryHash;
         this.#cache = cache;
+        this.updateGcTime(gcTime);
+        // A new query has nothing using it yet: its creator is about to, and if
+        // nothing ever does, gc removes it.
+        this.#scheduleGc();
     }
     get observerCount() {
         return this.#observers.size;
     }
-    setGcTime(ms) {
-        this.#gcTime = ms;
+    // Keeps the longest gcTime asked for by anything that used the query, as
+    // in TanStack: whoever created it, each component that showed it, each
+    // fetchQuery. A shorter one doesn't cut short a longer one asked for
+    // before. Never below 0.
+    updateGcTime(ms) {
+        this.#gcTime = Math.max(this.#gcTime, ms);
     }
     addObserver(observer) {
         this.#observers.add(observer);
@@ -339,10 +348,16 @@ class Query {
         // the fetch or schedule gc while others still watch.
         if (!this.#observers.delete(observer))
             return;
-        // No observers left: cancel any in-flight fetch (nobody is waiting for it)
-        // and schedule gc to dispose the query if no observer returns.
+        // No observers left: nobody waits for the fetch in flight any more. Stop
+        // it if that aborts its request; a request that runs on anyway is let
+        // land, so its response isn't thrown away, but nobody is left to want a
+        // failure tried again. Then schedule gc to dispose the query if no
+        // observer returns.
         if (this.#observers.size === 0) {
-            this.cancel();
+            if (this.#inFlight?.abortable)
+                this.cancel();
+            else if (this.#inFlight)
+                this.#inFlight.retriesStopped = true;
             this.#scheduleGc();
         }
     }
@@ -386,13 +401,18 @@ class Query {
     // with its own outcome; one stopped with nothing in its place settles it as
     // cancel() or destroy() says. Nobody has to wait for it.
     fetch({ queryFn, retry: retry$1 = 0, retryDelay = defaultRetryDelay, structuralSharing = false, }, { cancelRefetch = false } = {}) {
-        const running = this.#outcome;
+        const running = this.#inFlight;
         if (running) {
             // Already in-flight: dedupe unless the caller explicitly wants a fresh
-            // fetch (e.g. invalidate/refetch) — then replace the old one.
-            if (!cancelRefetch)
-                return running.promise;
-            this.#subscription?.unsubscribe();
+            // fetch (e.g. invalidate/refetch) — then replace the old one. A caller
+            // that joins hands its queryFn over for the retries to come, and wants
+            // them made, even after the observers the fetch was started for left.
+            if (!cancelRefetch) {
+                running.queryFn = queryFn;
+                running.retriesStopped = false;
+                return running.outcome.promise;
+            }
+            running.subscription.unsubscribe();
         }
         const outcome = deferred();
         // Its result or error lands in the state either way, so a caller may
@@ -400,12 +420,18 @@ class Query {
         // unhandled rejection, and whoever awaits the promise still gets it.
         outcome.promise.catch(() => undefined);
         // Whoever waits for the fetch this one replaces gets this one's outcome.
-        running?.resolve(outcome.promise);
-        this.#outcome = outcome;
-        // A fetch that replaces one in flight keeps the state the first one
-        // started from.
-        if (!running)
-            this.#beforeFetch = this.state();
+        running?.outcome.resolve(outcome.promise);
+        const inFlight = {
+            outcome,
+            subscription: new Subscription(),
+            // A fetch that replaces one in flight keeps the state the first one
+            // started from.
+            before: running?.before ?? this.state(),
+            queryFn,
+            abortable: false,
+            retriesStopped: false,
+        };
+        this.#inFlight = inFlight;
         // A query with no data reads like a first load while it fetches, even
         // after a failure: 'pending' with no error, so a loading state and
         // placeholderData show rather than the old error. One with data keeps
@@ -417,10 +443,19 @@ class Query {
             failureCount: 0,
             failureReason: null,
         }));
-        // defer + from: normalize Observable/Promise and re-invoke queryFn on each
-        // retry (a Promise is one-shot, so retry must produce a fresh one).
-        this.#subscription = defer(() => from(queryFn()))
-            .pipe(take(1), retry({
+        // The first attempt runs the caller's queryFn, each retry the one
+        // #retryQueryFn picks. defer + from: normalize Observable/Promise and
+        // make a fresh request for each attempt (a Promise is one-shot).
+        let firstAttempt = true;
+        const attempts = defer(() => {
+            const attemptQueryFn = firstAttempt
+                ? queryFn
+                : this.#retryQueryFn(inFlight);
+            firstAttempt = false;
+            const request = attemptQueryFn();
+            inFlight.abortable = isObservable(request);
+            return from(request);
+        }).pipe(take(1), retry({
             delay: (error, retryCount) => {
                 // retryCount (1-based) is the number of failures so far; the retry
                 // predicate/delay take a 0-based attempt index (0 = first retry).
@@ -430,20 +465,29 @@ class Query {
                     failureReason: error,
                 }));
                 const attemptIndex = retryCount - 1;
-                if (!shouldRetry(retry$1, attemptIndex, error))
+                // Once the last observer left, the failure ends the fetch at once.
+                if (inFlight.retriesStopped ||
+                    !shouldRetry(retry$1, attemptIndex, error)) {
                     throw error;
-                return timer(resolveRetryDelay(retryDelay, attemptIndex, error));
+                }
+                // The retry goes out when the wait is over. If the last observer
+                // left during the wait, an error thrown when the timer fires ends
+                // the fetch with this error instead, as in TanStack; whoever joins
+                // meanwhile clears the flag, and the retry goes out on time.
+                return timer(resolveRetryDelay(retryDelay, attemptIndex, error)).pipe(tap(() => {
+                    if (inFlight.retriesStopped)
+                        throw error;
+                }));
             },
         }), throwIfEmpty(() => new Error('Query function completed without emitting a value')), 
         // Keeps what didn't change from the data the query holds when the
         // response lands, a write made during the fetch included. After the
         // retries: a structuralSharing function that throws fails the fetch
         // rather than retrying it, or leaving it in flight.
-        map((data) => replaceData(this.state().data, data, structuralSharing)))
-            .subscribe({
+        map((data) => replaceData(this.state().data, data, structuralSharing)));
+        inFlight.subscription.add(attempts.subscribe({
             next: (data) => {
-                this.#outcome = null;
-                this.#beforeFetch = null;
+                this.#inFlight = null;
                 this.#fetchedStructuralSharing = structuralSharing;
                 this.#state.set({
                     data,
@@ -456,10 +500,10 @@ class Query {
                     updatedAt: Date.now(),
                 });
                 outcome.resolve(data);
+                this.#scheduleGc();
             },
             error: (err) => {
-                this.#outcome = null;
-                this.#beforeFetch = null;
+                this.#inFlight = null;
                 this.#state.update((state) => ({
                     ...state,
                     status: 'error',
@@ -467,8 +511,9 @@ class Query {
                     isFetching: false,
                 }));
                 outcome.reject(err);
+                this.#scheduleGc();
             },
-        });
+        }));
         return outcome.promise;
     }
     // Without a structuralSharing setting the data is stored as is: which one
@@ -485,12 +530,11 @@ class Query {
             updatedAt,
         }));
         // A write made during a fetch is what stopping the fetch goes back to.
-        if (this.#inFlight())
-            this.#beforeFetch = this.state();
-        // Keep an orphaned query (no observers) alive for another gcTime so a
-        // setQueryData write isn't collected before anyone subscribes.
-        if (this.#observers.size === 0)
-            this.#scheduleGc();
+        if (this.#inFlight)
+            this.#inFlight.before = this.state();
+        // A write counts as use: a query nobody observes is kept for another
+        // gcTime, so a setQueryData write isn't collected before anyone shows it.
+        this.#scheduleGc();
     }
     invalidate() {
         this.#state.update((state) => ({ ...state, isInvalidated: true }));
@@ -505,9 +549,14 @@ class Query {
     // holds, as in TanStack, or a CancelledError if it holds none.
     cancel() {
         const { data } = this.state();
+        const fetching = this.#inFlight !== null;
         this.#stop((outcome) => data === undefined
             ? outcome.reject(new CancelledError())
             : outcome.resolve(data));
+        // Only a fetch that stops can leave the query unused: cancelling none
+        // mustn't put off its gc.
+        if (fetching)
+            this.#scheduleGc();
     }
     // The query is thrown away with its data, so whoever waits for its fetch
     // gets a CancelledError, as in TanStack.
@@ -522,39 +571,33 @@ class Query {
     #isStale(staleTime) {
         return Date.now() - this.state().updatedAt >= staleTime;
     }
-    #inFlight() {
-        return this.#outcome !== null;
-    }
     // Stops the fetch in flight, if any, and settles its promise with settle.
     #stop(settle) {
-        const outcome = this.#outcome;
-        const before = this.#beforeFetch;
-        this.#subscription?.unsubscribe();
-        this.#subscription = null;
-        this.#outcome = null;
-        this.#beforeFetch = null;
-        if (outcome)
-            settle(outcome);
+        const inFlight = this.#inFlight;
+        if (!inFlight)
+            return;
+        inFlight.subscription.unsubscribe();
+        this.#inFlight = null;
+        settle(inFlight.outcome);
+        const { before } = inFlight;
         // The fetch is no longer running, so isFetching mustn't stay stuck true,
         // and what the fetch wrote over goes back to how it was: a query that
         // failed shows its error again, as in TanStack. Data and the stale mark
         // aren't the fetch's to put back: they stay as written meanwhile, so an
         // invalidation made during the fetch still holds.
-        if (before) {
-            this.#state.update((state) => ({
-                ...state,
-                status: before.status,
-                error: before.error,
-                failureCount: before.failureCount,
-                failureReason: before.failureReason,
-                isFetching: false,
-            }));
-        }
+        this.#state.update((state) => ({
+            ...state,
+            status: before.status,
+            error: before.error,
+            failureCount: before.failureCount,
+            failureReason: before.failureReason,
+            isFetching: false,
+        }));
     }
     // A fetch in flight is kept, as in TanStack, and the observers aren't even
     // asked: fetch() would drop the refetch anyway.
     #refetchOn(option) {
-        if (this.#inFlight())
+        if (this.#inFlight)
             return;
         for (const observer of this.#observers) {
             const options = observer.fetchOptions();
@@ -566,11 +609,36 @@ class Query {
             }
         }
     }
+    // The queryFn a retry runs: that of the first observer that wants the
+    // query fetched, as for a refetch, else that of whoever asked for the
+    // fetch last. Not simply the one the fetch started with: a queryFn may
+    // read its key's value only when it runs, as `() => api(this.id())` does,
+    // and by the retry its component may have moved on to another key. An
+    // observer whose key moved on doesn't want this query fetched.
+    #retryQueryFn(inFlight) {
+        for (const observer of this.#observers) {
+            const options = observer.fetchOptions();
+            if (options)
+                return options.queryFn;
+        }
+        return inFlight.queryFn;
+    }
+    // Removes the query gcTime from now, unless something uses it by then: an
+    // observer, or a fetch of it in flight. Called whenever the query may have
+    // become unused: when it's created, when its last observer leaves, when a
+    // fetch of it ends, when data is written into it by hand.
     #scheduleGc() {
         this.#clearGcTimer();
+        // While observed, the query is in use: the last observer leaving calls
+        // this again. Infinity, or a gcTime no timer can hold, keeps the query
+        // until something removes it: a browser would run the timer at once.
+        if (this.#observers.size > 0 || !isValidTimeout(this.#gcTime))
+            return;
         this.#gcTimer = setTimeout(() => {
             this.#gcTimer = null;
-            this.#cache.remove(this);
+            // A fetch still in flight keeps it: the fetch's end calls this again.
+            if (!this.#inFlight)
+                this.#cache.remove(this);
         }, this.#gcTime);
     }
     #clearGcTimer() {
@@ -583,12 +651,12 @@ class Query {
 
 /** @internal */
 class QueryCache extends Cache {
-    getOrCreate(key) {
+    getOrCreate(key, gcTime) {
         const queryHash = hashKey(key);
         const exist = this.getEntry(queryHash);
         if (exist)
             return exist;
-        return this.addEntry(queryHash, new Query(key, queryHash, this));
+        return this.addEntry(queryHash, new Query({ key, queryHash, cache: this, gcTime }));
     }
     get(key) {
         return this.getEntry(hashKey(key));
@@ -619,6 +687,9 @@ class QueryCache extends Cache {
         // Guard on identity, not just the hash: a stale instance (already removed
         // and recreated under the same key) must not evict the current query.
         if (this.getEntry(query.queryHash) === query) {
+            // Whoever removes it, gc or removeQueries, it leaves cleaned up: its
+            // fetch cancelled and its gc timer cleared.
+            query.destroy();
             this.removeEntry(query.queryHash);
         }
     }
@@ -837,6 +908,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.21", ngImpo
 /** @internal */
 const QUERY_CLIENT_CONFIG = new InjectionToken('QUERY_CLIENT_CONFIG');
 
+const DEFAULT_GC_TIME = 5 * 60 * 1000;
 /**
  * Central registry and cache for queries and mutations.
  *
@@ -861,6 +933,7 @@ class QueryClient {
     #cache = inject(QueryCache);
     #mutationCache = inject(MutationCache);
     #config = inject(QUERY_CLIENT_CONFIG, { optional: true }) ?? {};
+    #onServer = !inBrowser();
     /** @internal */
     #injector = inject(EnvironmentInjector);
     /**
@@ -899,7 +972,7 @@ class QueryClient {
         return {
             ...options,
             staleTime: options.staleTime ?? defaults?.staleTime ?? 0,
-            gcTime: options.gcTime ?? defaults?.gcTime,
+            gcTime: this.#gcTime(options.gcTime),
             retry: options.retry ?? defaults?.retry ?? 3,
             retryDelay: options.retryDelay ?? defaults?.retryDelay ?? defaultRetryDelay,
             structuralSharing: options.structuralSharing ?? this.#defaultStructuralSharing(),
@@ -944,6 +1017,9 @@ class QueryClient {
      * set here or in {@link withDefaultOptions}, so whoever waits for the data
      * hears of the failure at once.
      *
+     * A query no component shows is removed `gcTime` after the fetch lands (the
+     * configured default, or 5 minutes), as any unused query is.
+     *
      * @param key - The query key to fetch and cache under.
      * @param queryFn - Function returning the data as an `Observable` or `Promise`.
      * @param options - Fetch tuning (`staleTime`, `retry`, `retryDelay`,
@@ -977,7 +1053,10 @@ class QueryClient {
                     this.#config.defaultOptions?.queries?.retry ??
                     false,
             });
-            const query = this.#cache.getOrCreate(key);
+            const query = this.#cache.getOrCreate(key, defaulted.gcTime);
+            // A query already in the cache keeps this call's gcTime if it's
+            // longer, as it does for each component showing it.
+            query.updateGcTime(defaulted.gcTime);
             return query.shouldFetch(defaulted.staleTime)
                 ? query.fetch(defaulted, { cancelRefetch })
                 : Promise.resolve(query.state().data);
@@ -1005,6 +1084,9 @@ class QueryClient {
      * nothing. It merges as the query showing the key asks; with none showing
      * it, the way the cached data was fetched; otherwise by the default.
      *
+     * A key no component shows is kept for `gcTime` after the last write, then
+     * removed.
+     *
      * @param key - The query key to write.
      * @param updater - The new data, or a function `(prev) => next`.
      *
@@ -1015,7 +1097,7 @@ class QueryClient {
      */
     setQueryData(key, updater) {
         untracked(() => {
-            const query = this.#cache.getOrCreate(key);
+            const query = this.#cache.getOrCreate(key, this.#gcTime());
             const data = functionalUpdate(updater, query.state().data);
             // Matches TanStack: an updater returning undefined is a no-op.
             if (data === undefined)
@@ -1099,10 +1181,9 @@ class QueryClient {
      * @param filters - Which queries to remove; omit to remove all.
      */
     removeQueries(filters) {
-        untracked(() => this.#cache.findAll(filters).forEach((query) => {
-            query.destroy();
-            this.#cache.remove(query);
-        }));
+        untracked(() => this.#cache
+            .findAll(filters)
+            .forEach((query) => this.#cache.remove(query)));
     }
     /**
      * Returns the number of matching queries currently fetching. A snapshot: it
@@ -1127,6 +1208,22 @@ class QueryClient {
     isMutating() {
         return untracked(() => this.#mutationCache.findAll({ status: 'pending' }).length);
     }
+    /**
+     * How long a query stays in the cache once nothing uses it: the gcTime it
+     * asks for, else the configured default, else 5 minutes. Every path that
+     * puts a query into the cache takes it from here.
+     *
+     * On the server it's Infinity, whatever was asked: the cache lives as long
+     * as the app that renders the request, and a pending timer would hold up a
+     * render with zone.js.
+     *
+     * @internal
+     */
+    #gcTime(time) {
+        if (this.#onServer)
+            return Infinity;
+        return (time ?? this.#config.defaultOptions?.queries?.gcTime ?? DEFAULT_GC_TIME);
+    }
     /**
      * The configured default structuralSharing, or `true`. One default serves
      * every query whatever its data, so a function there takes and returns
@@ -1320,7 +1417,7 @@ function createQueryObserver(optionsFn, injector) {
     // writes signals (the cache's entries, the query's state), so callers run it
     // untracked: reached from a computed, a tracked write throws NG0600.
     const resolve = (key) => {
-        const q = cache.getOrCreate(key);
+        const q = cache.getOrCreate(key, untracked(defaultedOptions).gcTime);
         applyInitialData(q);
         return q;
     };
@@ -1393,10 +1490,7 @@ function createQueryObserver(optionsFn, injector) {
     };
     track((cleanup) => {
         const q = query();
-        const { gcTime } = untracked(defaultedOptions);
-        if (gcTime !== undefined) {
-            q.setGcTime(gcTime);
-        }
+        q.updateGcTime(untracked(defaultedOptions).gcTime);
         // This observer as q sees it.
         const subscriber = {
             fetchOptions: () => fetchOptionsFor(q),