wellcrafted 0.17.0 → 0.19.0

package/dist/error/index.d.ts

@@ -1,4 +1,7 @@
+import { Err } from "../result-t0dngyiE.js";
+
 //#region src/error/types.d.ts
+
 /**
  * Base error structure for all errors in the Result system.
  *
@@ -110,7 +113,72 @@ type TaggedError<T extends string> = BaseError & {
  * ```
  */
 declare function extractErrorMessage(error: unknown): string;
-//# sourceMappingURL=utils.d.ts.map
+/**
+ * Input type for creating a tagged error (everything except the name)
+ */
+type TaggedErrorWithoutName<T extends string> = Omit<TaggedError<T>, "name">;
+/**
+ * Replaces the "Error" suffix with "Err" suffix in error type names.
+ *
+ * This utility type is used to create companion function names for error constructors
+ * that return Err-wrapped results, maintaining consistent naming conventions.
+ *
+ * @template T - An error type name that must end with "Error"
+ * @returns The type name with "Error" replaced by "Err"
+ *
+ * @example
+ * ```ts
+ * type NetworkErr = ReplaceErrorWithErr<"NetworkError">; // "NetworkErr"
+ * type ValidationErr = ReplaceErrorWithErr<"ValidationError">; // "ValidationErr"
+ * type AuthErr = ReplaceErrorWithErr<"AuthError">; // "AuthErr"
+ * ```
+ */
+type ReplaceErrorWithErr<T extends `${string}Error`> = T extends `${infer TBase}Error` ? `${TBase}Err` : never;
+/**
+ * Return type for createTaggedError - contains both factory functions.
+ *
+ * Provides two factory functions:
+ * - One that creates plain TaggedError objects (named with "Error" suffix)
+ * - One that creates Err-wrapped TaggedError objects (named with "Err" suffix)
+ */
+type TaggedErrorFactories<TErrorName extends `${string}Error`> = { [K in TErrorName]: (input: TaggedErrorWithoutName<K>) => TaggedError<K> } & { [K in ReplaceErrorWithErr<TErrorName>]: (input: TaggedErrorWithoutName<TErrorName>) => Err<TaggedError<TErrorName>> };
+/**
+ * Returns two different factory functions for tagged errors.
+ *
+ * Given an error name like "NetworkError", this returns:
+ * - `NetworkError`: Creates a plain TaggedError object
+ * - `NetworkErr`: Creates a TaggedError object wrapped in an Err result
+ *
+ * The naming pattern automatically replaces the "Error" suffix with "Err" suffix
+ * for the Result-wrapped version.
+ *
+ * @param name - The name of the error type (must end with "Error")
+ * @returns An object with two factory functions:
+ *   - [name]: Function that creates plain TaggedError objects
+ *   - [name with "Error" replaced by "Err"]: Function that creates Err-wrapped TaggedError objects
+ *
+ * @example
+ * ```ts
+ * const { NetworkError, NetworkErr } = createTaggedError('NetworkError');
+ *
+ * // NetworkError: Creates just the error object
+ * const error = NetworkError({
+ *   message: 'Connection failed',
+ *   context: { url: 'https://api.example.com' },
+ *   cause: undefined
+ * });
+ * // Returns: { name: 'NetworkError', message: 'Connection failed', ... }
+ *
+ * // NetworkErr: Creates error and wraps in Err result
+ * return NetworkErr({
+ *   message: 'Connection failed',
+ *   context: { url: 'https://api.example.com' },
+ *   cause: undefined
+ * });
+ * // Returns: Err({ name: 'NetworkError', message: 'Connection failed', ... })
+ * ```
+ */
+declare function createTaggedError<TErrorName extends `${string}Error`>(name: TErrorName): TaggedErrorFactories<TErrorName>;
 //#endregion
-export { BaseError, TaggedError, extractErrorMessage };
+export { BaseError, TaggedError, createTaggedError, extractErrorMessage };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/error/types.ts","../../src/error/utils.ts"],"sourcesContent":[],"mappings":";;AAgBA;;;;AAAgC;AAsDhC;;;;AACiB;;;;ACpCjB;;KDnBY,SAAA,GAAY;;;YAGb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmDC,gCAAgC;iBAC5B;;;;;;AAvDhB;;;;AAAgC;AAsDhC;;;;AACiB;;;;ACpCjB;;;;;;;;;;;;;;;;;;;;;iBAAgB,mBAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/error/types.ts","../../src/error/utils.ts"],"sourcesContent":[],"mappings":";;;;;;;AAgBA;;;;AAAgC;AAsDhC;;;;AACiB;;;;ACjCD,KDtBJ,SAAA,GAAY,QCsBW,CAAA;EAoC9B,IAAA,EAAA,MAAA;EAAsB,OAAA,EAAA,MAAA;EAAA,OAAsC,CAAA,EDvDtD,MCuDsD,CAAA,MAAA,EAAA,OAAA,CAAA;EAAC,KAAb,EAAA,OAAA;CAAW,CAAA;AAAZ;AAAA;;;;AAmBT;AAAA;;;;;;;;;;;;;;AAclC;AAuCT;;;;;AAEuB;;;;;;;;;;;;;;;;;;;;;KD9EX,gCAAgC;iBAC5B;;;;;;AAvDhB;;;;AAAgC;AAsDhC;;;;AACiB;;;;ACjCjB;AA+BC;;;;;AAKmD;AAAA;;;;AAmBT;AAAA;;;;;;;;;AAaX,iBApEhB,mBAAA,CAoEgB,KAAA,EAAA,OAAA,CAAA,EAAA,MAAA;;;;KAhC3B,sBAiCC,CAAA,UAAA,MAAA,CAAA,GAjC0C,IAiC1C,CAjC+C,WAiC/C,CAjC2D,CAiC3D,CAAA,EAAA,MAAA,CAAA;AAAG;AAuCT;;;;;AAEuB;;;;;;;;;;KAxDlB,kDACJ,qCAAqC;;;;;;;;KASjC,oEACE,qBAAqB,uBAAuB,OAAO,YAAY,eAE/D,oBAAoB,sBAClB,uBAAuB,gBAC1B,IAAI,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuCN,6DACT,aACJ,qBAAqB"}

package/dist/error/index.js

@@ -1,3 +1,5 @@
+import { Err } from "../result-DxmXBFi5.js";
+
 //#region src/error/utils.ts
 /**
 * Extracts a readable error message from an unknown error value
@@ -50,7 +52,55 @@ function extractErrorMessage(error) {
 	}
 	return String(error);
 }
+/**
+* Returns two different factory functions for tagged errors.
+*
+* Given an error name like "NetworkError", this returns:
+* - `NetworkError`: Creates a plain TaggedError object
+* - `NetworkErr`: Creates a TaggedError object wrapped in an Err result
+*
+* The naming pattern automatically replaces the "Error" suffix with "Err" suffix
+* for the Result-wrapped version.
+*
+* @param name - The name of the error type (must end with "Error")
+* @returns An object with two factory functions:
+*   - [name]: Function that creates plain TaggedError objects
+*   - [name with "Error" replaced by "Err"]: Function that creates Err-wrapped TaggedError objects
+*
+* @example
+* ```ts
+* const { NetworkError, NetworkErr } = createTaggedError('NetworkError');
+*
+* // NetworkError: Creates just the error object
+* const error = NetworkError({
+*   message: 'Connection failed',
+*   context: { url: 'https://api.example.com' },
+*   cause: undefined
+* });
+* // Returns: { name: 'NetworkError', message: 'Connection failed', ... }
+*
+* // NetworkErr: Creates error and wraps in Err result
+* return NetworkErr({
+*   message: 'Connection failed',
+*   context: { url: 'https://api.example.com' },
+*   cause: undefined
+* });
+* // Returns: Err({ name: 'NetworkError', message: 'Connection failed', ... })
+* ```
+*/
+function createTaggedError(name) {
+	const errorConstructor = (error) => ({
+		...error,
+		name
+	});
+	const errName = name.replace(/Error$/, "Err");
+	const errConstructor = (error) => Err(errorConstructor(error));
+	return {
+		[name]: errorConstructor,
+		[errName]: errConstructor
+	};
+}
 
 //#endregion
-export { extractErrorMessage };
+export { createTaggedError, extractErrorMessage };
 //# sourceMappingURL=index.js.map

package/dist/error/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["error: unknown"],"sources":["../../src/error/utils.ts"],"sourcesContent":["/**\n * Extracts a readable error message from an unknown error value\n *\n * This utility is commonly used in mapError functions when converting\n * unknown errors to typed error objects in the Result system.\n *\n * @param error - The unknown error to extract a message from\n * @returns A string representation of the error\n *\n * @example\n * ```ts\n * // With native Error\n * const error = new Error(\"Something went wrong\");\n * const message = extractErrorMessage(error); // \"Something went wrong\"\n *\n * // With string error\n * const stringError = \"String error\";\n * const message2 = extractErrorMessage(stringError); // \"String error\"\n *\n * // With object error\n * const unknownError = { code: 500, details: \"Server error\" };\n * const message3 = extractErrorMessage(unknownError); // '{\"code\":500,\"details\":\"Server error\"}'\n *\n * // Used in mapError function\n * const result = await tryAsync({\n *   try: () => riskyOperation(),\n *   mapError: (error): NetworkError => ({\n *     name: \"NetworkError\",\n *     message: extractErrorMessage(error),\n *     context: { operation: \"riskyOperation\" },\n *     cause: error,\n *   }),\n * });\n * ```\n */\nexport function extractErrorMessage(error: unknown): string {\n\tif (error instanceof Error) {\n\t\treturn error.message;\n\t}\n\n\tif (typeof error === \"string\") {\n\t\treturn error;\n\t}\n\n\tif (typeof error === \"object\" && error !== null) {\n\t\t// Check for common error properties\n\t\tconst errorObj = error as Record<string, unknown>;\n\t\tif (typeof errorObj.message === \"string\") {\n\t\t\treturn errorObj.message;\n\t\t}\n\t\tif (typeof errorObj.error === \"string\") {\n\t\t\treturn errorObj.error;\n\t\t}\n\t\tif (typeof errorObj.description === \"string\") {\n\t\t\treturn errorObj.description;\n\t\t}\n\n\t\t// Fallback to JSON stringification\n\t\ttry {\n\t\t\treturn JSON.stringify(error);\n\t\t} catch {\n\t\t\treturn String(error);\n\t\t}\n\t}\n\n\treturn String(error);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,oBAAoBA,OAAwB;AAC3D,KAAI,iBAAiB,MACpB,QAAO,MAAM;AAGd,YAAW,UAAU,SACpB,QAAO;AAGR,YAAW,UAAU,YAAY,UAAU,MAAM;EAEhD,MAAM,WAAW;AACjB,aAAW,SAAS,YAAY,SAC/B,QAAO,SAAS;AAEjB,aAAW,SAAS,UAAU,SAC7B,QAAO,SAAS;AAEjB,aAAW,SAAS,gBAAgB,SACnC,QAAO,SAAS;AAIjB,MAAI;AACH,UAAO,KAAK,UAAU,MAAM;EAC5B,QAAO;AACP,UAAO,OAAO,MAAM;EACpB;CACD;AAED,QAAO,OAAO,MAAM;AACpB"}
+{"version":3,"file":"index.js","names":["error: unknown","name: TErrorName","error: TaggedErrorWithoutName<TErrorName>"],"sources":["../../src/error/utils.ts"],"sourcesContent":["import type { TaggedError } from \"./types.js\";\nimport { Err } from \"../result/result.js\";\n\n/**\n * Extracts a readable error message from an unknown error value\n *\n * This utility is commonly used in mapError functions when converting\n * unknown errors to typed error objects in the Result system.\n *\n * @param error - The unknown error to extract a message from\n * @returns A string representation of the error\n *\n * @example\n * ```ts\n * // With native Error\n * const error = new Error(\"Something went wrong\");\n * const message = extractErrorMessage(error); // \"Something went wrong\"\n *\n * // With string error\n * const stringError = \"String error\";\n * const message2 = extractErrorMessage(stringError); // \"String error\"\n *\n * // With object error\n * const unknownError = { code: 500, details: \"Server error\" };\n * const message3 = extractErrorMessage(unknownError); // '{\"code\":500,\"details\":\"Server error\"}'\n *\n * // Used in mapError function\n * const result = await tryAsync({\n *   try: () => riskyOperation(),\n *   mapError: (error): NetworkError => ({\n *     name: \"NetworkError\",\n *     message: extractErrorMessage(error),\n *     context: { operation: \"riskyOperation\" },\n *     cause: error,\n *   }),\n * });\n * ```\n */\nexport function extractErrorMessage(error: unknown): string {\n\tif (error instanceof Error) {\n\t\treturn error.message;\n\t}\n\n\tif (typeof error === \"string\") {\n\t\treturn error;\n\t}\n\n\tif (typeof error === \"object\" && error !== null) {\n\t\t// Check for common error properties\n\t\tconst errorObj = error as Record<string, unknown>;\n\t\tif (typeof errorObj.message === \"string\") {\n\t\t\treturn errorObj.message;\n\t\t}\n\t\tif (typeof errorObj.error === \"string\") {\n\t\t\treturn errorObj.error;\n\t\t}\n\t\tif (typeof errorObj.description === \"string\") {\n\t\t\treturn errorObj.description;\n\t\t}\n\n\t\t// Fallback to JSON stringification\n\t\ttry {\n\t\t\treturn JSON.stringify(error);\n\t\t} catch {\n\t\t\treturn String(error);\n\t\t}\n\t}\n\n\treturn String(error);\n}\n\n/**\n * Input type for creating a tagged error (everything except the name)\n */\ntype TaggedErrorWithoutName<T extends string> = Omit<TaggedError<T>, \"name\">;\n\n/**\n * Replaces the \"Error\" suffix with \"Err\" suffix in error type names.\n *\n * This utility type is used to create companion function names for error constructors\n * that return Err-wrapped results, maintaining consistent naming conventions.\n *\n * @template T - An error type name that must end with \"Error\"\n * @returns The type name with \"Error\" replaced by \"Err\"\n *\n * @example\n * ```ts\n * type NetworkErr = ReplaceErrorWithErr<\"NetworkError\">; // \"NetworkErr\"\n * type ValidationErr = ReplaceErrorWithErr<\"ValidationError\">; // \"ValidationErr\"\n * type AuthErr = ReplaceErrorWithErr<\"AuthError\">; // \"AuthErr\"\n * ```\n */\ntype ReplaceErrorWithErr<T extends `${string}Error`> =\n\tT extends `${infer TBase}Error` ? `${TBase}Err` : never;\n\n/**\n * Return type for createTaggedError - contains both factory functions.\n *\n * Provides two factory functions:\n * - One that creates plain TaggedError objects (named with \"Error\" suffix)\n * - One that creates Err-wrapped TaggedError objects (named with \"Err\" suffix)\n */\ntype TaggedErrorFactories<TErrorName extends `${string}Error`> = {\n\t[K in TErrorName]: (input: TaggedErrorWithoutName<K>) => TaggedError<K>;\n} & {\n\t[K in ReplaceErrorWithErr<TErrorName>]: (\n\t\tinput: TaggedErrorWithoutName<TErrorName>,\n\t) => Err<TaggedError<TErrorName>>;\n};\n\n/**\n * Returns two different factory functions for tagged errors.\n *\n * Given an error name like \"NetworkError\", this returns:\n * - `NetworkError`: Creates a plain TaggedError object\n * - `NetworkErr`: Creates a TaggedError object wrapped in an Err result\n *\n * The naming pattern automatically replaces the \"Error\" suffix with \"Err\" suffix\n * for the Result-wrapped version.\n *\n * @param name - The name of the error type (must end with \"Error\")\n * @returns An object with two factory functions:\n *   - [name]: Function that creates plain TaggedError objects\n *   - [name with \"Error\" replaced by \"Err\"]: Function that creates Err-wrapped TaggedError objects\n *\n * @example\n * ```ts\n * const { NetworkError, NetworkErr } = createTaggedError('NetworkError');\n *\n * // NetworkError: Creates just the error object\n * const error = NetworkError({\n *   message: 'Connection failed',\n *   context: { url: 'https://api.example.com' },\n *   cause: undefined\n * });\n * // Returns: { name: 'NetworkError', message: 'Connection failed', ... }\n *\n * // NetworkErr: Creates error and wraps in Err result\n * return NetworkErr({\n *   message: 'Connection failed',\n *   context: { url: 'https://api.example.com' },\n *   cause: undefined\n * });\n * // Returns: Err({ name: 'NetworkError', message: 'Connection failed', ... })\n * ```\n */\nexport function createTaggedError<TErrorName extends `${string}Error`>(\n\tname: TErrorName,\n): TaggedErrorFactories<TErrorName> {\n\tconst errorConstructor = (\n\t\terror: TaggedErrorWithoutName<TErrorName>,\n\t): TaggedError<TErrorName> => ({ ...error, name }) as TaggedError<TErrorName>;\n\n\tconst errName = name.replace(\n\t\t/Error$/,\n\t\t\"Err\",\n\t) as ReplaceErrorWithErr<TErrorName>;\n\tconst errConstructor = (error: TaggedErrorWithoutName<TErrorName>) =>\n\t\tErr(errorConstructor(error));\n\n\treturn {\n\t\t[name]: errorConstructor,\n\t\t[errName]: errConstructor,\n\t} as TaggedErrorFactories<TErrorName>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,oBAAoBA,OAAwB;AAC3D,KAAI,iBAAiB,MACpB,QAAO,MAAM;AAGd,YAAW,UAAU,SACpB,QAAO;AAGR,YAAW,UAAU,YAAY,UAAU,MAAM;EAEhD,MAAM,WAAW;AACjB,aAAW,SAAS,YAAY,SAC/B,QAAO,SAAS;AAEjB,aAAW,SAAS,UAAU,SAC7B,QAAO,SAAS;AAEjB,aAAW,SAAS,gBAAgB,SACnC,QAAO,SAAS;AAIjB,MAAI;AACH,UAAO,KAAK,UAAU,MAAM;EAC5B,QAAO;AACP,UAAO,OAAO,MAAM;EACpB;CACD;AAED,QAAO,OAAO,MAAM;AACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6ED,SAAgB,kBACfC,MACmC;CACnC,MAAM,mBAAmB,CACxBC,WAC8B;EAAE,GAAG;EAAO;CAAM;CAEjD,MAAM,UAAU,KAAK,QACpB,UACA,MACA;CACD,MAAM,iBAAiB,CAACA,UACvB,IAAI,iBAAiB,MAAM,CAAC;AAE7B,QAAO;GACL,OAAO;GACP,UAAU;CACX;AACD"}

package/dist/index-DRbikk8-.d.ts

@@ -0,0 +1,28 @@
+import { Err, Ok, Result } from "./result-t0dngyiE.js";
+
+//#region src/result/utils.d.ts
+
+/**
+ * Partitions an array of Result objects into two separate arrays based on their status.
+ *
+ * @template T - The success type
+ * @template E - The error type
+ * @param results - An array of Result objects to partition
+ * @returns An object containing two arrays:
+ *   - `oks`: Array of successful Result objects (Ok<T>[])
+ *   - `errs`: Array of error Result objects (Err<E>[])
+ *
+ * @example
+ * const results = [Ok(1), Err("error"), Ok(2)];
+ * const { oks, errs } = partitionResults(results);
+ * // oks = [Ok(1), Ok(2)]
+ * // errs = [Err("error")]
+ */
+declare function partitionResults<T, E>(results: Result<T, E>[]): {
+  oks: Ok<T>[];
+  errs: Err<E>[];
+};
+//# sourceMappingURL=utils.d.ts.map
+//#endregion
+export { partitionResults };
+//# sourceMappingURL=index-DRbikk8-.d.ts.map

package/dist/index-DRbikk8-.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-DRbikk8-.d.ts","names":[],"sources":["../src/result/utils.ts"],"sourcesContent":[],"mappings":";;;;;;AAmBA;;;;;;;;;AAK+B;;;;;iBALf,gCAAgC,OAAO,GAAG;OAK7C,GAAG;QAAY,IAAI"}

package/dist/query/index.d.ts

@@ -0,0 +1,119 @@
+import { Result } from "../result-t0dngyiE.js";
+import "../index-DRbikk8-.js";
+import { MutationFunction, MutationKey, MutationOptions, QueryClient, QueryFunction, QueryKey, QueryOptions } from "@tanstack/query-core";
+
+//#region src/query/utils.d.ts
+
+/**
+ * Input options for defining a query.
+ *
+ * Extends TanStack Query's QueryOptions 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, TError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Omit<QueryOptions<TQueryFnData, TError, TData, 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 Svelte components
+ * - `fetchCached()`: Imperatively fetches data (useful for actions/event handlers)
+ *
+ * @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, TError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = {
+  options: () => QueryOptions<TQueryFnData, TError, TData, TQueryKey>;
+  fetchCached: () => 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, 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, 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.fetchCached();
+ * ```
+ */
+declare function createQueryFactories(queryClient: QueryClient): {
+  defineQuery: <TQueryFnData, TError, TData = TQueryFnData, TQueryKey extends QueryKey = readonly unknown[]>(options: DefineQueryInput<TQueryFnData, TError, TData, TQueryKey>) => DefineQueryOutput<TQueryFnData, TError, TData, TQueryKey>;
+  defineMutation: <TData, TError, TVariables, 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/query/utils.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAwBA;;;;;;;;;;AAKI,KALQ,gBAKR,CAAA,YAAA,EAAA,MAAA,EAAA,QAFK,YAEL,EAAA,kBADe,QACf,GAD0B,QAC1B,CAAA,GAAA,IAAA,CAAK,YAAL,CAAkB,YAAlB,EAAgC,MAAhC,EAAwC,KAAxC,EAA+C,SAA/C,CAAA,EAAA,SAAA,CAAA,GAAA;EAAI,QACG,EAAA,SAAA;EAAS,aACiB,EAArB,aAAqB,CAAP,MAAO,CAAA,YAAA,EAAc,MAAd,CAAA,EAAuB,SAAvB,CAAA;CAAY;;;;AAApB;AAe7B;;;;;;;;AAM0D,KAN9C,iBAM8C,CAAA,YAAA,EAAA,MAAA,EAAA,QAHjD,YAGiD,EAAA,kBAFvC,QAEuC,GAF5B,QAE4B,CAAA,GAAA;EAAS,OAAnD,EAAA,GAAA,GAAA,YAAA,CAAa,YAAb,EAA2B,MAA3B,EAAmC,KAAnC,EAA0C,SAA1C,CAAA;EAAY,WACO,EAAA,GAAA,GAAf,OAAe,CAAP,MAAO,CAAA,KAAA,EAAO,MAAP,CAAA,CAAA;CAAK;;;AAAb;AAe3B;;;;;;;;;AAO2C,KAP/B,mBAO+B,CAAA,KAAA,EAAA,MAAA,EAAA,UAAA,EAAA,WAAA,OAAA,CAAA,GAFvC,IAEuC,CAFlC,eAEkC,CAFlB,KAEkB,EAFX,MAEW,EAFH,UAEG,EAFS,QAET,CAAA,EAAA,YAAA,CAAA,GAAA;EAAK,WAAE,EADpC,WACoC;EAAM,gBAApB,EAAjB,gBAAiB,CAAA,MAAA,CAAO,KAAP,EAAc,MAAd,CAAA,EAAuB,UAAvB,CAAA;CAAM;;AAAP;AAenC;;;;;;;;;;AAO6C,KAPjC,oBAOiC,CAAA,KAAA,EAAA,MAAA,EAAA,UAAA,EAAA,WAAA,OAAA,CAAA,GAAA;EAAM,OAAd,EAAA,GAAA,GADrB,eACqB,CADL,KACK,EADE,MACF,EADU,UACV,EADsB,QACtB,CAAA;EAAO,OAAA,EAAA,CAAA,SAAA,EAAtB,UAAsB,EAAA,GAAP,OAAO,CAAC,MAAD,CAAQ,KAAR,EAAe,MAAf,CAAA,CAAA;AA4C5C,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAqLwB;;;;;;;;;;;;;;;;;iBArLR,oBAAA,cAAkC;8CAuD3C,gCACa,wCAET,iBAAiB,cAAc,QAAQ,OAAO,eACrD,kBAAkB,cAAc,QAAQ,OAAO;2EAyHxC,oBAAoB,OAAO,QAAQ,YAAY,cACtD,qBAAqB,OAAO,QAAQ,YAAY"}

package/dist/query/index.js

@@ -0,0 +1,237 @@
+import { Err, Ok, resolve } from "../result-DxmXBFi5.js";
+import "../result-BCv06xhR.js";
+
+//#region src/query/utils.ts
+/**
+* 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.fetchCached();
+* ```
+*/
+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.
+	*
+	* ## Why use defineQuery?
+	*
+	* 1. **Dual Interface**: Provides both reactive (`.options()`) and imperative (`.fetchCached()`) APIs
+	* 2. **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
+	* 3. **Type Safety**: Full TypeScript support with proper inference for data and error types
+	* 4. **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.resultQueryFn - Function that fetches data and returns a Result type
+	* @param options.* - Any other TanStack Query options (staleTime, refetchInterval, etc.)
+	*
+	* @returns Query definition object with two methods:
+	*   - `options()`: Returns config for use with createQuery() in Svelte components
+	*   - `fetchCached()`: Imperatively fetches data (useful for actions/event handlers)
+	*
+	* @example
+	* ```typescript
+	* // Step 1: Define your query in the query layer
+	* const userQuery = defineQuery({
+	*   queryKey: ['users', userId],
+	*   resultQueryFn: () => services.getUser(userId), // Returns Result<User, ApiError>
+	*   staleTime: 5 * 60 * 1000, // Consider data fresh for 5 minutes
+	* });
+	*
+	* // Step 2a: Use reactively in a Svelte component
+	* const query = createQuery(userQuery.options());
+	* // $query.data is User | undefined
+	* // $query.error is ApiError | null
+	*
+	* // Step 2b: Use imperatively in an action
+	* async function prefetchUser() {
+	*   const { data, error } = await userQuery.fetchCached();
+	*   if (error) {
+	*     console.error('Failed to fetch user:', error);
+	*   }
+	* }
+	* ```
+	*/
+	const defineQuery = (options) => {
+		const newOptions = {
+			...options,
+			queryFn: async (context) => {
+				let result = options.resultQueryFn(context);
+				if (result instanceof Promise) result = await result;
+				return resolve(result);
+			}
+		};
+		return {
+			options: () => newOptions,
+			async fetchCached() {
+				try {
+					return Ok(await queryClient.fetchQuery({
+						queryKey: newOptions.queryKey,
+						queryFn: newOptions.queryFn
+					}));
+				} catch (error) {
+					return Err(error);
+				}
+			}
+		};
+	};
+	/**
+	* 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.
+	*
+	* ## Why use defineMutation?
+	*
+	* 1. **Dual Interface**: Just like queries, mutations can be used reactively or imperatively
+	* 2. **Direct Execution**: The `.execute()` method lets you run mutations without creating hooks,
+	*    perfect for event handlers and non-component code
+	* 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.resultMutationFn - Function that performs the mutation and returns a Result type
+	* @param options.* - Any other TanStack Mutation options (onSuccess, onError, etc.)
+	*
+	* @returns Mutation definition object with two methods:
+	*   - `options()`: Returns config for use with createMutation() in Svelte components
+	*   - `execute()`: Directly executes the mutation and returns a Result
+	*
+	* @example
+	* ```typescript
+	* // Step 1: Define your mutation with cache updates
+	* const createRecording = defineMutation({
+	*   mutationKey: ['recordings', 'create'],
+	*   resultMutationFn: 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 component
+	* const mutation = createMutation(createRecording.options());
+	* // Call with: $mutation.mutate(recordingData)
+	*
+	* // Step 2b: Use imperatively in an action
+	* async function saveRecording(data: Recording) {
+	*   const { error } = await createRecording.execute(data);
+	*   if (error) {
+	*     notify.error.execute({ title: 'Failed to save', description: error.message });
+	*   } else {
+	*     notify.success.execute({ title: 'Recording saved!' });
+	*   }
+	* }
+	* ```
+	*
+	* @tip The imperative `.execute()` method 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.resultMutationFn(variables));
+			}
+		};
+		return {
+			options: () => newOptions,
+			async execute(variables) {
+				try {
+					return Ok(await executeMutation(queryClient, newOptions, variables));
+				} catch (error) {
+					return Err(error);
+				}
+			}
+		};
+	};
+	return {
+		defineQuery,
+		defineMutation
+	};
+}
+/**
+* Internal helper that executes a mutation directly using the query client's mutation cache.
+*
+* This is what powers the `.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
+* @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 executeMutation(queryClient, options, variables) {
+	const mutation = queryClient.getMutationCache().build(queryClient, options);
+	return mutation.execute(variables);
+}
+
+//#endregion
+export { createQueryFactories };
+//# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["queryClient: QueryClient","options: DefineQueryInput<TQueryFnData, TError, TData, TQueryKey>","context: QueryFunctionContext<TQueryKey>","options: DefineMutationInput<TData, TError, TVariables, TContext>","variables: TVariables","options: MutationOptions<TData, TError, TVariables, TContext>"],"sources":["../../src/query/utils.ts"],"sourcesContent":["import type {\n\tMutationFunction,\n\tMutationKey,\n\tMutationOptions,\n\tQueryClient,\n\tQueryFunction,\n\tQueryFunctionContext,\n\tQueryKey,\n} from \"@tanstack/query-core\";\nimport { Err, Ok, type Result, resolve } from \"../result/index.js\";\nimport type { QueryOptions } from \"@tanstack/query-core\";\n\n/**\n * Input options for defining a query.\n *\n * Extends TanStack Query's QueryOptions but replaces queryFn with resultQueryFn.\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 */\nexport type DefineQueryInput<\n\tTQueryFnData,\n\tTError,\n\tTData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = Omit<QueryOptions<TQueryFnData, TError, TData, TQueryKey>, \"queryFn\"> & {\n\tqueryKey: TQueryKey;\n\tresultQueryFn: QueryFunction<Result<TQueryFnData, TError>, TQueryKey>;\n};\n\n/**\n * Output of defineQuery function.\n *\n * Provides both reactive and imperative interfaces for data fetching:\n * - `options()`: Returns config for use with createQuery() in Svelte components\n * - `fetchCached()`: Imperatively fetches data (useful for actions/event handlers)\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 */\nexport type DefineQueryOutput<\n\tTQueryFnData,\n\tTError,\n\tTData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = {\n\toptions: () => QueryOptions<TQueryFnData, TError, TData, TQueryKey>;\n\tfetchCached: () => Promise<Result<TData, TError>>;\n};\n\n/**\n * Input options for defining a mutation.\n *\n * Extends TanStack Query's MutationOptions but replaces mutationFn with resultMutationFn.\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 */\nexport type DefineMutationInput<\n\tTData,\n\tTError,\n\tTVariables,\n\tTContext = unknown,\n> = Omit<MutationOptions<TData, TError, TVariables, TContext>, \"mutationFn\"> & {\n\tmutationKey: MutationKey;\n\tresultMutationFn: MutationFunction<Result<TData, TError>, TVariables>;\n};\n\n/**\n * Output of defineMutation function.\n *\n * Provides both reactive and imperative interfaces for data mutations:\n * - `options()`: Returns config for use with createMutation() in Svelte components\n * - `execute()`: 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 */\nexport type DefineMutationOutput<\n\tTData,\n\tTError,\n\tTVariables,\n\tTContext = unknown,\n> = {\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 *   resultQueryFn: () => services.getUser(userId)\n * });\n *\n * // Use in components\n * const query = createQuery(userQuery.options());\n *\n * // Or imperatively\n * const { data, error } = await userQuery.fetchCached();\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 * ## Why use defineQuery?\n\t *\n\t * 1. **Dual Interface**: Provides both reactive (`.options()`) and imperative (`.fetchCached()`) APIs\n\t * 2. **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 * 3. **Type Safety**: Full TypeScript support with proper inference for data and error types\n\t * 4. **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.resultQueryFn - 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 Query definition object with two methods:\n\t *   - `options()`: Returns config for use with createQuery() in Svelte components\n\t *   - `fetchCached()`: Imperatively fetches data (useful for actions/event handlers)\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 *   resultQueryFn: () => 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 component\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: Use imperatively in an action\n\t * async function prefetchUser() {\n\t *   const { data, error } = await userQuery.fetchCached();\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,\n\t\tTError,\n\t\tTData = TQueryFnData,\n\t\tTQueryKey extends QueryKey = QueryKey,\n\t>(\n\t\toptions: DefineQueryInput<TQueryFnData, TError, TData, TQueryKey>,\n\t): DefineQueryOutput<TQueryFnData, TError, TData, TQueryKey> => {\n\t\tconst newOptions = {\n\t\t\t...options,\n\t\t\tqueryFn: async (context: QueryFunctionContext<TQueryKey>) => {\n\t\t\t\tlet result = options.resultQueryFn(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 QueryOptions<TQueryFnData, TError, TData, TQueryKey>;\n\n\t\treturn {\n\t\t\t/**\n\t\t\t * Returns the query options for reactive usage with TanStack Query hooks.\n\t\t\t * Use this with `createQuery()` in Svelte components for automatic subscriptions.\n\t\t\t * @returns The query options object configured for TanStack Query\n\t\t\t */\n\t\t\toptions: () => newOptions,\n\n\t\t\t/**\n\t\t\t * Fetches data for this query, returning cached data if fresh or refetching if stale/missing.\n\t\t\t *\n\t\t\t * This method is perfect for:\n\t\t\t * - Prefetching data before navigation\n\t\t\t * - Loading data in response to user actions\n\t\t\t * - Accessing query data outside of components\n\t\t\t *\n\t\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t\t *\n\t\t\t * @example\n\t\t\t * const { data, error } = await userQuery.fetchCached();\n\t\t\t * if (error) {\n\t\t\t *   console.error('Failed to load user:', error);\n\t\t\t * }\n\t\t\t */\n\t\t\tasync fetchCached(): Promise<Result<TData, TError>> {\n\t\t\t\ttry {\n\t\t\t\t\treturn Ok(\n\t\t\t\t\t\tawait queryClient.fetchQuery<TQueryFnData, Error, TData, TQueryKey>(\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\t\t\tqueryFn: newOptions.queryFn,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t} catch (error) {\n\t\t\t\t\treturn Err(error as TError);\n\t\t\t\t}\n\t\t\t},\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 * ## Why use defineMutation?\n\t *\n\t * 1. **Dual Interface**: Just like queries, mutations can be used reactively or imperatively\n\t * 2. **Direct Execution**: The `.execute()` method lets you run mutations without creating hooks,\n\t *    perfect for event handlers and non-component code\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.resultMutationFn - 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 Mutation definition object with two methods:\n\t *   - `options()`: Returns config for use with createMutation() in Svelte components\n\t *   - `execute()`: 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 *   resultMutationFn: 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 component\n\t * const mutation = createMutation(createRecording.options());\n\t * // Call with: $mutation.mutate(recordingData)\n\t *\n\t * // Step 2b: Use imperatively in an action\n\t * async function saveRecording(data: Recording) {\n\t *   const { error } = await createRecording.execute(data);\n\t *   if (error) {\n\t *     notify.error.execute({ title: 'Failed to save', description: error.message });\n\t *   } else {\n\t *     notify.success.execute({ title: 'Recording saved!' });\n\t *   }\n\t * }\n\t * ```\n\t *\n\t * @tip The imperative `.execute()` method 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, 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.resultMutationFn(variables));\n\t\t\t},\n\t\t} satisfies MutationOptions<TData, TError, TVariables, TContext>;\n\n\t\treturn {\n\t\t\t/**\n\t\t\t * Returns the mutation options for reactive usage with TanStack Query hooks.\n\t\t\t * Use this with `createMutation()` in Svelte components for reactive mutation state.\n\t\t\t * @returns The mutation options object configured for TanStack Query\n\t\t\t */\n\t\t\toptions: () => newOptions,\n\t\t\t/**\n\t\t\t * Bypasses the reactive mutation hooks and executes the mutation imperatively.\n\t\t\t *\n\t\t\t * This is the recommended way to trigger mutations from:\n\t\t\t * - Button click handlers\n\t\t\t * - Form submissions\n\t\t\t * - Keyboard shortcuts\n\t\t\t * - Any non-component code\n\t\t\t *\n\t\t\t * The method automatically wraps the result in a Result type, so you always\n\t\t\t * get back `{ data, error }` for consistent error handling.\n\t\t\t *\n\t\t\t * @param variables - The variables to pass to the mutation function\n\t\t\t * @returns Promise that resolves with a Result containing either the data or an error\n\t\t\t *\n\t\t\t * @example\n\t\t\t * // In an event handler\n\t\t\t * async function handleSubmit(formData: FormData) {\n\t\t\t *   const { data, error } = await createUser.execute(formData);\n\t\t\t *   if (error) {\n\t\t\t *     notify.error.execute({ title: 'Failed to create user', description: error.message });\n\t\t\t *     return;\n\t\t\t *   }\n\t\t\t *   goto(`/users/${data.id}`);\n\t\t\t * }\n\t\t\t */\n\t\t\tasync execute(variables: TVariables) {\n\t\t\t\ttry {\n\t\t\t\t\treturn Ok(await executeMutation(queryClient, newOptions, variables));\n\t\t\t\t} catch (error) {\n\t\t\t\t\treturn Err(error as TError);\n\t\t\t\t}\n\t\t\t},\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 `.execute()` method on mutations. It bypasses the reactive\n * mutation hooks and runs the mutation imperatively, which is perfect for event handlers\n * 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 executeMutation<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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6IA,SAAgB,qBAAqBA,aAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoD9D,MAAM,cAAc,CAMnBC,YAC+D;EAC/D,MAAM,aAAa;GAClB,GAAG;GACH,SAAS,OAAOC,YAA6C;IAC5D,IAAI,SAAS,QAAQ,cAAc,QAAQ;AAC3C,QAAI,kBAAkB,QAAS,UAAS,MAAM;AAC9C,WAAO,QAAQ,OAAO;GACtB;EACD;AAED,SAAO;GAMN,SAAS,MAAM;GAkBf,MAAM,cAA8C;AACnD,QAAI;AACH,YAAO,GACN,MAAM,YAAY,WACjB;MACC,UAAU,WAAW;MACrB,SAAS,WAAW;KACpB,EACD,CACD;IACD,SAAQ,OAAO;AACf,YAAO,IAAI,MAAgB;IAC3B;GACD;EACD;CACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuED,MAAM,iBAAiB,CACtBC,YAC+D;EAC/D,MAAM,aAAa;GAClB,GAAG;GACH,YAAY,OAAOC,cAA0B;AAC5C,WAAO,QAAQ,MAAM,QAAQ,iBAAiB,UAAU,CAAC;GACzD;EACD;AAED,SAAO;GAMN,SAAS,MAAM;GA2Bf,MAAM,QAAQA,WAAuB;AACpC,QAAI;AACH,YAAO,GAAG,MAAM,gBAAgB,aAAa,YAAY,UAAU,CAAC;IACpE,SAAQ,OAAO;AACf,YAAO,IAAI,MAAgB;IAC3B;GACD;EACD;CACD;AAED,QAAO;EACN;EACA;CACA;AACD;;;;;;;;;;;;;;;;;;AAmBD,SAAS,gBACRJ,aACAK,SACAD,WACC;CACD,MAAM,WAAW,YAAY,kBAAkB,CAAC,MAAM,aAAa,QAAQ;AAC3E,QAAO,SAAS,QAAQ,UAAU;AAClC"}