wellcrafted 0.23.1 → 0.25.0

package/README.md

@@ -345,13 +345,24 @@ The `catch` parameter in `trySync` and `tryAsync` enables smart return type narr
 
 ### Recovery Pattern (Always Succeeds)
 ```typescript
-// When catch always returns Ok<T>, function returns Ok<T>
-const alwaysSucceeds = trySync({
+// ❌ 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({ fallback: "default" }) // Always recover with fallback
+  catch: () => Ok([])
 });
-// alwaysSucceeds: Ok<object> - No error checking needed!
-console.log(alwaysSucceeds.data); // Safe to access directly
+// 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)
@@ -359,7 +370,7 @@ console.log(alwaysSucceeds.data); // Safe to access directly
 // When catch can return Err<E>, function returns Result<T, E>  
 const mayFail = trySync({
   try: () => JSON.parse(riskyJson),
-  catch: (error) => Err(ParseError({ message: "Invalid JSON", cause: error }))
+  catch: (error) => ParseErr({ message: "Invalid JSON", cause: error })
 });
 // mayFail: Result<object, ParseError> - Must check for errors
 if (isOk(mayFail)) {
@@ -377,7 +388,7 @@ const smartParse = trySync({
       return Ok({}); // Return Ok<T> for fallback
     }
     // Propagate other errors  
-    return Err(ParseError({ message: "Parse failed", cause: error }));
+    return ParseErr({ message: "Parse failed", cause: error });
   }
 });
 // smartParse: Result<object, ParseError> - Mixed handling = Result type

package/dist/error/index.d.ts

@@ -2,6 +2,22 @@ import { Err } from "../result-DRq8PMRe.js";
 
 //#region src/error/types.d.ts
 
+/**
+ * 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 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.
@@ -10,75 +26,44 @@ import { Err } from "../result-DRq8PMRe.js";
  * call stack. Each error wraps its cause, building a complete trace of how
  * an error propagated through your application layers.
  *
- * Error types should follow the convention of ending with "Error" suffix.
- * The Err data structure wraps these error types in the Result system.
+ * **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 TContext - Additional context data for the error (default: never = no context property)
+ * @template TCause - The type of error that caused this error (default: never = no cause property)
  *
  * @example
  * ```ts
- * // Simple error without cause
+ * // 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
  *
- * // Type-safe error chaining with specific cause types
- * type NetworkError = TaggedError<"NetworkError">;
- * type DatabaseError = TaggedError<"DatabaseError", NetworkError>;
- * type ServiceError = TaggedError<"ServiceError", DatabaseError>;
- * type APIError = TaggedError<"APIError", ServiceError>;
- *
+ * // Error with required context
+ * type NetworkError = TaggedError<"NetworkError", { host: string; port: number }>;
  * const networkError: NetworkError = {
  *   name: "NetworkError",
- *   message: "Socket timeout after 5000ms",
- *   context: { host: "db.example.com", port: 5432, timeout: 5000 }
+ *   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", { operation: string }, NetworkError>;
  * const dbError: DatabaseError = {
  *   name: "DatabaseError",
  *   message: "Failed to connect to database",
- *   context: { operation: "connect", retries: 3 },
- *   cause: networkError // TypeScript enforces this must be NetworkError
+ *   context: { operation: "connect" }, // Required!
+ *   cause: networkError // Required!
  * };
  *
- * const serviceError: ServiceError = {
- *   name: "UserServiceError",
- *   message: "Could not fetch user profile",
- *   context: { userId: "123", method: "getUserById" },
- *   cause: dbError // TypeScript enforces this must be DatabaseError
- * };
- *
- * const apiError: APIError = {
- *   name: "APIError",
- *   message: "Internal server error",
- *   context: { endpoint: "/api/users/123", statusCode: 500 },
- *   cause: serviceError // TypeScript enforces this must be ServiceError
- * };
- *
- * // The entire error chain is JSON-serializable and type-safe
- * console.log(JSON.stringify(apiError, null, 2));
- * // Outputs:
- * // {
- * //   "name": "APIError",
- * //   "message": "Internal server error",
- * //   "context": { "endpoint": "/api/users/123", "statusCode": 500 },
- * //   "cause": {
- * //     "name": "UserServiceError",
- * //     "message": "Could not fetch user profile",
- * //     "context": { "userId": "123", "method": "getUserById" },
- * //     "cause": {
- * //       "name": "DatabaseError",
- * //       "message": "Failed to connect to database",
- * //       "context": { "operation": "connect", "retries": 3 },
- * //       "cause": {
- * //         "name": "NetworkError",
- * //         "message": "Socket timeout after 5000ms",
- * //         "context": { "host": "db.example.com", "port": 5432, "timeout": 5000 }
- * //       }
- * //     }
- * //   }
- * // }
- *
  * // Discriminated unions still work
  * function handleError(error: ValidationError | NetworkError) {
  *   switch (error.name) {
@@ -88,38 +73,12 @@ import { Err } from "../result-DRq8PMRe.js";
  *       break;
  *   }
  * }
- *
- * // Used in Result types:
- * function validate(input: string): Result<string, ValidationError> {
- *   if (!input) {
- *     return Err({
- *       name: "ValidationError",
- *       message: "Input is required",
- *       context: { input }
- *     });
- *   }
- *   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"
- *     });
- *   }
- *   return Ok(currentUser);
- * }
  * ```
  */
-type TaggedError<TName extends string = string, TCause extends TaggedError<string, any> = TaggedError<string, any>> = Readonly<{
+type TaggedError<TName extends string = string, TContext = never, TCause = never> = Readonly<{
   name: TName;
   message: string;
-  context?: Record<string, unknown>;
-  cause?: TCause;
-}>;
-//# sourceMappingURL=types.d.ts.map
+} & WithContext<TContext> & WithCause<TCause>>;
 //#endregion
 //#region src/error/utils.d.ts
 /**
@@ -159,15 +118,15 @@ type TaggedError<TName extends string = string, TCause extends TaggedError<strin
  */
 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<TName extends string, TCause extends TaggedError<string, any> = TaggedError<string, any>> = Omit<TaggedError<TName, TCause>, "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"
  *
@@ -175,64 +134,165 @@ type TaggedErrorWithoutName<TName extends string, TCause extends TaggedError<str
  * ```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 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> };
+/**
+ * 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, TContext, never>;
+  <TCause extends AnyTaggedError>(input: {
+    message: string;
+    cause: TCause;
+  }): TaggedError<TName, never, TCause>;
+  <TContext extends Record<string, unknown>, TCause extends AnyTaggedError>(input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): TaggedError<TName, TContext, TCause>;
+};
+/**
+ * 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, TContext, never>>;
+  <TCause extends AnyTaggedError>(input: {
+    message: string;
+    cause: TCause;
+  }): Err<TaggedError<TName, never, TCause>>;
+  <TContext extends Record<string, unknown>, TCause extends AnyTaggedError>(input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): Err<TaggedError<TName, TContext, TCause>>;
+};
+/**
+ * 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, TContext, never>;
+  <TCause extends AnyTaggedError>(input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): TaggedError<TName, TContext, TCause>;
+};
+/**
+ * Creates Err-wrapped TaggedError objects with fixed context but flexible cause.
  */
-type TaggedErrorFactories<TErrorName extends `${string}Error`, TCause extends TaggedError<string, any> = TaggedError<string, any>> = { [K in TErrorName]: (input: TaggedErrorWithoutName<K, TCause>) => TaggedError<K, TCause> } & { [K in ReplaceErrorWithErr<TErrorName>]: (input: TaggedErrorWithoutName<TErrorName, TCause>) => Err<TaggedError<TErrorName, TCause>> };
+type ContextFixedErrConstructor<TName extends string, TContext extends Record<string, unknown>> = {
+  (input: {
+    message: string;
+    context: TContext;
+  }): Err<TaggedError<TName, TContext, never>>;
+  <TCause extends AnyTaggedError>(input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): Err<TaggedError<TName, TContext, TCause>>;
+};
 /**
- * Returns two different factory functions for tagged errors.
+ * 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, TContext, never>;
+  (input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): TaggedError<TName, TContext, TCause>;
+};
+/**
+ * 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, TContext, never>>;
+  (input: {
+    message: string;
+    context: TContext;
+    cause: TCause;
+  }): Err<TaggedError<TName, TContext, TCause>>;
+};
+/**
+ * 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
- * // Simple error without typed cause
+ * // 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' }
- * });
- * // 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' }
- * });
- * // Returns: Err({ 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
  *
- * // Type-safe error chaining with specific cause types
- * type NetworkError = TaggedError<"NetworkError">;
- * const { DatabaseError, DatabaseErr } = createTaggedError<"DatabaseError", NetworkError>('DatabaseError');
- *
- * const networkError: NetworkError = { name: "NetworkError", message: "Timeout" };
- * const dbError = DatabaseError({
- *   message: 'Connection failed',
- *   cause: networkError // TypeScript enforces NetworkError type
- * });
+ * // 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`, TCause extends TaggedError<string, any> = TaggedError<string, any>>(name: TErrorName): TaggedErrorFactories<TErrorName, TCause>;
+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 { 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":";;;;;;;AA+GA;;;;;;;;AAGY;;;;AC5EZ;AAkDC;;;;;;;;AAQO;AAAA;;;;AAmBmC;AAAA;;;;;;;;;;;;;;;;;;;;AAmBlC;AAgDT;;;;;;;;AAGyC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KD1E7B,0DAEI,2BAA2B,4BACvC;QACG;;YAEI;UACF;;;;;;AAPT;;;;;;;;AAGY;;;;AC5EZ;AAkDC;;;;;;;;AAQO;AAAA;;;;AAmBmC;AAAA;;;;;;;AAclC,iBA3FO,mBAAA,CA2FP,KAAA,EAAA,OAAA,CAAA,EAAA,MAAA;;;;KApCJ,sBAuCsB,CAAA,cAAA,MAAA,EAAA,eArCX,WAqCW,CAAA,MAAA,EAAA,GAAA,CAAA,GArCgB,WAqChB,CAAA,MAAA,EAAA,GAAA,CAAA,CAAA,GApCvB,IAoCuB,CApClB,WAoCkB,CApCN,KAoCM,EApCC,MAoCD,CAAA,EAAA,MAAA,CAAA;;;;;;;;;AAElB;AAgDT;;;;;;;KApEK,mBAuEgB,CAAA,UAAA,GAAA,MAAA,OAAA,CAAA,GAtEpB,CAsEoB,SAAA,GAAA,KAAA,MAAA,OAAA,GAAA,GAtEiB,KAsEjB,KAAA,GAAA,KAAA;AAAoB;;;;;;;KA7DpC,yEAEW,2BAA2B,oCAEpC,qBACE,uBAAuB,GAAG,YAC7B,YAAY,GAAG,oBAEd,oBAAoB,sBAClB,uBAAuB,YAAY,YACtC,IAAI,YAAY,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgDlB,sEAEA,2BAA2B,gCACnC,aAAa,qBAAqB,YAAY"}
+{"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

@@ -63,58 +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
-* // Simple error without typed cause
-* const { NetworkError, NetworkErr } = createTaggedError('NetworkError');
-*
-* // NetworkError: Creates just the error object
-* const error = NetworkError({
-*   message: 'Connection failed',
-*   context: { url: 'https://api.example.com' }
-* });
-* // 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' }
-* });
-* // Returns: Err({ name: 'NetworkError', message: 'Connection failed', ... })
-*
-* // Type-safe error chaining with specific cause types
-* type NetworkError = TaggedError<"NetworkError">;
-* const { DatabaseError, DatabaseErr } = createTaggedError<"DatabaseError", NetworkError>('DatabaseError');
-*
-* const networkError: NetworkError = { name: "NetworkError", message: "Timeout" };
-* const dbError = DatabaseError({
-*   message: 'Connection failed',
-*   cause: networkError // TypeScript enforces NetworkError type
-* });
-* ```
-*/
 function createTaggedError(name) {
-	const errorConstructor = (error) => ({
+	const errorConstructor = (input) => ({
 		name,
-		...error
+		...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, TCause>"],"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 * Input type for creating a tagged error (everything except the name)\n */\ntype TaggedErrorWithoutName<\n\tTName extends string,\n\tTCause extends TaggedError<string, any> = TaggedError<string, any>,\n> = Omit<TaggedError<TName, TCause>, \"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<\n\tTErrorName extends `${string}Error`,\n\tTCause extends TaggedError<string, any> = TaggedError<string, any>,\n> = {\n\t[K in TErrorName]: (\n\t\tinput: TaggedErrorWithoutName<K, TCause>,\n\t) => TaggedError<K, TCause>;\n} & {\n\t[K in ReplaceErrorWithErr<TErrorName>]: (\n\t\tinput: TaggedErrorWithoutName<TErrorName, TCause>,\n\t) => Err<TaggedError<TErrorName, TCause>>;\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 * // Simple error without typed cause\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 * });\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 * });\n * // Returns: Err({ name: 'NetworkError', message: 'Connection failed', ... })\n *\n * // Type-safe error chaining with specific cause types\n * type NetworkError = TaggedError<\"NetworkError\">;\n * const { DatabaseError, DatabaseErr } = createTaggedError<\"DatabaseError\", NetworkError>('DatabaseError');\n *\n * const networkError: NetworkError = { name: \"NetworkError\", message: \"Timeout\" };\n * const dbError = DatabaseError({\n *   message: 'Connection failed',\n *   cause: networkError // TypeScript enforces NetworkError type\n * });\n * ```\n */\nexport function createTaggedError<\n\tTErrorName extends `${string}Error`,\n\tTCause extends TaggedError<string, any> = TaggedError<string, any>,\n>(name: TErrorName): TaggedErrorFactories<TErrorName, TCause> {\n\tconst errorConstructor = (\n\t\terror: TaggedErrorWithoutName<TErrorName, TCause>,\n\t): TaggedError<TErrorName, TCause> => ({ name, ...error });\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, TCause>) =>\n\t\tErr(errorConstructor(error));\n\n\treturn {\n\t\t[name]: errorConstructor,\n\t\t[errName]: errConstructor,\n\t} as TaggedErrorFactories<TErrorName, TCause>;\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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FD,SAAgB,kBAGdC,MAA4D;CAC7D,MAAM,mBAAmB,CACxBC,WACsC;EAAE;EAAM,GAAG;CAAO;CAEzD,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, TContext, never>;\n\t// With cause only\n\t<TCause extends AnyTaggedError>(input: {\n\t\tmessage: string;\n\t\tcause: TCause;\n\t}): TaggedError<TName, never, TCause>;\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, TContext, TCause>;\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, TContext, never>>;\n\t<TCause extends AnyTaggedError>(input: {\n\t\tmessage: string;\n\t\tcause: TCause;\n\t}): Err<TaggedError<TName, never, TCause>>;\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, TContext, TCause>>;\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\tTContext,\n\t\tnever\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, TContext, TCause>;\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, TContext, never>\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, TContext, TCause>>;\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\tTContext,\n\t\tnever\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, TContext, TCause>;\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, TContext, never>\n\t>;\n\t(input: {\n\t\tmessage: string;\n\t\tcontext: TContext;\n\t\tcause: TCause;\n\t}): Err<TaggedError<TName, TContext, TCause>>;\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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "wellcrafted",
-	"version": "0.23.1",
+	"version": "0.25.0",
 	"description": "Delightful TypeScript patterns for elegant, type-safe applications",
 	"type": "module",
 	"files": [
@@ -30,6 +30,8 @@
 		"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": [
@@ -46,11 +48,16 @@
 	],
 	"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"
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.14"
 	}
 }