ngx-signal-query 1.0.0-dev.1

package/fesm2022/ngx-signal-query.mjs

@@ -0,0 +1,1003 @@
+import * as i0 from '@angular/core';
+import { signal, Injectable, InjectionToken, inject, makeEnvironmentProviders, assertInInjectionContext, Injector, runInInjectionContext, computed, untracked, effect, DestroyRef } from '@angular/core';
+import { defer, from, take, retry, timer, throwIfEmpty } from 'rxjs';
+
+class Cache {
+    #entries = signal([], ...(ngDevMode ? [{ debugName: "#entries" }] : []));
+    // Reactive snapshot of all entries; updated on add/remove/clear so that
+    // findAll() (and its computed consumers like isFetching) react to the
+    // collection. Protected: only subclasses read it, never external code.
+    entries = this.#entries.asReadonly();
+    #entriesMap = new Map();
+    getAll() {
+        return Array.from(this.#entriesMap.values());
+    }
+    clear() {
+        this.#entriesMap.clear();
+        this.#sync();
+    }
+    addEntry(key, entry) {
+        this.#entriesMap.set(key, entry);
+        this.#sync();
+        return entry;
+    }
+    getEntry(key) {
+        return this.#entriesMap.get(key);
+    }
+    removeEntry(key) {
+        const removed = this.#entriesMap.delete(key);
+        if (removed)
+            this.#sync();
+        return removed;
+    }
+    #sync() {
+        this.#entries.set(Array.from(this.#entriesMap.values()));
+    }
+}
+
+// Resolves an updater: calls it with the previous value if it's a function,
+// otherwise uses it as the value directly.
+function functionalUpdate(updater, input) {
+    return typeof updater === 'function'
+        ? updater(input)
+        : updater;
+}
+// True when `filter` is a (deep) prefix of `key`, e.g. ['app'] matches
+// ['app', 1]. Used to invalidate/find groups of queries by partial key.
+function partialMatchKey(key, filter) {
+    return partialDeepEqual(key, filter);
+}
+function partialDeepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a && b && typeof a === 'object' && typeof b === 'object') {
+        return Object.keys(b).every((key) => partialDeepEqual(a[key], b[key]));
+    }
+    return false;
+}
+function hashKey(key) {
+    return JSON.stringify(key, (_, value) => isPlainObject(value)
+        ? Object.keys(value)
+            .sort()
+            .reduce((result, k) => {
+            result[k] = value[k];
+            return result;
+        }, {})
+        : value);
+}
+// Copied from: https://github.com/jonschlinkert/is-plain-object
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isPlainObject(o) {
+    if (!hasObjectPrototype(o)) {
+        return false;
+    }
+    // If has no constructor
+    const ctor = o.constructor;
+    if (ctor === undefined) {
+        return true;
+    }
+    // If has modified prototype
+    const prot = ctor.prototype;
+    if (!hasObjectPrototype(prot)) {
+        return false;
+    }
+    // If constructor does not have an Object-specific method
+    if (!Object.prototype.hasOwnProperty.call(prot, 'isPrototypeOf')) {
+        return false;
+    }
+    // Handles Objects created by Object.create(<arbitrary prototype>)
+    if (Object.getPrototypeOf(o) !== Object.prototype) {
+        return false;
+    }
+    // Most likely a plain Object
+    return true;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function hasObjectPrototype(o) {
+    return Object.prototype.toString.call(o) === '[object Object]';
+}
+
+// Exponential backoff capped at 30s, matching TanStack's default.
+function defaultRetryDelay(failureCount) {
+    return Math.min(1000 * 2 ** failureCount, 30000);
+}
+function shouldRetry(retry, failureCount, error) {
+    if (typeof retry === 'function')
+        return retry(failureCount, error);
+    if (typeof retry === 'number')
+        return failureCount < retry;
+    return retry;
+}
+function resolveRetryDelay(retryDelay, failureCount, error) {
+    return typeof retryDelay === 'function'
+        ? retryDelay(failureCount, error)
+        : retryDelay;
+}
+
+const DEFAULT_GC_TIME = 5 * 60 * 1000;
+class Query {
+    key;
+    queryHash;
+    #state = signal({
+        data: undefined,
+        status: 'pending',
+        error: null,
+        isFetching: false,
+        isInvalidated: false,
+        failureCount: 0,
+        failureReason: null,
+        updatedAt: 0,
+    }, ...(ngDevMode ? [{ debugName: "#state" }] : []));
+    // `state` must follow `#state`: a public field can't precede the private
+    // field it reads during initialization (field init order).
+    // eslint-disable-next-line @typescript-eslint/member-ordering
+    state = this.#state.asReadonly();
+    #subscription = null;
+    #observers = 0;
+    #gcTime = DEFAULT_GC_TIME;
+    #gcTimer = null;
+    #cache;
+    constructor(key, queryHash, cache) {
+        this.key = key;
+        this.queryHash = queryHash;
+        this.#cache = cache;
+    }
+    get observerCount() {
+        return this.#observers;
+    }
+    setGcTime(ms) {
+        this.#gcTime = ms;
+    }
+    addObserver() {
+        this.#observers++;
+        this.#clearGcTimer();
+    }
+    removeObserver() {
+        if (this.#observers === 0)
+            return;
+        this.#observers--;
+        // No observers left: cancel any in-flight fetch (nobody is waiting for it)
+        // and schedule gc to dispose the query if no observer returns.
+        if (this.#observers === 0) {
+            this.cancel();
+            this.#scheduleGc();
+        }
+    }
+    fetch(queryFn, retry$1 = 0, retryDelay = defaultRetryDelay, cancelRefetch = false) {
+        if (this.#subscription && !this.#subscription.closed) {
+            // Already in-flight: dedupe unless the caller explicitly wants a fresh
+            // fetch (e.g. invalidate/refetch) — then cancel the old one and restart.
+            if (!cancelRefetch)
+                return;
+            this.cancel();
+        }
+        this.#state.update((state) => ({
+            ...state,
+            isFetching: true,
+            failureCount: 0,
+            failureReason: null,
+        }));
+        // defer + from: normalize Observable/Promise and re-invoke queryFn on each
+        // retry (a Promise is one-shot, so retry must produce a fresh one).
+        this.#subscription = defer(() => from(queryFn()))
+            .pipe(take(1), retry({
+            delay: (error, retryCount) => {
+                // retryCount (1-based) is the number of failures so far; the retry
+                // predicate/delay take a 0-based attempt index (0 = first retry).
+                this.#state.update((state) => ({
+                    ...state,
+                    failureCount: retryCount,
+                    failureReason: error,
+                }));
+                const attemptIndex = retryCount - 1;
+                if (!shouldRetry(retry$1, attemptIndex, error))
+                    throw error;
+                return timer(resolveRetryDelay(retryDelay, attemptIndex, error));
+            },
+        }), throwIfEmpty(() => new Error('Query function completed without emitting a value')))
+            .subscribe({
+            next: (data) => this.#state.set({
+                data,
+                status: 'success',
+                error: null,
+                isFetching: false,
+                isInvalidated: false,
+                failureCount: 0,
+                failureReason: null,
+                updatedAt: Date.now(),
+            }),
+            error: (err) => this.#state.update((state) => ({
+                ...state,
+                status: 'error',
+                error: err,
+                isFetching: false,
+            })),
+        });
+    }
+    setData(data, updatedAt = Date.now()) {
+        this.#state.update((state) => ({
+            ...state,
+            data,
+            status: 'success',
+            error: null,
+            isInvalidated: false,
+            failureCount: 0,
+            failureReason: null,
+            updatedAt,
+        }));
+        // Keep an orphaned query (no observers) alive for another gcTime so a
+        // setQueryData write isn't collected before anyone subscribes.
+        if (this.#observers === 0)
+            this.#scheduleGc();
+    }
+    invalidate() {
+        this.#state.update((state) => ({ ...state, isInvalidated: true }));
+    }
+    shouldFetch(staleTime) {
+        const state = this.state();
+        return (state.status !== 'success' ||
+            state.isInvalidated ||
+            this.#isStale(staleTime));
+    }
+    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 }));
+        }
+    }
+    destroy() {
+        this.cancel();
+        this.#clearGcTimer();
+    }
+    #isStale(staleTime) {
+        return Date.now() - this.state().updatedAt > staleTime;
+    }
+    #scheduleGc() {
+        this.#clearGcTimer();
+        this.#gcTimer = setTimeout(() => {
+            this.#gcTimer = null;
+            this.#cache.remove(this);
+        }, this.#gcTime);
+    }
+    #clearGcTimer() {
+        if (this.#gcTimer === null)
+            return;
+        clearTimeout(this.#gcTimer);
+        this.#gcTimer = null;
+    }
+}
+
+class QueryCache extends Cache {
+    getOrCreate(key) {
+        const queryHash = hashKey(key);
+        const exist = this.getEntry(queryHash);
+        if (exist)
+            return exist;
+        return this.addEntry(queryHash, new Query(key, queryHash, this));
+    }
+    get(key) {
+        return this.getEntry(hashKey(key));
+    }
+    findAll(filters = {}) {
+        const { queryKey, exact } = filters;
+        // Reads the reactive `entries()` so findAll() works inside computed().
+        const all = this.entries();
+        if (!queryKey)
+            return all;
+        if (exact) {
+            const queryHash = hashKey(queryKey);
+            return all.filter((query) => query.queryHash === queryHash);
+        }
+        return all.filter((query) => partialMatchKey(query.key, queryKey));
+    }
+    remove(query) {
+        // Guard on identity, not just the hash: a stale instance (already removed
+        // and recreated under the same key) must not evict the current query.
+        if (this.getEntry(query.queryHash) === query) {
+            this.removeEntry(query.queryHash);
+        }
+    }
+    clear() {
+        this.getAll().forEach((query) => query.destroy());
+        super.clear();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: QueryCache, deps: null, target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: QueryCache });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: QueryCache, decorators: [{
+            type: Injectable
+        }] });
+
+function getInitialState() {
+    return {
+        status: 'idle',
+        data: undefined,
+        error: null,
+        variables: undefined,
+        context: undefined,
+        failureCount: 0,
+        failureReason: null,
+        submittedAt: 0,
+    };
+}
+class Mutation {
+    mutationId;
+    #state = signal(getInitialState(), ...(ngDevMode ? [{ debugName: "#state" }] : []));
+    // `state` must follow `#state`: a public field can't precede the private
+    // field it reads during initialization (field init order).
+    // eslint-disable-next-line @typescript-eslint/member-ordering
+    state = this.#state.asReadonly();
+    #subscription = null;
+    #options;
+    constructor(mutationId, options) {
+        this.mutationId = mutationId;
+        this.#options = options;
+    }
+    execute(variables) {
+        const context = this.#options.onMutate?.(variables);
+        // Mutations default to no retry (not idempotent — a retried POST could
+        // create a duplicate); opt in explicitly via options.retry.
+        const retry$1 = this.#options.retry ?? 0;
+        const retryDelay = this.#options.retryDelay ?? defaultRetryDelay;
+        this.#state.set({
+            status: 'pending',
+            data: undefined,
+            error: null,
+            variables,
+            context,
+            failureCount: 0,
+            failureReason: null,
+            submittedAt: Date.now(),
+        });
+        // defer + from: normalize Observable/Promise and re-invoke mutationFn on
+        // each retry (a Promise is one-shot, so retry must produce a fresh one).
+        this.#subscription = defer(() => from(this.#options.mutationFn(variables)))
+            .pipe(take(1), retry({
+            delay: (error, retryCount) => {
+                this.#state.update((state) => ({
+                    ...state,
+                    failureCount: retryCount,
+                    failureReason: error,
+                }));
+                const attemptIndex = retryCount - 1;
+                if (!shouldRetry(retry$1, attemptIndex, error))
+                    throw error;
+                return timer(resolveRetryDelay(retryDelay, attemptIndex, error));
+            },
+        }), throwIfEmpty(() => new Error('Mutation function completed without emitting a value')))
+            .subscribe({
+            next: (data) => {
+                this.#state.update((state) => ({ ...state, status: 'success', data }));
+                this.#options.onSuccess?.(data, variables, context);
+                this.#options.onSettled?.(data, null, variables, context);
+            },
+            error: (error) => {
+                this.#state.update((state) => ({ ...state, status: 'error', error }));
+                this.#options.onError?.(error, variables, context);
+                this.#options.onSettled?.(undefined, error, variables, context);
+            },
+        });
+    }
+    reset() {
+        this.cancel();
+        this.#state.set(getInitialState());
+    }
+    cancel() {
+        this.#subscription?.unsubscribe();
+        this.#subscription = null;
+    }
+}
+
+class MutationCache extends Cache {
+    #lastId = 0;
+    build(options) {
+        const mutation = new Mutation(++this.#lastId, options);
+        this.addEntry(String(mutation.mutationId), mutation);
+        return mutation;
+    }
+    findAll(filters = {}) {
+        // Reads the reactive `entries()` so findAll() works inside computed().
+        const all = this.entries();
+        if (!filters.status)
+            return all;
+        return all.filter((mutation) => mutation.state().status === filters.status);
+    }
+    remove(mutation) {
+        this.removeEntry(String(mutation.mutationId));
+    }
+    clear() {
+        this.getAll().forEach((mutation) => mutation.cancel());
+        super.clear();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: MutationCache, deps: null, target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: MutationCache });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: MutationCache, decorators: [{
+            type: Injectable
+        }] });
+
+const QUERY_CLIENT_CONFIG = new InjectionToken('QUERY_CLIENT_CONFIG');
+
+/**
+ * Central registry and cache for queries and mutations.
+ *
+ * Provided by {@link provideQueryClient} and retrieved with
+ * {@link injectQueryClient}. Offers imperative cache access — reading and
+ * writing data, and invalidating, cancelling, or removing queries — that
+ * complements the reactive {@link injectQuery} / {@link injectMutation} APIs.
+ */
+class QueryClient {
+    #cache = inject(QueryCache);
+    #mutationCache = inject(MutationCache);
+    #config = inject(QUERY_CLIENT_CONFIG, { optional: true }) ?? {};
+    /** Returns the underlying query cache. Advanced/internal use. */
+    getQueryCache() {
+        return this.#cache;
+    }
+    /** Returns the underlying mutation cache. Advanced/internal use. */
+    getMutationCache() {
+        return this.#mutationCache;
+    }
+    /**
+     * Merges per-query options with the configured defaults, filling in
+     * `staleTime`, `gcTime`, `retry`, and `retryDelay`. Used internally by
+     * {@link injectQuery}.
+     */
+    defaultQueryOptions(options) {
+        const defaults = this.#config.defaultOptions?.queries;
+        return {
+            ...options,
+            staleTime: options.staleTime ?? defaults?.staleTime ?? 0,
+            gcTime: options.gcTime ?? defaults?.gcTime,
+            retry: options.retry ?? defaults?.retry ?? 3,
+            retryDelay: options.retryDelay ?? defaults?.retryDelay ?? defaultRetryDelay,
+        };
+    }
+    /**
+     * Imperatively fetches and caches a query, unless fresh data already exists
+     * (governed by `staleTime`). Prefer {@link injectQuery} in components; use
+     * this for prefetching outside the reactive flow.
+     *
+     * @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`,
+     *   `cancelRefetch`).
+     */
+    fetchQuery(key, queryFn, options = {}) {
+        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 query = this.#cache.getOrCreate(key);
+        if (query.shouldFetch(staleTime)) {
+            query.fetch(queryFn, retry, retryDelay, options.cancelRefetch);
+        }
+    }
+    /**
+     * Reads the current cached data for a query key, or `undefined` if the query
+     * is not cached yet.
+     *
+     * @param key - The query key to read.
+     * @returns The cached data, or `undefined`.
+     */
+    getQueryData(key) {
+        return this.#cache.get(key)?.state().data;
+    }
+    /**
+     * Writes data into the cache for a query key, creating the entry if needed.
+     * The `updater` may be a value or a function of the previous data; returning
+     * `undefined` from the function is a no-op. Useful for optimistic updates.
+     *
+     * @param key - The query key to write.
+     * @param updater - The new data, or a function `(prev) => next`.
+     *
+     * @example
+     * ```ts
+     * client.setQueryData<Todo[]>(['todos'], (prev = []) => [...prev, newTodo])
+     * ```
+     */
+    setQueryData(key, updater) {
+        const query = this.#cache.getOrCreate(key);
+        const data = functionalUpdate(updater, query.state().data);
+        // Matches TanStack: an updater returning undefined is a no-op.
+        if (data === undefined)
+            return;
+        query.setData(data);
+    }
+    /**
+     * Marks matching queries as stale and triggers a refetch for those that are
+     * actively observed. Commonly called after a mutation succeeds.
+     *
+     * @param filters - Which queries to invalidate; omit to invalidate all.
+     *
+     * @example
+     * ```ts
+     * client.invalidateQueries({ queryKey: ['todos'] })
+     * ```
+     */
+    invalidateQueries(filters) {
+        this.#cache.findAll(filters).forEach((query) => query.invalidate());
+    }
+    /**
+     * Cancels any in-flight fetches for matching queries.
+     *
+     * @param filters - Which queries to cancel; omit to cancel all.
+     */
+    cancelQueries(filters) {
+        this.#cache.findAll(filters).forEach((query) => query.cancel());
+    }
+    /**
+     * Removes matching queries from the cache entirely, discarding their data.
+     *
+     * @param filters - Which queries to remove; omit to remove all.
+     */
+    removeQueries(filters) {
+        this.#cache.findAll(filters).forEach((query) => {
+            query.destroy();
+            this.#cache.remove(query);
+        });
+    }
+    /**
+     * Returns the number of matching queries currently fetching. For a reactive
+     * count, prefer {@link injectIsFetching}.
+     *
+     * @param filters - Which queries to count; omit to count all.
+     */
+    isFetching(filters) {
+        return this.#cache
+            .findAll(filters)
+            .filter((query) => query.state().isFetching).length;
+    }
+    /**
+     * Returns the number of mutations currently pending. For a reactive count,
+     * prefer {@link injectIsMutating}.
+     */
+    isMutating() {
+        return this.#mutationCache.findAll({ status: 'pending' }).length;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: QueryClient, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: QueryClient });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.21", ngImport: i0, type: QueryClient, decorators: [{
+            type: Injectable
+        }] });
+
+/** Discriminator identifying each kind of {@link QueryClientFeature}. */
+var QueryClientFeatureKind;
+(function (QueryClientFeatureKind) {
+    QueryClientFeatureKind[QueryClientFeatureKind["DefaultOptions"] = 0] = "DefaultOptions";
+})(QueryClientFeatureKind || (QueryClientFeatureKind = {}));
+function queryClientFeature(kind, providers) {
+    return { ɵkind: kind, ɵproviders: providers };
+}
+
+/**
+ * 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.
+ *
+ * @param features - Optional {@link QueryClientFeature}s (e.g.
+ *   {@link withDefaultOptions}).
+ * @returns Environment providers to add to the app's provider list.
+ *
+ * @example
+ * ```ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideHttpClient(),
+ *     provideQueryClient(
+ *       withDefaultOptions({ queries: { staleTime: 30_000 } }),
+ *     ),
+ *   ],
+ * }
+ * ```
+ */
+function provideQueryClient(...features) {
+    const seenKinds = new Set();
+    for (const feature of features) {
+        if (seenKinds.has(feature.ɵkind)) {
+            throw new Error(`provideQueryClient: feature "${QueryClientFeatureKind[feature.ɵkind]}" is registered more than once`);
+        }
+        seenKinds.add(feature.ɵkind);
+    }
+    return makeEnvironmentProviders([
+        QueryCache,
+        MutationCache,
+        QueryClient,
+        ...features.flatMap((feature) => feature.ɵproviders),
+    ]);
+}
+
+/**
+ * Returns the application's {@link QueryClient} for imperative cache access.
+ *
+ * Use it to read or write cached data (`getQueryData`, `setQueryData`) and to
+ * invalidate, cancel, or remove queries — typically from mutation hooks or
+ * event handlers. Requires {@link provideQueryClient} to be registered.
+ *
+ * Must run in an injection context, or be given an explicit `injector`.
+ *
+ * @param options - Optional `injector` to use outside an injection context.
+ * @returns The shared {@link QueryClient} instance.
+ *
+ * @example
+ * ```ts
+ * const client = injectQueryClient()
+ * client.setQueryData<Todo[]>(['todos'], (prev = []) => [...prev, newTodo])
+ * client.invalidateQueries({ queryKey: ['todos'] })
+ * ```
+ */
+function injectQueryClient(options) {
+    if (!options?.injector)
+        assertInInjectionContext(injectQueryClient);
+    return options?.injector?.get(QueryClient) ?? inject(QueryClient);
+}
+
+/**
+ * Runs a cached, reactive query and exposes its state as signals.
+ *
+ * The query is keyed by `queryKey`: calls with the same key share a single
+ * cache entry and in-flight request (deduplication). `optionsFn` is read in a
+ * reactive context, so when a value it depends on changes (e.g. a route or
+ * input signal in the key), the query automatically switches to the new key
+ * and fetches. The query is bound to the current injection context and cleans
+ * up its cache observer when that context is destroyed.
+ *
+ * Must run in an injection context, or be given an explicit `injector`.
+ *
+ * @typeParam TData - Type of the data resolved by `queryFn`.
+ * @typeParam TError - Type of the error thrown by `queryFn`.
+ * @param optionsFn - Factory returning the {@link QueryOptions}. Re-evaluated
+ *   reactively, so reading signals inside it makes the query re-run on change.
+ * @param options - Optional `injector` to use outside an injection context.
+ * @returns A {@link QueryResult} of signals (`data`, `status`, `error`,
+ *   `isLoading`, `isPending`, …) plus a `refetch()` that forces a fresh fetch.
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   template: `
+ *     @if (todo.isPending()) { <p>Loading…</p> }
+ *     @if (todo.data(); as data) { <p>{{ data.title }}</p> }
+ *   `,
+ * })
+ * class TodoComponent {
+ *   readonly id = input.required<number>()
+ *   private readonly http = inject(HttpClient)
+ *
+ *   // Refetches automatically whenever `id()` changes.
+ *   readonly todo = injectQuery(() => ({
+ *     queryKey: ['todo', this.id()],
+ *     queryFn: () => this.http.get<Todo>(`/api/todos/${this.id()}`),
+ *   }))
+ * }
+ * ```
+ */
+function injectQuery(optionsFn, options) {
+    if (!options?.injector)
+        assertInInjectionContext(injectQuery);
+    const injector = options?.injector ?? inject(Injector);
+    return runInInjectionContext(injector, () => {
+        const client = inject(QueryClient);
+        const cache = client.getQueryCache();
+        // Single source of truth for defaulted options; resolves config defaults
+        // (staleTime, gcTime) once instead of scattering the logic across effects.
+        const defaultedOptions = computed(() => client.defaultQueryOptions(optionsFn()), ...(ngDevMode ? [{ debugName: "defaultedOptions" }] : []));
+        // Seed a fresh query (status 'pending', no data yet) with initialData so
+        // it renders immediately as 'success'. updatedAt defaults to 0 → stale →
+        // background refetch.
+        const applyInitialData = (q) => {
+            const { initialData, initialDataUpdatedAt } = untracked(defaultedOptions);
+            if (initialData === undefined || q.state().status !== 'pending')
+                return;
+            const data = typeof initialData === 'function'
+                ? initialData()
+                : initialData;
+            const updatedAt = typeof initialDataUpdatedAt === 'function'
+                ? initialDataUpdatedAt()
+                : (initialDataUpdatedAt ?? 0);
+            q.setData(data, updatedAt);
+        };
+        // getOrCreate mutates the cache (a side effect), so it must not run inside
+        // a computed. Resolve the query in a signal: seed it synchronously and
+        // update it from an effect whenever the key changes.
+        const seed = cache.getOrCreate(untracked(defaultedOptions).queryKey);
+        applyInitialData(seed);
+        const query = signal(seed, ...(ngDevMode ? [{ debugName: "query" }] : []));
+        effect(() => {
+            const key = defaultedOptions().queryKey;
+            const q = untracked(() => cache.getOrCreate(key));
+            untracked(() => applyInitialData(q));
+            query.set(q);
+        });
+        // Memoized: only emits when the flag itself flips, so ordinary data
+        // updates don't wake the fetch effect (no refetch loop).
+        const isInvalidated = computed(() => query().state().isInvalidated, ...(ngDevMode ? [{ debugName: "isInvalidated" }] : []));
+        effect((cleanup) => {
+            const q = query();
+            const { gcTime } = untracked(defaultedOptions);
+            if (gcTime !== undefined) {
+                q.setGcTime(gcTime);
+            }
+            q.addObserver();
+            cleanup(() => q.removeObserver());
+        });
+        effect(() => {
+            const { queryKey, queryFn, staleTime, retry, retryDelay, enabled } = defaultedOptions();
+            // Track invalidation so invalidateQueries() re-triggers a refetch.
+            // When invalidated, cancel any in-flight fetch and start a fresh one
+            // (otherwise the stale in-flight result would clear isInvalidated).
+            const invalidated = isInvalidated();
+            if (enabled === false)
+                return;
+            untracked(() => client.fetchQuery(queryKey, queryFn, {
+                staleTime,
+                retry,
+                retryDelay,
+                cancelRefetch: invalidated,
+            }));
+        });
+        // Polling: refetch on an interval, independent of staleTime (staleTime: 0
+        // forces the fetch). The function form is reactive — reading state() makes
+        // the effect re-run when data changes, so returning false stops polling.
+        effect((onCleanup) => {
+            const { queryKey, queryFn, retry, retryDelay, refetchInterval, enabled } = defaultedOptions();
+            if (enabled === false)
+                return;
+            const interval = typeof refetchInterval === 'function'
+                ? refetchInterval({ state: query().state() })
+                : refetchInterval;
+            if (!interval)
+                return;
+            const id = setInterval(() => {
+                client.fetchQuery(queryKey, queryFn, {
+                    staleTime: 0,
+                    retry,
+                    retryDelay,
+                });
+            }, interval);
+            onCleanup(() => clearInterval(id));
+        });
+        return {
+            data: computed(() => query().state().data),
+            status: computed(() => query().state().status),
+            error: computed(() => query().state().error),
+            isFetching: computed(() => query().state().isFetching),
+            // First fetch in-flight: fetching with no resolved data yet.
+            isLoading: computed(() => {
+                const state = query().state();
+                return state.isFetching && state.status === 'pending';
+            }),
+            isPending: computed(() => query().state().status === 'pending'),
+            isSuccess: computed(() => query().state().status === 'success'),
+            isError: computed(() => query().state().status === 'error'),
+            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 } = untracked(defaultedOptions);
+                client.fetchQuery(queryKey, queryFn, {
+                    staleTime: 0,
+                    retry,
+                    retryDelay,
+                    cancelRefetch: true,
+                });
+            },
+        };
+    });
+}
+
+/**
+ * Creates a mutation for imperative writes (create/update/delete) and exposes
+ * its state as signals.
+ *
+ * Unlike queries, a mutation does not run on its own — call `mutate(variables)`
+ * to trigger `mutationFn`. The `onMutate` / `onSuccess` / `onError` /
+ * `onSettled` lifecycle hooks make optimistic updates and cache invalidation
+ * straightforward. Mutations do not retry by default (a retried write is not
+ * idempotent); opt in via `options.retry`. Bound to the current injection
+ * context and cancelled when that context is destroyed.
+ *
+ * Must run in an injection context, or be given an explicit `injector`.
+ *
+ * @typeParam TData - Type of the data resolved by `mutationFn`.
+ * @typeParam TError - Type of the error thrown by `mutationFn`.
+ * @typeParam TVariables - Type of the argument passed to `mutate()`.
+ * @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`, …).
+ *
+ * @example
+ * ```ts
+ * const client = injectQueryClient()
+ *
+ * const addTodo = injectMutation(() => ({
+ *   mutationFn: (title: string) => http.post<Todo>('/api/todos', { title }),
+ *   onSuccess: () => client.invalidateQueries({ queryKey: ['todos'] }),
+ * }))
+ *
+ * // <button (click)="addTodo.mutate('Buy milk')" [disabled]="addTodo.isPending()">Add</button>
+ * ```
+ */
+function injectMutation(optionsFn, options) {
+    if (!options?.injector)
+        assertInInjectionContext(injectMutation);
+    const injector = options?.injector ?? inject(Injector);
+    return runInInjectionContext(injector, () => {
+        const cache = inject(QueryClient).getMutationCache();
+        const mutation = cache.build(optionsFn());
+        inject(DestroyRef).onDestroy(() => {
+            mutation.cancel();
+            cache.remove(mutation);
+        });
+        return {
+            mutate: (variables) => mutation.execute(variables),
+            reset: () => mutation.reset(),
+            data: computed(() => mutation.state().data),
+            error: computed(() => mutation.state().error),
+            variables: computed(() => mutation.state().variables),
+            status: computed(() => mutation.state().status),
+            isIdle: computed(() => mutation.state().status === 'idle'),
+            isPending: computed(() => mutation.state().status === 'pending'),
+            isSuccess: computed(() => mutation.state().status === 'success'),
+            isError: computed(() => mutation.state().status === 'error'),
+            failureCount: computed(() => mutation.state().failureCount),
+            failureReason: computed(() => mutation.state().failureReason),
+        };
+    });
+}
+
+/**
+ * Returns a signal with the number of queries currently fetching — useful for a
+ * global loading indicator.
+ *
+ * Pass {@link QueryFilters} to count only matching queries; omit them to count
+ * every fetching query in the cache.
+ *
+ * Must run in an injection context, or be given an explicit `injector`.
+ *
+ * @param filters - Optional filters (e.g. `{ queryKey: ['todos'] }`) to narrow
+ *   the count.
+ * @param options - Optional `injector` to use outside an injection context.
+ * @returns A `Signal<number>` of active fetches.
+ *
+ * @example
+ * ```ts
+ * readonly isFetching = injectIsFetching()
+ * // <app-spinner *ngIf="isFetching() > 0" />
+ * ```
+ */
+function injectIsFetching(filters, options) {
+    if (!options?.injector)
+        assertInInjectionContext(injectIsFetching);
+    const client = options?.injector?.get(QueryClient) ?? inject(QueryClient);
+    const cache = client.getQueryCache();
+    return computed(() => cache.findAll(filters).filter((query) => query.state().isFetching).length);
+}
+
+/**
+ * Returns a signal with the number of mutations currently pending — useful for
+ * a global "saving…" indicator.
+ *
+ * Must run in an injection context, or be given an explicit `injector`.
+ *
+ * @param options - Optional `injector` to use outside an injection context.
+ * @returns A `Signal<number>` of in-flight mutations.
+ *
+ * @example
+ * ```ts
+ * readonly isMutating = injectIsMutating()
+ * // <p *ngIf="isMutating() > 0">Saving…</p>
+ * ```
+ */
+function injectIsMutating(options) {
+    if (!options?.injector)
+        assertInInjectionContext(injectIsMutating);
+    const client = options?.injector?.get(QueryClient) ?? inject(QueryClient);
+    const cache = client.getMutationCache();
+    return computed(() => cache.findAll({ status: 'pending' }).length);
+}
+
+/**
+ * Identity helper that defines a typed, reusable set of {@link QueryOptions}.
+ *
+ * Returns the options unchanged at runtime, but anchors type inference so the
+ * same definition can be shared across {@link injectQuery},
+ * {@link QueryClient.setQueryData}, and friends without re-declaring generics.
+ * Keeping query definitions in a service (rather than inline) makes them easy
+ * to reuse and unit-test.
+ *
+ * @typeParam TData - Type of the data resolved by `queryFn`.
+ * @typeParam TError - Type of the error thrown by `queryFn`.
+ * @param options - The {@link QueryOptions} to define.
+ * @returns The same `options`, typed.
+ *
+ * @example
+ * ```ts
+ * @Injectable({ providedIn: 'root' })
+ * class TodoQueries {
+ *   private readonly http = inject(HttpClient)
+ *
+ *   todos() {
+ *     return queryOptions({
+ *       queryKey: ['todos'],
+ *       queryFn: () => this.http.get<Todo[]>('/api/todos'),
+ *     })
+ *   }
+ * }
+ *
+ * // const todos = injectQuery(() => inject(TodoQueries).todos())
+ * ```
+ */
+function queryOptions(options) {
+    return options;
+}
+
+/**
+ * Identity helper that defines a typed, reusable set of {@link MutationOptions}.
+ *
+ * Returns the options unchanged at runtime; its job is to anchor type inference
+ * (notably linking `TContext` returned by `onMutate` to the later hooks) so a
+ * mutation can be defined once in a service and passed to {@link injectMutation}.
+ *
+ * @typeParam TData - Type of the data resolved by `mutationFn`.
+ * @typeParam TError - Type of the error thrown by `mutationFn`.
+ * @typeParam TVariables - Type of the argument passed to `mutate()`.
+ * @typeParam TContext - Type returned by `onMutate`, passed to later hooks.
+ * @param options - The {@link MutationOptions} to define.
+ * @returns The same `options`, typed.
+ *
+ * @example
+ * ```ts
+ * addTodo() {
+ *   return mutationOptions({
+ *     mutationFn: (title: string) => this.http.post<Todo>('/api/todos', { title }),
+ *     onSuccess: () => this.client.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ * }
+ * ```
+ */
+function mutationOptions(options) {
+    return options;
+}
+
+/**
+ * Feature for {@link provideQueryClient} that sets application-wide default
+ * query options. Per-query options always take precedence over these defaults.
+ *
+ * @param options - The {@link DefaultOptions} to apply.
+ * @returns A {@link QueryClientFeature} to pass to {@link provideQueryClient}.
+ *
+ * @example
+ * ```ts
+ * provideQueryClient(
+ *   withDefaultOptions({ queries: { staleTime: 60_000, retry: 1 } }),
+ * )
+ * ```
+ */
+function withDefaultOptions(options) {
+    return queryClientFeature(QueryClientFeatureKind.DefaultOptions, [
+        { provide: QUERY_CLIENT_CONFIG, useValue: { defaultOptions: options } },
+    ]);
+}
+
+/*
+ * Public API Surface of ngx-query
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { QueryClient, QueryClientFeatureKind, injectIsFetching, injectIsMutating, injectMutation, injectQuery, injectQueryClient, mutationOptions, provideQueryClient, queryOptions, withDefaultOptions };
+//# sourceMappingURL=ngx-signal-query.mjs.map