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

package/index.d.ts

@@ -1,6 +1,6 @@
 import { Observable } from 'rxjs';
 import * as i0 from '@angular/core';
-import { Signal, Provider, EnvironmentProviders, Injector } from '@angular/core';
+import { Signal, PendingTasks, Provider, EnvironmentProviders, Injector } from '@angular/core';
 
 /** @internal */
 declare abstract class Cache<TEntry> {
@@ -112,7 +112,9 @@ type QueryOptions<TData, TError = Error> = {
      * for no data: `undefined` fails the fetch, with no retry. Once no
      * component shows the query, an `Observable` fetch in flight is
      * unsubscribed, which aborts an `HttpClient` request; a `Promise` one runs
-     * to the end, and its response is kept.
+     * to the end, and its response is kept. Either way, Angular counts the app
+     * as busy until the fetch is done: a server render and `whenStable()` wait
+     * for it.
      */
     queryFn: () => Observable<TData> | Promise<TData>;
     /** How long fetched data stays fresh before refetching, in ms. Default `0`. */
@@ -218,9 +220,10 @@ type QueryResult<TData, TError = Error> = {
     /**
      * When the data was last updated, as a timestamp in ms: when the last
      * response landed or `setQueryData` wrote it; for `initialData`, its
-     * `initialDataUpdatedAt`, or when it was seeded. A refetch that brings the
-     * same data moves it too; one that fails or is cancelled doesn't. `0` while
-     * there is no data, placeholder data included.
+     * `initialDataUpdatedAt`, or when it was seeded; for data a server render
+     * brought over (see {@link withHydration}), when the server fetched it. A
+     * refetch that brings the same data moves it too; one that fails or is
+     * cancelled doesn't. `0` while there is no data, placeholder data included.
      */
     dataUpdatedAt: Signal<number>;
     /** Current {@link QueryStatus}. */
@@ -340,7 +343,8 @@ interface QuerySubscriber<TData, TError = Error> {
 }
 /**
  * What a query is created with: its key and the key's hash, the cache it
- * lives in, and how long it stays there once nothing uses it.
+ * lives in, how long it stays there once nothing uses it, and the app's
+ * pending tasks, one of which each of its fetches holds while in flight.
  *
  * @internal
  */
@@ -349,6 +353,7 @@ interface QueryConfig {
     queryHash: string;
     cache: QueryCache;
     gcTime: number;
+    pendingTasks: Pick<PendingTasks, 'add'>;
 }
 /** @internal */
 declare class Query<TData, TError = Error> {
@@ -356,7 +361,7 @@ declare class Query<TData, TError = Error> {
     readonly key: QueryKey;
     readonly queryHash: string;
     readonly state: i0.Signal<QueryState<TData, TError>>;
-    constructor({ key, queryHash, cache, gcTime }: QueryConfig);
+    constructor({ key, queryHash, cache, gcTime, pendingTasks }: QueryConfig);
     get observerCount(): number;
     updateGcTime(ms: number): void;
     addObserver(observer: QuerySubscriber<TData, TError>): void;
@@ -380,7 +385,9 @@ declare class Query<TData, TError = Error> {
 
 /** @internal */
 declare class QueryCache extends Cache<Query<unknown, unknown>> {
-    getOrCreate<TData, TError = Error>(key: QueryKey, gcTime: number): Query<TData, TError>;
+    #private;
+    constructor();
+    getOrCreate<TData, TError = Error>(key: QueryKey, gcTime: number, queryHash?: string): Query<TData, TError>;
     get<TData, TError = Error>(key: QueryKey): Query<TData, TError> | undefined;
     /**
      * Like get(), but reactive, as findAll() is: a computed or an effect that
@@ -499,7 +506,7 @@ declare class Mutation<TData = unknown, TError = Error, TVariables = void, TCont
     #private;
     readonly mutationId: number;
     readonly state: Signal<MutationState<TData, TError, TVariables, TContext>>;
-    constructor(mutationId: number, options: MutationOptions<TData, TError, TVariables, TContext>, cache: MutationCache);
+    constructor(mutationId: number, options: MutationOptions<TData, TError, TVariables, TContext>, cache: MutationCache, pendingTasks: Pick<PendingTasks, 'add'>);
     get observerCount(): number;
     addObserver(): void;
     /**
@@ -583,7 +590,9 @@ declare 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
@@ -718,7 +727,8 @@ declare 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
@@ -753,7 +763,8 @@ declare class QueryClient {
  * @internal
  */
 declare enum QueryClientFeatureKind {
-    DefaultOptions = 0
+    DefaultOptions = 0,
+    Hydration = 1
 }
 /**
  * An opaque feature passed to {@link provideQueryClient}. Create one with a
@@ -769,11 +780,15 @@ interface QueryClientFeature<K extends QueryClientFeatureKind = QueryClientFeatu
  * 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
@@ -936,7 +951,9 @@ declare function injectQueries<TData, TError = Error>(optionsFn: () => InjectQue
  * 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`.
  *
@@ -1125,5 +1142,42 @@ declare class CancelledError extends Error {
  */
 declare function withDefaultOptions(options: DefaultOptions): QueryClientFeature<QueryClientFeatureKind.DefaultOptions>;
 
-export { CancelledError, QueryClient, QueryClientFeatureKind, injectIsFetching, injectIsMutating, injectMutation, injectQueries, injectQuery, injectQueryClient, keepPreviousData, mutationOptions, provideQueryClient, queryOptions, withDefaultOptions };
+/**
+ * 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(),
+ *     ),
+ *   ],
+ * }
+ * ```
+ */
+declare function withHydration(): QueryClientFeature<QueryClientFeatureKind.Hydration>;
+
+export { CancelledError, QueryClient, QueryClientFeatureKind, injectIsFetching, injectIsMutating, injectMutation, injectQueries, injectQuery, injectQueryClient, keepPreviousData, mutationOptions, provideQueryClient, queryOptions, withDefaultOptions, withHydration };
 export type { DefaultMutationOptions, DefaultOptions, DefaultQueryOptions, DefaultedQueryOptions, InjectQueriesOptions, InvalidateQueryFilters, MutationFilters, MutationOptions, MutationResult, MutationState, MutationStatus, PlaceholderDataFunction, QueryClientFeature, QueryFilters, QueryKey, QueryOptions, QueryResult, QueryState, QueryStatus, RefetchIntervalValue, RetryDelayValue, RetryValue, StructuralSharingValue, Updater };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-signal-query",
-  "version": "1.8.0-dev.1",
+  "version": "1.8.0-dev.3",
   "description": "Data fetching, caching and mutations for Angular, built on signals and RxJS. Observables end to end, TanStack Query concepts.",
   "keywords": [
     "angular",