ngx-signal-query 1.8.0-dev.1 → 1.8.0-dev.3

package/README.md

@@ -29,11 +29,12 @@ know from it carries over.
 - 🔁 Retries, polling, and refetch on window focus and reconnect
 - ✏️ Mutations with async lifecycle hooks and optimistic updates
 - 🌍 App-wide defaults and global indicators (`injectIsFetching()`, `injectIsMutating()`)
+- 🖥️ Server rendering: the server waits for every fetch, and `withHydration()` brings the data over to the browser
 
 ## Not here (yet)
 
-Infinite queries, SSR cache hydration, devtools and persistence. If you need
-them today, TanStack Query has them.
+Infinite queries, devtools and persistence. If you need them today, TanStack
+Query has them.
 
 ## Installation
 

package/fesm2022/ngx-signal-query.mjs

@@ -1,5 +1,5 @@
 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 { inject, PLATFORM_ID, makeStateKey, TransferState, NgZone, signal, PendingTasks, DestroyRef, Injectable, InjectionToken, EnvironmentInjector, untracked, runInInjectionContext, makeEnvironmentProviders, assertInInjectionContext, effect, computed, Injector } from '@angular/core';
 import { isPlatformBrowser, DOCUMENT } from '@angular/common';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import { fromEvent, filter, Subscription, defer, isObservable, from, take, retry, timer, tap, throwIfEmpty, map, concatMap, catchError, of, endWith, concat, ignoreElements, EMPTY } from 'rxjs';
@@ -70,48 +70,6 @@ function onReconnect(listener) {
         .subscribe(() => listener());
 }
 
-/** @internal */
-class Cache {
-    #entries = signal([], ...(ngDevMode ? [{ debugName: "#entries" }] : []));
-    // Reactive snapshot of all entries; updated on add/remove/clear so that
-    // findAll() (and its computed consumers like isFetching) react to the
-    // collection. Protected: only subclasses read it, never external code.
-    entries = this.#entries.asReadonly();
-    #entriesMap = new Map();
-    getAll() {
-        return Array.from(this.#entriesMap.values());
-    }
-    clear() {
-        this.#entriesMap.clear();
-        this.#sync();
-    }
-    // Updates the snapshot again once the current computation is over, in a
-    // microtask. An entry added in the middle of a computation is in the
-    // snapshot at once, but a computed that read the snapshot earlier in that
-    // computation doesn't hear of it: it only starts listening once its
-    // computation is done. The second update reaches it.
-    notifyLater() {
-        queueMicrotask(() => this.#sync());
-    }
-    addEntry(key, entry) {
-        this.#entriesMap.set(key, entry);
-        this.#sync();
-        return entry;
-    }
-    getEntry(key) {
-        return this.#entriesMap.get(key);
-    }
-    removeEntry(key) {
-        const removed = this.#entriesMap.delete(key);
-        if (removed)
-            this.#sync();
-        return removed;
-    }
-    #sync() {
-        this.#entries.set(Array.from(this.#entriesMap.values()));
-    }
-}
-
 // Resolves an updater: calls it with the previous value if it's a function,
 // otherwise uses it as the value directly.
 /** @internal */
@@ -245,6 +203,54 @@ function replaceData(prevData, data, structuralSharing) {
     }
     return structuralSharing ? replaceEqualDeep(prevData, data) : data;
 }
+// Past this many levels survivesJson gives up: a value that references
+// itself never ends, and real data is never this deep.
+const MAX_JSON_DEPTH = 500;
+// Whether JSON carries the value over as it is: JSON.parse gives back a value
+// equal to it, of the same kind. Strings, finite numbers, booleans, null,
+// plain objects and arrays without holes do. A Date, a Map, a class instance,
+// a BigInt, NaN, undefined in an array, or a value that references itself
+// don't. An object property that's undefined counts as carried: JSON drops
+// it, and reading it gives undefined all the same. Symbol keys and extra
+// properties on an array aren't checked, and don't make it over.
+/** @internal */
+function survivesJson(value, depth = 0) {
+    if (value === null)
+        return true;
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    // NaN and Infinity come back as null.
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    // undefined, a function or a symbol is dropped, or comes back as null; a
+    // BigInt can't be written at all.
+    if (typeof value !== 'object')
+        return false;
+    if (depth > MAX_JSON_DEPTH)
+        return false;
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            // An item that's undefined, a hole included, comes back as null.
+            if (!survivesJson(value[i], depth + 1))
+                return false;
+        }
+        return true;
+    }
+    // JSON.parse makes objects whose prototype is Object.prototype. Whatever
+    // has another one, a Date, a Map, a class instance, comes back as something
+    // else. One with none comes back as an ordinary object, which reads the
+    // same.
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return false;
+    // for...in rather than Object.keys(): no array to allocate per object.
+    for (const key in value) {
+        const item = value[key];
+        if (item !== undefined && !survivesJson(item, depth + 1))
+            return false;
+    }
+    return true;
+}
 // The longest delay a browser timer holds, in ms. A longer one overflows and
 // the timer fires at once.
 const MAX_TIMEOUT = 2 ** 31 - 1;
@@ -277,6 +283,126 @@ function deferred() {
     return { promise, resolve, reject };
 }
 
+/**
+ * Where in Angular's TransferState the page carries the cache.
+ *
+ * @internal
+ */
+const TRANSFER_KEY = makeStateKey('ngx-signal-query');
+/**
+ * Hands the cache from a server render over to the browser through Angular's
+ * TransferState: on the server, the queries go into the page once the render
+ * is done; in the browser, they go back into the cache, as fetched when the
+ * server fetched them. Must run in an injection context.
+ *
+ * @internal
+ */
+function transferCache(cache, gcTime) {
+    const transferState = inject(TransferState);
+    if (!inBrowser()) {
+        // Called as Angular writes the state into the page, once the app is
+        // stable: every fetch of the render has landed by then.
+        transferState.onSerialize(TRANSFER_KEY, () => dehydrate(cache));
+        return;
+    }
+    const queries = transferState.get(TRANSFER_KEY, null);
+    if (!queries)
+        return;
+    // Read once: from now on the cache holds the data.
+    transferState.remove(TRANSFER_KEY);
+    // Outside Angular's zone: with zone.js, the gc timer of a query no
+    // component shows yet would keep the app from counting as stable, and
+    // Angular's HTTP transfer cache would go on answering its requests with the
+    // server's responses until then.
+    inject(NgZone).runOutsideAngular(() => hydrate(cache, queries, gcTime));
+}
+// The queries the page carries: those that succeeded, with data JSON carries
+// as is. Any other is left to the browser, which fetches it as it would
+// without a server render. Data JSON can't carry would reach the browser as
+// something else, a Date as a string, or not at all: a BigInt or a value that
+// references itself fails the whole page's state, Angular's own included.
+function dehydrate(cache) {
+    return cache.getAll().flatMap((query) => {
+        const { status, data, updatedAt, isInvalidated } = query.state();
+        if (status !== 'success')
+            return [];
+        if (!survivesJson(data)) {
+            warnLeftOut(query.queryHash);
+            return [];
+        }
+        return [
+            {
+                key: query.key,
+                hash: query.queryHash,
+                data,
+                updatedAt,
+                ...(isInvalidated && { isInvalidated }),
+            },
+        ];
+    });
+}
+// Puts the queries the page carries into a cache nothing has read yet. One
+// that nothing uses is kept for gcTime, as data written with setQueryData is.
+function hydrate(cache, queries, gcTime) {
+    for (const { key, hash, data, updatedAt, isInvalidated } of queries) {
+        const query = cache.getOrCreate(key, gcTime, hash);
+        query.setData(data, { updatedAt });
+        if (isInvalidated)
+            query.invalidate();
+    }
+}
+// Tells the developer why a query loads again in the browser. Development
+// builds only: a production build drops it with the rest of Angular's
+// development checks.
+function warnLeftOut(queryHash) {
+    if (typeof ngDevMode === 'undefined' || ngDevMode) {
+        // eslint-disable-next-line no-console
+        console.warn(`ngx-signal-query: query ${queryHash} stays on the server: JSON can't carry its data as is (a Date, a Map or a class instance, say), so the browser fetches it again. Return plain data from its queryFn to bring it over.`);
+    }
+}
+
+/** @internal */
+class Cache {
+    #entries = signal([], ...(ngDevMode ? [{ debugName: "#entries" }] : []));
+    // Reactive snapshot of all entries; updated on add/remove/clear so that
+    // findAll() (and its computed consumers like isFetching) react to the
+    // collection. Protected: only subclasses read it, never external code.
+    entries = this.#entries.asReadonly();
+    #entriesMap = new Map();
+    getAll() {
+        return Array.from(this.#entriesMap.values());
+    }
+    clear() {
+        this.#entriesMap.clear();
+        this.#sync();
+    }
+    // Updates the snapshot again once the current computation is over, in a
+    // microtask. An entry added in the middle of a computation is in the
+    // snapshot at once, but a computed that read the snapshot earlier in that
+    // computation doesn't hear of it: it only starts listening once its
+    // computation is done. The second update reaches it.
+    notifyLater() {
+        queueMicrotask(() => this.#sync());
+    }
+    addEntry(key, entry) {
+        this.#entriesMap.set(key, entry);
+        this.#sync();
+        return entry;
+    }
+    getEntry(key) {
+        return this.#entriesMap.get(key);
+    }
+    removeEntry(key) {
+        const removed = this.#entriesMap.delete(key);
+        if (removed)
+            this.#sync();
+        return removed;
+    }
+    #sync() {
+        this.#entries.set(Array.from(this.#entriesMap.values()));
+    }
+}
+
 /**
  * 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
@@ -338,10 +464,12 @@ class Query {
     #gcTime = 0;
     #gcTimer = null;
     #cache;
-    constructor({ key, queryHash, cache, gcTime }) {
+    #pendingTasks;
+    constructor({ key, queryHash, cache, gcTime, pendingTasks }) {
         this.key = key;
         this.queryHash = queryHash;
         this.#cache = cache;
+        this.#pendingTasks = pendingTasks;
         this.updateGcTime(gcTime);
         // A new query has nothing using it yet: its creator is about to, and if
         // nothing ever does, gc removes it.
@@ -453,8 +581,12 @@ class Query {
             queryFn,
             abortable: false,
             retriesStopped: false,
+            removeTask: this.#pendingTasks.add(),
         };
         this.#inFlight = inFlight;
+        // Only now that this fetch holds its task: the app mustn't count as
+        // stable in between.
+        running?.removeTask();
         // 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
@@ -535,6 +667,8 @@ class Query {
                 });
                 outcome.resolve(data);
                 this.#scheduleGc();
+                // Last: whatever waits for the app to settle finds the data in.
+                inFlight.removeTask();
             },
             error: (err) => {
                 this.#inFlight = null;
@@ -546,6 +680,7 @@ class Query {
                 }));
                 outcome.reject(err);
                 this.#scheduleGc();
+                inFlight.removeTask();
             },
         }));
         return outcome.promise;
@@ -627,6 +762,7 @@ class Query {
             failureReason: before.failureReason,
             isFetching: false,
         }));
+        inFlight.removeTask();
     }
     // A fetch in flight is kept, as in TanStack, and the observers aren't even
     // asked: fetch() would drop the refetch anyway.
@@ -685,12 +821,28 @@ class Query {
 
 /** @internal */
 class QueryCache extends Cache {
-    getOrCreate(key, gcTime) {
-        const queryHash = hashKey(key);
+    // Handed to each query it creates, which has no injector of its own.
+    #pendingTasks = inject(PendingTasks);
+    constructor() {
+        super();
+        // The cache goes with the injector that provides it. Its queries stop
+        // with it: once nothing can reach them, no fetch of theirs may keep the
+        // app busy, and no timer of theirs may run on.
+        inject(DestroyRef).onDestroy(() => this.clear());
+    }
+    // The hash is the key's, unless the caller brings the one the query had
+    // elsewhere, as a query the server hands over does.
+    getOrCreate(key, gcTime, queryHash = hashKey(key)) {
         const exist = this.getEntry(queryHash);
         if (exist)
             return exist;
-        return this.addEntry(queryHash, new Query({ key, queryHash, cache: this, gcTime }));
+        return this.addEntry(queryHash, new Query({
+            key,
+            queryHash,
+            cache: this,
+            gcTime,
+            pendingTasks: this.#pendingTasks,
+        }));
     }
     get(key) {
         return this.getEntry(hashKey(key));
@@ -731,12 +883,12 @@ class QueryCache extends Cache {
         this.getAll().forEach((query) => query.destroy());
         super.clear();
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: QueryCache, deps: null, target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: QueryCache, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: QueryCache });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: QueryCache, decorators: [{
             type: Injectable
-        }] });
+        }], ctorParameters: () => [] });
 
 /** @internal */
 function getInitialState() {
@@ -762,10 +914,12 @@ class Mutation {
     #observers = 0;
     #options;
     #cache;
-    constructor(mutationId, options, cache) {
+    #pendingTasks;
+    constructor(mutationId, options, cache, pendingTasks) {
         this.mutationId = mutationId;
         this.#options = options;
         this.#cache = cache;
+        this.#pendingTasks = pendingTasks;
     }
     get observerCount() {
         return this.#observers;
@@ -792,6 +946,11 @@ class Mutation {
      */
     execute(variables) {
         const run = deferred();
+        // One of the app's pending tasks, held until the last hook is done:
+        // Angular counts the app as busy meanwhile, so a server render and
+        // whenStable() wait for the run, whatever its mutationFn sends the write
+        // with. A run that outlives its component holds it all the same.
+        const removeTask = this.#pendingTasks.add();
         this.#state.set({
             status: 'pending',
             data: undefined,
@@ -829,6 +988,8 @@ class Mutation {
             else {
                 run.reject(outcome.error);
             }
+            // Last: whatever waits for the app to settle finds the outcome in.
+            removeTask();
         });
         return run.promise;
     }
@@ -901,8 +1062,10 @@ function runHook(hook) {
 /** @internal */
 class MutationCache extends Cache {
     #lastId = 0;
+    // Handed to each mutation it builds, which has no injector of its own.
+    #pendingTasks = inject(PendingTasks);
     build(options) {
-        const mutation = new Mutation(++this.#lastId, options, this);
+        const mutation = new Mutation(++this.#lastId, options, this, this.#pendingTasks);
         this.addEntry(String(mutation.mutationId), mutation);
         return mutation;
     }
@@ -925,6 +1088,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.21", ngImpo
 
 /** @internal */
 const QUERY_CLIENT_CONFIG = new InjectionToken('QUERY_CLIENT_CONFIG');
+/**
+ * Set by {@link withHydration}: the client hands its cache from the server
+ * render over to the browser.
+ *
+ * @internal
+ */
+const QUERY_CLIENT_HYDRATION = new InjectionToken('QUERY_CLIENT_HYDRATION');
 
 const DEFAULT_GC_TIME = 5 * 60 * 1000;
 /**
@@ -964,6 +1134,12 @@ class QueryClient {
     /** @internal */
     constructor() {
         inject(DestroyRef).onDestroy(() => (this.#destroyed = true));
+        // With withHydration(), the cache carries over from the server render.
+        // Here, before anything can read the cache: whatever reads it first, a
+        // component or an app initializer, finds the server's data in it.
+        if (inject(QUERY_CLIENT_HYDRATION, { optional: true })) {
+            transferCache(this.#cache, this.#gcTime());
+        }
         // When the user comes back to the page, or the network comes back, each
         // query refetches if one of its observers wants that. Untracked like the
         // methods: an event fired from an effect mustn't make the effect depend
@@ -1041,7 +1217,9 @@ class QueryClient {
      * if the fetch fails. A cancelled fetch resolves with the data the cache
      * holds, or rejects with a {@link CancelledError} if it holds none; a
      * removed query always rejects with one. Nothing has to wait for the
-     * promise: a prefetch that fails only leaves the query in `'error'`.
+     * promise: a prefetch that fails only leaves the query in `'error'`. A
+     * server render and `whenStable()` wait for the fetch all the same, as for
+     * a component's query, so its data is in the cache by then.
      *
      * Unlike a component's query in the browser, it doesn't retry a failure
      * unless `retry` is set here or in {@link withDefaultOptions}, so whoever
@@ -1226,7 +1404,8 @@ class QueryClient {
      * `refetch()`. A mutation in flight isn't stopped: its write
      * has most likely reached the server, so it finishes and runs its hooks, as
      * when its component goes away, and a component showing it sees how it
-     * went. A hook that writes into the cache puts that key back.
+     * went. The app counts as busy until it's done. A hook that writes into the
+     * cache puts that key back.
      *
      * @example
      * ```ts
@@ -1326,6 +1505,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.21", ngImpo
 var QueryClientFeatureKind;
 (function (QueryClientFeatureKind) {
     QueryClientFeatureKind[QueryClientFeatureKind["DefaultOptions"] = 0] = "DefaultOptions";
+    QueryClientFeatureKind[QueryClientFeatureKind["Hydration"] = 1] = "Hydration";
 })(QueryClientFeatureKind || (QueryClientFeatureKind = {}));
 /** @internal */
 function queryClientFeature(kind, providers) {
@@ -1336,11 +1516,15 @@ function queryClientFeature(kind, providers) {
  * Registers the {@link QueryClient} and its caches for the application.
  *
  * Call once at the app root (in `ApplicationConfig.providers` or a root
- * `bootstrapApplication`). Pass features such as {@link withDefaultOptions} to
- * configure defaults. Registering the same feature twice throws.
+ * `bootstrapApplication`). A client provided by another environment injector
+ * goes with it: once that injector is destroyed, its queries stop, and none
+ * of their fetches keeps the app busy. Pass features such as
+ * {@link withDefaultOptions} to configure defaults, or {@link withHydration}
+ * to bring the data of a server render over to the browser. Registering the
+ * same feature twice throws.
  *
  * @param features - Optional {@link QueryClientFeature}s (e.g.
- *   {@link withDefaultOptions}).
+ *   {@link withDefaultOptions}, {@link withHydration}).
  * @returns Environment providers to add to the app's provider list.
  *
  * @example
@@ -1907,7 +2091,9 @@ function injectQueries(optionsFn, options) {
  * context. Destroying it doesn't cancel a run in flight: the write has most
  * likely reached the server, so the run finishes and fires its hooks. A
  * `mutate()` that comes after that, say from a timer, runs and fires its
- * hooks too.
+ * hooks too. From `mutate()` until its last hook is done, a run keeps the app
+ * busy, whether its component is still there or not: a server render and
+ * `whenStable()` wait for it.
  *
  * Must run in an injection context, or be given an explicit `injector`.
  *
@@ -2178,6 +2364,47 @@ function withDefaultOptions(options) {
     ]);
 }
 
+/**
+ * Feature for {@link provideQueryClient} that brings the data a server render
+ * fetched over to the browser, so the page shows it at once rather than a
+ * loading state. Add it to the providers the server and the browser share. It
+ * works with Angular's `provideClientHydration()` or without it.
+ *
+ * Only queries that succeeded go over, and only data JSON carries as is:
+ * strings, numbers, booleans, `null`, plain objects and arrays. A query whose
+ * data holds a `Date`, a `Map` or a class instance stays on the server, and
+ * the browser fetches it again; in development the server logs a warning
+ * naming it.
+ *
+ * In the browser the data counts as fetched when the server fetched it, and
+ * `staleTime` decides as for any data in the cache: with the default of `0`,
+ * a component refetches its query in the background as it appears, showing
+ * the server's data meanwhile. Set a `staleTime` to skip that request.
+ *
+ * Give it to one client per app: clients provided by other environment
+ * injectors would share one place in the page, and only one of them would get
+ * its data over.
+ *
+ * @returns A {@link QueryClientFeature} to pass to {@link provideQueryClient}.
+ *
+ * @example
+ * ```ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideQueryClient(
+ *       withDefaultOptions({ queries: { staleTime: 30_000 } }),
+ *       withHydration(),
+ *     ),
+ *   ],
+ * }
+ * ```
+ */
+function withHydration() {
+    return queryClientFeature(QueryClientFeatureKind.Hydration, [
+        { provide: QUERY_CLIENT_HYDRATION, useValue: true },
+    ]);
+}
+
 /*
  * Public API Surface of ngx-query
  */
@@ -2186,5 +2413,5 @@ function withDefaultOptions(options) {
  * Generated bundle index. Do not edit.
  */
 
-export { CancelledError, QueryClient, QueryClientFeatureKind, injectIsFetching, injectIsMutating, injectMutation, injectQueries, injectQuery, injectQueryClient, keepPreviousData, mutationOptions, provideQueryClient, queryOptions, withDefaultOptions };
+export { CancelledError, QueryClient, QueryClientFeatureKind, injectIsFetching, injectIsMutating, injectMutation, injectQueries, injectQuery, injectQueryClient, keepPreviousData, mutationOptions, provideQueryClient, queryOptions, withDefaultOptions, withHydration };
 //# sourceMappingURL=ngx-signal-query.mjs.map