wellcrafted 0.21.4 → 0.23.1

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,162 @@ 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 }
+        });
+      }
+
+      // 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
+// When catch always returns Ok<T>, function returns Ok<T>
+const alwaysSucceeds = trySync({
+  try: () => JSON.parse(riskyJson),
+  catch: () => Ok({ fallback: "default" }) // Always recover with fallback
+});
+// alwaysSucceeds: Ok<object> - No error checking needed!
+console.log(alwaysSucceeds.data); // Safe to access 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) => Err(ParseError({ message: "Invalid JSON", cause: error }))
+});
+// mayFail: Result<object, ParseError> - Must check for errors
+if (isOk(mayFail)) {
+  console.log(mayFail.data); // Only safe after checking
+}
+```
 
-// Create a live instance (dependency injection at build time)
-export const UserServiceLive = createUserService(databaseInstance);
+### 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 Err(ParseError({ 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 +574,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 +594,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

@@ -1,41 +1,85 @@
-import { Err } from "../result-DucAuR8u.js";
+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
- * };
- * ```
- */
-type BaseError = Readonly<{
-  name: string;
-  message: string;
-  context?: Record<string, unknown>;
-  cause: unknown;
-}>;
 /**
  * Creates a tagged error type for type-safe error handling.
  * Uses the `name` property as a discriminator for tagged unions.
  *
+ * 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.
+ *
  * Error types should follow the convention of ending with "Error" suffix.
  * The Err data structure wraps these error types in the Result system.
  *
  * @example
  * ```ts
- * type ValidationError = TaggedError<"ValidationError">
- * type NetworkError = TaggedError<"NetworkError">
+ * // Simple error without cause
+ * type ValidationError = TaggedError<"ValidationError">;
+ * const validationError: ValidationError = {
+ *   name: "ValidationError",
+ *   message: "Input is required"
+ * };
  *
+ * // 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>;
+ *
+ * const networkError: NetworkError = {
+ *   name: "NetworkError",
+ *   message: "Socket timeout after 5000ms",
+ *   context: { host: "db.example.com", port: 5432, timeout: 5000 }
+ * };
+ *
+ * const dbError: DatabaseError = {
+ *   name: "DatabaseError",
+ *   message: "Failed to connect to database",
+ *   context: { operation: "connect", retries: 3 },
+ *   cause: networkError // TypeScript enforces this must be NetworkError
+ * };
+ *
+ * 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) {
  *     case "ValidationError": // TypeScript knows this is ValidationError
@@ -51,8 +95,7 @@ type BaseError = Readonly<{
  *     return Err({
  *       name: "ValidationError",
  *       message: "Input is required",
- *       context: { input },
- *       cause: null,
+ *       context: { input }
  *     });
  *   }
  *   return Ok(input);
@@ -63,17 +106,19 @@ type BaseError = Readonly<{
  *   if (!isAuthenticated) {
  *     return Err({
  *       name: "AuthError",
- *       message: "User not authenticated",
- *       cause: null,
+ *       message: "User not authenticated"
  *     });
  *   }
  *   return Ok(currentUser);
  * }
  * ```
  */
-type TaggedError<T extends string> = BaseError & {
-  readonly name: T;
-};
+type TaggedError<TName extends string = string, TCause extends TaggedError<string, any> = TaggedError<string, any>> = Readonly<{
+  name: TName;
+  message: string;
+  context?: Record<string, unknown>;
+  cause?: TCause;
+}>;
 //# sourceMappingURL=types.d.ts.map
 //#endregion
 //#region src/error/utils.d.ts
@@ -116,7 +161,7 @@ declare function extractErrorMessage(error: unknown): string;
 /**
  * Input type for creating a tagged error (everything except the name)
  */
-type TaggedErrorWithoutName<T extends string> = Omit<TaggedError<T>, "name">;
+type TaggedErrorWithoutName<TName extends string, TCause extends TaggedError<string, any> = TaggedError<string, any>> = Omit<TaggedError<TName, TCause>, "name">;
 /**
  * Replaces the "Error" suffix with "Err" suffix in error type names.
  *
@@ -141,7 +186,7 @@ type ReplaceErrorWithErr<T extends `${string}Error`> = T extends `${infer TBase}
  * - One that creates plain TaggedError objects (named with "Error" suffix)
  * - One that creates Err-wrapped TaggedError objects (named with "Err" suffix)
  */
-type TaggedErrorFactories<TErrorName extends `${string}Error`> = { [K in TErrorName]: (input: TaggedErrorWithoutName<K>) => TaggedError<K> } & { [K in ReplaceErrorWithErr<TErrorName>]: (input: TaggedErrorWithoutName<TErrorName>) => Err<TaggedError<TErrorName>> };
+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>> };
 /**
  * Returns two different factory functions for tagged errors.
  *
@@ -159,26 +204,35 @@ type TaggedErrorFactories<TErrorName extends `${string}Error`> = { [K in TErrorN
  *
  * @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' },
- *   cause: undefined
+ *   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' },
- *   cause: undefined
+ *   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
+ * });
  * ```
  */
-declare function createTaggedError<TErrorName extends `${string}Error`>(name: TErrorName): TaggedErrorFactories<TErrorName>;
+declare function createTaggedError<TErrorName extends `${string}Error`, TCause extends TaggedError<string, any> = TaggedError<string, any>>(name: TErrorName): TaggedErrorFactories<TErrorName, 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":";;;;;;;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"}

package/dist/error/index.js

@@ -1,4 +1,4 @@
-import { Err } from "../result-BPrctj1f.js";
+import { Err } from "../result-B1iWFqM9.js";
 
 //#region src/error/utils.ts
 /**
@@ -39,11 +39,22 @@ import { Err } from "../result-BPrctj1f.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 {
@@ -69,29 +80,38 @@ function extractErrorMessage(error) {
 *
 * @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' },
-*   cause: undefined
+*   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' },
-*   cause: undefined
+*   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) => ({
-		...error,
-		name
+		name,
+		...error
 	});
 	const errName = name.replace(/Error$/, "Err");
 	const errConstructor = (error) => Err(errorConstructor(error));

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: 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"}