ngx-signal-query 1.8.0-dev.2 → 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, PendingTasks, DestroyRef, Injectable, InjectionToken, EnvironmentInjector, 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
@@ -704,8 +830,9 @@ class QueryCache extends Cache {
         // app busy, and no timer of theirs may run on.
         inject(DestroyRef).onDestroy(() => this.clear());
     }
-    getOrCreate(key, gcTime) {
-        const queryHash = hashKey(key);
+    // 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;
@@ -961,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;
 /**
@@ -1000,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
@@ -1365,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) {
@@ -1378,11 +1519,12 @@ function queryClientFeature(kind, providers) {
  * `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. Registering the same
- * feature twice throws.
+ * {@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
@@ -2222,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
  */
@@ -2230,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