ngx-signal-query 1.5.0-dev.1 → 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 */
@@ -273,6 +306,9 @@ class Query {
     // 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 structuralSharing of the fetch whose response the query holds.
     #fetchedStructuralSharing;
     #observers = new Set();
@@ -306,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
@@ -338,14 +376,28 @@ class Query {
     }
     // Without a structuralSharing setting the response is stored as is: the
     // default is the client's to resolve.
+    //
+    // Returns a promise of the data as the query stores it, which every caller
+    // that joins the fetch shares. A fetch that replaces this one settles it
+    // 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 } = {}) {
-        if (this.#inFlight()) {
+        const running = this.#outcome;
+        if (running) {
             // Already in-flight: dedupe unless the caller explicitly wants a fresh
-            // fetch (e.g. invalidate/refetch) — then cancel the old one and restart.
+            // fetch (e.g. invalidate/refetch) — then replace the old one.
             if (!cancelRefetch)
-                return;
-            this.cancel();
+                return running.promise;
+            this.#subscription?.unsubscribe();
         }
+        const outcome = deferred();
+        // Its result or error lands in the state either way, so a caller may
+        // ignore the promise: handled here, a failure doesn't surface as an
+        // 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;
         this.#state.update((state) => ({
             ...state,
             isFetching: true,
@@ -377,6 +429,7 @@ class Query {
         map((data) => replaceData(this.state().data, data, structuralSharing)))
             .subscribe({
             next: (data) => {
+                this.#outcome = null;
                 this.#fetchedStructuralSharing = structuralSharing;
                 this.#state.set({
                     data,
@@ -388,14 +441,20 @@ class Query {
                     failureReason: null,
                     updatedAt: Date.now(),
                 });
+                outcome.resolve(data);
+            },
+            error: (err) => {
+                this.#outcome = null;
+                this.#state.update((state) => ({
+                    ...state,
+                    status: 'error',
+                    error: err,
+                    isFetching: false,
+                }));
+                outcome.reject(err);
             },
-            error: (err) => this.#state.update((state) => ({
-                ...state,
-                status: 'error',
-                error: err,
-                isFetching: false,
-            })),
         });
+        return outcome.promise;
     }
     // Without a structuralSharing setting the data is stored as is: which one
     // a write uses is the client's to resolve.
@@ -424,17 +483,18 @@ class Query {
             state.isInvalidated ||
             this.#isStale(staleTime));
     }
+    // Stops the fetch in flight. Whoever waits for it gets the data the query
+    // holds, as in TanStack, or a CancelledError if it holds none.
     cancel() {
-        this.#subscription?.unsubscribe();
-        this.#subscription = null;
-        // The fetch is no longer running; clear the in-flight flag so isFetching
-        // doesn't stay stuck true after a cancellation.
-        if (this.state().isFetching) {
-            this.#state.update((state) => ({ ...state, isFetching: false }));
-        }
+        const { data } = this.state();
+        this.#stop((outcome) => data === undefined
+            ? outcome.reject(new CancelledError())
+            : outcome.resolve(data));
     }
+    // The query is thrown away with its data, so whoever waits for its fetch
+    // gets a CancelledError, as in TanStack.
     destroy() {
-        this.cancel();
+        this.#stop((outcome) => outcome.reject(new CancelledError()));
         this.#clearGcTimer();
     }
     // Inclusive: data fetched exactly `staleTime` ago is already stale. This
@@ -445,7 +505,21 @@ class Query {
         return Date.now() - this.state().updatedAt >= staleTime;
     }
     #inFlight() {
-        return this.#subscription !== null && !this.#subscription.closed;
+        return this.#outcome !== null;
+    }
+    // Stops the fetch in flight, if any, and settles its promise with settle.
+    #stop(settle) {
+        const outcome = this.#outcome;
+        this.#subscription?.unsubscribe();
+        this.#subscription = null;
+        this.#outcome = null;
+        if (outcome)
+            settle(outcome);
+        // The fetch is no longer running; clear the in-flight flag so isFetching
+        // doesn't stay stuck true after a cancellation.
+        if (this.state().isFetching) {
+            this.#state.update((state) => ({ ...state, isFetching: false }));
+        }
     }
     // A fetch in flight is kept, as in TanStack, and the observers aren't even
     // asked: fetch() would drop the refetch anyway.
@@ -551,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;
@@ -577,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,
@@ -607,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) {
@@ -804,24 +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(() => {
-            const defaults = this.#config.defaultOptions?.queries;
-            const staleTime = options.staleTime ?? defaults?.staleTime ?? 0;
-            const retry = options.retry ?? defaults?.retry ?? 3;
-            const retryDelay = options.retryDelay ?? defaults?.retryDelay ?? defaultRetryDelay;
-            const structuralSharing = options.structuralSharing ?? this.#defaultStructuralSharing();
+        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(staleTime)) {
-                query.fetch({ queryFn, retry, retryDelay, structuralSharing }, { cancelRefetch: options.cancelRefetch });
-            }
+            return query.shouldFetch(defaulted.staleTime)
+                ? query.fetch(defaulted, { cancelRefetch })
+                : Promise.resolve(query.state().data);
         });
     }
     /**
@@ -872,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
@@ -884,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.
      *
@@ -1235,18 +1384,19 @@ function createQueryObserver(optionsFn, injector) {
     // Invalidation isn't a trigger: invalidateQueries() refetches each active
     // query once itself. A query it skipped (unobserved, or its observers
     // disabled) stays invalidated, so it fetches here once observed or enabled:
-    // shouldFetch sees the flag.
+    // shouldFetch sees the flag. The key and queryFn come from one read of the
+    // options, so the fetch can't go to another key's query, whatever order the
+    // effects run in.
     track(() => {
         query();
         if (!enabled())
             return;
-        const { queryKey, queryFn, staleTime, retry, retryDelay, structuralSharing, } = untracked(defaultedOptions);
-        untracked(() => client.fetchQuery(queryKey, queryFn, {
-            staleTime,
-            retry,
-            retryDelay,
-            structuralSharing,
-        }));
+        untracked(() => {
+            const options = defaultedOptions();
+            const q = resolve(options.queryKey);
+            if (q.shouldFetch(options.staleTime))
+                q.fetch(options);
+        });
     });
     // The polling interval this observer asks for, or false for none. Memoized,
     // so the polling effect wakes only when the value changes. The function form
@@ -1314,34 +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, cancelling any in-flight
-            // request (explicit user intent — get current data).
-            refetch: () => {
-                const { queryKey, queryFn, retry, retryDelay, structuralSharing } = untracked(defaultedOptions);
-                client.fetchQuery(queryKey, queryFn, {
-                    staleTime: 0,
-                    retry,
-                    retryDelay,
-                    structuralSharing,
-                    cancelRefetch: true,
-                });
-            },
-        },
+        result,
         destroy: () => refs.forEach((ref) => ref.destroy()),
     };
 }
@@ -1517,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.
  *
@@ -1531,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
@@ -1564,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
@@ -1773,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