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

package/fesm2022/ngx-signal-query.mjs

@@ -232,6 +232,39 @@ function isValidTimeout(value) {
 function isPromiseLike(value) {
     return typeof value?.then === 'function';
 }
+// Resolves once every promise has settled, and never rejects. It resolves
+// with nothing: what the promises brought isn't the caller's to see.
+/** @internal */
+function whenAllSettled(promises) {
+    return Promise.allSettled(promises).then(() => undefined);
+}
+/** @internal */
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+
+/**
+ * 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`.
+ *
+ * A mutation's `mutateAsync()` rejects with one too, when the mutation cache
+ * is cleared while its run is in flight.
+ */
+class CancelledError extends Error {
+    constructor(message = 'The query fetch was cancelled') {
+        super(message);
+        this.name = 'CancelledError';
+    }
+}
 
 // Exponential backoff capped at 30s, matching TanStack's default.
 /** @internal */
@@ -254,28 +287,6 @@ function resolveRetryDelay(retryDelay, failureCount, error) {
 }
 
 const DEFAULT_GC_TIME = 5 * 60 * 1000;
-/**
- * What the promise of a query's fetch rejects with when the fetch stops with
- * no data to give: cancelled before the query had any, or thrown away with
- * the query.
- *
- * @internal
- */
-class CancelledError extends Error {
-    constructor() {
-        super('The query fetch was cancelled');
-        this.name = 'CancelledError';
-    }
-}
-function deferred() {
-    let resolve;
-    let reject;
-    const promise = new Promise((res, rej) => {
-        resolve = res;
-        reject = rej;
-    });
-    return { promise, resolve, reject };
-}
 /** @internal */
 class Query {
     key;
@@ -331,15 +342,17 @@ class Query {
             this.#scheduleGc();
         }
     }
-    // How to refetch this query on its observers' behalf: the first observer
-    // that wants it fetched decides, as in TanStack; null if none does.
-    activeFetchOptions() {
+    // Refetches the query if a component shows it: the first observer that
+    // wants it fetched decides how, as in TanStack. A fetch in flight is
+    // replaced, as it may predate the change the caller is after. Returns the
+    // fetch's promise, or undefined if no observer wants the query fetched.
+    refetchIfActive() {
         for (const observer of this.#observers) {
             const options = observer.fetchOptions();
             if (options)
-                return options;
+                return this.fetch(options, { cancelRefetch: true });
         }
-        return null;
+        return;
     }
     // Refetches the query now that the user is back on the page, if one of its
     // observers wants that: its refetchOnWindowFocus is 'always', or true while
@@ -612,6 +625,9 @@ class Mutation {
     // eslint-disable-next-line @typescript-eslint/member-ordering
     state = this.#state.asReadonly();
     #subscription = null;
+    // The promise of the run in flight and how to settle it; null once it has
+    // settled, or before the run.
+    #run = null;
     #observers = 0;
     #options;
     #cache;
@@ -638,8 +654,14 @@ class Mutation {
         this.#observers--;
         this.#disposeIfDone();
     }
-    /** Runs the mutation once. `variables` are passed straight to `mutationFn`. */
+    /**
+     * Runs the mutation once. `variables` are passed straight to `mutationFn`.
+     * Returns a promise of the run, settled as the state is, once its last hook
+     * is done: with the data, or with the error.
+     */
     execute(variables) {
+        const run = deferred();
+        this.#run = run;
         this.#state.set({
             status: 'pending',
             data: undefined,
@@ -668,12 +690,24 @@ class Mutation {
         })), concatMap((outcome) => this.#runHooks(outcome, variables).pipe(endWith(outcome))))
             .subscribe((outcome) => {
             this.#state.update((state) => ({ ...state, ...outcome }));
+            this.#run = null;
             this.#disposeIfDone();
+            if (outcome.status === 'success') {
+                run.resolve(outcome.data);
+            }
+            else {
+                run.reject(outcome.error);
+            }
         });
+        return run.promise;
     }
+    // Whoever waits for the run hears that it was cancelled, so its promise
+    // doesn't hang.
     cancel() {
         this.#subscription?.unsubscribe();
         this.#subscription = null;
+        this.#run?.reject(new CancelledError('The mutation was cancelled'));
+        this.#run = null;
     }
     /** Sends the write, retrying as `retry` allows, and emits its data once. */
     #request(variables) {
@@ -865,27 +899,58 @@ class QueryClient {
     /**
      * Imperatively fetches and caches a query, unless fresh data already exists
      * (governed by `staleTime`). Prefer {@link injectQuery} in components; use
-     * this to prefetch, from an event handler or an effect.
+     * this to prefetch, from an event handler or an effect, or to wait for the
+     * data, e.g. in a route resolver.
+     *
+     * Resolves with the data as the cache holds it: at once if it's fresh,
+     * otherwise once the fetch lands. A key already fetching is waited for,
+     * not fetched again, unless `cancelRefetch` is set. Rejects with the error
+     * 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'`.
+     *
+     * Unlike a component's query, it doesn't retry a failure unless `retry` is
+     * set here or in {@link withDefaultOptions}, so whoever waits for the data
+     * hears of the failure at once.
      *
      * @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`,
      *   `structuralSharing`, `cancelRefetch`).
+     * @returns A promise of the data.
+     *
+     * @example
+     * ```ts
+     * export const todoResolver: ResolveFn<Todo> = (route) => {
+     *   const http = inject(HttpClient)
+     *   const id = Number(route.paramMap.get('id'))
+     *
+     *   return injectQueryClient().fetchQuery(['todos', id], () =>
+     *     http.get<Todo>(`/api/todos/${id}`),
+     *   )
+     * }
+     * ```
      */
     fetchQuery(key, queryFn, options = {}) {
-        untracked(() => {
-            // Resolved as a query's options are, so one set of defaults serves both.
-            // cancelRefetch is about this call, not an option of the query.
+        return untracked(() => {
+            // Resolved as a query's options are, so one set of defaults serves
+            // both, except that a failure isn't retried unless asked: whoever waits
+            // for the data hears of it at once. cancelRefetch is about this call,
+            // not an option of the query.
             const { cancelRefetch, ...queryOptions } = options;
             const defaulted = this.defaultQueryOptions({
                 ...queryOptions,
                 queryKey: key,
                 queryFn,
+                retry: queryOptions.retry ??
+                    this.#config.defaultOptions?.queries?.retry ??
+                    false,
             });
             const query = this.#cache.getOrCreate(key);
-            if (query.shouldFetch(defaulted.staleTime)) {
-                query.fetch(defaulted, { cancelRefetch });
-            }
+            return query.shouldFetch(defaulted.staleTime)
+                ? query.fetch(defaulted, { cancelRefetch })
+                : Promise.resolve(query.state().data);
         });
     }
     /**
@@ -936,11 +1001,16 @@ class QueryClient {
      * Marks matching queries as stale and refetches the actively observed ones,
      * once per query however many components observe it. The refetch starts
      * right away and replaces a fetch already in flight, which may predate the
-     * change; this method doesn't wait for it. A query with no enabled observer
-     * keeps the stale mark and refetches as soon as one appears. Commonly called
-     * after a mutation succeeds.
+     * change. A query with no enabled observer keeps the stale mark and
+     * refetches as soon as one appears. Commonly called after a mutation
+     * succeeds.
+     *
+     * Resolves once those refetches have settled, so a mutation hook that
+     * returns it keeps the mutation pending until the data is fresh. It never
+     * rejects: a refetch that fails shows in its query's `error`.
      *
      * @param filters - Which queries to invalidate; omit to invalidate all.
+     *   `refetchType: 'none'` only marks them, and resolves at once.
      *
      * @example
      * ```ts
@@ -948,21 +1018,36 @@ class QueryClient {
      * ```
      */
     invalidateQueries(filters) {
-        untracked(() => {
+        return untracked(() => {
             const queries = this.#cache.findAll(filters);
             queries.forEach((query) => query.invalidate());
-            // Refetch each active query once, however many observers watch it; an
-            // inactive one refetches when next observed, as shouldFetch sees the
-            // flag. cancelRefetch: a fetch already in flight started before the
-            // invalidation, so it may have missed the change.
-            queries.forEach((query) => {
-                const options = query.activeFetchOptions();
-                if (options) {
-                    query.fetch(options, { cancelRefetch: true });
-                }
-            });
+            // An inactive query refetches when next observed, as shouldFetch sees
+            // the flag.
+            return filters?.refetchType === 'none'
+                ? Promise.resolve()
+                : whenAllSettled(queries.map((query) => query.refetchIfActive()));
         });
     }
+    /**
+     * Refetches the matching queries that a component shows, whether their
+     * data is stale or not, once per query however many components show it. A
+     * fetch already in flight is replaced. Queries nobody shows are left as
+     * they are, not even marked stale: to have them refetch once they're shown,
+     * invalidate them with `invalidateQueries()`.
+     *
+     * Resolves once the refetches have settled. It never rejects: a refetch
+     * that fails shows in its query's `error`.
+     *
+     * @param filters - Which queries to refetch; omit to refetch all.
+     *
+     * @example
+     * ```ts
+     * await client.refetchQueries({ queryKey: ['todos'] })
+     * ```
+     */
+    refetchQueries(filters) {
+        return untracked(() => whenAllSettled(this.#cache.findAll(filters).map((query) => query.refetchIfActive())));
+    }
     /**
      * Cancels any in-flight fetches for matching queries.
      *
@@ -1379,30 +1464,37 @@ function createQueryObserver(optionsFn, injector) {
         }
         return { data: state.data, status: state.status, isPlaceholderData: false };
     }, ...(ngDevMode ? [{ debugName: "resolved" }] : []));
+    const result = {
+        data: computed(() => resolved().data),
+        status: computed(() => resolved().status),
+        error: computed(() => query().state().error),
+        isFetching: computed(() => query().state().isFetching),
+        // First fetch in-flight: fetching with no resolved data yet. An active
+        // placeholder counts as data — the UI shows it, not a loading state.
+        isLoading: computed(() => query().state().isFetching && resolved().status === 'pending'),
+        isPending: computed(() => resolved().status === 'pending'),
+        isSuccess: computed(() => resolved().status === 'success'),
+        isError: computed(() => resolved().status === 'error'),
+        isPlaceholderData: computed(() => resolved().isPlaceholderData),
+        failureCount: computed(() => query().state().failureCount),
+        failureReason: computed(() => query().state().failureReason),
+        // Force a fresh fetch regardless of staleTime and enabled, cancelling
+        // any in-flight request (explicit user intent — get current data).
+        // Untracked, as the client's methods are: called from an effect, it
+        // mustn't make the effect depend on the options or on the query. However
+        // the fetch ends, the signals show it, so the promise resolves with their
+        // data and error and never rejects.
+        refetch: () => untracked(() => {
+            const options = defaultedOptions();
+            return resolve(options.queryKey).fetch(options, {
+                cancelRefetch: true,
+            });
+        })
+            .catch(() => undefined)
+            .then(() => ({ data: result.data(), error: result.error() })),
+    };
     return {
-        result: {
-            data: computed(() => resolved().data),
-            status: computed(() => resolved().status),
-            error: computed(() => query().state().error),
-            isFetching: computed(() => query().state().isFetching),
-            // First fetch in-flight: fetching with no resolved data yet. An active
-            // placeholder counts as data — the UI shows it, not a loading state.
-            isLoading: computed(() => query().state().isFetching && resolved().status === 'pending'),
-            isPending: computed(() => resolved().status === 'pending'),
-            isSuccess: computed(() => resolved().status === 'success'),
-            isError: computed(() => resolved().status === 'error'),
-            isPlaceholderData: computed(() => resolved().isPlaceholderData),
-            failureCount: computed(() => query().state().failureCount),
-            failureReason: computed(() => query().state().failureReason),
-            // Force a fresh fetch regardless of staleTime and enabled, cancelling
-            // any in-flight request (explicit user intent — get current data).
-            // Untracked, as the client's methods are: called from an effect, it
-            // mustn't make the effect depend on the options or on the query.
-            refetch: () => untracked(() => {
-                const options = defaultedOptions();
-                resolve(options.queryKey).fetch(options, { cancelRefetch: true });
-            }),
-        },
+        result,
         destroy: () => refs.forEach((ref) => ref.destroy()),
     };
 }
@@ -1578,9 +1670,11 @@ function injectQueries(optionsFn, options) {
  * until it settles. Mutations do not retry by default (a retried write is not
  * idempotent); opt in via `options.retry`. Whatever of `retry`, `retryDelay`
  * and the `onSuccess` / `onError` / `onSettled` hooks a mutation leaves unset
- * comes from {@link withDefaultOptions}. `mutate()` and `reset()` are safe
- * to call from an effect: neither makes the effect depend on what it reads,
- * such as the options or the previous run. Bound to the current injection
+ * comes from {@link withDefaultOptions}. `mutateAsync(variables)` runs it
+ * the same way and returns a promise of the run's data. `mutate()`,
+ * `mutateAsync()` and `reset()` are safe to call from an effect: none makes
+ * the effect depend on what it reads, such as the options or the previous
+ * run. Bound to the current injection
  * 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.
  *
@@ -1592,8 +1686,8 @@ function injectQueries(optionsFn, options) {
  * @typeParam TContext - Type returned by `onMutate`, passed to later hooks.
  * @param optionsFn - Factory returning the {@link MutationOptions}.
  * @param options - Optional `injector` to use outside an injection context.
- * @returns A {@link MutationResult}: `mutate()`, `reset()`, and state signals
- *   (`status`, `data`, `error`, `isPending`, …).
+ * @returns A {@link MutationResult}: `mutate()`, `mutateAsync()`, `reset()`,
+ *   and state signals (`status`, `data`, `error`, `isPending`, …).
  *
  * @example
  * ```ts
@@ -1625,23 +1719,32 @@ function injectMutation(optionsFn, options) {
         inject(DestroyRef).onDestroy(() => untracked(current)?.removeObserver());
         const state = computed(() => current()?.state() ??
             getInitialState(), ...(ngDevMode ? [{ debugName: "state" }] : []));
+        // mutate(), mutateAsync() and reset() run untracked, as the QueryClient's
+        // methods do. A call made from an effect mustn't make the effect depend on
+        // what they read to do their job: the previous run's state, the options,
+        // or what onMutate and mutationFn read. Otherwise a change to any of them
+        // re-runs the effect, and the effect repeats the call.
+        //
+        // Starts a run for mutate() and mutateAsync(), makes it the run the
+        // signals below follow, and returns its promise.
+        const start = (variables) => untracked(() => {
+            // Stop observing the previous run. It isn't cancelled — if it's
+            // still in flight it finishes and fires its hooks; it just no longer
+            // feeds the signals below.
+            current()?.removeObserver();
+            // Options are read per call, so a signal used in them stays live.
+            const run = cache.build(client.defaultMutationOptions(optionsFn()));
+            run.addObserver();
+            current.set(run);
+            return run.execute(variables);
+        });
         return {
-            // mutate() and reset() run untracked, as the QueryClient's methods do. A
-            // call made from an effect mustn't make the effect depend on what they
-            // read to do their job: the previous run's state, the options, or what
-            // onMutate and mutationFn read. Otherwise a change to any of them
-            // re-runs the effect, and the effect repeats the call.
-            mutate: (variables) => untracked(() => {
-                // Stop observing the previous run. It isn't cancelled — if it's
-                // still in flight it finishes and fires its hooks; it just no longer
-                // feeds the signals below.
-                current()?.removeObserver();
-                // Options are read per call, so a signal used in them stays live.
-                const run = cache.build(client.defaultMutationOptions(optionsFn()));
-                run.addObserver();
-                current.set(run);
-                run.execute(variables);
-            }),
+            // The outcome shows in the signals; a failure mustn't surface as an
+            // unhandled rejection too.
+            mutate: (variables) => {
+                start(variables).catch(() => undefined);
+            },
+            mutateAsync: start,
             reset: () => untracked(() => {
                 // "Forget the result", not "stop the request". A run still in
                 // flight keeps going and fires its hooks, so the cache stays in step
@@ -1834,5 +1937,5 @@ function withDefaultOptions(options) {
  * Generated bundle index. Do not edit.
  */
 
-export { 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 };
 //# sourceMappingURL=ngx-signal-query.mjs.map