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

package/README.md

@@ -1,22 +1,39 @@
 # ngx-signal-query
 
 [![npm version](https://img.shields.io/npm/v/ngx-signal-query.svg)](https://www.npmjs.com/package/ngx-signal-query)
+[![bundle size](https://deno.bundlejs.com/badge?q=ngx-signal-query&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22%40angular/core%22%2C%22%40angular/common%22%2C%22rxjs%22%2C%22rxjs/operators%22%2C%22tslib%22%5D%7D%7D)](https://bundlejs.com/?q=ngx-signal-query&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22%40angular/core%22%2C%22%40angular/common%22%2C%22rxjs%22%2C%22rxjs/operators%22%2C%22tslib%22%5D%7D%7D)
 [![license](https://img.shields.io/npm/l/ngx-signal-query.svg)](./LICENSE)
 [![docs](https://img.shields.io/badge/docs-ngx--signal--query-blue)](https://dhutaryan.github.io/ngx-signal-query/)
 
-A tiny, signal-native library for data fetching, caching, and mutations in
-Angular — inspired by [TanStack Query](https://tanstack.com/query). Built
-directly on Angular Signals, with first-class RxJS support: your `queryFn` can
-return an `Observable` (hello `HttpClient`) or a `Promise`.
+A data fetching, caching and mutation library for Angular, built on signals and
+RxJS. Queries and mutations take an `Observable` as is, so `HttpClient` works
+without `lastValueFrom`, and when no component needs a query any more, its
+request is cancelled. The model (query keys, staleness, invalidation) follows
+[TanStack Query](https://tanstack.com/query), so what you know from it carries
+over.
+
+## Why this one
+
+- 🔌 **Observables end to end.** Return `http.get()` from a `queryFn` or `mutationFn`. For a query, unsubscribing is the cancellation: once no component needs it, the request is aborted, with no `AbortSignal` plumbing.
+- 🅰️ **Angular all the way down.** State is signals, configuration is `provideQueryClient(withDefaultOptions(...))`, and default mutation hooks run in an injection context, so a global `onError` can `inject()` what it needs.
+- 🪶 **Small.** About 5 KB min+gzip, tree-shakable ESM, no runtime dependencies beyond `tslib`.
+- 🧭 **Familiar concepts.** `queryKey`, `staleTime`, `invalidateQueries` and `placeholderData` mean what you'd expect. Moving to TanStack Query later is mostly mechanical: wrap Observables in `lastValueFrom` and swap the provider.
 
 ## Features
 
-- 🚦 **Signal-native** — query state is exposed as signals (`data()`, `status()`, …), no manual subscriptions.
-- 🗄️ **Caching & deduplication** — identical query keys share a single in-flight request and cache entry.
-- ✏️ **Mutations** — with `onMutate` / `onSuccess` / `onError` lifecycle for optimistic updates.
-- 🔁 **Retries & polling** — configurable `retry` and `refetchInterval`.
-- 🌍 **Global indicators** — `injectIsFetching()` / `injectIsMutating()` for app-wide loading state.
-- 🪶 **Lean** — ESM, `sideEffects: false`, no runtime deps beyond `tslib`.
+- 🚦 State as signals: read `data()` or `isPending()` in a template or a `computed`, no subscriptions
+- 🗄️ Caching, request deduplication and structural sharing
+- ♻️ Invalidation, cancellation and manual cache updates
+- 🔗 Dependent, parallel (`injectQueries`) and disabled queries
+- 🖼️ Seed and placeholder data while a query loads (`initialData`, `placeholderData`, `keepPreviousData`)
+- 🔁 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()`)
+
+## Not here (yet)
+
+Infinite queries, SSR cache hydration, devtools and persistence. If you need
+them today, TanStack Query has them.
 
 ## Installation
 
@@ -77,26 +94,39 @@ export class TodosComponent {
 }
 ```
 
-## Mutations
+### 3. Mutate and reconcile the cache
+
+`injectMutation` works the same way: call `mutate()`, read `isPending()` /
+`status()` as signals, and invalidate affected queries once it succeeds.
 
 ```ts
-import {
-  mutationOptions,
-  injectMutation,
-  injectQueryClient,
-} from 'ngx-signal-query'
-
-const client = injectQueryClient()
-
-const addTodo = injectMutation(() =>
-  mutationOptions({
-    mutationFn: (title: string) => http.post<Todo>('/api/todos', { title }),
-    onSuccess: () => client.invalidateQueries({ queryKey: ['todos'] }),
-  }),
-)
-
-// in a template
-// <button (click)="addTodo.mutate('Buy milk')" [disabled]="addTodo.isPending()">Add</button>
+import { Component, inject } from '@angular/core'
+import { HttpClient } from '@angular/common/http'
+import { injectMutation, injectQueryClient } from 'ngx-signal-query'
+
+type Todo = { id: number; title: string }
+
+@Component({
+  selector: 'app-add-todo',
+  template: `
+    <button
+      (click)="addTodo.mutate('Buy milk')"
+      [disabled]="addTodo.isPending()"
+    >
+      Add todo
+    </button>
+  `,
+})
+export class AddTodoComponent {
+  private readonly http = inject(HttpClient)
+  private readonly client = injectQueryClient()
+
+  protected readonly addTodo = injectMutation(() => ({
+    mutationFn: (title: string) =>
+      this.http.post<Todo>('/api/todos', { title }),
+    onSuccess: () => this.client.invalidateQueries({ queryKey: ['todos'] }),
+  }))
+}
 ```
 
 ## Documentation

package/fesm2022/ngx-signal-query.mjs

@@ -1,6 +1,54 @@
 import * as i0 from '@angular/core';
-import { signal, Injectable, InjectionToken, inject, EnvironmentInjector, DestroyRef, untracked, runInInjectionContext, makeEnvironmentProviders, assertInInjectionContext, effect, computed, Injector } from '@angular/core';
-import { defer, from, take, retry, timer, throwIfEmpty, map, tap, concatMap, catchError, of, endWith, concat, ignoreElements, EMPTY } from 'rxjs';
+import { inject, PLATFORM_ID, signal, Injectable, InjectionToken, EnvironmentInjector, DestroyRef, untracked, runInInjectionContext, makeEnvironmentProviders, assertInInjectionContext, effect, computed, Injector } from '@angular/core';
+import { DOCUMENT, isPlatformBrowser } from '@angular/common';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { fromEvent, filter, defer, from, take, retry, timer, throwIfEmpty, map, tap, concatMap, catchError, of, endWith, concat, ignoreElements, EMPTY } from 'rxjs';
+
+/**
+ * Calls `listener` whenever the user comes back to the page, as the tab or
+ * the window turns visible again. The window's `focus` event isn't used: it
+ * also fires when an alert or a file picker closes, or on coming back from
+ * DevTools, with the user on the page all along.
+ *
+ * Listens until the current injector is destroyed, and only in the browser:
+ * on the server there is no page to come back to. Must run in an injection
+ * context.
+ *
+ * @internal
+ */
+function onWindowFocus(listener) {
+    if (!inBrowser())
+        return;
+    const document = inject(DOCUMENT);
+    fromEvent(document, 'visibilitychange')
+        .pipe(filter(() => document.visibilityState !== 'hidden'), takeUntilDestroyed())
+        .subscribe(() => listener());
+}
+/**
+ * Calls `listener` whenever the browser reports that the network is back
+ * (`online`). Each such event means it was off: the browser fires it only
+ * when going from offline to online, a page opened offline included.
+ *
+ * Listens until the current injector is destroyed, and only in the browser.
+ * Must run in an injection context.
+ *
+ * @internal
+ */
+function onReconnect(listener) {
+    if (!inBrowser())
+        return;
+    const window = inject(DOCUMENT).defaultView;
+    if (!window)
+        return;
+    fromEvent(window, 'online')
+        .pipe(takeUntilDestroyed())
+        .subscribe(() => listener());
+}
+// On the server, DOCUMENT is an emulated document that has listeners,
+// a window and no visibilityState: only the platform tells.
+function inBrowser() {
+    return isPlatformBrowser(inject(PLATFORM_ID));
+}
 
 /** @internal */
 class Cache {
@@ -206,6 +254,28 @@ 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;
@@ -225,6 +295,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();
@@ -268,6 +341,17 @@ class Query {
         }
         return null;
     }
+    // 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
+    // the data is stale for its staleTime. The first such observer decides
+    // how, as in TanStack.
+    onFocus() {
+        this.#refetchOn('refetchOnWindowFocus');
+    }
+    // The same once the network is back, by refetchOnReconnect.
+    onOnline() {
+        this.#refetchOn('refetchOnReconnect');
+    }
     // How data written into the query by hand merges with what it holds: as
     // its first observer says, enabled or not; with none, the way its data was
     // fetched; undefined if neither has a say.
@@ -279,14 +363,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.#subscription && !this.#subscription.closed) {
+        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,
@@ -318,6 +416,7 @@ class Query {
         map((data) => replaceData(this.state().data, data, structuralSharing)))
             .subscribe({
             next: (data) => {
+                this.#outcome = null;
                 this.#fetchedStructuralSharing = structuralSharing;
                 this.#state.set({
                     data,
@@ -329,14 +428,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.
@@ -365,17 +470,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
@@ -385,6 +491,38 @@ class Query {
     #isStale(staleTime) {
         return Date.now() - this.state().updatedAt >= staleTime;
     }
+    #inFlight() {
+        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.
+    #refetchOn(option) {
+        if (this.#inFlight())
+            return;
+        for (const observer of this.#observers) {
+            const options = observer.fetchOptions();
+            if (!options || options[option] === false)
+                continue;
+            if (options[option] === 'always' || this.shouldFetch(options.staleTime)) {
+                this.fetch(options);
+                return;
+            }
+        }
+    }
     #scheduleGc() {
         this.#clearGcTimer();
         this.#gcTimer = setTimeout(() => {
@@ -671,6 +809,12 @@ class QueryClient {
     /** @internal */
     constructor() {
         inject(DestroyRef).onDestroy(() => (this.#destroyed = true));
+        // 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
+        // on what the refetch reads.
+        onWindowFocus(() => untracked(() => this.#cache.getAll().forEach((query) => query.onFocus())));
+        onReconnect(() => untracked(() => this.#cache.getAll().forEach((query) => query.onOnline())));
     }
     /** Returns the underlying query cache. Advanced/internal use. */
     getQueryCache() {
@@ -682,8 +826,9 @@ class QueryClient {
     }
     /**
      * Merges per-query options with the configured defaults, filling in
-     * `staleTime`, `gcTime`, `retry`, `retryDelay` and `structuralSharing`.
-     * Used internally by {@link injectQuery}.
+     * `staleTime`, `gcTime`, `retry`, `retryDelay`, `structuralSharing`,
+     * `refetchOnWindowFocus` and `refetchOnReconnect`. Used internally by
+     * {@link injectQuery}.
      */
     defaultQueryOptions(options) {
         const defaults = this.#config.defaultOptions?.queries;
@@ -694,6 +839,8 @@ class QueryClient {
             retry: options.retry ?? defaults?.retry ?? 3,
             retryDelay: options.retryDelay ?? defaults?.retryDelay ?? defaultRetryDelay,
             structuralSharing: options.structuralSharing ?? this.#defaultStructuralSharing(),
+            refetchOnWindowFocus: options.refetchOnWindowFocus ?? defaults?.refetchOnWindowFocus ?? true,
+            refetchOnReconnect: options.refetchOnReconnect ?? defaults?.refetchOnReconnect ?? true,
         };
     }
     /**
@@ -727,14 +874,17 @@ class QueryClient {
      */
     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();
+            // 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.
+            const { cancelRefetch, ...queryOptions } = options;
+            const defaulted = this.defaultQueryOptions({
+                ...queryOptions,
+                queryKey: key,
+                queryFn,
+            });
             const query = this.#cache.getOrCreate(key);
-            if (query.shouldFetch(staleTime)) {
-                query.fetch({ queryFn, retry, retryDelay, structuralSharing }, { cancelRefetch: options.cancelRefetch });
+            if (query.shouldFetch(defaulted.staleTime)) {
+                query.fetch(defaulted, { cancelRefetch });
             }
         });
     }
@@ -1102,17 +1252,26 @@ function createQueryObserver(optionsFn, injector) {
             return;
         switchTo(untracked(() => resolve(entry.key)));
     });
-    // How this observer would fetch q right now, from the live options; null
-    // while it is disabled, or once the key has moved on. Before the key effect
-    // above catches up, queryFn already fetches the next query's data, so q
-    // must not be fetched with it. Both refetches made on our behalf go by it:
-    // the invalidation one (through q's subscriber handle) and polling.
+    // How this observer would fetch q right now, and when it wants q
+    // refetched, from the live options; null while it is disabled, or once the
+    // key has moved on. Before the key effect above catches up, queryFn already
+    // fetches the next query's data, so q must not be fetched with it. Every
+    // refetch made on our behalf goes by it: through q's subscriber handle the
+    // invalidation one and the window focus and reconnect ones, and polling.
     const fetchOptionsFor = (q) => {
-        const { queryKey, queryFn, retry, retryDelay, structuralSharing, enabled } = untracked(defaultedOptions);
+        const { queryKey, queryFn, retry, retryDelay, structuralSharing, staleTime, refetchOnWindowFocus, refetchOnReconnect, enabled, } = untracked(defaultedOptions);
         if (enabled === false || hashKey(queryKey) !== q.queryHash) {
             return null;
         }
-        return { queryFn, retry, retryDelay, structuralSharing };
+        return {
+            queryFn,
+            retry,
+            retryDelay,
+            structuralSharing,
+            staleTime,
+            refetchOnWindowFocus,
+            refetchOnReconnect,
+        };
     };
     track((cleanup) => {
         const q = query();
@@ -1140,18 +1299,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
@@ -1234,18 +1394,14 @@ function createQueryObserver(optionsFn, injector) {
             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,
-                });
-            },
+            // 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 });
+            }),
         },
         destroy: () => refs.forEach((ref) => ref.destroy()),
     };