ngx-signal-query 1.0.0-dev.1

package/index.d.ts

@@ -0,0 +1,619 @@
+import { Observable } from 'rxjs';
+import * as i0 from '@angular/core';
+import { Signal, Provider, EnvironmentProviders, Injector } from '@angular/core';
+
+declare abstract class Cache<TEntry> {
+    #private;
+    protected readonly entries: i0.Signal<TEntry[]>;
+    getAll(): TEntry[];
+    clear(): void;
+    protected addEntry(key: string, entry: TEntry): TEntry;
+    protected getEntry(key: string): TEntry | undefined;
+    protected removeEntry(key: string): boolean;
+}
+
+/**
+ * Uniquely identifies a query and serves as its cache key. Use a serializable
+ * 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. */
+type QueryStatus = 'pending' | 'success' | 'error';
+/** Full state snapshot of a query (the reactive source behind {@link QueryResult}). */
+interface QueryState<TData, TError = Error> {
+    /** Last successfully resolved data, or `undefined` before the first success. */
+    data: TData | undefined;
+    /** Current {@link QueryStatus}. */
+    status: QueryStatus;
+    /** Last error, or `null` if the latest attempt did not fail. */
+    error: TError | null;
+    /** Whether a fetch is currently in flight. */
+    isFetching: boolean;
+    /** Whether the query has been marked stale via `invalidateQueries`. */
+    isInvalidated: boolean;
+    /** Number of consecutive failed attempts in the current fetch. */
+    failureCount: number;
+    /** Error of the most recent failed attempt, or `null`. */
+    failureReason: TError | null;
+    /** Timestamp (ms) of the last successful update; `0` if never. */
+    updatedAt: number;
+}
+/** Selects which queries an operation applies to (e.g. invalidate, cancel). */
+type QueryFilters = {
+    /** Match queries whose key starts with (or, with `exact`, equals) this key. */
+    queryKey?: QueryKey;
+    /** Require an exact key match instead of a prefix match. */
+    exact?: boolean;
+};
+/** A new value, or a function deriving it from the previous one. */
+type Updater<TInput, TOutput> = TOutput | ((input: TInput) => TOutput);
+/**
+ * Polling interval in ms, `false` to disable, or a function of the current
+ * query snapshot returning the next interval (e.g. stop polling on error).
+ */
+type RefetchIntervalValue<TData, TError> = number | false | ((query: {
+    state: QueryState<TData, TError>;
+}) => number | false | undefined);
+/**
+ * Retry policy: `true`/`false` to enable/disable, a max retry count, or a
+ * predicate `(failureCount, error) => boolean`.
+ */
+type RetryValue<TError> = boolean | number | ((failureCount: number, error: TError) => boolean);
+/** Delay between retries: fixed ms, or a function of the attempt and error. */
+type RetryDelayValue<TError> = number | ((failureCount: number, error: TError) => number);
+/** Configuration for a query, passed to {@link injectQuery} / {@link queryOptions}. */
+type QueryOptions<TData, TError = Error> = {
+    /** Unique cache key for this query. See {@link QueryKey}. */
+    queryKey: QueryKey;
+    /** Fetcher returning the data as an `Observable` or `Promise`. */
+    queryFn: () => Observable<TData> | Promise<TData>;
+    /** How long fetched data stays fresh before refetching, in ms. Default `0`. */
+    staleTime?: number;
+    /** How long unused data is kept before garbage collection, in ms. */
+    gcTime?: number;
+    /** Retry policy on failure. Default `3`. See {@link RetryValue}. */
+    retry?: RetryValue<TError>;
+    /** Delay between retries. See {@link RetryDelayValue}. */
+    retryDelay?: RetryDelayValue<TError>;
+    /** Poll on an interval. See {@link RefetchIntervalValue}. */
+    refetchInterval?: RefetchIntervalValue<TData, TError>;
+    /** Seed data to render immediately (treated as already-resolved). */
+    initialData?: TData | (() => TData);
+    /** Timestamp (ms) for `initialData`; older data is considered stale. */
+    initialDataUpdatedAt?: number | (() => number);
+    /** Set `false` to disable fetching (e.g. until a dependency is ready). */
+    enabled?: boolean;
+};
+/** {@link QueryOptions} with defaults resolved (internal, set by {@link QueryClient}). */
+type DefaultedQueryOptions<TData, TError = Error> = QueryOptions<TData, TError> & {
+    staleTime: number;
+    retry: RetryValue<TError>;
+    retryDelay: RetryDelayValue<TError>;
+};
+/** Reactive result returned by {@link injectQuery}; every field is a signal. */
+type QueryResult<TData, TError = Error> = {
+    /** Last resolved data, or `undefined` before the first success. */
+    data: Signal<TData | undefined>;
+    /** Current {@link QueryStatus}. */
+    status: Signal<QueryStatus>;
+    /** Last error, or `null`. */
+    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`). */
+    isLoading: Signal<boolean>;
+    /** Whether status is `'pending'` (no data resolved yet). */
+    isPending: Signal<boolean>;
+    /** Whether status is `'success'`. */
+    isSuccess: Signal<boolean>;
+    /** Whether status is `'error'`. */
+    isError: Signal<boolean>;
+    /** Consecutive failures in the current fetch. */
+    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;
+};
+
+declare class Query<TData, TError = Error> {
+    #private;
+    readonly key: QueryKey;
+    readonly queryHash: string;
+    readonly state: i0.Signal<QueryState<TData, TError>>;
+    constructor(key: QueryKey, queryHash: string, cache: QueryCache);
+    get observerCount(): number;
+    setGcTime(ms: number): void;
+    addObserver(): void;
+    removeObserver(): void;
+    fetch(queryFn: () => Observable<TData> | Promise<TData>, retry?: RetryValue<TError>, retryDelay?: RetryDelayValue<TError>, cancelRefetch?: boolean): void;
+    setData(data: TData, updatedAt?: number): void;
+    invalidate(): void;
+    shouldFetch(staleTime: number): boolean;
+    cancel(): void;
+    destroy(): void;
+}
+
+declare class QueryCache extends Cache<Query<unknown, unknown>> {
+    getOrCreate<TData, TError = Error>(key: QueryKey): Query<TData, TError>;
+    get<TData, TError = Error>(key: QueryKey): Query<TData, TError> | undefined;
+    findAll(filters?: QueryFilters): Array<Query<unknown, unknown>>;
+    remove(query: Query<unknown, unknown>): void;
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<QueryCache, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<QueryCache>;
+}
+
+/** Lifecycle status of a mutation: not yet run, running, succeeded, or failed. */
+type MutationStatus = 'idle' | 'pending' | 'success' | 'error';
+/** Selects which mutations an operation applies to (e.g. `injectIsMutating`). */
+type MutationFilters = {
+    /** Match mutations in this status. */
+    status?: MutationStatus;
+};
+/** Full state snapshot of a mutation (the reactive source behind {@link MutationResult}). */
+type MutationState<TData, TError, TVariables, TContext> = {
+    /** Current {@link MutationStatus}. */
+    status: MutationStatus;
+    /** Data resolved by the last successful run, or `undefined`. */
+    data: TData | undefined;
+    /** Error of the last failed run, or `null`. */
+    error: TError | null;
+    /** Variables passed to the most recent `mutate()` call. */
+    variables: TVariables | undefined;
+    /** Value returned by `onMutate` for the current run. */
+    context: TContext | undefined;
+    /** Number of failed attempts in the current run. */
+    failureCount: number;
+    /** Error of the most recent failed attempt, or `null`. */
+    failureReason: TError | null;
+    /** Timestamp (ms) when the current run was submitted; `0` if never. */
+    submittedAt: number;
+};
+/**
+ * Configuration for a mutation, passed to {@link injectMutation} /
+ * {@link mutationOptions}. The hooks fire in order: `onMutate` →
+ * (`onSuccess` | `onError`) → `onSettled`. The value returned by `onMutate`
+ * is passed as `context` to the later hooks — handy for rollback.
+ */
+type MutationOptions<TData, TError, TVariables, TContext> = {
+    /** Performs the write; receives `mutate()`'s argument. Returns `Observable`/`Promise`. */
+    mutationFn: (variables: TVariables) => Observable<TData> | Promise<TData>;
+    /** Retry policy. Defaults to no retry (writes are not idempotent). */
+    retry?: RetryValue<TError>;
+    /** Delay between retries. See {@link RetryDelayValue}. */
+    retryDelay?: RetryDelayValue<TError>;
+    /** Runs before `mutationFn`; its return value becomes `context` (e.g. for optimistic rollback). */
+    onMutate?: (variables: TVariables) => TContext | undefined;
+    /** Runs after a successful `mutationFn`. */
+    onSuccess?: (data: TData, variables: TVariables, context: TContext | undefined) => void;
+    /** Runs after a failed `mutationFn`. */
+    onError?: (error: TError, variables: TVariables, context: TContext | undefined) => void;
+    /** Runs after success or error — for cleanup that should happen either way. */
+    onSettled?: (data: TData | undefined, error: TError | null, variables: TVariables, context: TContext | undefined) => void;
+};
+/** Reactive result returned by {@link injectMutation}; state fields are signals. */
+type MutationResult<TData, TError, TVariables> = {
+    /** Triggers the mutation with the given variables. */
+    mutate: (variables: TVariables) => void;
+    /** Resets state back to `idle`, cancelling any in-flight run. */
+    reset: () => void;
+    /** Data from the last successful run, or `undefined`. */
+    data: Signal<TData | undefined>;
+    /** Error from the last failed run, or `null`. */
+    error: Signal<TError | null>;
+    /** Variables from the most recent `mutate()` call. */
+    variables: Signal<TVariables | undefined>;
+    /** Current {@link MutationStatus}. */
+    status: Signal<MutationStatus>;
+    /** Whether the mutation has not been run yet. */
+    isIdle: Signal<boolean>;
+    /** Whether the mutation is currently running. */
+    isPending: Signal<boolean>;
+    /** Whether the last run succeeded. */
+    isSuccess: Signal<boolean>;
+    /** Whether the last run failed. */
+    isError: Signal<boolean>;
+    /** Consecutive failures in the current run. */
+    failureCount: Signal<number>;
+    /** Error of the most recent failed attempt, or `null`. */
+    failureReason: Signal<TError | null>;
+};
+declare class Mutation<TData = unknown, TError = Error, TVariables = void, TContext = unknown> {
+    #private;
+    readonly mutationId: number;
+    readonly state: Signal<MutationState<TData, TError, TVariables, TContext>>;
+    constructor(mutationId: number, options: MutationOptions<TData, TError, TVariables, TContext>);
+    execute(variables: TVariables): void;
+    reset(): void;
+    cancel(): void;
+}
+
+declare class MutationCache extends Cache<Mutation<unknown, unknown, unknown, unknown>> {
+    #private;
+    build<TData, TError, TVariables, TContext>(options: MutationOptions<TData, TError, TVariables, TContext>): Mutation<TData, TError, TVariables, TContext>;
+    findAll(filters?: MutationFilters): Array<Mutation<unknown, unknown, unknown, unknown>>;
+    remove<TData, TError, TVariables, TContext>(mutation: Mutation<TData, TError, TVariables, TContext>): void;
+    clear(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MutationCache, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<MutationCache>;
+}
+
+/**
+ * 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.
+ */
+declare class QueryClient {
+    #private;
+    /** Returns the underlying query cache. Advanced/internal use. */
+    getQueryCache(): QueryCache;
+    /** Returns the underlying mutation cache. Advanced/internal use. */
+    getMutationCache(): MutationCache;
+    /**
+     * Merges per-query options with the configured defaults, filling in
+     * `staleTime`, `gcTime`, `retry`, and `retryDelay`. Used internally by
+     * {@link injectQuery}.
+     */
+    defaultQueryOptions<TData, TError = Error>(options: QueryOptions<TData, TError>): DefaultedQueryOptions<TData, TError>;
+    /**
+     * 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<TData>(key: QueryKey, queryFn: () => Observable<TData> | Promise<TData>, options?: {
+        staleTime?: number;
+        retry?: RetryValue<any>;
+        retryDelay?: RetryDelayValue<any>;
+        cancelRefetch?: boolean;
+    }): void;
+    /**
+     * 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<TData>(key: QueryKey): TData | undefined;
+    /**
+     * 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<TData>(key: QueryKey, updater: Updater<TData | undefined, TData>): void;
+    /**
+     * 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?: QueryFilters): void;
+    /**
+     * Cancels any in-flight fetches for matching queries.
+     *
+     * @param filters - Which queries to cancel; omit to cancel all.
+     */
+    cancelQueries(filters?: QueryFilters): void;
+    /**
+     * Removes matching queries from the cache entirely, discarding their data.
+     *
+     * @param filters - Which queries to remove; omit to remove all.
+     */
+    removeQueries(filters?: QueryFilters): void;
+    /**
+     * 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?: QueryFilters): number;
+    /**
+     * Returns the number of mutations currently pending. For a reactive count,
+     * prefer {@link injectIsMutating}.
+     */
+    isMutating(): number;
+    static ɵfac: i0.ɵɵFactoryDeclaration<QueryClient, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<QueryClient>;
+}
+
+/** Discriminator identifying each kind of {@link QueryClientFeature}. */
+declare enum QueryClientFeatureKind {
+    DefaultOptions = 0
+}
+/**
+ * An opaque feature passed to {@link provideQueryClient}. Create one with a
+ * `with*` helper such as {@link withDefaultOptions} rather than constructing it
+ * directly; the `ɵ`-prefixed members are internal.
+ */
+interface QueryClientFeature<K extends QueryClientFeatureKind = QueryClientFeatureKind> {
+    ɵkind: K;
+    ɵproviders: Provider[];
+}
+
+/**
+ * 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 } }),
+ *     ),
+ *   ],
+ * }
+ * ```
+ */
+declare function provideQueryClient(...features: QueryClientFeature[]): EnvironmentProviders;
+
+/**
+ * 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'] })
+ * ```
+ */
+declare function injectQueryClient(options?: {
+    injector?: Injector;
+}): 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()}`),
+ *   }))
+ * }
+ * ```
+ */
+declare function injectQuery<TData, TError = Error>(optionsFn: () => QueryOptions<TData, TError>, options?: {
+    injector?: Injector;
+}): QueryResult<TData, TError>;
+
+/**
+ * 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>
+ * ```
+ */
+declare function injectMutation<TData, TError = Error, TVariables = void, TContext = unknown>(optionsFn: () => MutationOptions<TData, TError, TVariables, TContext>, options?: {
+    injector?: Injector;
+}): MutationResult<TData, TError, TVariables>;
+
+/**
+ * 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" />
+ * ```
+ */
+declare function injectIsFetching(filters?: QueryFilters, options?: {
+    injector?: Injector;
+}): Signal<number>;
+
+/**
+ * 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>
+ * ```
+ */
+declare function injectIsMutating(options?: {
+    injector?: Injector;
+}): Signal<number>;
+
+/**
+ * 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())
+ * ```
+ */
+declare function queryOptions<TData, TError = Error>(options: QueryOptions<TData, TError>): QueryOptions<TData, TError>;
+
+/**
+ * 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'] }),
+ *   })
+ * }
+ * ```
+ */
+declare function mutationOptions<TData, TError = Error, TVariables = void, TContext = unknown>(options: MutationOptions<TData, TError, TVariables, TContext>): MutationOptions<TData, TError, TVariables, TContext>;
+
+/** Default query options applied to every query unless overridden per-query. */
+interface DefaultQueryOptions {
+    /** How long fetched data is considered fresh, in ms. Defaults to `0`. */
+    staleTime?: number;
+    /** How long unused (unobserved) data is kept before garbage collection, in ms. */
+    gcTime?: number;
+    /** Retry policy on failure: a boolean, a count, or a predicate. Defaults to `3`. */
+    retry?: RetryValue<unknown>;
+    /** Delay between retries, in ms or a function of the attempt. */
+    retryDelay?: RetryDelayValue<unknown>;
+}
+/** Application-wide defaults configured via {@link withDefaultOptions}. */
+interface DefaultOptions {
+    /** Defaults applied to all queries. */
+    queries?: DefaultQueryOptions;
+}
+/**
+ * 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 } }),
+ * )
+ * ```
+ */
+declare function withDefaultOptions(options: DefaultOptions): QueryClientFeature<QueryClientFeatureKind.DefaultOptions>;
+
+export { QueryClient, QueryClientFeatureKind, injectIsFetching, injectIsMutating, injectMutation, injectQuery, injectQueryClient, mutationOptions, provideQueryClient, queryOptions, withDefaultOptions };
+export type { DefaultOptions, DefaultQueryOptions, DefaultedQueryOptions, MutationFilters, MutationOptions, MutationResult, MutationState, MutationStatus, QueryClientFeature, QueryFilters, QueryKey, QueryOptions, QueryResult, QueryState, QueryStatus, RefetchIntervalValue, RetryDelayValue, RetryValue, Updater };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "ngx-signal-query",
+  "version": "1.0.0-dev.1",
+  "description": "Signal-first data fetching, caching, and mutations for Angular — inspired by TanStack Query.",
+  "keywords": [
+    "angular",
+    "signals",
+    "query",
+    "tanstack",
+    "tanstack-query",
+    "data-fetching",
+    "cache",
+    "mutations",
+    "async-state"
+  ],
+  "license": "MIT",
+  "author": "Dzmitry Hutaryan",
+  "homepage": "https://github.com/dhutaryan/ngx-signal-query#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dhutaryan/ngx-signal-query.git",
+    "directory": "projects/ngx-signal-query"
+  },
+  "bugs": {
+    "url": "https://github.com/dhutaryan/ngx-signal-query/issues"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=19.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/ngx-signal-query.mjs",
+  "typings": "index.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./fesm2022/ngx-signal-query.mjs"
+    }
+  }
+}