tanstack-query-craft/dist/index.d.mts

Type-safe module registry for TanStack Query with enhanced developer experience

import { MutationKey, QueryKey, QueryClient } from '@tanstack/react-query';

interface TanstackQueryCraftRegistry {
}
type MutationConfig<TVariables = any, TData = unknown> = {
    type: "mutation";
    mutationKey: MutationKey;
    mutationFn: (variables: TVariables) => Promise<TData>;
};
type QueryConfig<TData = unknown> = {
    type: "query";
    queryKey: QueryKey;
    queryFn: () => Promise<TData>;
};
type ModuleConfig = {
    [key: string]: (options?: any) => MutationConfig | QueryConfig;
};

declare class TanstackQueryCraft {
    private modules;
    register<TModuleName extends string, TModule extends ModuleConfig>(moduleName: TModuleName, module: TModule): void;
    get<TModuleName extends string, TKey extends string, TOptions extends any>(moduleName: TModuleName, key: TKey, options?: TOptions): any;
    getModuleNames(): string[];
    getKeys<TModuleName extends keyof TanstackQueryCraftRegistry>(moduleName: TModuleName): ModuleConfig;
}
declare const tanstackQueryCraft: TanstackQueryCraft;

/**
 * Creates a reusable mutation definition for TanStack Query.
 *
 * This function allows you to define a mutation with a key and mutation function,
 * which can be called later with optional variables. It supports both static
 * and dynamic mutation keys based on the provided variables. Mutations are used
 * for operations that modify data (POST, PUT, DELETE, etc.).
 *
 * @template TVariables - The type of variables passed to the mutation (defaults to void)
 * @template TData - The type of data returned by the mutation
 *
 * @param config - Configuration object for the mutation
 * @param config.mutationKey - Static mutation key or a function that generates a key from variables
 * @param config.mutationFn - Async function that performs the mutation using the provided variables
 *
 * @returns A function that accepts optional variables and returns a MutationConfig object
 *
 * @example
 * const createUserMutation = defineMutation({
 *   mutationKey: ['createUser'],
 *   mutationFn: (vars) => createUser(vars.name, vars.email)
 * });
 */
declare function defineMutation<TVariables = void, TData = unknown>(config: {
    mutationKey: MutationKey | ((variables: TVariables) => MutationKey);
    mutationFn: (variables: TVariables) => Promise<TData>;
}): (options?: TVariables) => {
    type: "mutation";
    mutationKey: readonly unknown[];
    mutationFn: (variables: TVariables) => Promise<TData>;
};

/**
 * Creates a reusable query definition for TanStack Query.
 *
 * This function allows you to define a query with a key and fetch function,
 * which can be called later with optional variables. It supports both static
 * and dynamic query keys based on the provided variables.
 *
 * @template TVariables - The type of variables passed to the query (defaults to void)
 * @template TData - The type of data returned by the query
 *
 * @param config - Configuration object for the query
 * @param config.queryKey - Static query key or a function that generates a key from variables
 * @param config.queryFn - Async function that fetches the data using the provided variables
 *
 * @returns A function that accepts optional variables and returns a QueryConfig object
 *
 * @example
 * const getUserQuery = defineQuery({
 *   queryKey: (vars) => ['user', vars.id],
 *   queryFn: (vars) => fetchUser(vars.id)
 * });
 */
declare function defineQuery<TVariables = void, TData = unknown>(config: {
    queryKey: QueryKey | ((variables: TVariables) => QueryKey);
    queryFn: (variables: TVariables) => Promise<TData>;
}): (options?: {
    variables?: TVariables;
}) => {
    type: "query";
    queryKey: readonly unknown[];
    queryFn: () => Promise<TData>;
};

/**
 * Register a module configuration under the given `name` in the global
 * `tanstackQueryCraft` registry and return the module unchanged.
 *
 * This is a convenience wrapper around the registry's `register` method
 * that preserves typing for the module being defined.
 *
 * @param name - The unique module name to register.
 * @param module - The module configuration object (queries/mutations).
 * @returns The same `module` object that was registered.
 */
declare function defineModule<TModuleName extends string, TModule extends ModuleConfig>(name: TModuleName, module: TModule): TModule;

declare function sanitizeKey(key: unknown[] | readonly unknown[]): readonly unknown[];

/**
 * Returns a set of helpers to invalidate queries using a provided
 * `QueryClient` instance. The returned object includes methods to:
 * - `invalidate`: invalidate a single registered query (optionally as the
 *   parent by using `asParent`).
 * - `invalidateByPrefix`: invalidate queries that match a given prefix
 *   `QueryKey`.
 * - `invalidateAll`: invalidate all queries in the client.
 * - `invalidateBulk`: invalidate multiple registered queries in parallel.
 *
 * This helper centralizes invalidation logic so callers can reference
 * registered module/query definitions instead of constructing query keys
 * manually.
 *
 * @param queryClient - The TanStack `QueryClient` used to perform
 *   invalidation operations.
 */
declare function invalidateQueries(queryClient: QueryClient): {
    invalidate: <TModuleName extends keyof TanstackQueryCraftRegistry & string, TKey extends keyof TanstackQueryCraftRegistry[TModuleName] & string, TOptions = TanstackQueryCraftRegistry[TModuleName][TKey] extends (options?: infer O) => any ? O : never>(moduleName: TModuleName, key: TKey, options?: TOptions & {
        asParent?: boolean;
    }) => Promise<void>;
    invalidateByPrefix: (prefix: QueryKey) => Promise<void>;
    invalidateAll: () => Promise<void>;
    invalidateBulk: <TModuleName extends keyof TanstackQueryCraftRegistry & string, TKey extends keyof TanstackQueryCraftRegistry[TModuleName] & string, TOptions = TanstackQueryCraftRegistry[TModuleName][TKey] extends (options?: infer O) => any ? O : never>(queries: Array<{
        moduleName: TModuleName;
        key: TKey;
        options?: TOptions & {
            asParent?: boolean;
        };
    }>) => Promise<void[]>;
    queryClient: QueryClient;
};
/**
 * Retrieve a registered query or mutation configuration from the global
 * `tanstackQueryCraft` registry.
 *
 * This function forwards the `moduleName`, `key` and optional `options`
 * to the registry and returns the resolved configuration or factory
 * result. Type generics ensure the return type matches the registered
 * definition.
 *
 * @param moduleName - The registered module name.
 * @param key - The key of the query or mutation within the module.
 * @param options - Optional options that may be passed to the registered
 *   factory function when resolving the configuration.
 */
declare function getRegisteredQuery<TModuleName extends keyof TanstackQueryCraftRegistry & string, TKey extends keyof TanstackQueryCraftRegistry[TModuleName] & string, TOptions = TanstackQueryCraftRegistry[TModuleName][TKey] extends (options?: infer O) => any ? O : never>(moduleName: TModuleName, key: TKey, options?: TOptions): TanstackQueryCraftRegistry[TModuleName][TKey] extends (options?: any) => infer R ? R : never;
/**
 * Return the list of module names that have been registered in the
 * `tanstackQueryCraft` registry.
 */
declare function getRegisteredModuleNames(): string[];
/**
 * Return the keys (query and mutation identifiers) available for the
 * specified registered module.
 *
 * @param moduleName - The name of the registered module to inspect.
 */
declare function getModuleKeys<TModuleName extends keyof TanstackQueryCraftRegistry>(moduleName: TModuleName): ModuleConfig;

export { type ModuleConfig, type MutationConfig, type QueryConfig, type TanstackQueryCraftRegistry, defineModule, defineMutation, defineQuery, getModuleKeys, getRegisteredModuleNames, getRegisteredQuery, invalidateQueries, sanitizeKey, tanstackQueryCraft };