wellcrafted/dist/query/index.d.ts

Delightful TypeScript patterns for elegant, type-safe applications

import { Result } from "../result-fCtNge01.js";
import "../index-BoczdhDh.js";
import { DefaultError, MutationFunction, MutationKey, MutationOptions, QueryClient, QueryFunction, QueryKey, QueryObserverOptions } from "@tanstack/query-core";

//#region src/query/utils.d.ts

/**
 * Input options for defining a query.
 *
 * Extends TanStack Query's QueryObserverOptions but replaces queryFn with resultQueryFn.
 * This type represents the configuration for creating a query definition with both
 * reactive and imperative interfaces for data fetching.
 *
 * @template TQueryFnData - The type of data returned by the query function
 * @template TError - The type of error that can be thrown
 * @template TData - The type of data returned by the query (after select transform)
 * @template TQueryKey - The type of the query key
 */
type DefineQueryInput<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, "queryFn"> & {
  queryKey: TQueryKey;
  resultQueryFn: QueryFunction<Result<TQueryFnData, TError>, TQueryKey>;
};
/**
 * Output of defineQuery function.
 *
 * Provides both reactive and imperative interfaces for data fetching:
 * - `options()`: Returns config for use with createQuery() in components
 * - `fetch()`: Always attempts to fetch data (from cache if fresh, network if stale)
 * - `ensure()`: Guarantees data availability, preferring cached data (recommended for preloaders)
 *
 * @template TQueryFnData - The type of data returned by the query function
 * @template TError - The type of error that can be thrown
 * @template TData - The type of data returned by the query (after select transform)
 * @template TQueryKey - The type of the query key
 */
type DefineQueryOutput<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = {
  options: () => QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
  fetch: () => Promise<Result<TData, TError>>;
  ensure: () => Promise<Result<TData, TError>>;
};
/**
 * Input options for defining a mutation.
 *
 * Extends TanStack Query's MutationOptions but replaces mutationFn with resultMutationFn.
 * This type represents the configuration for creating a mutation definition with both
 * reactive and imperative interfaces for data mutations.
 *
 * @template TData - The type of data returned by the mutation
 * @template TError - The type of error that can be thrown
 * @template TVariables - The type of variables passed to the mutation
 * @template TContext - The type of context data for optimistic updates
 */
type DefineMutationInput<TData, TError, TVariables = void, TContext = unknown> = Omit<MutationOptions<TData, TError, TVariables, TContext>, "mutationFn"> & {
  mutationKey: MutationKey;
  resultMutationFn: MutationFunction<Result<TData, TError>, TVariables>;
};
/**
 * Output of defineMutation function.
 *
 * Provides both reactive and imperative interfaces for data mutations:
 * - `options()`: Returns config for use with createMutation() in Svelte components
 * - `execute()`: Directly executes the mutation and returns a Result
 *
 * @template TData - The type of data returned by the mutation
 * @template TError - The type of error that can be thrown
 * @template TVariables - The type of variables passed to the mutation
 * @template TContext - The type of context data for optimistic updates
 */
type DefineMutationOutput<TData, TError, TVariables = void, TContext = unknown> = {
  options: () => MutationOptions<TData, TError, TVariables, TContext>;
  execute: (variables: TVariables) => Promise<Result<TData, TError>>;
};
/**
 * Creates factory functions for defining queries and mutations bound to a specific QueryClient.
 *
 * This factory pattern allows you to create isolated query/mutation definitions that are
 * bound to a specific QueryClient instance, enabling:
 * - Multiple query clients in the same application
 * - Testing with isolated query clients
 * - Framework-agnostic query definitions
 * - Proper separation of concerns between query logic and client instances
 *
 * The returned functions handle Result types automatically, unwrapping them for TanStack Query
 * while maintaining type safety throughout your application.
 *
 * @param queryClient - The QueryClient instance to bind the factories to
 * @returns An object containing defineQuery and defineMutation functions bound to the provided client
 *
 * @example
 * ```typescript
 * // Create your query client
 * const queryClient = new QueryClient({
 *   defaultOptions: {
 *     queries: { staleTime: 5 * 60 * 1000 }
 *   }
 * });
 *
 * // Create the factory functions
 * const { defineQuery, defineMutation } = createQueryFactories(queryClient);
 *
 * // Now use defineQuery and defineMutation as before
 * const userQuery = defineQuery({
 *   queryKey: ['user', userId],
 *   resultQueryFn: () => services.getUser(userId)
 * });
 *
 * // Use in components
 * const query = createQuery(userQuery.options());
 *
 * // Or imperatively
 * const { data, error } = await userQuery.fetch();
 * ```
 */
declare function createQueryFactories(queryClient: QueryClient): {
  defineQuery: <TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = readonly unknown[]>(options: DefineQueryInput<TQueryFnData, TError, TData, TQueryData, TQueryKey>) => DefineQueryOutput<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
  defineMutation: <TData, TError, TVariables = void, TContext = unknown>(options: DefineMutationInput<TData, TError, TVariables, TContext>) => DefineMutationOutput<TData, TError, TVariables, TContext>;
};
//# sourceMappingURL=utils.d.ts.map
//#endregion
export { createQueryFactories };
//# sourceMappingURL=index.d.ts.map