wellcrafted 0.22.0 → 0.24.0

package/README.md

@@ -62,6 +62,34 @@ const { ApiError, ApiErr } = createTaggedError("ApiError");
 // ApiError() creates error object, ApiErr() creates Err-wrapped error
 ```
 
+### 🔄 Query Integration
+Seamless TanStack Query integration with dual interfaces
+```typescript
+import { createQueryFactories } from "wellcrafted/query";
+import { QueryClient } from "@tanstack/query-core";
+
+const queryClient = new QueryClient();
+const { defineQuery, defineMutation } = createQueryFactories(queryClient);
+
+// Define operations that return Result types
+const userQuery = defineQuery({
+  queryKey: ['users', userId],
+  resultQueryFn: () => getUserFromAPI(userId) // Returns Result<User, ApiError>
+});
+
+// Use reactively in components with automatic state management
+const query = createQuery(userQuery.options());
+// query.data, query.error, query.isPending all managed automatically
+
+// Or use imperatively for direct execution (perfect for event handlers)
+const { data, error } = await userQuery.fetch();
+if (error) {
+  showErrorToast(error.message);
+  return;
+}
+// Use data...
+```
+
 ## Installation
 
 ```bash
@@ -81,7 +109,7 @@ type ApiError = ReturnType<typeof ApiError>;
 // Wrap any throwing operation
 const { data, error } = await tryAsync({
   try: () => fetch('/api/user').then(r => r.json()),
-  mapErr: (error) => ApiErr({
+  catch: (error) => ApiErr({
     message: "Failed to fetch user",
     context: { endpoint: '/api/user' },
     cause: error
@@ -145,13 +173,12 @@ Mix and match utilities
 The Result type makes error handling explicit and type-safe:
 
 ```typescript
-// The entire implementation
 type Ok<T> = { data: T; error: null };
 type Err<E> = { error: E; data: null };
 type Result<T, E> = Ok<T> | Err<E>;
 ```
 
-**The Magic**: This creates a discriminated union where TypeScript automatically narrows types:
+This creates a discriminated union where TypeScript automatically narrows types:
 
 ```typescript
 if (result.error) {
@@ -182,7 +209,7 @@ if (error) {
 // Synchronous
 const result = trySync({
   try: () => JSON.parse(jsonString),
-  mapErr: (error) => Err({
+  catch: (error) => Err({
     name: "ParseError",
     message: "Invalid JSON",
     context: { input: jsonString },
@@ -193,7 +220,7 @@ const result = trySync({
 // Asynchronous  
 const result = await tryAsync({
   try: () => fetch(url),
-  mapErr: (error) => Err({
+  catch: (error) => Err({
     name: "NetworkError",
     message: "Request failed",
     context: { url },
@@ -202,62 +229,173 @@ const result = await tryAsync({
 });
 ```
 
-### Service Layer Example
+### Real-World Service + Query Layer Example
 
 ```typescript
-import { Result, Ok, tryAsync } from "wellcrafted/result";
+// 1. Service Layer - Pure business logic
 import { createTaggedError } from "wellcrafted/error";
+import { tryAsync, Result } from "wellcrafted/result";
 
-// Define service-specific errors
-const { ValidationError, ValidationErr } = createTaggedError("ValidationError");
-const { DatabaseError, DatabaseErr } = createTaggedError("DatabaseError");
+const { RecorderServiceError, RecorderServiceErr } = createTaggedError("RecorderServiceError");
+type RecorderServiceError = ReturnType<typeof RecorderServiceError>;
 
-type ValidationError = ReturnType<typeof ValidationError>;
-type DatabaseError = ReturnType<typeof DatabaseError>;
+export function createRecorderService() {
+  let isRecording = false;
+  let currentBlob: Blob | null = null;
 
-// Factory function pattern - no classes!
-export function createUserService(db: Database) {
   return {
-    async createUser(input: CreateUserInput): Promise<Result<User, ValidationError | DatabaseError>> {
-      // Direct return with Err variant
-      if (!input.email.includes('@')) {
-        return ValidationErr({
-          message: "Invalid email format",
-          context: { field: 'email', value: input.email },
+    async startRecording(): Promise<Result<void, RecorderServiceError>> {
+      if (isRecording) {
+        return RecorderServiceErr({
+          message: "Already recording",
+          context: { currentState: 'recording' },
           cause: undefined
         });
       }
 
       return tryAsync({
-        try: () => db.save(input),
-        mapErr: (error) => DatabaseErr({
-          message: "Failed to save user",
-          context: { operation: 'createUser', input },
+        try: async () => {
+          const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+          const recorder = new MediaRecorder(stream);
+          // ... recording setup
+          isRecording = true;
+        },
+        catch: (error) => RecorderServiceErr({
+          message: "Failed to start recording",
+          context: { permissions: 'microphone' },
           cause: error
         })
       });
     },
 
-    async getUser(id: string): Promise<Result<User | null, DatabaseError>> {
-      return tryAsync({
-        try: () => db.findById(id),
-        mapErr: (error) => DatabaseErr({
-          message: "Failed to fetch user",
-          context: { userId: id },
-          cause: error
-        })
-      });
+    async stopRecording(): Promise<Result<Blob, RecorderServiceError>> {
+      if (!isRecording) {
+        return RecorderServiceErr({
+          message: "Not currently recording",
+          context: { currentState: 'idle' },
+          cause: undefined
+        });
+      }
+      
+      // Stop recording and return blob...
+      isRecording = false;
+      return Ok(currentBlob!);
     }
   };
 }
 
-// Export type for the service
-export type UserService = ReturnType<typeof createUserService>;
+// 2. Query Layer - Adds caching, reactivity, and UI error handling
+import { createQueryFactories } from "wellcrafted/query";
+
+const { defineQuery, defineMutation } = createQueryFactories(queryClient);
+
+export const recorder = {
+  getRecorderState: defineQuery({
+    queryKey: ['recorder', 'state'],
+    resultQueryFn: async () => {
+      const { data, error } = await services.recorder.getState();
+      if (error) {
+        // Transform service error to UI-friendly error
+        return Err({
+          title: "❌ Failed to get recorder state",
+          description: error.message,
+          action: { type: 'retry' }
+        });
+      }
+      return Ok(data);
+    },
+    refetchInterval: 1000, // Poll for state changes
+  }),
+
+  startRecording: defineMutation({
+    mutationKey: ['recorder', 'start'],
+    resultMutationFn: async () => {
+      const { error } = await services.recorder.startRecording();
+      if (error) {
+        return Err({
+          title: "❌ Failed to start recording",  
+          description: error.message,
+          action: { type: 'more-details', error }
+        });
+      }
 
-// Create a live instance (dependency injection at build time)
-export const UserServiceLive = createUserService(databaseInstance);
+      // Optimistically update cache
+      queryClient.setQueryData(['recorder', 'state'], 'recording');
+      return Ok(undefined);
+    }
+  })
+};
+
+// 3. Component Usage - Choose reactive or imperative based on needs
+// Reactive: Automatic state management
+const recorderState = createQuery(recorder.getRecorderState.options());
+
+// Imperative: Direct execution for event handlers
+async function handleStartRecording() {
+  const { error } = await recorder.startRecording.execute();
+  if (error) {
+    showToast(error.title, { description: error.description });
+  }
+}
+```
+
+## Smart Return Type Narrowing
+
+The `catch` parameter in `trySync` and `tryAsync` enables smart return type narrowing based on your error handling strategy:
+
+### Recovery Pattern (Always Succeeds)
+```typescript
+// ❌ Before: Mutable variable required
+let parsed: unknown;
+try {
+  parsed = JSON.parse(riskyJson);
+} catch {
+  parsed = [];
+}
+// Now use parsed...
+
+// ✅ After: Clean, immutable pattern
+const { data: parsed } = trySync({
+  try: () => JSON.parse(riskyJson),
+  catch: () => Ok([])
+});
+// parsed is always defined and type-safe!
+
+// When catch always returns Ok<T>, the function returns Ok<T>
+// This means no error checking needed - you can safely destructure and use data directly
 ```
 
+### Propagation Pattern (May Fail)
+```typescript
+// When catch can return Err<E>, function returns Result<T, E>  
+const mayFail = trySync({
+  try: () => JSON.parse(riskyJson),
+  catch: (error) => ParseErr({ message: "Invalid JSON", cause: error })
+});
+// mayFail: Result<object, ParseError> - Must check for errors
+if (isOk(mayFail)) {
+  console.log(mayFail.data); // Only safe after checking
+}
+```
+
+### Mixed Strategy (Conditional Recovery)
+```typescript
+const smartParse = trySync({
+  try: () => JSON.parse(input),
+  catch: (error) => {
+    // Recover from empty input
+    if (input.trim() === "") {
+      return Ok({}); // Return Ok<T> for fallback
+    }
+    // Propagate other errors  
+    return ParseErr({ message: "Parse failed", cause: error });
+  }
+});
+// smartParse: Result<object, ParseError> - Mixed handling = Result type
+```
+
+This eliminates unnecessary error checking when you always recover, while still requiring proper error handling when failures are possible.
+
 ## Why wellcrafted?
 
 JavaScript's `try-catch` has fundamental problems:
@@ -447,11 +585,16 @@ function useUser(id: number) {
 
 | | wellcrafted | fp-ts | Effect | neverthrow |
 |---|---|---|---|---|
+| **Bundle Size** | < 2KB | ~30KB | ~50KB | ~5KB |
 | **Learning Curve** | Minimal | Steep | Steep | Moderate |
 | **Syntax** | Native async/await | Pipe operators | Generators | Method chains |
-| **Bundle Size** | < 2KB | ~30KB | ~50KB | ~5KB |
 | **Type Safety** | ✅ Full | ✅ Full | ✅ Full | ✅ Full |
 | **Serializable Errors** | ✅ Built-in | ❌ Classes | ❌ Classes | ❌ Classes |
+| **Runtime Overhead** | Zero | Minimal | Moderate | Minimal |
+
+## Advanced Usage
+
+For comprehensive examples, service layer patterns, framework integrations, and migration guides, see the **[full documentation →](https://docs.wellcrafted.dev)**
 
 ## API Reference
 
@@ -462,18 +605,32 @@ function useUser(id: number) {
 - **`isErr(result)`** - Type guard for failure
 - **`trySync(options)`** - Wrap throwing function
 - **`tryAsync(options)`** - Wrap async function
+- **`unwrap(result)`** - Extract data or throw error
+- **`resolve(value)`** - Handle values that may or may not be Results
 - **`partitionResults(results)`** - Split array into oks/errs
 
+### Query Functions
+- **`createQueryFactories(client)`** - Create query/mutation factories for TanStack Query
+- **`defineQuery(options)`** - Define a query with dual interface (`.options()` + `.fetch()`)
+- **`defineMutation(options)`** - Define a mutation with dual interface (`.options()` + `.execute()`)
+
 ### Error Functions
 - **`createTaggedError(name)`** - Creates error factory functions
   - Returns two functions: `{ErrorName}` and `{ErrorName}Err`
   - The first creates plain error objects
   - The second creates Err-wrapped errors
+- **`extractErrorMessage(error)`** - Extract readable message from unknown error
 
 ### Types
 - **`Result<T, E>`** - Union of Ok<T> | Err<E>
+- **`Ok<T>`** - Success result type
+- **`Err<E>`** - Error result type
 - **`TaggedError<T>`** - Structured error type
 - **`Brand<T, B>`** - Branded type wrapper
+- **`ExtractOkFromResult<R>`** - Extract Ok variant from Result union
+- **`ExtractErrFromResult<R>`** - Extract Err variant from Result union
+- **`UnwrapOk<R>`** - Extract success value type from Result
+- **`UnwrapErr<R>`** - Extract error value type from Result
 
 ## License
 

package/dist/error/index.d.ts

@@ -3,39 +3,68 @@ import { Err } from "../result-DRq8PMRe.js";
 //#region src/error/types.d.ts
 
 /**
- * Base error structure for all errors in the Result system.
- *
- * Provides a consistent structure for error objects that are JSON-serializable
- * and contain comprehensive debugging information.
- *
- * @example
- * ```ts
- * const error: BaseError = {
- *   name: "DatabaseError",
- *   message: "Connection failed",
- *   context: { host: "localhost", port: 5432 },
- *   cause: originalError
- * };
- * ```
+ * Helper type that adds a context property only when TContext is not never.
+ * When TContext is never, returns an empty object (no context property).
+ * When TContext is a real type, returns { context: TContext } (required property).
  */
-type BaseError = Readonly<{
-  name: string;
-  message: string;
-  context?: Record<string, unknown>;
-  cause: unknown;
-}>;
+type WithContext<TContext> = [TContext] extends [never] ? {} : {
+  context: TContext;
+};
+/**
+ * Helper type that adds a cause property only when TCause is not never.
+ * When TCause is never, returns an empty object (no cause property).
+ * When TCause is a real type, returns { cause: TCause } (required property).
+ */
+type WithCause<TCause> = [TCause] extends [never] ? {} : {
+  cause: TCause;
+};
 /**
  * Creates a tagged error type for type-safe error handling.
  * Uses the `name` property as a discriminator for tagged unions.
  *
- * Error types should follow the convention of ending with "Error" suffix.
- * The Err data structure wraps these error types in the Result system.
+ * The `cause` property enables error chaining, creating a JSON-serializable
+ * call stack. Each error wraps its cause, building a complete trace of how
+ * an error propagated through your application layers.
+ *
+ * **Type Parameter Behavior:**
+ * - When `TContext` is `never` (default): No `context` property exists
+ * - When `TContext` is specified: `context` is a **required** property
+ * - When `TCause` is `never` (default): No `cause` property exists
+ * - When `TCause` is specified: `cause` is a **required** property
+ *
+ * @template TName - The error name (discriminator for tagged unions)
+ * @template TCause - The type of error that caused this error (default: never = no cause property)
+ * @template TContext - Additional context data for the error (default: never = no context property)
  *
  * @example
  * ```ts
- * type ValidationError = TaggedError<"ValidationError">
- * type NetworkError = TaggedError<"NetworkError">
+ * // Simple error without context or cause (properties don't exist)
+ * type ValidationError = TaggedError<"ValidationError">;
+ * const validationError: ValidationError = {
+ *   name: "ValidationError",
+ *   message: "Input is required"
+ * };
+ * // validationError.context // Property 'context' does not exist
+ *
+ * // Error with required context
+ * type NetworkError = TaggedError<"NetworkError", never, { host: string; port: number }>;
+ * const networkError: NetworkError = {
+ *   name: "NetworkError",
+ *   message: "Socket timeout",
+ *   context: { host: "db.example.com", port: 5432 } // Required!
+ * };
+ * const host = networkError.context.host; // No optional chaining needed
+ *
+ * // Type-safe error chaining with required cause
+ * type DatabaseError = TaggedError<"DatabaseError", NetworkError, { operation: string }>;
+ * const dbError: DatabaseError = {
+ *   name: "DatabaseError",
+ *   message: "Failed to connect to database",
+ *   context: { operation: "connect" }, // Required!
+ *   cause: networkError // Required!
+ * };
  *
+ * // Discriminated unions still work
  * function handleError(error: ValidationError | NetworkError) {
  *   switch (error.name) {
  *     case "ValidationError": // TypeScript knows this is ValidationError
@@ -44,37 +73,12 @@ type BaseError = Readonly<{
  *       break;
  *   }
  * }
- *
- * // Used in Result types:
- * function validate(input: string): Result<string, ValidationError> {
- *   if (!input) {
- *     return Err({
- *       name: "ValidationError",
- *       message: "Input is required",
- *       context: { input },
- *       cause: null,
- *     });
- *   }
- *   return Ok(input);
- * }
- *
- * // Context is optional - omit when not needed:
- * function checkAuth(): Result<User, AuthError> {
- *   if (!isAuthenticated) {
- *     return Err({
- *       name: "AuthError",
- *       message: "User not authenticated",
- *       cause: null,
- *     });
- *   }
- *   return Ok(currentUser);
- * }
  * ```
  */
-type TaggedError<T extends string> = BaseError & {
-  readonly name: T;
-};
-//# sourceMappingURL=types.d.ts.map
+type TaggedError<TName extends string = string, TCause = never, TContext = never> = Readonly<{
+  name: TName;
+  message: string;
+} & WithContext<TContext> & WithCause<TCause>>;
 //#endregion
 //#region src/error/utils.d.ts
 /**
@@ -114,15 +118,15 @@ type TaggedError<T extends string> = BaseError & {
  */
 declare function extractErrorMessage(error: unknown): string;
 /**
- * Input type for creating a tagged error (everything except the name)
+ * Base type for any tagged error, used as a constraint for cause parameters.
  */
-type TaggedErrorWithoutName<T extends string> = Omit<TaggedError<T>, "name">;
+type AnyTaggedError = {
+  name: string;
+  message: string;
+};
 /**
  * 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"
  *
@@ -130,55 +134,165 @@ type TaggedErrorWithoutName<T extends string> = Omit<TaggedError<T>, "name">;
  * ```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)
+ * Return type when neither context nor cause are constrained.
+ * Both factory functions accept any context and cause at call time.
+ */
+type FlexibleFactories<TName extends `${string}Error`> = { [K in TName]: FlexibleErrorConstructor<K> } & { [K in ReplaceErrorWithErr<TName>]: FlexibleErrConstructor<TName> };
+/**
+ * Return type when context is fixed but cause is flexible.
+ * Context shape is locked, but cause can be any TaggedError at call time.
+ */
+type ContextFixedFactories<TName extends `${string}Error`, TContext extends Record<string, unknown>> = { [K in TName]: ContextFixedErrorConstructor<K, TContext> } & { [K in ReplaceErrorWithErr<TName>]: ContextFixedErrConstructor<TName, TContext> };
+/**
+ * Return type when both context and cause are fixed.
+ * Both shapes are locked at factory creation time.
  */
-type TaggedErrorFactories<TErrorName extends `${string}Error`> = { [K in TErrorName]: (input: TaggedErrorWithoutName<K>) => TaggedError<K> } & { [K in ReplaceErrorWithErr<TErrorName>]: (input: TaggedErrorWithoutName<TErrorName>) => Err<TaggedError<TErrorName>> };
+type BothFixedFactories<TName extends `${string}Error`, TContext extends Record<string, unknown>, TCause extends AnyTaggedError> = { [K in TName]: BothFixedErrorConstructor<K, TContext, TCause> } & { [K in ReplaceErrorWithErr<TName>]: BothFixedErrConstructor<TName, TContext, TCause> };
 /**
- * Returns two different factory functions for tagged errors.
+ * Creates plain TaggedError objects with flexible context and cause.
+ * Uses function overloads to precisely match return types to inputs.
+ */
+type FlexibleErrorConstructor<TName extends string> = {
+  (input: {
+    message: string;
+  }): TaggedError<TName, never, never>;
+  <TContext extends Record<string, unknown>>(input: {
+    message: string;
+    context: TContext;
+  }): TaggedError<TName, never, TContext>;
+  <TCause extends AnyTaggedError>(input: {
+    message: string;
+    cause: TCause;
+  }): TaggedError<TName, TCause, never>;
+  <TContext extends Record<string, unknown>, TCause extends AnyTaggedError>(input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): TaggedError<TName, TCause, TContext>;
+};
+/**
+ * Creates Err-wrapped TaggedError objects with flexible context and cause.
+ */
+type FlexibleErrConstructor<TName extends string> = {
+  (input: {
+    message: string;
+  }): Err<TaggedError<TName, never, never>>;
+  <TContext extends Record<string, unknown>>(input: {
+    message: string;
+    context: TContext;
+  }): Err<TaggedError<TName, never, TContext>>;
+  <TCause extends AnyTaggedError>(input: {
+    message: string;
+    cause: TCause;
+  }): Err<TaggedError<TName, TCause, never>>;
+  <TContext extends Record<string, unknown>, TCause extends AnyTaggedError>(input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): Err<TaggedError<TName, TCause, TContext>>;
+};
+/**
+ * Creates plain TaggedError objects with fixed context but flexible cause.
+ * Context is always required. Cause is optional and inferred at call site.
+ */
+type ContextFixedErrorConstructor<TName extends string, TContext extends Record<string, unknown>> = {
+  (input: {
+    message: string;
+    context: TContext;
+  }): TaggedError<TName, never, TContext>;
+  <TCause extends AnyTaggedError>(input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): TaggedError<TName, TCause, TContext>;
+};
+/**
+ * Creates Err-wrapped TaggedError objects with fixed context but flexible cause.
+ */
+type ContextFixedErrConstructor<TName extends string, TContext extends Record<string, unknown>> = {
+  (input: {
+    message: string;
+    context: TContext;
+  }): Err<TaggedError<TName, never, TContext>>;
+  <TCause extends AnyTaggedError>(input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): Err<TaggedError<TName, TCause, TContext>>;
+};
+/**
+ * Creates plain TaggedError objects with both context and cause fixed.
+ * Context is required. Cause is optional but must match the specified type.
+ */
+type BothFixedErrorConstructor<TName extends string, TContext extends Record<string, unknown>, TCause extends AnyTaggedError> = {
+  (input: {
+    message: string;
+    context: TContext;
+  }): TaggedError<TName, never, TContext>;
+  (input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): TaggedError<TName, TCause, TContext>;
+};
+/**
+ * Creates Err-wrapped TaggedError objects with both context and cause fixed.
+ */
+type BothFixedErrConstructor<TName extends string, TContext extends Record<string, unknown>, TCause extends AnyTaggedError> = {
+  (input: {
+    message: string;
+    context: TContext;
+  }): Err<TaggedError<TName, never, TContext>>;
+  (input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): Err<TaggedError<TName, TCause, TContext>>;
+};
+/**
+ * Creates two factory functions for building tagged errors with type-safe error chaining.
  *
  * 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.
+ * **Three usage modes:**
  *
+ * 1. **Flexible mode** (no type params): Context and cause are optional, any shape accepted
+ * 2. **Fixed context mode** (TContext specified): Context is required with that exact shape
+ * 3. **Both fixed mode** (TContext + TCause): Context required, cause (if provided) must match
+ *
+ * @template TName - The name of the error type (must end with "Error")
+ * @template TContext - Optional fixed context shape (makes context required)
+ * @template TCause - Optional fixed cause type (constrains cause type if provided)
  * @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
+ * // Mode 1: Flexible - context optional, any shape
  * const { NetworkError, NetworkErr } = createTaggedError('NetworkError');
+ * NetworkError({ message: 'Connection failed' });
+ * NetworkError({ message: 'Timeout', context: { url: 'https://...' } });
  *
- * // 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', ... }
+ * // Mode 2: Fixed context - context REQUIRED with exact shape
+ * type BlobContext = { filename: string; code: 'INVALID' | 'TOO_LARGE' };
+ * const { BlobError, BlobErr } = createTaggedError<'BlobError', BlobContext>('BlobError');
+ * BlobError({ message: 'Invalid', context: { filename: 'x', code: 'INVALID' } });
+ * // BlobError({ message: 'Error' }); // Type error - context required
  *
- * // 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', ... })
+ * // Mode 3: Fixed context + cause - context required, cause constrained
+ * const { ApiError, ApiErr } = createTaggedError<'ApiError', { endpoint: string }, NetworkError>('ApiError');
+ * ApiError({ message: 'Failed', context: { endpoint: '/users' } });
+ * ApiError({ message: 'Failed', context: { endpoint: '/users' }, cause: networkError });
  * ```
  */
-declare function createTaggedError<TErrorName extends `${string}Error`>(name: TErrorName): TaggedErrorFactories<TErrorName>;
+declare function createTaggedError<TName extends `${string}Error`>(name: TName): FlexibleFactories<TName>;
+declare function createTaggedError<TName extends `${string}Error`, TContext extends Record<string, unknown>>(name: TName): ContextFixedFactories<TName, TContext>;
+declare function createTaggedError<TName extends `${string}Error`, TContext extends Record<string, unknown>, TCause extends AnyTaggedError>(name: TName): BothFixedFactories<TName, TContext, TCause>;
 //#endregion
-export { BaseError, TaggedError, createTaggedError, extractErrorMessage };
+export { 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;;;;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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/error/types.ts","../../src/error/utils.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/error/index.js

@@ -39,11 +39,22 @@ import { Err } from "../result-B1iWFqM9.js";
 function extractErrorMessage(error) {
 	if (error instanceof Error) return error.message;
 	if (typeof error === "string") return error;
-	if (typeof error === "object" && error !== null) {
+	if (typeof error === "number" || typeof error === "boolean" || typeof error === "bigint") return String(error);
+	if (typeof error === "symbol") return error.toString();
+	if (error === null) return "null";
+	if (error === void 0) return "undefined";
+	if (Array.isArray(error)) return JSON.stringify(error);
+	if (typeof error === "object") {
 		const errorObj = error;
-		if (typeof errorObj.message === "string") return errorObj.message;
-		if (typeof errorObj.error === "string") return errorObj.error;
-		if (typeof errorObj.description === "string") return errorObj.description;
+		const messageProps = [
+			"message",
+			"error",
+			"description",
+			"title",
+			"reason",
+			"details"
+		];
+		for (const prop of messageProps) if (prop in errorObj && typeof errorObj[prop] === "string") return errorObj[prop];
 		try {
 			return JSON.stringify(error);
 		} catch {
@@ -52,49 +63,13 @@ 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 errorConstructor = (input) => ({
+		name,
+		...input
 	});
 	const errName = name.replace(/Error$/, "Err");
-	const errConstructor = (error) => Err(errorConstructor(error));
+	const errConstructor = (input) => Err(errorConstructor(input));
 	return {
 		[name]: errorConstructor,
 		[errName]: errConstructor

package/dist/error/index.js.map

@@ -1 +1 @@
-{"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 mapErr 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 mapErr function\n * const result = await tryAsync({\n *   try: () => riskyOperation(),\n *   mapErr: (error) => Err({\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"}
+{"version":3,"file":"index.js","names":["error: unknown","name: TName","input: {\n\t\tmessage: string;\n\t\tcontext?: TContext;\n\t\tcause?: TCause;\n\t}"],"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 mapErr 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 mapErr function\n * const result = await tryAsync({\n *   try: () => riskyOperation(),\n *   mapErr: (error) => Err({\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\t// Handle Error instances\n\tif (error instanceof Error) {\n\t\treturn error.message;\n\t}\n\n\t// Handle primitives\n\tif (typeof error === \"string\") return error;\n\tif (\n\t\ttypeof error === \"number\" ||\n\t\ttypeof error === \"boolean\" ||\n\t\ttypeof error === \"bigint\"\n\t)\n\t\treturn String(error);\n\tif (typeof error === \"symbol\") return error.toString();\n\tif (error === null) return \"null\";\n\tif (error === undefined) return \"undefined\";\n\n\t// Handle arrays\n\tif (Array.isArray(error)) return JSON.stringify(error);\n\n\t// Handle plain objects\n\tif (typeof error === \"object\") {\n\t\tconst errorObj = error as Record<string, unknown>;\n\n\t\t// Check common error properties\n\t\tconst messageProps = [\n\t\t\t\"message\",\n\t\t\t\"error\",\n\t\t\t\"description\",\n\t\t\t\"title\",\n\t\t\t\"reason\",\n\t\t\t\"details\",\n\t\t] as const;\n\t\tfor (const prop of messageProps) {\n\t\t\tif (prop in errorObj && typeof errorObj[prop] === \"string\") {\n\t\t\t\treturn errorObj[prop];\n\t\t\t}\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\t// Final fallback\n\treturn String(error);\n}\n\n/**\n * Base type for any tagged error, used as a constraint for cause parameters.\n */\ntype AnyTaggedError = { name: string; message: string };\n\n/**\n * Replaces the \"Error\" suffix with \"Err\" suffix in error type names.\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 * ```\n */\ntype ReplaceErrorWithErr<T extends `${string}Error`> =\n\tT extends `${infer TBase}Error` ? `${TBase}Err` : never;\n\n// =============================================================================\n// Factory Return Types\n// =============================================================================\n\n/**\n * Return type when neither context nor cause are constrained.\n * Both factory functions accept any context and cause at call time.\n */\ntype FlexibleFactories<TName extends `${string}Error`> = {\n\t[K in TName]: FlexibleErrorConstructor<K>;\n} & {\n\t[K in ReplaceErrorWithErr<TName>]: FlexibleErrConstructor<TName>;\n};\n\n/**\n * Return type when context is fixed but cause is flexible.\n * Context shape is locked, but cause can be any TaggedError at call time.\n */\ntype ContextFixedFactories<\n\tTName extends `${string}Error`,\n\tTContext extends Record<string, unknown>,\n> = {\n\t[K in TName]: ContextFixedErrorConstructor<K, TContext>;\n} & {\n\t[K in ReplaceErrorWithErr<TName>]: ContextFixedErrConstructor<TName, TContext>;\n};\n\n/**\n * Return type when both context and cause are fixed.\n * Both shapes are locked at factory creation time.\n */\ntype BothFixedFactories<\n\tTName extends `${string}Error`,\n\tTContext extends Record<string, unknown>,\n\tTCause extends AnyTaggedError,\n> = {\n\t[K in TName]: BothFixedErrorConstructor<K, TContext, TCause>;\n} & {\n\t[K in ReplaceErrorWithErr<TName>]: BothFixedErrConstructor<\n\t\tTName,\n\t\tTContext,\n\t\tTCause\n\t>;\n};\n\n// =============================================================================\n// Flexible Mode Constructor Types (using function overloads)\n// =============================================================================\n\n/**\n * Creates plain TaggedError objects with flexible context and cause.\n * Uses function overloads to precisely match return types to inputs.\n */\ntype FlexibleErrorConstructor<TName extends string> = {\n\t// Just message - no context or cause\n\t(input: { message: string }): TaggedError<TName, never, never>;\n\t// With context only\n\t<TContext extends Record<string, unknown>>(input: {\n\t\tmessage: string;\n\t\tcontext: TContext;\n\t}): TaggedError<TName, never, TContext>;\n\t// With cause only\n\t<TCause extends AnyTaggedError>(input: {\n\t\tmessage: string;\n\t\tcause: TCause;\n\t}): TaggedError<TName, TCause, never>;\n\t// With both context and cause\n\t<TContext extends Record<string, unknown>, TCause extends AnyTaggedError>(input: {\n\t\tmessage: string;\n\t\tcontext: TContext;\n\t\tcause: TCause;\n\t}): TaggedError<TName, TCause, TContext>;\n};\n\n/**\n * Creates Err-wrapped TaggedError objects with flexible context and cause.\n */\ntype FlexibleErrConstructor<TName extends string> = {\n\t(input: { message: string }): Err<TaggedError<TName, never, never>>;\n\t<TContext extends Record<string, unknown>>(input: {\n\t\tmessage: string;\n\t\tcontext: TContext;\n\t}): Err<TaggedError<TName, never, TContext>>;\n\t<TCause extends AnyTaggedError>(input: {\n\t\tmessage: string;\n\t\tcause: TCause;\n\t}): Err<TaggedError<TName, TCause, never>>;\n\t<TContext extends Record<string, unknown>, TCause extends AnyTaggedError>(input: {\n\t\tmessage: string;\n\t\tcontext: TContext;\n\t\tcause: TCause;\n\t}): Err<TaggedError<TName, TCause, TContext>>;\n};\n\n// =============================================================================\n// Context-Fixed Mode Constructor Types\n// =============================================================================\n\n/**\n * Creates plain TaggedError objects with fixed context but flexible cause.\n * Context is always required. Cause is optional and inferred at call site.\n */\ntype ContextFixedErrorConstructor<\n\tTName extends string,\n\tTContext extends Record<string, unknown>,\n> = {\n\t// Without cause\n\t(input: { message: string; context: TContext }): TaggedError<\n\t\tTName,\n\t\tnever,\n\t\tTContext\n\t>;\n\t// With cause\n\t<TCause extends AnyTaggedError>(input: {\n\t\tmessage: string;\n\t\tcontext: TContext;\n\t\tcause: TCause;\n\t}): TaggedError<TName, TCause, TContext>;\n};\n\n/**\n * Creates Err-wrapped TaggedError objects with fixed context but flexible cause.\n */\ntype ContextFixedErrConstructor<\n\tTName extends string,\n\tTContext extends Record<string, unknown>,\n> = {\n\t(input: { message: string; context: TContext }): Err<\n\t\tTaggedError<TName, never, TContext>\n\t>;\n\t<TCause extends AnyTaggedError>(input: {\n\t\tmessage: string;\n\t\tcontext: TContext;\n\t\tcause: TCause;\n\t}): Err<TaggedError<TName, TCause, TContext>>;\n};\n\n// =============================================================================\n// Both-Fixed Mode Constructor Types\n// =============================================================================\n\n/**\n * Creates plain TaggedError objects with both context and cause fixed.\n * Context is required. Cause is optional but must match the specified type.\n */\ntype BothFixedErrorConstructor<\n\tTName extends string,\n\tTContext extends Record<string, unknown>,\n\tTCause extends AnyTaggedError,\n> = {\n\t// Without cause\n\t(input: { message: string; context: TContext }): TaggedError<\n\t\tTName,\n\t\tnever,\n\t\tTContext\n\t>;\n\t// With cause (must match TCause)\n\t(input: {\n\t\tmessage: string;\n\t\tcontext: TContext;\n\t\tcause: TCause;\n\t}): TaggedError<TName, TCause, TContext>;\n};\n\n/**\n * Creates Err-wrapped TaggedError objects with both context and cause fixed.\n */\ntype BothFixedErrConstructor<\n\tTName extends string,\n\tTContext extends Record<string, unknown>,\n\tTCause extends AnyTaggedError,\n> = {\n\t(input: { message: string; context: TContext }): Err<\n\t\tTaggedError<TName, never, TContext>\n\t>;\n\t(input: {\n\t\tmessage: string;\n\t\tcontext: TContext;\n\t\tcause: TCause;\n\t}): Err<TaggedError<TName, TCause, TContext>>;\n};\n\n// =============================================================================\n// Main Factory Function\n// =============================================================================\n\n/**\n * Creates two factory functions for building tagged errors with type-safe error chaining.\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 * **Three usage modes:**\n *\n * 1. **Flexible mode** (no type params): Context and cause are optional, any shape accepted\n * 2. **Fixed context mode** (TContext specified): Context is required with that exact shape\n * 3. **Both fixed mode** (TContext + TCause): Context required, cause (if provided) must match\n *\n * @template TName - The name of the error type (must end with \"Error\")\n * @template TContext - Optional fixed context shape (makes context required)\n * @template TCause - Optional fixed cause type (constrains cause type if provided)\n * @param name - The name of the error type (must end with \"Error\")\n *\n * @example\n * ```ts\n * // Mode 1: Flexible - context optional, any shape\n * const { NetworkError, NetworkErr } = createTaggedError('NetworkError');\n * NetworkError({ message: 'Connection failed' });\n * NetworkError({ message: 'Timeout', context: { url: 'https://...' } });\n *\n * // Mode 2: Fixed context - context REQUIRED with exact shape\n * type BlobContext = { filename: string; code: 'INVALID' | 'TOO_LARGE' };\n * const { BlobError, BlobErr } = createTaggedError<'BlobError', BlobContext>('BlobError');\n * BlobError({ message: 'Invalid', context: { filename: 'x', code: 'INVALID' } });\n * // BlobError({ message: 'Error' }); // Type error - context required\n *\n * // Mode 3: Fixed context + cause - context required, cause constrained\n * const { ApiError, ApiErr } = createTaggedError<'ApiError', { endpoint: string }, NetworkError>('ApiError');\n * ApiError({ message: 'Failed', context: { endpoint: '/users' } });\n * ApiError({ message: 'Failed', context: { endpoint: '/users' }, cause: networkError });\n * ```\n */\n// Overload 1: Flexible (no type constraints)\nexport function createTaggedError<TName extends `${string}Error`>(\n\tname: TName,\n): FlexibleFactories<TName>;\n\n// Overload 2: Context fixed, cause flexible\nexport function createTaggedError<\n\tTName extends `${string}Error`,\n\tTContext extends Record<string, unknown>,\n>(name: TName): ContextFixedFactories<TName, TContext>;\n\n// Overload 3: Both context and cause fixed\nexport function createTaggedError<\n\tTName extends `${string}Error`,\n\tTContext extends Record<string, unknown>,\n\tTCause extends AnyTaggedError,\n>(name: TName): BothFixedFactories<TName, TContext, TCause>;\n\n// Implementation\nexport function createTaggedError<\n\tTName extends `${string}Error`,\n\tTContext extends Record<string, unknown> = Record<string, unknown>,\n\tTCause extends AnyTaggedError = never,\n>(name: TName): unknown {\n\tconst errorConstructor = (input: {\n\t\tmessage: string;\n\t\tcontext?: TContext;\n\t\tcause?: TCause;\n\t}) => ({ name, ...input });\n\n\tconst errName = name.replace(/Error$/, \"Err\") as ReplaceErrorWithErr<TName>;\n\tconst errConstructor = (input: {\n\t\tmessage: string;\n\t\tcontext?: TContext;\n\t\tcause?: TCause;\n\t}) => Err(errorConstructor(input));\n\n\treturn {\n\t\t[name]: errorConstructor,\n\t\t[errName]: errConstructor,\n\t};\n}\n\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,oBAAoBA,OAAwB;AAE3D,KAAI,iBAAiB,MACpB,QAAO,MAAM;AAId,YAAW,UAAU,SAAU,QAAO;AACtC,YACQ,UAAU,mBACV,UAAU,oBACV,UAAU,SAEjB,QAAO,OAAO,MAAM;AACrB,YAAW,UAAU,SAAU,QAAO,MAAM,UAAU;AACtD,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,iBAAqB,QAAO;AAGhC,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,KAAK,UAAU,MAAM;AAGtD,YAAW,UAAU,UAAU;EAC9B,MAAM,WAAW;EAGjB,MAAM,eAAe;GACpB;GACA;GACA;GACA;GACA;GACA;EACA;AACD,OAAK,MAAM,QAAQ,aAClB,KAAI,QAAQ,mBAAmB,SAAS,UAAU,SACjD,QAAO,SAAS;AAKlB,MAAI;AACH,UAAO,KAAK,UAAU,MAAM;EAC5B,QAAO;AACP,UAAO,OAAO,MAAM;EACpB;CACD;AAGD,QAAO,OAAO,MAAM;AACpB;AAwQD,SAAgB,kBAIdC,MAAsB;CACvB,MAAM,mBAAmB,CAACC,WAInB;EAAE;EAAM,GAAG;CAAO;CAEzB,MAAM,UAAU,KAAK,QAAQ,UAAU,MAAM;CAC7C,MAAM,iBAAiB,CAACA,UAIlB,IAAI,iBAAiB,MAAM,CAAC;AAElC,QAAO;GACL,OAAO;GACP,UAAU;CACX;AACD"}

package/dist/query/index.d.ts

@@ -24,7 +24,7 @@ type DefineQueryInput<TQueryFnData = unknown, TError = DefaultError, TData = TQu
  * Output of defineQuery function.
  *
  * Provides both reactive and imperative interfaces for data fetching:
- * - `options()`: Returns config for use with createQuery() in components
+ * - `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)
  *
@@ -58,7 +58,7 @@ type DefineMutationInput<TData, TError, TVariables = void, TContext = unknown> =
  * Output of defineMutation function.
  *
  * Provides both reactive and imperative interfaces for data mutations:
- * - `options()`: Returns config for use with createMutation() in Svelte components
+ * - `options()`: Returns config for use with useMutation() or createMutation()
  * - `execute()`: Directly executes the mutation and returns a Result
  *
  * @template TData - The type of data returned by the mutation
@@ -105,7 +105,7 @@ type DefineMutationOutput<TData, TError, TVariables = void, TContext = unknown>
  * });
  *
  * // Use in components
- * const query = createQuery(userQuery.options());
+ * const query = createQuery(userQuery.options);
  *
  * // Or imperatively
  * const { data, error } = await userQuery.fetch();

package/dist/query/index.js

@@ -37,7 +37,7 @@ import "../result-DfuKgZo9.js";
 * });
 *
 * // Use in components
-* const query = createQuery(userQuery.options());
+* const query = createQuery(userQuery.options);
 *
 * // Or imperatively
 * const { data, error } = await userQuery.fetch();
@@ -52,7 +52,7 @@ function createQueryFactories(queryClient) {
 	*
 	* ## Why use defineQuery?
 	*
-	* 1. **Dual Interface**: Provides both reactive (`.options()`) and imperative (`.fetch()`) APIs
+	* 1. **Dual Interface**: Provides both reactive (`.options`) and imperative (`.fetch()`) 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
@@ -69,7 +69,7 @@ function createQueryFactories(queryClient) {
 	* @param options.* - Any other TanStack Query options (staleTime, refetchInterval, etc.)
 	*
 	* @returns Query definition object with three methods:
-	*   - `options()`: Returns config for use with createQuery() in Svelte components
+	*   - `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)
 	*
@@ -83,7 +83,7 @@ function createQueryFactories(queryClient) {
 	* });
 	*
 	* // Step 2a: Use reactively in a Svelte component
-	* const query = createQuery(userQuery.options());
+	* const query = createQuery(userQuery.options);
 	* // $query.data is User | undefined
 	* // $query.error is ApiError | null
 	*
@@ -163,7 +163,7 @@ function createQueryFactories(queryClient) {
 	* @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
+	*   - `options()`: Returns config for use with useMutation() or createMutation()
 	*   - `execute()`: Directly executes the mutation and returns a Result
 	*
 	* @example
@@ -186,7 +186,7 @@ function createQueryFactories(queryClient) {
 	* });
 	*
 	* // Step 2a: Use reactively in a component
-	* const mutation = createMutation(createRecording.options());
+	* const mutation = createMutation(createRecording.options);
 	* // Call with: $mutation.mutate(recordingData)
 	*
 	* // Step 2b: Use imperatively in an action

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 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 = 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\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 components\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 */\nexport type DefineQueryOutput<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = {\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 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 = void,\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 = void,\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.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 * ## Why use defineQuery?\n\t *\n\t * 1. **Dual Interface**: Provides both reactive (`.options()`) and imperative (`.fetch()`) 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 three methods:\n\t *   - `options()`: Returns config for use with createQuery() in Svelte components\n\t *   - `fetch()`: Always attempts to fetch data (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 *   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 preloaders (recommended)\n\t * export const load = async () => {\n\t *   const { data, error } = await userQuery.ensure();\n\t *   if (error) throw error;\n\t *   return { user: data };\n\t * };\n\t *\n\t * // Step 2c: Use imperatively for explicit refresh\n\t * async function refreshUser() {\n\t *   const { data, error } = await userQuery.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\tTQueryKey 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.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 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\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 using queryClient.fetchQuery().\n\t\t\t *\n\t\t\t * This method ALWAYS evaluates freshness and will refetch if data is stale.\n\t\t\t * It wraps TanStack Query's fetchQuery method, which returns cached data if fresh\n\t\t\t * or makes a network request if the data is stale or missing.\n\t\t\t *\n\t\t\t * **When to use fetch():**\n\t\t\t * - When you explicitly want to check data freshness\n\t\t\t * - For user-triggered refresh actions\n\t\t\t * - When you need the most up-to-date data\n\t\t\t *\n\t\t\t * **For preloaders, use ensure() instead** - it's more efficient for initial data loading.\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 * // Good for user-triggered refresh\n\t\t\t * const { data, error } = await userQuery.fetch();\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 fetch(): Promise<Result<TQueryData, TError>> {\n\t\t\t\ttry {\n\t\t\t\t\treturn Ok(\n\t\t\t\t\t\tawait queryClient.fetchQuery<\n\t\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\t\tTError,\n\t\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t\t>({\n\t\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\t\tqueryFn: newOptions.queryFn,\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\n\t\t\t/**\n\t\t\t * Ensures data is available for this query using queryClient.ensureQueryData().\n\t\t\t *\n\t\t\t * This method PRIORITIZES cached data and only calls fetchQuery internally if no cached\n\t\t\t * data exists. It wraps TanStack Query's ensureQueryData method, which is perfect for\n\t\t\t * guaranteeing data availability with minimal network requests.\n\t\t\t *\n\t\t\t * **This is the RECOMMENDED method for preloaders** because:\n\t\t\t * - It returns cached data immediately if available\n\t\t\t * - It updates the query client cache properly\n\t\t\t * - It minimizes network requests during navigation\n\t\t\t * - It ensures components have data ready when they mount\n\t\t\t *\n\t\t\t * **When to use ensure():**\n\t\t\t * - Route preloaders and data loading functions\n\t\t\t * - Initial component data requirements\n\t\t\t * - When cached data is acceptable for immediate display\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 * // Perfect for preloaders\n\t\t\t * export const load = async () => {\n\t\t\t *   const { data, error } = await userQuery.ensure();\n\t\t\t *   if (error) {\n\t\t\t *     throw error;\n\t\t\t *   }\n\t\t\t *   return { user: data };\n\t\t\t * };\n\t\t\t */\n\t\t\tasync ensure(): Promise<Result<TQueryData, TError>> {\n\t\t\t\ttry {\n\t\t\t\t\treturn Ok(\n\t\t\t\t\t\tawait queryClient.ensureQueryData<\n\t\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\t\tTError,\n\t\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t\t>({\n\t\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\t\tqueryFn: newOptions.queryFn,\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 = 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.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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0JA,SAAgB,qBAAqBA,aAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4D9D,MAAM,cAAc,CAOnBC,YAO2E;EAC3E,MAAM,aAAa;GAClB,GAAG;GACH,SAAS,OAAO,YAAY;IAC3B,IAAI,SAAS,QAAQ,cAAc,QAAQ;AAC3C,QAAI,kBAAkB,QAAS,UAAS,MAAM;AAC9C,WAAO,QAAQ,OAAO;GACtB;EACD;AAQD,SAAO;GAMN,SAAS,MAAM;GAyBf,MAAM,QAA6C;AAClD,QAAI;AACH,YAAO,GACN,MAAM,YAAY,WAKhB;MACD,UAAU,WAAW;MACrB,SAAS,WAAW;KACpB,EAAC,CACF;IACD,SAAQ,OAAO;AACf,YAAO,IAAI,MAAgB;IAC3B;GACD;GAgCD,MAAM,SAA8C;AACnD,QAAI;AACH,YAAO,GACN,MAAM,YAAY,gBAKhB;MACD,UAAU,WAAW;MACrB,SAAS,WAAW;KACpB,EAAC,CACF;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,gBACRH,aACAI,SACAD,WACC;CACD,MAAM,WAAW,YAAY,kBAAkB,CAAC,MAAM,aAAa,QAAQ;AAC3E,QAAO,SAAS,QAAQ,UAAU;AAClC"}
+{"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 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 = 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\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 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 */\nexport type DefineQueryOutput<\n\tTQueryFnData = unknown,\n\tTError = DefaultError,\n\tTData = TQueryFnData,\n\tTQueryData = TQueryFnData,\n\tTQueryKey extends QueryKey = QueryKey,\n> = {\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 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 = void,\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 useMutation() or createMutation()\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 = void,\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.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 * ## Why use defineQuery?\n\t *\n\t * 1. **Dual Interface**: Provides both reactive (`.options`) and imperative (`.fetch()`) 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 three methods:\n\t *   - `options()`: Returns config for use with useQuery() or createQuery()\n\t *   - `fetch()`: Always attempts to fetch data (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 *   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 preloaders (recommended)\n\t * export const load = async () => {\n\t *   const { data, error } = await userQuery.ensure();\n\t *   if (error) throw error;\n\t *   return { user: data };\n\t * };\n\t *\n\t * // Step 2c: Use imperatively for explicit refresh\n\t * async function refreshUser() {\n\t *   const { data, error } = await userQuery.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\tTQueryKey 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.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 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\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 `useQuery()` or `createQuery()` 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 using queryClient.fetchQuery().\n\t\t\t *\n\t\t\t * This method ALWAYS evaluates freshness and will refetch if data is stale.\n\t\t\t * It wraps TanStack Query's fetchQuery method, which returns cached data if fresh\n\t\t\t * or makes a network request if the data is stale or missing.\n\t\t\t *\n\t\t\t * **When to use fetch():**\n\t\t\t * - When you explicitly want to check data freshness\n\t\t\t * - For user-triggered refresh actions\n\t\t\t * - When you need the most up-to-date data\n\t\t\t *\n\t\t\t * **For preloaders, use ensure() instead** - it's more efficient for initial data loading.\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 * // Good for user-triggered refresh\n\t\t\t * const { data, error } = await userQuery.fetch();\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 fetch(): Promise<Result<TQueryData, TError>> {\n\t\t\t\ttry {\n\t\t\t\t\treturn Ok(\n\t\t\t\t\t\tawait queryClient.fetchQuery<\n\t\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\t\tTError,\n\t\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t\t>({\n\t\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\t\tqueryFn: newOptions.queryFn,\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\n\t\t\t/**\n\t\t\t * Ensures data is available for this query using queryClient.ensureQueryData().\n\t\t\t *\n\t\t\t * This method PRIORITIZES cached data and only calls fetchQuery internally if no cached\n\t\t\t * data exists. It wraps TanStack Query's ensureQueryData method, which is perfect for\n\t\t\t * guaranteeing data availability with minimal network requests.\n\t\t\t *\n\t\t\t * **This is the RECOMMENDED method for preloaders** because:\n\t\t\t * - It returns cached data immediately if available\n\t\t\t * - It updates the query client cache properly\n\t\t\t * - It minimizes network requests during navigation\n\t\t\t * - It ensures components have data ready when they mount\n\t\t\t *\n\t\t\t * **When to use ensure():**\n\t\t\t * - Route preloaders and data loading functions\n\t\t\t * - Initial component data requirements\n\t\t\t * - When cached data is acceptable for immediate display\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 * // Perfect for preloaders\n\t\t\t * export const load = async () => {\n\t\t\t *   const { data, error } = await userQuery.ensure();\n\t\t\t *   if (error) {\n\t\t\t *     throw error;\n\t\t\t *   }\n\t\t\t *   return { user: data };\n\t\t\t * };\n\t\t\t */\n\t\t\tasync ensure(): Promise<Result<TQueryData, TError>> {\n\t\t\t\ttry {\n\t\t\t\t\treturn Ok(\n\t\t\t\t\t\tawait queryClient.ensureQueryData<\n\t\t\t\t\t\t\tTQueryFnData,\n\t\t\t\t\t\t\tTError,\n\t\t\t\t\t\t\tTQueryData,\n\t\t\t\t\t\t\tTQueryKey\n\t\t\t\t\t\t>({\n\t\t\t\t\t\t\tqueryKey: newOptions.queryKey,\n\t\t\t\t\t\t\tqueryFn: newOptions.queryFn,\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 useMutation() or createMutation()\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 = 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.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 `useMutation()` or `createMutation()` 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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0JA,SAAgB,qBAAqBA,aAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4D9D,MAAM,cAAc,CAOnBC,YAO2E;EAC3E,MAAM,aAAa;GAClB,GAAG;GACH,SAAS,OAAO,YAAY;IAC3B,IAAI,SAAS,QAAQ,cAAc,QAAQ;AAC3C,QAAI,kBAAkB,QAAS,UAAS,MAAM;AAC9C,WAAO,QAAQ,OAAO;GACtB;EACD;AAQD,SAAO;GAMN,SAAS,MAAM;GAyBf,MAAM,QAA6C;AAClD,QAAI;AACH,YAAO,GACN,MAAM,YAAY,WAKhB;MACD,UAAU,WAAW;MACrB,SAAS,WAAW;KACpB,EAAC,CACF;IACD,SAAQ,OAAO;AACf,YAAO,IAAI,MAAgB;IAC3B;GACD;GAgCD,MAAM,SAA8C;AACnD,QAAI;AACH,YAAO,GACN,MAAM,YAAY,gBAKhB;MACD,UAAU,WAAW;MACrB,SAAS,WAAW;KACpB,EAAC,CACF;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,gBACRH,aACAI,SACAD,WACC;CACD,MAAM,WAAW,YAAY,kBAAkB,CAAC,MAAM,aAAa,QAAQ;AAC3E,QAAO,SAAS,QAAQ,UAAU;AAClC"}

package/package.json

@@ -1,56 +1,63 @@
 {
-  "name": "wellcrafted",
-  "version": "0.22.0",
-  "description": "Delightful TypeScript patterns for elegant, type-safe applications",
-  "type": "module",
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "exports": {
-    "./result": {
-      "types": "./dist/result/index.d.ts",
-      "import": "./dist/result/index.js"
-    },
-    "./error": {
-      "types": "./dist/error/index.d.ts",
-      "import": "./dist/error/index.js"
-    },
-    "./brand": {
-      "types": "./dist/brand.d.ts",
-      "import": "./dist/brand.js"
-    },
-    "./query": {
-      "types": "./dist/query/index.d.ts",
-      "import": "./dist/query/index.js"
-    }
-  },
-  "keywords": [
-    "typescript",
-    "delightful",
-    "elegant",
-    "type-safe",
-    "well-crafted",
-    "polished",
-    "utilities",
-    "result",
-    "error-handling",
-    "brand-types"
-  ],
-  "author": "",
-  "license": "MIT",
-  "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "@changesets/cli": "^2.27.10",
-    "@tanstack/query-core": "^5.82.0",
-    "tsdown": "^0.12.5",
-    "typescript": "^5.8.3"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "format": "biome format --write .",
-    "lint": "biome lint --write .",
-    "release": "pnpm run build && changeset version && changeset publish"
-  }
-}
+	"name": "wellcrafted",
+	"version": "0.24.0",
+	"description": "Delightful TypeScript patterns for elegant, type-safe applications",
+	"type": "module",
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"exports": {
+		"./result": {
+			"types": "./dist/result/index.d.ts",
+			"import": "./dist/result/index.js"
+		},
+		"./error": {
+			"types": "./dist/error/index.d.ts",
+			"import": "./dist/error/index.js"
+		},
+		"./brand": {
+			"types": "./dist/brand.d.ts",
+			"import": "./dist/brand.js"
+		},
+		"./query": {
+			"types": "./dist/query/index.d.ts",
+			"import": "./dist/query/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsdown",
+		"format": "biome format --write .",
+		"lint": "biome lint --write .",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"release": "pnpm run build && changeset version && changeset publish"
+	},
+	"keywords": [
+		"typescript",
+		"delightful",
+		"elegant",
+		"type-safe",
+		"well-crafted",
+		"polished",
+		"utilities",
+		"result",
+		"error-handling",
+		"brand-types"
+	],
+	"author": "",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/wellcrafted-dev/wellcrafted"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.3",
+		"@changesets/cli": "^2.27.10",
+		"@tanstack/query-core": "^5.82.0",
+		"tsdown": "^0.12.5",
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.14"
+	}
+}