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

package/index.d.ts

@@ -18,7 +18,10 @@ declare abstract class Cache<TEntry> {
  * array, from broad to specific, e.g. `['todos']` or `['todo', id]`.
  */
 type QueryKey = readonly unknown[];
-/** Lifecycle status of a query: no data yet, resolved, or failed. */
+/**
+ * Lifecycle status of a query: no data yet (the first load, or a new attempt
+ * after a failure), resolved, or failed.
+ */
 type QueryStatus = 'pending' | 'success' | 'error';
 /** Full state snapshot of a query (the reactive source behind {@link QueryResult}). */
 interface QueryState<TData, TError = Error> {
@@ -26,7 +29,11 @@ interface QueryState<TData, TError = Error> {
     data: TData | undefined;
     /** Current {@link QueryStatus}. */
     status: QueryStatus;
-    /** Last error, or `null` if the latest attempt did not fail. */
+    /**
+     * The error the last fetch failed with, or `null`. A query with no data
+     * clears it when it fetches again; one with data keeps it until the next
+     * response.
+     */
     error: TError | null;
     /** Whether a fetch is currently in flight. */
     isFetching: boolean;
@@ -46,6 +53,16 @@ type QueryFilters = {
     /** Require an exact key match instead of a prefix match. */
     exact?: boolean;
 };
+/** Selects which queries `invalidateQueries` marks stale, and what it refetches. */
+type InvalidateQueryFilters = QueryFilters & {
+    /**
+     * Which of the marked queries to refetch now: `'active'`, the default,
+     * refetches those a component shows; `'none'` refetches none, so each one
+     * refetches when stale data next would, e.g. as a component starts showing
+     * it. Queries nobody shows are only marked either way.
+     */
+    refetchType?: 'active' | 'none';
+};
 /** A new value, or a function deriving it from the previous one. */
 type Updater<TInput, TOutput> = TOutput | ((input: TInput) => TOutput);
 /**
@@ -166,11 +183,18 @@ type QueryResult<TData, TError = Error> = {
     data: Signal<TData | undefined>;
     /** Current {@link QueryStatus}. */
     status: Signal<QueryStatus>;
-    /** Last error, or `null`. */
+    /**
+     * The error the last fetch failed with, or `null`. It's cleared while a
+     * query with no data is tried again, and kept while one with data
+     * refetches.
+     */
     error: Signal<TError | null>;
     /** Whether a fetch is in flight (including background refetches). */
     isFetching: Signal<boolean>;
-    /** Whether the first fetch is in flight with no data yet (`isFetching && pending`). */
+    /**
+     * Whether a fetch is in flight with no data to show: the first one, or a
+     * new attempt after a failure (`isFetching && pending`).
+     */
     isLoading: Signal<boolean>;
     /** Whether status is `'pending'` (no data resolved yet). */
     isPending: Signal<boolean>;
@@ -184,8 +208,16 @@ type QueryResult<TData, TError = Error> = {
     failureCount: Signal<number>;
     /** Error of the most recent failed attempt, or `null`. */
     failureReason: Signal<TError | null>;
-    /** Forces a fresh fetch, cancelling any in-flight request. */
-    refetch: () => void;
+    /**
+     * Forces a fresh fetch, cancelling any in-flight request. Resolves once the
+     * fetch has settled, or the fetch that replaced it has, with `data` and
+     * `error` as the signals above hold them then. It never rejects: a failure
+     * shows in `error`.
+     */
+    refetch: () => Promise<{
+        data: TData | undefined;
+        error: TError | null;
+    }>;
 };
 /** Default query options applied to every query unless overridden per-query. */
 interface DefaultQueryOptions {
@@ -265,7 +297,7 @@ declare class Query<TData, TError = Error> {
     setGcTime(ms: number): void;
     addObserver(observer: QuerySubscriber<TData, TError>): void;
     removeObserver(observer: QuerySubscriber<TData, TError>): void;
-    activeFetchOptions(): ReturnType<QuerySubscriber<TData, TError>['fetchOptions']>;
+    refetchIfActive(): Promise<TData> | undefined;
     onFocus(): void;
     onOnline(): void;
     structuralSharing(): StructuralSharingValue<TData> | undefined;
@@ -364,6 +396,14 @@ type MutationOptions<TData, TError, TVariables, TContext> = {
 type MutationResult<TData, TError, TVariables> = {
     /** Triggers the mutation with the given variables. */
     mutate: (variables: TVariables) => void;
+    /**
+     * Triggers the mutation as `mutate()` does, and returns a promise of that
+     * run: it resolves with the data once the last hook is done, or rejects
+     * with the error once `onError` and `onSettled` are. Unlike `mutate()`, a
+     * failure nobody catches surfaces as an unhandled rejection, as with any
+     * async call.
+     */
+    mutateAsync: (variables: TVariables) => Promise<TData>;
     /**
      * Resets the state to `idle`. It forgets the result and doesn't stop the
      * request: a run in flight finishes and fires its hooks.
@@ -405,8 +445,12 @@ declare class Mutation<TData = unknown, TError = Error, TVariables = void, TCont
      * settled and been abandoned — whichever of the two happens last.
      */
     removeObserver(): void;
-    /** Runs the mutation once. `variables` are passed straight to `mutationFn`. */
-    execute(variables: TVariables): void;
+    /**
+     * 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: TVariables): Promise<TData>;
     cancel(): void;
 }
 
@@ -463,12 +507,38 @@ declare 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<TData>(key: QueryKey, queryFn: () => Observable<TData> | Promise<TData>, options?: {
         staleTime?: number;
@@ -476,7 +546,7 @@ declare class QueryClient {
         retryDelay?: RetryDelayValue<any>;
         structuralSharing?: StructuralSharingValue<TData>;
         cancelRefetch?: boolean;
-    }): void;
+    }): Promise<TData>;
     /**
      * Reads the current cached data for a query key, or `undefined` if the query
      * is not cached yet. A snapshot: it doesn't update a template, a `computed`
@@ -510,20 +580,46 @@ declare 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
      * client.invalidateQueries({ queryKey: ['todos'] })
      * ```
      */
-    invalidateQueries(filters?: QueryFilters): void;
+    invalidateQueries(filters?: InvalidateQueryFilters): Promise<void>;
+    /**
+     * 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?: QueryFilters): Promise<void>;
     /**
-     * Cancels any in-flight fetches for matching queries.
+     * Cancels any in-flight fetches for matching queries. Each query goes back
+     * to how it was before its fetch: one that failed and was being tried
+     * again shows its error again. Data written meanwhile stays, and so does a
+     * stale mark from `invalidateQueries()`.
      *
      * @param filters - Which queries to cancel; omit to cancel all.
      */
@@ -737,9 +833,11 @@ declare function injectQueries<TData, TError = Error>(optionsFn: () => InjectQue
  * 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.
  *
@@ -751,8 +849,8 @@ declare function injectQueries<TData, TError = Error>(optionsFn: () => InjectQue
  * @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
@@ -892,6 +990,20 @@ declare function keepPreviousData<TData>(previousData: TData | undefined): TData
  */
 declare function mutationOptions<TData, TError = Error, TVariables = void, TContext = unknown>(options: MutationOptions<TData, TError, TVariables, TContext>): MutationOptions<TData, TError, TVariables, TContext>;
 
+/**
+ * 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.
+ */
+declare class CancelledError extends Error {
+    constructor(message?: string);
+}
+
 /**
  * Feature for {@link provideQueryClient} that sets application-wide default
  * query and mutation options. A query's or mutation's own options take
@@ -914,5 +1026,5 @@ declare function mutationOptions<TData, TError = Error, TVariables = void, TCont
  */
 declare function withDefaultOptions(options: DefaultOptions): QueryClientFeature<QueryClientFeatureKind.DefaultOptions>;
 
-export { QueryClient, QueryClientFeatureKind, injectIsFetching, injectIsMutating, injectMutation, injectQueries, injectQuery, injectQueryClient, keepPreviousData, mutationOptions, provideQueryClient, queryOptions, withDefaultOptions };
-export type { DefaultMutationOptions, DefaultOptions, DefaultQueryOptions, DefaultedQueryOptions, InjectQueriesOptions, MutationFilters, MutationOptions, MutationResult, MutationState, MutationStatus, PlaceholderDataFunction, QueryClientFeature, QueryFilters, QueryKey, QueryOptions, QueryResult, QueryState, QueryStatus, RefetchIntervalValue, RetryDelayValue, RetryValue, StructuralSharingValue, Updater };
+export { CancelledError, QueryClient, QueryClientFeatureKind, injectIsFetching, injectIsMutating, injectMutation, injectQueries, injectQuery, injectQueryClient, keepPreviousData, mutationOptions, provideQueryClient, queryOptions, withDefaultOptions };
+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.5.0-dev.2",
+  "version": "1.5.0-dev.4",
   "description": "Data fetching, caching and mutations for Angular, built on signals and RxJS. Observables end to end, TanStack Query concepts.",
   "keywords": [
     "angular",