wellcrafted 0.39.0 → 0.41.0

package/dist/query/index.d.ts

@@ -1,161 +1,189 @@
 import { Result } from "../result-DKwq9BCr.js";
 import "../tap-err-CFhHBPfH.js";
 import "../index-DnoV2ZDO.js";
-import { DefaultError, MutationFunction, MutationKey, MutationOptions, QueryClient, QueryFunction, QueryKey, QueryObserverOptions } from "@tanstack/query-core";
+import { DefaultError, MutationKey, MutationOptions, QueryClient, QueryFunction, QueryKey, QueryObserverOptions } from "@tanstack/query-core";
 
 //#region src/query/utils.d.ts
 
 /**
- * Input options for defining a query.
+ * Input for `queryOptions` and `defineQuery`.
  *
- * Extends TanStack Query's QueryObserverOptions but expects queryFn to return a Result type.
- * This type represents the configuration for creating a query definition with both
- * reactive and imperative interfaces for data fetching.
+ * Mirrors TanStack Query's `QueryObserverOptions` but expects `queryFn` to
+ * return a Wellcrafted `Result`. The Result is unwrapped into TanStack's
+ * throwing data/error contract by `queryOptions`.
  *
- * @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
+ * @template TQueryFnData - The success type produced by `queryFn`
+ * @template TError - The error type carried by the Result
+ * @template TData - The type seen by consumers after `select`
+ * @template TQueryData - The type stored in the cache (usually `TQueryFnData`)
+ * @template TQueryKey - The literal query key tuple
  */
-type DefineQueryInput<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, "queryFn"> & {
+type QueryOptionsInput<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, "queryFn"> & {
   queryKey: TQueryKey;
   queryFn: QueryFunction<Result<TQueryFnData, TError>, TQueryKey>;
 };
 /**
- * Output of defineQuery function.
+ * Input for `mutationOptions` and `defineMutation`.
  *
- * The query definition is directly callable and defaults to `ensure()` behavior,
- * which is recommended for most imperative use cases like preloaders.
+ * Mirrors TanStack Query's `MutationOptions` but expects `mutationFn` to
+ * return a Wellcrafted `Result`. The Result is unwrapped into TanStack's
+ * throwing data/error contract by `mutationOptions`.
  *
- * Provides both reactive and imperative interfaces for data fetching:
- * - `()` (callable): Same as `ensure()` - returns cached data if available, fetches if not
- * - `options`: Returns config for use with useQuery() or createQuery()
- * - `fetch()`: Always attempts to fetch data (from cache if fresh, network if stale)
- * - `ensure()`: Guarantees data availability, preferring cached data (recommended for preloaders)
+ * @template TData - The success type produced by `mutationFn`
+ * @template TError - The error type carried by the Result
+ * @template TVariables - The variables passed to `mutationFn`
+ * @template TContext - The context type for optimistic updates
+ * @template TMutationKey - The literal mutation key tuple
+ */
+type MutationOptionsInput<TData, TError, TVariables = void, TContext = unknown, TMutationKey extends MutationKey = MutationKey> = Omit<MutationOptions<TData, TError, TVariables, TContext>, "mutationFn"> & {
+  mutationKey: TMutationKey;
+  mutationFn: (variables: TVariables) => Result<TData, TError> | Promise<Result<TData, TError>>;
+};
+/**
+ * Adapter from a Result-returning query function to TanStack Query options.
  *
- * @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
+ * This is the single canonical place where `Result<TQueryFnData, TError>`
+ * is converted into TanStack's contract: `Ok(data)` resolves with `data`,
+ * `Err(error)` throws `error` into the query error channel.
  *
- * @example
- * ```typescript
- * const userQuery = defineQuery({...});
+ * Use this directly with framework hooks when you do not need the
+ * `QueryClient`-bound imperative helpers from `defineQuery`:
  *
- * // Directly callable (same as .ensure())
- * const { data, error } = await userQuery();
+ * ```ts
+ * const query = createQuery(() => queryOptions({
+ *   queryKey: ['user', userId],
+ *   queryFn: () => services.getUser(userId),
+ * }));
+ * ```
  *
- * // Or use explicit methods
- * const { data, error } = await userQuery.ensure();
- * const { data, error } = await userQuery.fetch();
+ * `defineQuery` composes through this helper, so the `.options` it returns
+ * is the same shape `queryOptions` produces.
  *
- * // For reactive usage (Svelte 5 requires accessor wrapper)
- * const query = createQuery(() => userQuery.options); // Svelte 5
- * const query = useQuery(userQuery.options); // React
- * ```
+ * @param input - Result-aware query configuration
+ * @returns TanStack Query `QueryObserverOptions` with `queryFn` rewired to
+ *   resolve `Ok` and throw `Err`
  */
-type DefineQueryOutput<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = (() => Promise<Result<TQueryData, TError>>) & {
-  options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
-  fetch: () => Promise<Result<TQueryData, TError>>;
-  ensure: () => Promise<Result<TQueryData, TError>>;
-};
+declare function queryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, const TQueryKey extends QueryKey = QueryKey>(input: QueryOptionsInput<TQueryFnData, TError, TData, TQueryData, TQueryKey>): QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
 /**
- * Input options for defining a mutation.
+ * Adapter from a Result-returning mutation function to TanStack Query options.
  *
- * Extends TanStack Query's MutationOptions but expects mutationFn to return a Result type.
- * This type represents the configuration for creating a mutation definition with both
- * reactive and imperative interfaces for data mutations.
+ * This is the single canonical place where `Result<TData, TError>` is
+ * converted into TanStack's contract: `Ok(data)` resolves with `data`,
+ * `Err(error)` throws `error` into the mutation error channel.
  *
- * @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;
-  mutationFn: MutationFunction<Result<TData, TError>, TVariables>;
-};
-/**
- * Output of defineMutation function.
+ * Use this directly with framework hooks when you do not need the
+ * `QueryClient`-bound imperative helpers from `defineMutation`:
  *
- * The mutation definition is directly callable, which executes the mutation
- * and returns a Result. This is equivalent to calling `.execute()`.
+ * ```ts
+ * const save = createMutation(() => mutationOptions({
+ *   mutationKey: ['saveUser'],
+ *   mutationFn: (input: SaveUserInput) => services.saveUser(input),
+ * }));
+ * ```
  *
- * Provides both reactive and imperative interfaces for data mutations:
- * - `(variables)` (callable): Same as `execute()` - directly executes the mutation
- * - `options`: Returns config for use with useMutation() or createMutation()
- * - `execute(variables)`: Directly executes the mutation and returns a Result
+ * `defineMutation` composes through this helper, so the `.options` it
+ * returns is the same shape `mutationOptions` produces.
  *
- * @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
+ * @param input - Result-aware mutation configuration
+ * @returns TanStack Query `MutationOptions` with `mutationFn` rewired to
+ *   resolve `Ok` and throw `Err`
+ */
+declare function mutationOptions<TData, TError, TVariables = void, TContext = unknown, const TMutationKey extends MutationKey = MutationKey>(input: MutationOptionsInput<TData, TError, TVariables, TContext, TMutationKey>): MutationOptions<TData, TError, TVariables, TContext>;
+/**
+ * Output of `defineQuery`.
  *
- * @example
- * ```typescript
- * const createUser = defineMutation({...});
+ * The returned object is directly callable and defaults to `ensure()` behavior,
+ * which is recommended for most imperative use cases like preloaders.
  *
- * // Directly callable (same as .execute())
- * const { data, error } = await createUser({ name: 'John' });
+ * - `()` (callable): Same as `ensure()`. Returns cached data if available.
+ * - `options`: Options shape produced by `queryOptions`, ready for hooks.
+ * - `fetch()`: Always evaluates freshness; refetches if stale.
+ * - `ensure()`: Prefers cached data; fetches only when missing.
+ */
+type DefineQueryOutput<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = (() => Promise<Result<TQueryData, TError>>) & {
+  options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
+  fetch: () => Promise<Result<TQueryData, TError>>;
+  ensure: () => Promise<Result<TQueryData, TError>>;
+};
+/**
+ * Output of `defineMutation`.
  *
- * // Or use explicit method
- * const { data, error } = await createUser.execute({ name: 'John' });
+ * The returned object is directly callable and executes the mutation,
+ * equivalent to calling `.execute()`.
  *
- * // For reactive usage (Svelte 5 requires accessor wrapper)
- * const mutation = createMutation(() => createUser.options); // Svelte 5
- * const mutation = useMutation(createUser.options); // React
- * ```
+ * - `(variables)` (callable): Same as `execute(variables)`.
+ * - `options`: Options shape produced by `mutationOptions`, ready for hooks.
+ * - `execute(variables)`: Imperatively runs the mutation, returning a Result.
  */
 type DefineMutationOutput<TData, TError, TVariables = void, TContext = unknown> = ((variables: TVariables) => Promise<Result<TData, TError>>) & {
   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.
+ * Creates `defineQuery` and `defineMutation` 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
+ * Use this when you want a reusable query/mutation definition that carries
+ * its own imperative helpers (`.fetch`, `.ensure`, `.execute`, callable form)
+ * powered by a specific client. For local one-shot options that only need
+ * to flow into a framework hook, prefer `queryOptions` / `mutationOptions`
+ * directly: those are platform-agnostic and do not require a `QueryClient`.
  *
- * The returned functions handle Result types automatically, unwrapping them for TanStack Query
- * while maintaining type safety throughout your application.
+ * Both `defineQuery` and `defineMutation` compose through `queryOptions` and
+ * `mutationOptions`, so there is exactly one place that unwraps `Result`
+ * into TanStack's throwing contract.
  *
- * @param queryClient - The QueryClient instance to bind the factories to
- * @returns An object containing defineQuery and defineMutation functions bound to the provided client
+ * @param queryClient - The TanStack `QueryClient` to bind imperative helpers to
  *
  * @example
- * ```typescript
- * // Create your query client
- * const queryClient = new QueryClient({
- *   defaultOptions: {
- *     queries: { staleTime: 5 * 60 * 1000 }
- *   }
- * });
- *
- * // Create the factory functions
+ * ```ts
+ * const queryClient = new QueryClient();
  * const { defineQuery, defineMutation } = createQueryFactories(queryClient);
  *
- * // Now use defineQuery and defineMutation as before
  * const userQuery = defineQuery({
  *   queryKey: ['user', userId],
- *   queryFn: () => services.getUser(userId)
+ *   queryFn: () => services.getUser(userId),
  * });
  *
- * // Use in components (Svelte 5 requires accessor wrapper)
- * const query = createQuery(() => userQuery.options); // Svelte 5
- * const query = useQuery(userQuery.options); // React
+ * // Reactive
+ * const query = createQuery(() => userQuery.options);
  *
- * // Or imperatively
+ * // Imperative
  * const { data, error } = await userQuery.fetch();
  * ```
  */
 declare function createQueryFactories(queryClient: QueryClient): {
-  defineQuery: <TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, const 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>;
+  defineQuery: <TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, const TQueryKey extends QueryKey = readonly unknown[]>(input: QueryOptionsInput<TQueryFnData, TError, TData, TQueryData, TQueryKey>) => DefineQueryOutput<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
+  defineMutation: <TData, TError, TVariables = void, TContext = unknown, const TMutationKey extends MutationKey = readonly unknown[]>(input: MutationOptionsInput<TData, TError, TVariables, TContext, TMutationKey>) => DefineMutationOutput<TData, TError, TVariables, TContext>;
 };
+/**
+ * Identity helper for declaring a TanStack Query key map while preserving
+ * tuple types.
+ *
+ * - **Static entries** like `['users', 'active']` are narrowed to readonly
+ *   tuples with full literal precision (e.g. `readonly ['users', 'active']`)
+ *   via the `const` type parameter modifier. No per-line `as const` needed.
+ *
+ * - **Factory entries** like `(id: string) => ['users', id]` are narrowed to
+ *   tuple SHAPE (e.g. `[string, string]` with correct arity), not widened to
+ *   `string[]`. This happens because the strict tuple constraint provides
+ *   contextual typing into the function body. Literal positions still widen
+ *   without `as const` (TS does not propagate literal narrowing through
+ *   contextual typing). Add `as const` to the body when you need the literal:
+ *   `(id) => ['users', id] as const` -> `readonly ['users', string]`.
+ *
+ * Empty arrays and non-key values are rejected at the type level.
+ *
+ * @example
+ * ```ts
+ * const userKeys = defineKeys({
+ *   all: ['users'],                          // readonly ['users']
+ *   active: ['users', 'active'],             // readonly ['users', 'active']
+ *   detail: (id: string) => ['users', id],   // [string, string] (tuple shape kept)
+ *   page: (n: number) => ['users', n] as const, // readonly ['users', number]
+ * });
+ * ```
+ */
+declare function defineKeys<const TKeys extends Record<string, readonly [unknown, ...unknown[]] | ((...args: never[]) => readonly [unknown, ...unknown[]])>>(keys: TKeys): TKeys;
 //#endregion
-export { createQueryFactories };
+export { MutationOptionsInput, QueryOptionsInput, createQueryFactories, defineKeys, mutationOptions, queryOptions };
 //# sourceMappingURL=index.d.ts.map

package/dist/query/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/query/utils.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAUmE;;;;;;;;KAc9D,gBAO+B,CAAA,eAAA,OAAA,EAAA,SAL1B,YAK0B,EAAA,QAJ3B,YAI2B,EAAA,aAHtB,YAGsB,EAAA,kBAFjB,QAEiB,GAFN,QAEM,CAAA,GADhC,IACgC,CAAnC,oBAAmC,CAAd,YAAc,EAAA,MAAA,EAAQ,KAAR,EAAe,UAAf,EAA2B,SAA3B,CAAA,EAAA,SAAA,CAAA,GAAA;EAAM,QAAE,EAGjC,SAHiC;EAAK,OAAE,EAIzC,aAJyC,CAI3B,MAJ2B,CAIpB,YAJoB,EAIN,MAJM,CAAA,EAIG,SAJH,CAAA;CAAU;;;;;;;;;AAItC;AAAA;;;;;;;;;;;;;;;;;;;;;;;;KAoClB,iBAeU,CAAA,eAAA,OAAA,EAAA,SAbL,YAaK,EAAA,QAZN,YAYM,EAAA,aAXD,YAWC,EAAA,kBAVI,QAUJ,GAVe,QAUf,CAAA,GAAA,CAAA,GAAA,GATJ,OASI,CATI,MASJ,CATW,UASX,EATuB,MASvB,CAAA,CAAA,CAAA,GAAA;EAAO,OAAA,EARZ,oBAQY,CAPpB,YAOoB,EANpB,MAMoB,EALpB,KAKoB,EAJpB,UAIoB,EAHpB,SAGoB,CAAA;EAejB,KAAA,EAAA,GAAA,GAhBS,OAgBT,CAhBiB,MAgBE,CAhBK,UAgBL,EAhBiB,MAgBjB,CAAA,CAAA;EAAA,MAAA,EAAA,GAAA,GAfT,OAeS,CAfD,MAeC,CAfM,UAeN,EAfkB,MAelB,CAAA,CAAA;CAAA;;;;;;;;;;;;AAOK;AAAA,KAPxB,mBAyCA,CAAA,KAAoB,EAAA,MAAA,EAAA,aAAA,IAAA,EAAA,WAAA,OAAA,CAAA,GApCrB,IAoCqB,CApChB,eAoCgB,CApCA,KAoCA,EApCO,MAoCP,EApCe,UAoCf,EApC2B,QAoC3B,CAAA,EAAA,YAAA,CAAA,GAAA;EAAA,WAAA,EAnCX,WAmCW;EAAA,UAKR,EAvCJ,gBAuCI,CAvCa,MAuCb,CAvCoB,KAuCpB,EAvC2B,MAuC3B,CAAA,EAvCoC,UAuCpC,CAAA;CAAU;;;;;;;;;;;;;;AAEiB;AA6C5C;;;;;;;;;;;;;;;;;KApDK,oBAmI0D,CAAA,KAAA,EAAA,MAAA,EAAA,aAAA,IAAA,EAAA,WAAA,OAAA,CAAA,GAAA,CAAA,CAAA,SAAA,EA9H9C,UA8H8C,EAAA,GA9H/B,OA8H+B,CA9HvB,MA8HuB,CA9HhB,KA8HgB,EA9HT,MA8HS,CAAA,CAAA,CAAA,GAAA;EAAS,OAApE,EA7HM,eA6HN,CA7HsB,KA6HtB,EA7H6B,MA6H7B,EA7HqC,UA6HrC,EA7HiD,QA6HjD,CAAA;EAAiB,OA8LU,EAAA,CAAA,SAAA,EA1TT,UA0TS,EAAA,GA1TM,OA0TN,CA1Tc,MA0Td,CA1TqB,KA0TrB,EA1T4B,MA0T5B,CAAA,CAAA;CAAK;;;;;;;;;AACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA9QR,oBAAA,cAAkC;iDAmE1C,eACD,2BACK,sCACc,wCAEf,iBACR,cACA,QACA,OACA,YACA,eAEC,kBAAkB,cAAc,QAAQ,OAAO,YAAY;kFA8LpD,oBAAoB,OAAO,QAAQ,YAAY,cACtD,qBAAqB,OAAO,QAAQ,YAAY"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/query/utils.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAwBA;;;;;;;;;AAO4C,KAPhC,iBAOgC,CAAA,eAAA,OAAA,EAAA,SALlC,YAKkC,EAAA,QAJnC,YAImC,EAAA,aAH9B,YAG8B,EAAA,kBAFzB,QAEyB,GAFd,QAEc,CAAA,GADxC,IACwC,CAA3C,oBAA2C,CAAtB,YAAsB,EAAR,MAAQ,EAAA,KAAA,EAAO,UAAP,EAAmB,SAAnB,CAAA,EAAA,SAAA,CAAA,GAAA;EAAK,QAAE,EAGxC,SAHwC;EAAU,OAAE,EAIrD,aAJqD,CAIvC,MAJuC,CAIhC,YAJgC,EAIlB,MAJkB,CAAA,EAIT,SAJS,CAAA;CAAS;;;;;;;;AAIjD;AAgBvB;;;;;AAMgC,KANpB,oBAMoB,CAAA,KAAA,EAAA,MAAA,EAAA,aAAA,IAAA,EAAA,WAAA,OAAA,EAAA,qBADV,WACU,GADI,WACJ,CAAA,GAA5B,IAA4B,CAAvB,eAAuB,CAAP,KAAO,EAAA,MAAA,EAAQ,UAAR,EAAoB,QAApB,CAAA,EAAA,YAAA,CAAA,GAAA;EAAM,WAAE,EAC1B,YAD0B;EAAU,UAAE,EAAA,CAAA,SAAA,EAGvC,UAHuC,EAAA,GAI9C,MAJ8C,CAIvC,KAJuC,EAIhC,MAJgC,CAAA,GAItB,OAJsB,CAId,MAJc,CAIP,KAJO,EAIA,MAJA,CAAA,CAAA;CAAQ;;;;;;;;;;;AAIvB;AA2BrC;;;;;;;;;;;;;AAQwB,iBARR,YAQQ,CAAA,eAAA,OAAA,EAAA,SANd,YAMc,EAAA,QALf,YAKe,EAAA,aAJV,YAIU,EAAA,wBAHC,QAGD,GAHY,QAGZ,CAAA,CAAA,KAAA,EADhB,iBACgB,CADE,YACF,EADgB,MAChB,EADwB,KACxB,EAD+B,UAC/B,EAD2C,SAC3C,CAAA,CAAA,EAArB,oBAAqB,CAAA,YAAA,EAAc,MAAd,EAAsB,KAAtB,EAA6B,UAA7B,EAAyC,SAAzC,CAAA;;;;;;AAAD;AAqCvB;;;;;;;;;;;;;;;AAckB;AAMjB;;AAeS,iBAnCM,eAmCN,CAAA,KAAA,EAAA,MAAA,EAAA,aAAA,IAAA,EAAA,WAAA,OAAA,EAAA,2BA9BkB,WA8BlB,GA9BgC,WA8BhC,CAAA,CAAA,KAAA,EA5BF,oBA4BE,CA3BR,KA2BQ,EA1BR,MA0BQ,EAzBR,UAyBQ,EAxBR,QAwBQ,EAvBR,YAuBQ,CAAA,CAAA,EArBP,eAqBO,CArBS,KAqBT,EArBgB,MAqBhB,EArBwB,UAqBxB,EArBoC,QAqBpC,CAAA;;;;;;;;;;;;KAFL,iBAWH,CAAA,eAAA,OAAA,EAAA,SATQ,YASR,EAAA,QARO,YAQP,EAAA,aAPY,YAOZ,EAAA,kBANiB,QAMjB,GAN4B,QAM5B,CAAA,GAAA,CAAA,GAAA,GALS,OAKT,CALiB,MAKjB,CALwB,UAKxB,EALoC,MAKpC,CAAA,CAAA,CAAA,GAAA;EAAU,OACV,EALQ,oBAKR,CAJA,YAIA,EAHA,MAGA,EAFA,KAEA,EADA,UACA,EAAA,SAAA,CAAA;EAAS,KALD,EAAA,GAAA,GAOI,OAPJ,CAOY,MAPZ,CAOmB,UAPnB,EAO+B,MAP/B,CAAA,CAAA;EAAoB,MAOD,EAAA,GAAA,GACd,OADc,CACN,MADM,CACC,UADD,EACa,MADb,CAAA,CAAA;CAAU;;;;;;;AACjB;AAAA;;;KAajB,oBAK0C,CAAA,KAAA,EAAA,MAAA,EAAA,aAAA,IAAA,EAAA,WAAA,OAAA,CAAA,GAAA,CAAA,CAAA,SAAA,EAA9B,UAA8B,EAAA,GAAf,OAAe,CAAP,MAAO,CAAA,KAAA,EAAO,MAAP,CAAA,CAAA,CAAA,GAAA;EAAK,OAAE,EAC5C,eAD4C,CAC5B,KAD4B,EACrB,MADqB,EACb,UADa,EACD,QADC,CAAA;EAAM,OAApB,EAAA,CAAA,SAAA,EAElB,UAFkB,EAAA,GAEH,OAFG,CAEK,MAFL,CAEY,KAFZ,EAEmB,MAFnB,CAAA,CAAA;CAAM;;;;;;;;;;;AAEF;AAmC5C;;;;;;;;;;;;;;;;;;;;;AAsEG,iBAtEa,oBAAA,CAsEb,WAAA,EAtE+C,WAsE/C,CAAA,EAAA;EAAM,WACN,EAAA,CAAA,eAAA,OAAA,EAAA,SApEK,KAoEL,EAAA,QAnEI,YAmEJ,EAAA,aAlES,YAkET,EAAA,wBAjEuB,QAiEvB,GAAA,SAAA,OAAA,EAAA,CAAA,CAAA,KAAA,EA/DM,iBA+DN,CA9DA,YA8DA,EA7DA,MA6DA,EA5DA,KA4DA,EA3DA,UA2DA,EA1DA,SA0DA,CAAA,EAAA,GAxDC,iBAwDD,CAxDmB,YAwDnB,EAxDiC,MAwDjC,EAxDyC,KAwDzC,EAxDgD,UAwDhD,EAxD4D,SAwD5D,CAAA;EAAU,cACV,EAAA,CAAA,KAAA,EAAA,MAAA,EAAA,aAAA,IAAA,EAAA,WAAA,OAAA,EAAA,2BAN0B,WAM1B,GAAA,SAAA,OAAA,EAAA,CAAA,CAAA,KAAA,EAJM,oBAIN,CAHA,KAGA,EAFA,MAEA,EADA,UACA,EAAA,QAAA,EACA,YADA,CAAA,EAAA,GAGC,oBAHD,CAGsB,KAHtB,EAG6B,MAH7B,EAGqC,UAHrC,EAGiD,QAHjD,CAAA;CAAQ;;;;;;;AAGa;AAmExB;;;;;AAMqB;;;;;;;;;;;;;;;;iBANL,+BACK,mHAKb,QAAQ"}

package/dist/query/index.js

@@ -4,320 +4,137 @@ import "../result-C9V2Knvt.js";
 
 //#region src/query/utils.ts
 /**
-* Creates factory functions for defining queries and mutations bound to a specific QueryClient.
+* Adapter from a Result-returning query function to TanStack Query options.
 *
-* 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
+* This is the single canonical place where `Result<TQueryFnData, TError>`
+* is converted into TanStack's contract: `Ok(data)` resolves with `data`,
+* `Err(error)` throws `error` into the query error channel.
 *
-* The returned functions handle Result types automatically, unwrapping them for TanStack Query
-* while maintaining type safety throughout your application.
+* Use this directly with framework hooks when you do not need the
+* `QueryClient`-bound imperative helpers from `defineQuery`:
 *
-* @param queryClient - The QueryClient instance to bind the factories to
-* @returns An object containing defineQuery and defineMutation functions bound to the provided client
+* ```ts
+* const query = createQuery(() => queryOptions({
+*   queryKey: ['user', userId],
+*   queryFn: () => services.getUser(userId),
+* }));
+* ```
 *
-* @example
-* ```typescript
-* // Create your query client
-* const queryClient = new QueryClient({
-*   defaultOptions: {
-*     queries: { staleTime: 5 * 60 * 1000 }
-*   }
-* });
+* `defineQuery` composes through this helper, so the `.options` it returns
+* is the same shape `queryOptions` produces.
+*
+* @param input - Result-aware query configuration
+* @returns TanStack Query `QueryObserverOptions` with `queryFn` rewired to
+*   resolve `Ok` and throw `Err`
+*/
+function queryOptions(input) {
+	return {
+		...input,
+		queryFn: async (context) => resolve(await input.queryFn(context))
+	};
+}
+/**
+* Adapter from a Result-returning mutation function to TanStack Query options.
+*
+* This is the single canonical place where `Result<TData, TError>` is
+* converted into TanStack's contract: `Ok(data)` resolves with `data`,
+* `Err(error)` throws `error` into the mutation error channel.
+*
+* Use this directly with framework hooks when you do not need the
+* `QueryClient`-bound imperative helpers from `defineMutation`:
+*
+* ```ts
+* const save = createMutation(() => mutationOptions({
+*   mutationKey: ['saveUser'],
+*   mutationFn: (input: SaveUserInput) => services.saveUser(input),
+* }));
+* ```
+*
+* `defineMutation` composes through this helper, so the `.options` it
+* returns is the same shape `mutationOptions` produces.
+*
+* @param input - Result-aware mutation configuration
+* @returns TanStack Query `MutationOptions` with `mutationFn` rewired to
+*   resolve `Ok` and throw `Err`
+*/
+function mutationOptions(input) {
+	return {
+		...input,
+		mutationFn: async (variables) => resolve(await input.mutationFn(variables))
+	};
+}
+/**
+* Creates `defineQuery` and `defineMutation` bound to a specific `QueryClient`.
+*
+* Use this when you want a reusable query/mutation definition that carries
+* its own imperative helpers (`.fetch`, `.ensure`, `.execute`, callable form)
+* powered by a specific client. For local one-shot options that only need
+* to flow into a framework hook, prefer `queryOptions` / `mutationOptions`
+* directly: those are platform-agnostic and do not require a `QueryClient`.
+*
+* Both `defineQuery` and `defineMutation` compose through `queryOptions` and
+* `mutationOptions`, so there is exactly one place that unwraps `Result`
+* into TanStack's throwing contract.
+*
+* @param queryClient - The TanStack `QueryClient` to bind imperative helpers to
 *
-* // Create the factory functions
+* @example
+* ```ts
+* const queryClient = new QueryClient();
 * const { defineQuery, defineMutation } = createQueryFactories(queryClient);
 *
-* // Now use defineQuery and defineMutation as before
 * const userQuery = defineQuery({
 *   queryKey: ['user', userId],
-*   queryFn: () => services.getUser(userId)
+*   queryFn: () => services.getUser(userId),
 * });
 *
-* // Use in components (Svelte 5 requires accessor wrapper)
-* const query = createQuery(() => userQuery.options); // Svelte 5
-* const query = useQuery(userQuery.options); // React
+* // Reactive
+* const query = createQuery(() => userQuery.options);
 *
-* // Or imperatively
+* // Imperative
 * const { data, error } = await userQuery.fetch();
 * ```
 */
 function createQueryFactories(queryClient) {
-	/**
-	* Creates a query definition that bridges the gap between pure service functions and reactive UI components.
-	*
-	* This factory function is the cornerstone of our data fetching architecture. It wraps service calls
-	* with TanStack Query superpowers while maintaining type safety through Result types.
-	*
-	* The returned query definition is **directly callable** and defaults to `ensure()` behavior,
-	* which is recommended for most imperative use cases like preloaders.
-	*
-	* ## Why use defineQuery?
-	*
-	* 1. **Callable**: Call directly like `userQuery()` for imperative data fetching
-	* 2. **Dual Interface**: Also provides reactive (`.options`) and explicit imperative (`.fetch()`, `.ensure()`) APIs
-	* 3. **Automatic Error Handling**: Service functions return `Result<T, E>` types which are automatically
-	*    unwrapped by TanStack Query, giving you proper error states in your components
-	* 4. **Type Safety**: Full TypeScript support with proper inference for data and error types
-	* 5. **Consistency**: Every query in the app follows the same pattern, making it easy to understand
-	*
-	* @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
-	*
-	* @param options - Query configuration object
-	* @param options.queryKey - Unique key for this query (used for caching and refetching)
-	* @param options.queryFn - Function that fetches data and returns a Result type
-	* @param options.* - Any other TanStack Query options (staleTime, refetchInterval, etc.)
-	*
-	* @returns Callable query definition with:
-	*   - `()` (callable): Same as `ensure()` - returns cached data if available, fetches if not
-	*   - `.options`: Config for use with useQuery() or createQuery()
-	*   - `.fetch()`: Always attempts to fetch (from cache if fresh, network if stale)
-	*   - `.ensure()`: Guarantees data availability, preferring cached data (recommended for preloaders)
-	*
-	* @example
-	* ```typescript
-	* // Step 1: Define your query in the query layer
-	* const userQuery = defineQuery({
-	*   queryKey: ['users', userId],
-	*   queryFn: () => services.getUser(userId), // Returns Result<User, ApiError>
-	*   staleTime: 5 * 60 * 1000, // Consider data fresh for 5 minutes
-	* });
-	*
-	* // Step 2a: Use reactively in a Svelte 5 component (accessor wrapper required)
-	* const query = createQuery(() => userQuery.options);
-	* // query.data is User | undefined
-	* // query.error is ApiError | null
-	*
-	* // Step 2b: Call directly in preloaders (recommended)
-	* export const load = async () => {
-	*   const { data, error } = await userQuery(); // Same as userQuery.ensure()
-	*   if (error) throw error;
-	*   return { user: data };
-	* };
-	*
-	* // Step 2c: Use explicit methods when needed
-	* async function refreshUser() {
-	*   const { data, error } = await userQuery.fetch(); // Force fresh fetch
-	*   if (error) {
-	*     console.error('Failed to fetch user:', error);
-	*   }
-	* }
-	* ```
-	*/
-	const defineQuery = (options) => {
-		const newOptions = {
-			...options,
-			queryFn: async (context) => {
-				let result = options.queryFn(context);
-				if (result instanceof Promise) result = await result;
-				return resolve(result);
-			}
-		};
-		/**
-		* Fetches data for this query using queryClient.fetchQuery().
-		*
-		* This method ALWAYS evaluates freshness and will refetch if data is stale.
-		* It wraps TanStack Query's fetchQuery method, which returns cached data if fresh
-		* or makes a network request if the data is stale or missing.
-		*
-		* **When to use fetch():**
-		* - When you explicitly want to check data freshness
-		* - For user-triggered refresh actions
-		* - When you need the most up-to-date data
-		*
-		* **For preloaders, use ensure() instead** - it's more efficient for initial data loading.
-		*
-		* @returns Promise that resolves with a Result containing either the data or an error
-		*
-		* @example
-		* // Good for user-triggered refresh
-		* const { data, error } = await userQuery.fetch();
-		* if (error) {
-		*   console.error('Failed to load user:', error);
-		* }
-		*/
+	const defineQuery = (input) => {
+		const options = queryOptions(input);
 		async function fetch() {
 			try {
 				return Ok(await queryClient.fetchQuery({
-					queryKey: newOptions.queryKey,
-					queryFn: newOptions.queryFn
+					queryKey: options.queryKey,
+					queryFn: options.queryFn
 				}));
 			} catch (error) {
 				return Err(error);
 			}
 		}
-		/**
-		* Ensures data is available for this query using queryClient.ensureQueryData().
-		*
-		* This method PRIORITIZES cached data and only calls fetchQuery internally if no cached
-		* data exists. It wraps TanStack Query's ensureQueryData method, which is perfect for
-		* guaranteeing data availability with minimal network requests.
-		*
-		* **This is the RECOMMENDED method for preloaders** because:
-		* - It returns cached data immediately if available
-		* - It updates the query client cache properly
-		* - It minimizes network requests during navigation
-		* - It ensures components have data ready when they mount
-		*
-		* **When to use ensure():**
-		* - Route preloaders and data loading functions
-		* - Initial component data requirements
-		* - When cached data is acceptable for immediate display
-		*
-		* This is also the default behavior when calling the query directly.
-		*
-		* @returns Promise that resolves with a Result containing either the data or an error
-		*
-		* @example
-		* // Perfect for preloaders
-		* export const load = async () => {
-		*   const { data, error } = await userQuery.ensure();
-		*   // Or simply: await userQuery();
-		*   if (error) {
-		*     throw error;
-		*   }
-		*   return { user: data };
-		* };
-		*/
 		async function ensure() {
 			try {
 				return Ok(await queryClient.ensureQueryData({
-					queryKey: newOptions.queryKey,
-					queryFn: newOptions.queryFn
+					queryKey: options.queryKey,
+					queryFn: options.queryFn
 				}));
 			} catch (error) {
 				return Err(error);
 			}
 		}
 		return Object.assign(ensure, {
-			options: newOptions,
+			options,
 			fetch,
 			ensure
 		});
 	};
-	/**
-	* Creates a mutation definition for operations that modify data (create, update, delete).
-	*
-	* This factory function is the mutation counterpart to defineQuery. It provides a clean way to
-	* wrap service functions that perform side effects, while maintaining the same dual interface
-	* pattern for maximum flexibility.
-	*
-	* The returned mutation definition is **directly callable**, which executes the mutation
-	* and returns a Result. This is equivalent to calling `.execute()`.
-	*
-	* ## Why use defineMutation?
-	*
-	* 1. **Callable**: Call directly like `createUser({ name: 'John' })` for imperative execution
-	* 2. **Dual Interface**: Also provides reactive (`.options`) and explicit imperative (`.execute()`) APIs
-	* 3. **Consistent Error Handling**: Service functions return `Result<T, E>` types, ensuring
-	*    errors are handled consistently throughout the app
-	* 4. **Cache Management**: Mutations often update the cache after success (see examples)
-	*
-	* @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
-	*
-	* @param options - Mutation configuration object
-	* @param options.mutationKey - Unique key for this mutation (used for tracking in-flight state)
-	* @param options.mutationFn - Function that performs the mutation and returns a Result type
-	* @param options.* - Any other TanStack Mutation options (onSuccess, onError, etc.)
-	*
-	* @returns Callable mutation definition with:
-	*   - `(variables)` (callable): Same as `execute()` - directly executes the mutation
-	*   - `.options`: Config for use with useMutation() or createMutation()
-	*   - `.execute(variables)`: Directly executes the mutation and returns a Result
-	*
-	* @example
-	* ```typescript
-	* // Step 1: Define your mutation with cache updates
-	* const createRecording = defineMutation({
-	*   mutationKey: ['recordings', 'create'],
-	*   mutationFn: async (recording: Recording) => {
-	*     // Call the service
-	*     const result = await services.db.createRecording(recording);
-	*     if (result.error) return Err(result.error);
-	*
-	*     // Update cache on success
-	*     queryClient.setQueryData(['recordings'], (old) =>
-	*       [...(old || []), recording]
-	*     );
-	*
-	*     return Ok(result.data);
-	*   }
-	* });
-	*
-	* // Step 2a: Use reactively in a Svelte 5 component (accessor wrapper required)
-	* const mutation = createMutation(() => createRecording.options);
-	* // Call with: mutation.mutate(recordingData)
-	*
-	* // Step 2b: Call directly in an action (recommended)
-	* async function saveRecording(data: Recording) {
-	*   const { error } = await createRecording(data); // Same as createRecording.execute(data)
-	*   if (error) {
-	*     notify.error({ title: 'Failed to save', description: error.message });
-	*   } else {
-	*     notify.success({ title: 'Recording saved!' });
-	*   }
-	* }
-	* ```
-	*
-	* @tip Calling directly is especially useful for:
-	* - Event handlers that need to await the result
-	* - Sequential operations that depend on each other
-	* - Non-component code that needs to trigger mutations
-	*/
-	const defineMutation = (options) => {
-		const newOptions = {
-			...options,
-			mutationFn: async (variables) => {
-				return resolve(await options.mutationFn(variables));
-			}
-		};
-		/**
-		* Executes the mutation imperatively and returns a Result.
-		*
-		* This is the recommended way to trigger mutations from:
-		* - Button click handlers
-		* - Form submissions
-		* - Keyboard shortcuts
-		* - Any non-component code
-		*
-		* The method automatically wraps the result in a Result type, so you always
-		* get back `{ data, error }` for consistent error handling.
-		*
-		* This is also the default behavior when calling the mutation directly.
-		*
-		* @param variables - The variables to pass to the mutation function
-		* @returns Promise that resolves with a Result containing either the data or an error
-		*
-		* @example
-		* // In an event handler
-		* async function handleSubmit(formData: FormData) {
-		*   const { data, error } = await createUser.execute(formData);
-		*   // Or simply: await createUser(formData);
-		*   if (error) {
-		*     notify.error({ title: 'Failed to create user', description: error.message });
-		*     return;
-		*   }
-		*   goto(`/users/${data.id}`);
-		* }
-		*/
+	const defineMutation = (input) => {
+		const options = mutationOptions(input);
 		async function execute(variables) {
 			try {
-				return Ok(await runMutation(queryClient, newOptions, variables));
+				return Ok(await runMutation(queryClient, options, variables));
 			} catch (error) {
 				return Err(error);
 			}
 		}
 		return Object.assign(execute, {
-			options: newOptions,
+			options,
 			execute
 		});
 	};
@@ -327,27 +144,48 @@ function createQueryFactories(queryClient) {
 	};
 }
 /**
-* Internal helper that executes a mutation directly using the query client's mutation cache.
-*
-* This is what powers the callable behavior and `.execute()` method on mutations.
-* It bypasses the reactive mutation hooks and runs the mutation imperatively,
-* which is perfect for event handlers and other imperative code.
+* Internal helper that executes a mutation directly using the query client's
+* mutation cache. Powers the callable behavior and `.execute()` method on
+* mutations returned from `defineMutation`.
 *
 * @internal
-* @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
-* @param queryClient - The query client instance to use
-* @param options - The mutation options including mutationFn and mutationKey
-* @param variables - The variables to pass to the mutation function
-* @returns Promise that resolves with the mutation result
 */
 function runMutation(queryClient, options, variables) {
 	const mutation = queryClient.getMutationCache().build(queryClient, options);
 	return mutation.execute(variables);
 }
+/**
+* Identity helper for declaring a TanStack Query key map while preserving
+* tuple types.
+*
+* - **Static entries** like `['users', 'active']` are narrowed to readonly
+*   tuples with full literal precision (e.g. `readonly ['users', 'active']`)
+*   via the `const` type parameter modifier. No per-line `as const` needed.
+*
+* - **Factory entries** like `(id: string) => ['users', id]` are narrowed to
+*   tuple SHAPE (e.g. `[string, string]` with correct arity), not widened to
+*   `string[]`. This happens because the strict tuple constraint provides
+*   contextual typing into the function body. Literal positions still widen
+*   without `as const` (TS does not propagate literal narrowing through
+*   contextual typing). Add `as const` to the body when you need the literal:
+*   `(id) => ['users', id] as const` -> `readonly ['users', string]`.
+*
+* Empty arrays and non-key values are rejected at the type level.
+*
+* @example
+* ```ts
+* const userKeys = defineKeys({
+*   all: ['users'],                          // readonly ['users']
+*   active: ['users', 'active'],             // readonly ['users', 'active']
+*   detail: (id: string) => ['users', id],   // [string, string] (tuple shape kept)
+*   page: (n: number) => ['users', n] as const, // readonly ['users', number]
+* });
+* ```
+*/
+function defineKeys(keys) {
+	return keys;
+}
 
 //#endregion
-export { createQueryFactories };
+export { createQueryFactories, defineKeys, mutationOptions, queryOptions };
 //# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["queryClient: QueryClient","options: DefineQueryInput<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>","options: DefineMutationInput<TData, TError, TVariables, TContext>","variables: TVariables","options: MutationOptions<TData, TError, TVariables, TContext>"],"sources":["../../src/query/utils.ts"],"sourcesContent":["import type {\n\tDefaultError,\n\tMutationFunction,\n\tMutationKey,\n\tMutationOptions,\n\tQueryClient,\n\tQueryFunction,\n\tQueryKey,\n\tQueryObserverOptions,\n} from \"@tanstack/query-core\";\nimport { Err, Ok, type Result, resolve } from \"../result/index.js\";\n\n/**\n * Input options for defining a query.\n *\n * Extends TanStack Query's QueryObserverOptions but expects queryFn to return a Result type.\n * This type represents the configuration for creating a query definition with both\n * reactive and imperative interfaces for data fetching.\n *\n * @template TQueryFnData - The type of data returned by the query function\n * @template TError - The type of error that can be thrown\n * @template TData - The type of data returned by the query (after select transform)\n * @template TQueryKey - The type of the query key\n */\ntype DefineQueryInput<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = Omit<\n\tQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,\n\t\"queryFn\"\n> & {\n\tqueryKey: TQueryKey;\n\tqueryFn: QueryFunction<Result<TQueryFnData, TError>, TQueryKey>;\n};\n\n/**\n * Output of defineQuery function.\n *\n * The query definition is directly callable and defaults to `ensure()` behavior,\n * which is recommended for most imperative use cases like preloaders.\n *\n * Provides both reactive and imperative interfaces for data fetching:\n * - `()` (callable): Same as `ensure()` - returns cached data if available, fetches if not\n * - `options`: Returns config for use with useQuery() or createQuery()\n * - `fetch()`: Always attempts to fetch data (from cache if fresh, network if stale)\n * - `ensure()`: Guarantees data availability, preferring cached data (recommended for preloaders)\n *\n * @template TQueryFnData - The type of data returned by the query function\n * @template TError - The type of error that can be thrown\n * @template TData - The type of data returned by the query (after select transform)\n * @template TQueryKey - The type of the query key\n *\n * @example\n * ```typescript\n * const userQuery = defineQuery({...});\n *\n * // Directly callable (same as .ensure())\n * const { data, error } = await userQuery();\n *\n * // Or use explicit methods\n * const { data, error } = await userQuery.ensure();\n * const { data, error } = await userQuery.fetch();\n *\n * // For reactive usage (Svelte 5 requires accessor wrapper)\n * const query = createQuery(() => userQuery.options); // Svelte 5\n * const query = useQuery(userQuery.options); // React\n * ```\n */\ntype DefineQueryOutput<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = (() => Promise<Result<TQueryData, TError>>) & {\n\toptions: QueryObserverOptions<\n\t\tTQueryFnData,\n\t\tTError,\n\t\tTData,\n\t\tTQueryData,\n\t\tTQueryKey\n\t>;\n\tfetch: () => Promise<Result<TQueryData, TError>>;\n\tensure: () => Promise<Result<TQueryData, TError>>;\n};\n\n/**\n * Input options for defining a mutation.\n *\n * Extends TanStack Query's MutationOptions but expects mutationFn to return a Result type.\n * This type represents the configuration for creating a mutation definition with both\n * reactive and imperative interfaces for data mutations.\n *\n * @template TData - The type of data returned by the mutation\n * @template TError - The type of error that can be thrown\n * @template TVariables - The type of variables passed to the mutation\n * @template TContext - The type of context data for optimistic updates\n */\ntype DefineMutationInput<\n\tTData,\n\tTError,\n\tTVariables = void,\n\tTContext = unknown,\n> = Omit<MutationOptions<TData, TError, TVariables, TContext>, \"mutationFn\"> & {\n\tmutationKey: MutationKey;\n\tmutationFn: MutationFunction<Result<TData, TError>, TVariables>;\n};\n\n/**\n * Output of defineMutation function.\n *\n * The mutation definition is directly callable, which executes the mutation\n * and returns a Result. This is equivalent to calling `.execute()`.\n *\n * Provides both reactive and imperative interfaces for data mutations:\n * - `(variables)` (callable): Same as `execute()` - directly executes the mutation\n * - `options`: Returns config for use with useMutation() or createMutation()\n * - `execute(variables)`: Directly executes the mutation and returns a Result\n *\n * @template TData - The type of data returned by the mutation\n * @template TError - The type of error that can be thrown\n * @template TVariables - The type of variables passed to the mutation\n * @template TContext - The type of context data for optimistic updates\n *\n * @example\n * ```typescript\n * const createUser = defineMutation({...});\n *\n * // Directly callable (same as .execute())\n * const { data, error } = await createUser({ name: 'John' });\n *\n * // Or use explicit method\n * const { data, error } = await createUser.execute({ name: 'John' });\n *\n * // For reactive usage (Svelte 5 requires accessor wrapper)\n * const mutation = createMutation(() => createUser.options); // Svelte 5\n * const mutation = useMutation(createUser.options); // React\n * ```\n */\ntype DefineMutationOutput<\n\tTData,\n\tTError,\n\tTVariables = void,\n\tTContext = unknown,\n> = ((variables: TVariables) => Promise<Result<TData, TError>>) & {\n\toptions: MutationOptions<TData, TError, TVariables, TContext>;\n\texecute: (variables: TVariables) => Promise<Result<TData, TError>>;\n};\n\n/**\n * Creates factory functions for defining queries and mutations bound to a specific QueryClient.\n *\n * This factory pattern allows you to create isolated query/mutation definitions that are\n * bound to a specific QueryClient instance, enabling:\n * - Multiple query clients in the same application\n * - Testing with isolated query clients\n * - Framework-agnostic query definitions\n * - Proper separation of concerns between query logic and client instances\n *\n * The returned functions handle Result types automatically, unwrapping them for TanStack Query\n * while maintaining type safety throughout your application.\n *\n * @param queryClient - The QueryClient instance to bind the factories to\n * @returns An object containing defineQuery and defineMutation functions bound to the provided client\n *\n * @example\n * ```typescript\n * // Create your query client\n * const queryClient = new QueryClient({\n *   defaultOptions: {\n *     queries: { staleTime: 5 * 60 * 1000 }\n *   }\n * });\n *\n * // Create the factory functions\n * const { defineQuery, defineMutation } = createQueryFactories(queryClient);\n *\n * // Now use defineQuery and defineMutation as before\n * const userQuery = defineQuery({\n *   queryKey: ['user', userId],\n *   queryFn: () => services.getUser(userId)\n * });\n *\n * // Use in components (Svelte 5 requires accessor wrapper)\n * const query = createQuery(() => userQuery.options); // Svelte 5\n * const query = useQuery(userQuery.options); // React\n *\n * // Or imperatively\n * const { data, error } = await userQuery.fetch();\n * ```\n */\nexport function createQueryFactories(queryClient: QueryClient) {\n\t/**\n\t * Creates a query definition that bridges the gap between pure service functions and reactive UI components.\n\t *\n\t * This factory function is the cornerstone of our data fetching architecture. It wraps service calls\n\t * with TanStack Query superpowers while maintaining type safety through Result types.\n\t *\n\t * The returned query definition is **directly callable** and defaults to `ensure()` behavior,\n\t * which is recommended for most imperative use cases like preloaders.\n\t *\n\t * ## Why use defineQuery?\n\t *\n\t * 1. **Callable**: Call directly like `userQuery()` for imperative data fetching\n\t * 2. **Dual Interface**: Also provides reactive (`.options`) and explicit imperative (`.fetch()`, `.ensure()`) APIs\n\t * 3. **Automatic Error Handling**: Service functions return `Result<T, E>` types which are automatically\n\t *    unwrapped by TanStack Query, giving you proper error states in your components\n\t * 4. **Type Safety**: Full TypeScript support with proper inference for data and error types\n\t * 5. **Consistency**: Every query in the app follows the same pattern, making it easy to understand\n\t *\n\t * @template TQueryFnData - The type of data returned by the query function\n\t * @template TError - The type of error that can be thrown\n\t * @template TData - The type of data returned by the query (after select transform)\n\t * @template TQueryKey - The type of the query key\n\t *\n\t * @param options - Query configuration object\n\t * @param options.queryKey - Unique key for this query (used for caching and refetching)\n\t * @param options.queryFn - Function that fetches data and returns a Result type\n\t * @param options.* - Any other TanStack Query options (staleTime, refetchInterval, etc.)\n\t *\n\t * @returns Callable query definition with:\n\t *   - `()` (callable): Same as `ensure()` - returns cached data if available, fetches if not\n\t *   - `.options`: Config for use with useQuery() or createQuery()\n\t *   - `.fetch()`: Always attempts to fetch (from cache if fresh, network if stale)\n\t *   - `.ensure()`: Guarantees data availability, preferring cached data (recommended for preloaders)\n\t *\n\t * @example\n\t * ```typescript\n\t * // Step 1: Define your query in the query layer\n\t * const userQuery = defineQuery({\n\t *   queryKey: ['users', userId],\n\t *   queryFn: () => services.getUser(userId), // Returns Result<User, ApiError>\n\t *   staleTime: 5 * 60 * 1000, // Consider data fresh for 5 minutes\n\t * });\n\t *\n\t * // Step 2a: Use reactively in a Svelte 5 component (accessor wrapper required)\n\t * const query = createQuery(() => userQuery.options);\n\t * // query.data is User | undefined\n\t * // query.error is ApiError | null\n\t *\n\t * // Step 2b: Call directly in preloaders (recommended)\n\t * export const load = async () => {\n\t *   const { data, error } = await userQuery(); // Same as userQuery.ensure()\n\t *   if (error) throw error;\n\t *   return { user: data };\n\t * };\n\t *\n\t * // Step 2c: Use explicit methods when needed\n\t * async function refreshUser() {\n\t *   const { data, error } = await userQuery.fetch(); // Force fresh fetch\n\t *   if (error) {\n\t *     console.error('Failed to fetch user:', error);\n\t *   }\n\t * }\n\t * ```\n\t */\n\tconst defineQuery = <\n\t\tTQueryFnData = unknown,\n\t\tTError = DefaultError,\n\t\tTData = TQueryFnData,\n\t\tTQueryData = TQueryFnData,\n\t\tconst TQueryKey extends QueryKey = QueryKey,\n\t>(\n\t\toptions: DefineQueryInput<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>,\n\t): DefineQueryOutput<TQueryFnData, TError, TData, TQueryData, TQueryKey> => {\n\t\tconst newOptions = {\n\t\t\t...options,\n\t\t\tqueryFn: async (context) => {\n\t\t\t\tlet result = options.queryFn(context);\n\t\t\t\tif (result instanceof Promise) result = await result;\n\t\t\t\treturn resolve(result);\n\t\t\t},\n\t\t} satisfies QueryObserverOptions<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>;\n\n\t\t/**\n\t\t * Fetches data for this query using queryClient.fetchQuery().\n\t\t *\n\t\t * This method ALWAYS evaluates freshness and will refetch if data is stale.\n\t\t * It wraps TanStack Query's fetchQuery method, which returns cached data if fresh\n\t\t * or makes a network request if the data is stale or missing.\n\t\t *\n\t\t * **When to use fetch():**\n\t\t * - When you explicitly want to check data freshness\n\t\t * - For user-triggered refresh actions\n\t\t * - When you need the most up-to-date data\n\t\t *\n\t\t * **For preloaders, use ensure() instead** - it's more efficient for initial data loading.\n\t\t *\n\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t *\n\t\t * @example\n\t\t * // Good for user-triggered refresh\n\t\t * const { data, error } = await userQuery.fetch();\n\t\t * if (error) {\n\t\t *   console.error('Failed to load user:', error);\n\t\t * }\n\t\t */\n\t\tasync function fetch(): Promise<Result<TQueryData, TError>> {\n\t\t\ttry {\n\t\t\t\treturn Ok(\n\t\t\t\t\tawait queryClient.fetchQuery<\n\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\tTError,\n\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t>({\n\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\tqueryFn: newOptions.queryFn,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\t/**\n\t\t * Ensures data is available for this query using queryClient.ensureQueryData().\n\t\t *\n\t\t * This method PRIORITIZES cached data and only calls fetchQuery internally if no cached\n\t\t * data exists. It wraps TanStack Query's ensureQueryData method, which is perfect for\n\t\t * guaranteeing data availability with minimal network requests.\n\t\t *\n\t\t * **This is the RECOMMENDED method for preloaders** because:\n\t\t * - It returns cached data immediately if available\n\t\t * - It updates the query client cache properly\n\t\t * - It minimizes network requests during navigation\n\t\t * - It ensures components have data ready when they mount\n\t\t *\n\t\t * **When to use ensure():**\n\t\t * - Route preloaders and data loading functions\n\t\t * - Initial component data requirements\n\t\t * - When cached data is acceptable for immediate display\n\t\t *\n\t\t * This is also the default behavior when calling the query directly.\n\t\t *\n\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t *\n\t\t * @example\n\t\t * // Perfect for preloaders\n\t\t * export const load = async () => {\n\t\t *   const { data, error } = await userQuery.ensure();\n\t\t *   // Or simply: await userQuery();\n\t\t *   if (error) {\n\t\t *     throw error;\n\t\t *   }\n\t\t *   return { user: data };\n\t\t * };\n\t\t */\n\t\tasync function ensure(): Promise<Result<TQueryData, TError>> {\n\t\t\ttry {\n\t\t\t\treturn Ok(\n\t\t\t\t\tawait queryClient.ensureQueryData<\n\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\tTError,\n\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t>({\n\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\tqueryFn: newOptions.queryFn,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\t// Create a callable function that defaults to ensure() behavior\n\t\t// and attach options, fetch, and ensure as properties\n\t\treturn Object.assign(ensure, {\n\t\t\toptions: newOptions,\n\t\t\tfetch,\n\t\t\tensure,\n\t\t});\n\t};\n\n\t/**\n\t * Creates a mutation definition for operations that modify data (create, update, delete).\n\t *\n\t * This factory function is the mutation counterpart to defineQuery. It provides a clean way to\n\t * wrap service functions that perform side effects, while maintaining the same dual interface\n\t * pattern for maximum flexibility.\n\t *\n\t * The returned mutation definition is **directly callable**, which executes the mutation\n\t * and returns a Result. This is equivalent to calling `.execute()`.\n\t *\n\t * ## Why use defineMutation?\n\t *\n\t * 1. **Callable**: Call directly like `createUser({ name: 'John' })` for imperative execution\n\t * 2. **Dual Interface**: Also provides reactive (`.options`) and explicit imperative (`.execute()`) APIs\n\t * 3. **Consistent Error Handling**: Service functions return `Result<T, E>` types, ensuring\n\t *    errors are handled consistently throughout the app\n\t * 4. **Cache Management**: Mutations often update the cache after success (see examples)\n\t *\n\t * @template TData - The type of data returned by the mutation\n\t * @template TError - The type of error that can be thrown\n\t * @template TVariables - The type of variables passed to the mutation\n\t * @template TContext - The type of context data for optimistic updates\n\t *\n\t * @param options - Mutation configuration object\n\t * @param options.mutationKey - Unique key for this mutation (used for tracking in-flight state)\n\t * @param options.mutationFn - Function that performs the mutation and returns a Result type\n\t * @param options.* - Any other TanStack Mutation options (onSuccess, onError, etc.)\n\t *\n\t * @returns Callable mutation definition with:\n\t *   - `(variables)` (callable): Same as `execute()` - directly executes the mutation\n\t *   - `.options`: Config for use with useMutation() or createMutation()\n\t *   - `.execute(variables)`: Directly executes the mutation and returns a Result\n\t *\n\t * @example\n\t * ```typescript\n\t * // Step 1: Define your mutation with cache updates\n\t * const createRecording = defineMutation({\n\t *   mutationKey: ['recordings', 'create'],\n\t *   mutationFn: async (recording: Recording) => {\n\t *     // Call the service\n\t *     const result = await services.db.createRecording(recording);\n\t *     if (result.error) return Err(result.error);\n\t *\n\t *     // Update cache on success\n\t *     queryClient.setQueryData(['recordings'], (old) =>\n\t *       [...(old || []), recording]\n\t *     );\n\t *\n\t *     return Ok(result.data);\n\t *   }\n\t * });\n\t *\n\t * // Step 2a: Use reactively in a Svelte 5 component (accessor wrapper required)\n\t * const mutation = createMutation(() => createRecording.options);\n\t * // Call with: mutation.mutate(recordingData)\n\t *\n\t * // Step 2b: Call directly in an action (recommended)\n\t * async function saveRecording(data: Recording) {\n\t *   const { error } = await createRecording(data); // Same as createRecording.execute(data)\n\t *   if (error) {\n\t *     notify.error({ title: 'Failed to save', description: error.message });\n\t *   } else {\n\t *     notify.success({ title: 'Recording saved!' });\n\t *   }\n\t * }\n\t * ```\n\t *\n\t * @tip Calling directly is especially useful for:\n\t * - Event handlers that need to await the result\n\t * - Sequential operations that depend on each other\n\t * - Non-component code that needs to trigger mutations\n\t */\n\tconst defineMutation = <TData, TError, TVariables = void, TContext = unknown>(\n\t\toptions: DefineMutationInput<TData, TError, TVariables, TContext>,\n\t): DefineMutationOutput<TData, TError, TVariables, TContext> => {\n\t\tconst newOptions = {\n\t\t\t...options,\n\t\t\tmutationFn: async (variables: TVariables) => {\n\t\t\t\treturn resolve(await options.mutationFn(variables));\n\t\t\t},\n\t\t} satisfies MutationOptions<TData, TError, TVariables, TContext>;\n\n\t\t/**\n\t\t * Executes the mutation imperatively and returns a Result.\n\t\t *\n\t\t * This is the recommended way to trigger mutations from:\n\t\t * - Button click handlers\n\t\t * - Form submissions\n\t\t * - Keyboard shortcuts\n\t\t * - Any non-component code\n\t\t *\n\t\t * The method automatically wraps the result in a Result type, so you always\n\t\t * get back `{ data, error }` for consistent error handling.\n\t\t *\n\t\t * This is also the default behavior when calling the mutation directly.\n\t\t *\n\t\t * @param variables - The variables to pass to the mutation function\n\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t *\n\t\t * @example\n\t\t * // In an event handler\n\t\t * async function handleSubmit(formData: FormData) {\n\t\t *   const { data, error } = await createUser.execute(formData);\n\t\t *   // Or simply: await createUser(formData);\n\t\t *   if (error) {\n\t\t *     notify.error({ title: 'Failed to create user', description: error.message });\n\t\t *     return;\n\t\t *   }\n\t\t *   goto(`/users/${data.id}`);\n\t\t * }\n\t\t */\n\t\tasync function execute(variables: TVariables) {\n\t\t\ttry {\n\t\t\t\treturn Ok(await runMutation(queryClient, newOptions, variables));\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\t// Create a callable function that executes the mutation\n\t\t// and attach options and execute as properties\n\t\treturn Object.assign(execute, {\n\t\t\toptions: newOptions,\n\t\t\texecute,\n\t\t});\n\t};\n\n\treturn {\n\t\tdefineQuery,\n\t\tdefineMutation,\n\t};\n}\n\n/**\n * Internal helper that executes a mutation directly using the query client's mutation cache.\n *\n * This is what powers the callable behavior and `.execute()` method on mutations.\n * It bypasses the reactive mutation hooks and runs the mutation imperatively,\n * which is perfect for event handlers and other imperative code.\n *\n * @internal\n * @template TData - The type of data returned by the mutation\n * @template TError - The type of error that can be thrown\n * @template TVariables - The type of variables passed to the mutation\n * @template TContext - The type of context data\n * @param queryClient - The query client instance to use\n * @param options - The mutation options including mutationFn and mutationKey\n * @param variables - The variables to pass to the mutation function\n * @returns Promise that resolves with the mutation result\n */\nfunction runMutation<TData, TError, TVariables, TContext>(\n\tqueryClient: QueryClient,\n\toptions: MutationOptions<TData, TError, TVariables, TContext>,\n\tvariables: TVariables,\n) {\n\tconst mutation = queryClient.getMutationCache().build(queryClient, options);\n\treturn mutation.execute(variables);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkMA,SAAgB,qBAAqBA,aAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiE9D,MAAM,cAAc,CAOnBC,YAO2E;EAC3E,MAAM,aAAa;GAClB,GAAG;GACH,SAAS,OAAO,YAAY;IAC3B,IAAI,SAAS,QAAQ,QAAQ,QAAQ;AACrC,QAAI,kBAAkB,QAAS,UAAS,MAAM;AAC9C,WAAO,QAAQ,OAAO;GACtB;EACD;;;;;;;;;;;;;;;;;;;;;;;;EA+BD,eAAe,QAA6C;AAC3D,OAAI;AACH,WAAO,GACN,MAAM,YAAY,WAKhB;KACD,UAAU,WAAW;KACrB,SAAS,WAAW;IACpB,EAAC,CACF;GACD,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCD,eAAe,SAA8C;AAC5D,OAAI;AACH,WAAO,GACN,MAAM,YAAY,gBAKhB;KACD,UAAU,WAAW;KACrB,SAAS,WAAW;IACpB,EAAC,CACF;GACD,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;AAID,SAAO,OAAO,OAAO,QAAQ;GAC5B,SAAS;GACT;GACA;EACA,EAAC;CACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0ED,MAAM,iBAAiB,CACtBC,YAC+D;EAC/D,MAAM,aAAa;GAClB,GAAG;GACH,YAAY,OAAOC,cAA0B;AAC5C,WAAO,QAAQ,MAAM,QAAQ,WAAW,UAAU,CAAC;GACnD;EACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BD,eAAe,QAAQA,WAAuB;AAC7C,OAAI;AACH,WAAO,GAAG,MAAM,YAAY,aAAa,YAAY,UAAU,CAAC;GAChE,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;AAID,SAAO,OAAO,OAAO,SAAS;GAC7B,SAAS;GACT;EACA,EAAC;CACF;AAED,QAAO;EACN;EACA;CACA;AACD;;;;;;;;;;;;;;;;;;AAmBD,SAAS,YACRH,aACAI,SACAD,WACC;CACD,MAAM,WAAW,YAAY,kBAAkB,CAAC,MAAM,aAAa,QAAQ;AAC3E,QAAO,SAAS,QAAQ,UAAU;AAClC"}
+{"version":3,"file":"index.js","names":["input: QueryOptionsInput<TQueryFnData, TError, TData, TQueryData, TQueryKey>","input: MutationOptionsInput<\n\t\tTData,\n\t\tTError,\n\t\tTVariables,\n\t\tTContext,\n\t\tTMutationKey\n\t>","variables: TVariables","queryClient: QueryClient","input: QueryOptionsInput<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>","input: MutationOptionsInput<\n\t\t\tTData,\n\t\t\tTError,\n\t\t\tTVariables,\n\t\t\tTContext,\n\t\t\tTMutationKey\n\t\t>","options: MutationOptions<TData, TError, TVariables, TContext>","keys: TKeys"],"sources":["../../src/query/utils.ts"],"sourcesContent":["import type {\n\tDefaultError,\n\tMutationKey,\n\tMutationOptions,\n\tQueryClient,\n\tQueryFunction,\n\tQueryKey,\n\tQueryObserverOptions,\n} from \"@tanstack/query-core\";\nimport { Err, Ok, type Result, resolve } from \"../result/index.js\";\n\n/**\n * Input for `queryOptions` and `defineQuery`.\n *\n * Mirrors TanStack Query's `QueryObserverOptions` but expects `queryFn` to\n * return a Wellcrafted `Result`. The Result is unwrapped into TanStack's\n * throwing data/error contract by `queryOptions`.\n *\n * @template TQueryFnData - The success type produced by `queryFn`\n * @template TError - The error type carried by the Result\n * @template TData - The type seen by consumers after `select`\n * @template TQueryData - The type stored in the cache (usually `TQueryFnData`)\n * @template TQueryKey - The literal query key tuple\n */\nexport type QueryOptionsInput<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = Omit<\n\tQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,\n\t\"queryFn\"\n> & {\n\tqueryKey: TQueryKey;\n\tqueryFn: QueryFunction<Result<TQueryFnData, TError>, TQueryKey>;\n};\n\n/**\n * Input for `mutationOptions` and `defineMutation`.\n *\n * Mirrors TanStack Query's `MutationOptions` but expects `mutationFn` to\n * return a Wellcrafted `Result`. The Result is unwrapped into TanStack's\n * throwing data/error contract by `mutationOptions`.\n *\n * @template TData - The success type produced by `mutationFn`\n * @template TError - The error type carried by the Result\n * @template TVariables - The variables passed to `mutationFn`\n * @template TContext - The context type for optimistic updates\n * @template TMutationKey - The literal mutation key tuple\n */\nexport type MutationOptionsInput<\n\tTData,\n\tTError,\n\tTVariables = void,\n\tTContext = unknown,\n\tTMutationKey extends MutationKey = MutationKey,\n> = Omit<MutationOptions<TData, TError, TVariables, TContext>, \"mutationFn\"> & {\n\tmutationKey: TMutationKey;\n\tmutationFn: (\n\t\tvariables: TVariables,\n\t) => Result<TData, TError> | Promise<Result<TData, TError>>;\n};\n\n/**\n * Adapter from a Result-returning query function to TanStack Query options.\n *\n * This is the single canonical place where `Result<TQueryFnData, TError>`\n * is converted into TanStack's contract: `Ok(data)` resolves with `data`,\n * `Err(error)` throws `error` into the query error channel.\n *\n * Use this directly with framework hooks when you do not need the\n * `QueryClient`-bound imperative helpers from `defineQuery`:\n *\n * ```ts\n * const query = createQuery(() => queryOptions({\n *   queryKey: ['user', userId],\n *   queryFn: () => services.getUser(userId),\n * }));\n * ```\n *\n * `defineQuery` composes through this helper, so the `.options` it returns\n * is the same shape `queryOptions` produces.\n *\n * @param input - Result-aware query configuration\n * @returns TanStack Query `QueryObserverOptions` with `queryFn` rewired to\n *   resolve `Ok` and throw `Err`\n */\nexport function queryOptions<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tconst TQueryKey extends QueryKey = QueryKey,\n>(\n\tinput: QueryOptionsInput<TQueryFnData, TError, TData, TQueryData, TQueryKey>,\n): QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> {\n\treturn {\n\t\t...input,\n\t\tqueryFn: async (context) => resolve(await input.queryFn(context)),\n\t} satisfies QueryObserverOptions<\n\t\tTQueryFnData,\n\t\tTError,\n\t\tTData,\n\t\tTQueryData,\n\t\tTQueryKey\n\t>;\n}\n\n/**\n * Adapter from a Result-returning mutation function to TanStack Query options.\n *\n * This is the single canonical place where `Result<TData, TError>` is\n * converted into TanStack's contract: `Ok(data)` resolves with `data`,\n * `Err(error)` throws `error` into the mutation error channel.\n *\n * Use this directly with framework hooks when you do not need the\n * `QueryClient`-bound imperative helpers from `defineMutation`:\n *\n * ```ts\n * const save = createMutation(() => mutationOptions({\n *   mutationKey: ['saveUser'],\n *   mutationFn: (input: SaveUserInput) => services.saveUser(input),\n * }));\n * ```\n *\n * `defineMutation` composes through this helper, so the `.options` it\n * returns is the same shape `mutationOptions` produces.\n *\n * @param input - Result-aware mutation configuration\n * @returns TanStack Query `MutationOptions` with `mutationFn` rewired to\n *   resolve `Ok` and throw `Err`\n */\nexport function mutationOptions<\n\tTData,\n\tTError,\n\tTVariables = void,\n\tTContext = unknown,\n\tconst TMutationKey extends MutationKey = MutationKey,\n>(\n\tinput: MutationOptionsInput<\n\t\tTData,\n\t\tTError,\n\t\tTVariables,\n\t\tTContext,\n\t\tTMutationKey\n\t>,\n): MutationOptions<TData, TError, TVariables, TContext> {\n\treturn {\n\t\t...input,\n\t\tmutationFn: async (variables: TVariables) =>\n\t\t\tresolve(await input.mutationFn(variables)),\n\t} satisfies MutationOptions<TData, TError, TVariables, TContext>;\n}\n\n/**\n * Output of `defineQuery`.\n *\n * The returned object is directly callable and defaults to `ensure()` behavior,\n * which is recommended for most imperative use cases like preloaders.\n *\n * - `()` (callable): Same as `ensure()`. Returns cached data if available.\n * - `options`: Options shape produced by `queryOptions`, ready for hooks.\n * - `fetch()`: Always evaluates freshness; refetches if stale.\n * - `ensure()`: Prefers cached data; fetches only when missing.\n */\ntype DefineQueryOutput<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = (() => Promise<Result<TQueryData, TError>>) & {\n\toptions: QueryObserverOptions<\n\t\tTQueryFnData,\n\t\tTError,\n\t\tTData,\n\t\tTQueryData,\n\t\tTQueryKey\n\t>;\n\tfetch: () => Promise<Result<TQueryData, TError>>;\n\tensure: () => Promise<Result<TQueryData, TError>>;\n};\n\n/**\n * Output of `defineMutation`.\n *\n * The returned object is directly callable and executes the mutation,\n * equivalent to calling `.execute()`.\n *\n * - `(variables)` (callable): Same as `execute(variables)`.\n * - `options`: Options shape produced by `mutationOptions`, ready for hooks.\n * - `execute(variables)`: Imperatively runs the mutation, returning a Result.\n */\ntype DefineMutationOutput<\n\tTData,\n\tTError,\n\tTVariables = void,\n\tTContext = unknown,\n> = ((variables: TVariables) => Promise<Result<TData, TError>>) & {\n\toptions: MutationOptions<TData, TError, TVariables, TContext>;\n\texecute: (variables: TVariables) => Promise<Result<TData, TError>>;\n};\n\n/**\n * Creates `defineQuery` and `defineMutation` bound to a specific `QueryClient`.\n *\n * Use this when you want a reusable query/mutation definition that carries\n * its own imperative helpers (`.fetch`, `.ensure`, `.execute`, callable form)\n * powered by a specific client. For local one-shot options that only need\n * to flow into a framework hook, prefer `queryOptions` / `mutationOptions`\n * directly: those are platform-agnostic and do not require a `QueryClient`.\n *\n * Both `defineQuery` and `defineMutation` compose through `queryOptions` and\n * `mutationOptions`, so there is exactly one place that unwraps `Result`\n * into TanStack's throwing contract.\n *\n * @param queryClient - The TanStack `QueryClient` to bind imperative helpers to\n *\n * @example\n * ```ts\n * const queryClient = new QueryClient();\n * const { defineQuery, defineMutation } = createQueryFactories(queryClient);\n *\n * const userQuery = defineQuery({\n *   queryKey: ['user', userId],\n *   queryFn: () => services.getUser(userId),\n * });\n *\n * // Reactive\n * const query = createQuery(() => userQuery.options);\n *\n * // Imperative\n * const { data, error } = await userQuery.fetch();\n * ```\n */\nexport function createQueryFactories(queryClient: QueryClient) {\n\tconst defineQuery = <\n\t\tTQueryFnData = unknown,\n\t\tTError = DefaultError,\n\t\tTData = TQueryFnData,\n\t\tTQueryData = TQueryFnData,\n\t\tconst TQueryKey extends QueryKey = QueryKey,\n\t>(\n\t\tinput: QueryOptionsInput<\n\t\t\tTQueryFnData,\n\t\t\tTError,\n\t\t\tTData,\n\t\t\tTQueryData,\n\t\t\tTQueryKey\n\t\t>,\n\t): DefineQueryOutput<TQueryFnData, TError, TData, TQueryData, TQueryKey> => {\n\t\tconst options = queryOptions(input);\n\n\t\tasync function fetch(): Promise<Result<TQueryData, TError>> {\n\t\t\ttry {\n\t\t\t\treturn Ok(\n\t\t\t\t\tawait queryClient.fetchQuery<\n\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\tTError,\n\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t>({\n\t\t\t\t\t\tqueryKey: options.queryKey,\n\t\t\t\t\t\tqueryFn: options.queryFn,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\tasync function ensure(): Promise<Result<TQueryData, TError>> {\n\t\t\ttry {\n\t\t\t\treturn Ok(\n\t\t\t\t\tawait queryClient.ensureQueryData<\n\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\tTError,\n\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t>({\n\t\t\t\t\t\tqueryKey: options.queryKey,\n\t\t\t\t\t\tqueryFn: options.queryFn,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\treturn Object.assign(ensure, {\n\t\t\toptions,\n\t\t\tfetch,\n\t\t\tensure,\n\t\t});\n\t};\n\n\tconst defineMutation = <\n\t\tTData,\n\t\tTError,\n\t\tTVariables = void,\n\t\tTContext = unknown,\n\t\tconst TMutationKey extends MutationKey = MutationKey,\n\t>(\n\t\tinput: MutationOptionsInput<\n\t\t\tTData,\n\t\t\tTError,\n\t\t\tTVariables,\n\t\t\tTContext,\n\t\t\tTMutationKey\n\t\t>,\n\t): DefineMutationOutput<TData, TError, TVariables, TContext> => {\n\t\tconst options = mutationOptions(input);\n\n\t\tasync function execute(variables: TVariables) {\n\t\t\ttry {\n\t\t\t\treturn Ok(await runMutation(queryClient, options, variables));\n\t\t\t} catch (error) {\n\t\t\t\treturn Err(error as TError);\n\t\t\t}\n\t\t}\n\n\t\treturn Object.assign(execute, {\n\t\t\toptions,\n\t\t\texecute,\n\t\t});\n\t};\n\n\treturn {\n\t\tdefineQuery,\n\t\tdefineMutation,\n\t};\n}\n\n/**\n * Internal helper that executes a mutation directly using the query client's\n * mutation cache. Powers the callable behavior and `.execute()` method on\n * mutations returned from `defineMutation`.\n *\n * @internal\n */\nfunction runMutation<TData, TError, TVariables, TContext>(\n\tqueryClient: QueryClient,\n\toptions: MutationOptions<TData, TError, TVariables, TContext>,\n\tvariables: TVariables,\n) {\n\tconst mutation = queryClient.getMutationCache().build(queryClient, options);\n\treturn mutation.execute(variables);\n}\n\n/**\n * Identity helper for declaring a TanStack Query key map while preserving\n * tuple types.\n *\n * - **Static entries** like `['users', 'active']` are narrowed to readonly\n *   tuples with full literal precision (e.g. `readonly ['users', 'active']`)\n *   via the `const` type parameter modifier. No per-line `as const` needed.\n *\n * - **Factory entries** like `(id: string) => ['users', id]` are narrowed to\n *   tuple SHAPE (e.g. `[string, string]` with correct arity), not widened to\n *   `string[]`. This happens because the strict tuple constraint provides\n *   contextual typing into the function body. Literal positions still widen\n *   without `as const` (TS does not propagate literal narrowing through\n *   contextual typing). Add `as const` to the body when you need the literal:\n *   `(id) => ['users', id] as const` -> `readonly ['users', string]`.\n *\n * Empty arrays and non-key values are rejected at the type level.\n *\n * @example\n * ```ts\n * const userKeys = defineKeys({\n *   all: ['users'],                          // readonly ['users']\n *   active: ['users', 'active'],             // readonly ['users', 'active']\n *   detail: (id: string) => ['users', id],   // [string, string] (tuple shape kept)\n *   page: (n: number) => ['users', n] as const, // readonly ['users', number]\n * });\n * ```\n */\nexport function defineKeys<\n\tconst TKeys extends Record<\n\t\tstring,\n\t\t| readonly [unknown, ...unknown[]]\n\t\t| ((...args: never[]) => readonly [unknown, ...unknown[]])\n\t>,\n>(keys: TKeys): TKeys {\n\treturn keys;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFA,SAAgB,aAOfA,OAC2E;AAC3E,QAAO;EACN,GAAG;EACH,SAAS,OAAO,YAAY,QAAQ,MAAM,MAAM,QAAQ,QAAQ,CAAC;CACjE;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;AA0BD,SAAgB,gBAOfC,OAOuD;AACvD,QAAO;EACN,GAAG;EACH,YAAY,OAAOC,cAClB,QAAQ,MAAM,MAAM,WAAW,UAAU,CAAC;CAC3C;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmFD,SAAgB,qBAAqBC,aAA0B;CAC9D,MAAM,cAAc,CAOnBC,UAO2E;EAC3E,MAAM,UAAU,aAAa,MAAM;EAEnC,eAAe,QAA6C;AAC3D,OAAI;AACH,WAAO,GACN,MAAM,YAAY,WAKhB;KACD,UAAU,QAAQ;KAClB,SAAS,QAAQ;IACjB,EAAC,CACF;GACD,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;EAED,eAAe,SAA8C;AAC5D,OAAI;AACH,WAAO,GACN,MAAM,YAAY,gBAKhB;KACD,UAAU,QAAQ;KAClB,SAAS,QAAQ;IACjB,EAAC,CACF;GACD,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;AAED,SAAO,OAAO,OAAO,QAAQ;GAC5B;GACA;GACA;EACA,EAAC;CACF;CAED,MAAM,iBAAiB,CAOtBC,UAO+D;EAC/D,MAAM,UAAU,gBAAgB,MAAM;EAEtC,eAAe,QAAQH,WAAuB;AAC7C,OAAI;AACH,WAAO,GAAG,MAAM,YAAY,aAAa,SAAS,UAAU,CAAC;GAC7D,SAAQ,OAAO;AACf,WAAO,IAAI,MAAgB;GAC3B;EACD;AAED,SAAO,OAAO,OAAO,SAAS;GAC7B;GACA;EACA,EAAC;CACF;AAED,QAAO;EACN;EACA;CACA;AACD;;;;;;;;AASD,SAAS,YACRC,aACAG,SACAJ,WACC;CACD,MAAM,WAAW,YAAY,kBAAkB,CAAC,MAAM,aAAa,QAAQ;AAC3E,QAAO,SAAS,QAAQ,UAAU;AAClC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BD,SAAgB,WAMdK,MAAoB;AACrB,QAAO;AACP"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wellcrafted",
-	"version": "0.39.0",
+	"version": "0.41.0",
 	"description": "Delightful TypeScript patterns for elegant, type-safe applications",
 	"type": "module",
 	"files": [