wellcrafted 0.17.0 → 0.19.0

package/README.md

@@ -7,125 +7,60 @@
 
 *Delightful TypeScript utilities for elegant, type-safe applications*
 
-This library provides a robust, Rust-inspired `Result` type, elegant brand types, and a lightweight, serializable error handling system for TypeScript. It's designed to help you write more predictable, type-safe, and composable code by making error handling an explicit part of your function signatures.
+## Transform unpredictable errors into type-safe results
 
-## Table of Contents
-
-- [Quick Start](#quick-start)
-- [Core Idea: The Result Type](#core-idea-the-result-type)
-- [Installation](#installation)
-- [Handling Operation Outcomes](#handling-operation-outcomes)
-- [Understanding TaggedError](#understanding-taggederror)
-- [Basic Usage](#basic-usage)
-- [Wrapping Functions That Throw](#wrapping-functions-that-throw)
-- [API Reference](#api-reference)
-- [Design Philosophy](#design-philosophy)
-- [FAQ](#faq)
-
-## Quick Start
-
-**30-second example:** Transform throwing async operations into type-safe Results.
-
-```bash
-npm install wellcrafted
-```
-
-```ts
-import { tryAsync } from "wellcrafted/result";
-import { type TaggedError } from "wellcrafted/error";
-import * as fs from 'fs/promises';
-
-type FileError = TaggedError<"FileError">;
-
-async function readConfig(path: string) {
-  return tryAsync<string, FileError>({
-    try: async () => {
-      const content = await fs.readFile(path, 'utf-8');
-      return content;
-    },
-    mapError: (error) => ({
-      name: "FileError",
-      message: "Failed to read configuration file",
-      context: { path },
-      cause: error
-    })
-  });
+```typescript
+// ❌ Before: Which errors can this throw? 🤷
+try {
+  await saveUser(user);
+} catch (error) {
+  // ... good luck debugging in production
 }
 
-// Handle the result
-const { data, error } = await readConfig('./config.json');
-
+// ✅ After: Every error is visible and typed
+const { data, error } = await saveUser(user);
 if (error) {
-  console.error(`${error.name}: ${error.message}`);
-  console.log("Context:", error.context);
-  process.exit(1);
+  switch (error.name) {
+    case "ValidationError": 
+      showToast(`Invalid ${error.context.field}`);
+      break;
+    case "AuthError":
+      redirectToLogin();
+      break;
+    // TypeScript ensures you handle all cases!
+  }
 }
-
-console.log("Config loaded:", data); // TypeScript knows data is safe here
 ```
 
-**What just happened?** Instead of letting file operations throw unpredictable errors, `tryAsync` wraps them in a `Result` type that makes success and failure explicit in your function signatures. No more unhandled exceptions!
-
----
-
-## Core Idea: The Result Type
-
-> **💡 TL;DR:** Replace `throw new Error()` with `return Err()` to make errors visible in your function signatures.
-
-JavaScript's traditional error handling, based on `try...catch` and throwing `Error` objects, has two major drawbacks for modern application development:
-1.  **It's not type-safe**: A function signature `function doSomething(): User` doesn't tell you that it might throw a `NetworkError` or a `ValidationError`. Errors are invisible until they strike at runtime.
-2.  **It's not serialization-friendly**: `Error` instances lose their prototype chain when crossing serialization boundaries (JSON.stringify/parse, network requests, worker threads), breaking `instanceof` checks.
-
-This library solves these problems with the `Result<T, E>` type. Instead of throwing, functions return a `Result` object that explicitly represents either a success or a failure.
-
-A `Result` is a union of two "variants":
-- **`Ok<T>`**: Represents a successful outcome, containing a `data` field with the success value. In this variant, the `error` property is always `null`.
-- **`Err<E>`**: Represents a failure outcome, containing an `error` field with the error value. In this variant, the `data` property is always `null`.
-
-This structure allows TypeScript's control-flow analysis to act as if it's a **discriminated union**. By checking if `result.error === null`, TypeScript knows it must be an `Ok` variant and can safely access `result.data`. This makes error handling explicit, type-safe, and predictable.
+## A collection of simple, powerful primitives
 
-### Anatomy of a Result Type
-
-Here's the complete TypeScript implementation - it's simpler than you might think:
-
-```ts
-// The two possible outcomes
-export type Ok<T> = { data: T; error: null };
-export type Err<E> = { error: E; data: null };
-
-// Result is just a union of these two types
-export type Result<T, E> = Ok<T> | Err<E>;
-
-// Helper functions to create each variant
-export const Ok = <T>(data: T): Ok<T> => ({ data, error: null });
-export const Err = <E>(error: E): Err<E> => ({ error, data: null });
+### 🎯 Result Type
+Make errors explicit in function signatures
+```typescript
+function divide(a: number, b: number): Result<number, string> {
+  if (b === 0) return Err("Division by zero");
+  return Ok(a / b);
+}
 ```
 
-**That's it!** The entire foundation is built on this elegant simplicity:
-
-- **`Ok<T>`** always has `data: T` and `error: null`
-- **`Err<E>`** always has `error: E` and `data: null`  
-- **`Result<T, E>`** is simply `Ok<T> | Err<E>`
-
-This design creates a **discriminated union** where the `error` (or `data`) property acts as the discriminant (with literal types `null` vs non-null), allowing TypeScript to automatically narrow types:
+### 🏷️ Brand Types
+Create distinct types from primitives
+```typescript
+type UserId = Brand<string, "UserId">;
+type OrderId = Brand<string, "OrderId">;
 
-```ts
-function handleResult<T, E>(result: Result<T, E>) {
-  if (result.error === null) {
-    // TypeScript knows this is Ok<T>
-    console.log(result.data); // ✅ data is type T
-    // console.log(result.error); // ❌ TypeScript knows this is null
-  } else {
-    // TypeScript knows this is Err<E>  
-    console.log(result.error); // ✅ error is type E
-    // console.log(result.data); // ❌ TypeScript knows this is null
-  }
-}
+// TypeScript prevents mixing them up!
+function getUser(id: UserId) { /* ... */ }
 ```
 
-The beauty is in the transparency - you can see exactly how it works under the hood, yet it provides powerful type safety and ergonomics.
+### 📋 Tagged Errors
+Structured, serializable errors with convenient factory functions
+```typescript
+import { createTaggedError } from "wellcrafted/error";
 
----
+const { ApiError, ApiErr } = createTaggedError("ApiError");
+// ApiError() creates error object, ApiErr() creates Err-wrapped error
+```
 
 ## Installation
 
@@ -133,731 +68,423 @@ The beauty is in the transparency - you can see exactly how it works under the h
 npm install wellcrafted
 ```
 
----
-
-## Handling Operation Outcomes
-
-Once you have a `Result`, there are two main patterns for working with it. Choose the pattern that best fits your preference for code style and the specific context of your code.
-
-### Pattern 1: Destructuring (Preferred)
-
-This pattern will feel familiar to developers working with modern libraries like Supabase or Astro Actions. You can destructure the `data` and `error` properties directly from the result object and use a simple conditional check on the `error` property.
-
-This approach is often cleaner and more direct for handling the two possible outcomes, as it gives you immediate access to the inner `data` and `error` values.
+## Quick Start
 
-```ts
-const { data, error } = someOperation();
+```typescript
+import { tryAsync } from "wellcrafted/result";
+import { createTaggedError } from "wellcrafted/error";
+
+// Define your error with factory function
+const { ApiError, ApiErr } = createTaggedError("ApiError");
+type ApiError = ReturnType<typeof ApiError>;
+
+// Wrap any throwing operation
+const { data, error } = await tryAsync({
+  try: () => fetch('/api/user').then(r => r.json()),
+  mapError: (error) => ApiError({
+    message: "Failed to fetch user",
+    context: { endpoint: '/api/user' },
+    cause: error
+  })
+});
 
 if (error) {
-  // `error` holds the inner error value from the Err variant.
-  console.error(`An error occurred: ${error.message}`);
-  return; // Or handle the error appropriately
-}
-
-// If `error` is null, `data` holds the inner success value from the Ok variant.
-// In most modern TypeScript setups, `data` will be correctly inferred as the success type.
-console.log(`The result is: ${data}`);
-```
-
-### Pattern 2: Using Type Guards
-
-In some complex scenarios or with certain TypeScript configurations, the compiler might not be able to perfectly infer the relationship between `data` and `error` when they are destructured into separate variables. In these cases, using the `isOk()` and `isErr()` type guards is a more robust solution. TypeScript's control flow analysis is designed to work flawlessly with this pattern, guaranteeing type safety within each conditional block.
-
-```ts
-import { isOk, isErr } from "wellcrafted/result";
-
-const result = someOperation();
-
-if (isErr(result)) {
-  // TypeScript *guarantees* that `result` is `Err<E>` here.
-  // The `result.data` property is `null`.
-  // The `result.error` property contains the error value.
-  const errorValue = result.error;
-  console.error(errorValue);
-
+  console.error(`${error.name}: ${error.message}`);
 } else {
-  // If it's not an error, it must be a success.
-  // TypeScript *guarantees* that `result` is `Ok<T>` here.
-  // The `result.error` property is `null`.
-  // The `result.data` property contains the success value.
-  const successValue = result.data;
-  console.log(successValue);
+  console.log("User:", data);
 }
 ```
 
-> **When to use Type Guards:** While destructuring is preferred for its simplicity, reach for `isOk()` and `isErr()` whenever you notice that TypeScript isn't correctly narrowing the type of `data` after an error check. This ensures your code remains fully type-safe without needing manual type assertions.
+## Core Features
 
----
+<table>
+<tr>
+<td>
 
-## Understanding TaggedError
+**🎯 Explicit Error Handling**  
+All errors visible in function signatures
 
-This library promotes a **serializable, type-safe error system** using plain objects instead of JavaScript's `Error` class. The foundation of this system is the `TaggedError` type.
+</td>
+<td>
 
-### Why Plain Objects for Errors?
+**📦 Serialization-Safe**  
+Plain objects work everywhere
 
-1.  **Serialization-First**: Plain objects can be easily serialized to JSON (`JSON.stringify`) and transmitted across boundaries (network APIs, IPC, web workers) without losing information, unlike `Error` classes.
-2.  **Type Safety**: Use TypeScript's literal and union types to create a discriminated union of possible errors, allowing `switch` statements to safely narrow down error types.
-3.  **Lightweight**: Avoids the overhead of class instantiation and the complexities of `instanceof` checks.
-4.  **Structured Context**: Easily enforce that all errors carry structured, machine-readable context.
+</td>
+<td>
 
-Every `TaggedError` contains four essential properties that work together to create a robust, debuggable error system:
+**✨ Elegant API**  
+Clean, intuitive patterns
 
-### The Four Properties
+</td>
+</tr>
+<tr>
+<td>
 
-```ts
-type TaggedError<T extends string> = {
-  readonly name: T;                    // 1. The discriminant
-  message: string;                     // 2. Human-readable description  
-  context: Record<string, unknown>;    // 3. Debugging data
-  cause?: unknown;                     // 4. Root cause (optional)
-};
-```
+**🔍 Zero Magic**  
+~50 lines of core code
 
-#### 1. **`name`** - The Discriminant (Tagged Field)
+</td>
+<td>
 
-This is your error's unique identifier and the key to pattern matching. Use it in `if` statements and `switch` statements to handle different error types:
-
-```ts
-type ValidationError = TaggedError<"ValidationError">;
-type NetworkError = TaggedError<"NetworkError">;
-type FileError = TaggedError<"FileError">;
-
-function handleError(error: ValidationError | NetworkError | FileError) {
-  switch (error.name) {
-    case "ValidationError":
-      // TypeScript knows this is ValidationError
-      console.log("Invalid input:", error.context);
-      break;
-    case "NetworkError": 
-      // TypeScript knows this is NetworkError
-      console.log("Network failed:", error.message);
-      break;
-    case "FileError":
-      // TypeScript knows this is FileError
-      console.log("File issue:", error.context);
-      break;
-  }
-}
-```
+**🚀 Lightweight**  
+Zero dependencies, < 2KB
 
-#### 2. **`message`** - Human-Readable Text
+</td>
+<td>
 
-Pure text description that explains what went wrong. Keep it clear and actionable:
+**🎨 Composable**  
+Mix and match utilities
 
-```ts
-return Err({
-  name: "ValidationError",
-  message: "Email address must contain an @ symbol",  // Clear, specific
-  context: { email: userInput },
-  cause: undefined
-});
-```
+</td>
+</tr>
+</table>
 
-#### 3. **`context`** - Debugging Data
+## The Result Pattern Explained
 
-Include function inputs and any data that would help debug the issue. This is invaluable for logging and troubleshooting:
+The Result type makes error handling explicit and type-safe:
 
-```ts
-function processUser(id: number, options: UserOptions): Result<User, ProcessError> {
-  return Err({
-    name: "ProcessError",
-    message: "User processing failed",
-    context: {
-      userId: id,           // Function input
-      options,              // Function input  
-      timestamp: new Date().toISOString(),  // Additional context
-      retryCount: 3         // Useful debugging info
-    },
-    cause: undefined
-  });
-}
+```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>;
 ```
 
-#### 4. **`cause`** - Root Cause Bubbling
-
-- **For new errors**: Set `cause: undefined`
-- **For wrapping existing errors**: Pass the original error as `cause`
+**The Magic**: This creates a discriminated union where TypeScript automatically narrows types:
 
-```ts
-// Creating a new error
-return Err({
-  name: "ValidationError",
-  message: "Invalid user data",
-  context: { input },
-  cause: undefined  // New error, no underlying cause
-});
-
-// Wrapping an existing error
-try {
-  await database.save(user);
-} catch (dbError) {
-  return Err({
-    name: "SaveError", 
-    message: "Failed to save user",
-    context: { userId: user.id },
-    cause: dbError  // Bubble up the original database error
-  });
+```typescript
+if (result.error) {
+  // TypeScript knows: error is E, data is null
+} else {
+  // TypeScript knows: data is T, error is null
 }
 ```
 
-### Creating Domain-Specific Errors
+## Basic Patterns
 
-You can define a set of possible errors for a specific domain:
+### Handle Results with Destructuring
 
 ```typescript
-// Define your specific error types
-export type FileNotFoundError = TaggedError<"FileNotFoundError">;
-export type PermissionDeniedError = TaggedError<"PermissionDeniedError">;
-export type DiskFullError = TaggedError<"DiskFullError">;
-
-// Create a union of all possible errors for this domain
-export type FileSystemError = FileNotFoundError | PermissionDeniedError | DiskFullError;
+const { data, error } = await someOperation();
 
-// A factory function to create an error
-function createFileNotFoundError(path: string, cause?: unknown): FileNotFoundError {
-  return {
-    name: "FileNotFoundError",
-    message: `The file at path "${path}" was not found.`,
-    context: { path },
-    cause
-  };
+if (error) {
+  // Handle error with full type safety
+  return;
 }
-```
 
-Because `name` is a unique literal type for each error, TypeScript can use it to discriminate between them in a `switch` statement:
-
-```ts
-function handleError(error: FileSystemError) {
-  switch (error.name) {
-    case "FileNotFoundError":
-      // TypeScript knows `error` is `FileNotFoundError` here.
-      console.error(`Path not found: ${error.context.path}`);
-      break;
-    case "PermissionDeniedError":
-      // TypeScript knows `error` is `PermissionDeniedError` here.
-      console.error("Permission was denied.");
-      break;
-    case "DiskFullError":
-      // ...
-      break;
-  }
-}
+// Use data - TypeScript knows it's safe
 ```
 
-### Best Practices for Errors
-
-#### 1. Include Meaningful Context
-Always include function inputs and other relevant state in the `context` object. This is invaluable for logging and debugging.
+### Wrap Unsafe Operations
 
 ```typescript
-function createDbError(
-  message: string,
-  query: string,
-  params: unknown[],
-  cause: unknown
-): DbError {
-  return {
-    name: "DbError",
-    message,
-    context: {
-      query,
-      params,
-      timestamp: new Date().toISOString(),
-    },
-    cause,
-  };
-}
-```
-
-#### 2. Handle Errors at the Right Level
-Handle or transform errors where you can add more context or make a recovery decision.
-
-```ts
-async function initializeApp(): Promise<Result<App, FsError | ValidationError>> {
-  const configResult = await readConfig("./config.json");
-
-  // Propagate the file system error directly if config read fails
-  if (isErr(configResult)) {
-    return configResult;
-  }
-
-  // If config is read, but is invalid, return a *different* kind of error
-  const validationResult = validateConfig(configResult.data);
-  if (isErr(validationResult)) {
-    return validationResult;
-  }
+// Synchronous
+const result = trySync({
+  try: () => JSON.parse(jsonString),
+  mapError: (error) => ({
+    name: "ParseError",
+    message: "Invalid JSON",
+    context: { input: jsonString },
+    cause: error
+  })
+});
 
-  return Ok(new App(validationResult.data));
-}
+// Asynchronous  
+const result = await tryAsync({
+  try: () => fetch(url),
+  mapError: (error) => ({
+    name: "NetworkError",
+    message: "Request failed",
+    context: { url },
+    cause: error
+  })
+});
 ```
 
-This structure makes errors **trackable**, **debuggable**, and **type-safe** while maintaining clean separation between different failure modes in your application.
-
----
-
-## Basic Usage
+### Service Layer Example
 
-Now that you understand how to handle Result values and the TaggedError structure, let's see complete examples that combine both concepts:
-
-```ts
-import { Result, Ok, Err, isOk } from "wellcrafted/result";
-import { type TaggedError } from "wellcrafted/error";
-
-// --- Example 1: A Safe Division Function ---
+```typescript
+import { Result, Ok, tryAsync } from "wellcrafted/result";
+import { createTaggedError } from "wellcrafted/error";
 
-// 1. Define a specific error for math-related failures
-type MathError = TaggedError<"MathError">;
+// Define service-specific errors
+const { ValidationError, ValidationErr } = createTaggedError("ValidationError");
+const { DatabaseError, DatabaseErr } = createTaggedError("DatabaseError");
 
-// 2. Create a function that returns a Result with our structured error
-function divide(numerator: number, denominator: number): Result<number, MathError> {
-  if (denominator === 0) {
-    return Err({
-      name: "MathError",
-      message: "Cannot divide by zero.",
-      context: { numerator, denominator },
-      cause: undefined 
-    });
-  }
-  return Ok(numerator / denominator);
-}
+type ValidationError = ReturnType<typeof ValidationError>;
+type DatabaseError = ReturnType<typeof DatabaseError>;
 
-// 3. Handle the result
-const divisionResult = divide(10, 0);
+// 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 },
+          cause: undefined
+        });
+      }
 
-if (!isOk(divisionResult)) {
-  // `divisionResult.error` is a fully-typed MathError object
-  console.error(`Error (${divisionResult.error.name}): ${divisionResult.error.message}`);
-  console.log("Context:", divisionResult.error.context); // { numerator: 10, denominator: 0 }
-}
+      return tryAsync({
+        try: () => db.save(input),
+        mapError: (error) => DatabaseError({
+          message: "Failed to save user",
+          context: { operation: 'createUser', input },
+          cause: error
+        })
+      });
+    },
 
-// --- Example 2: Parsing a User Object ---
-
-// 1. Define a specific error for parsing failures
-type ParseError = TaggedError<"ParseError">;
-
-// 2. Create a function that returns a Result with our structured error
-function parseUser(json: string): Result<{ name: string }, ParseError> {
-  try {
-    const data = JSON.parse(json);
-    if (typeof data.name !== "string") {
-      return Err({
-        name: "ParseError",
-        message: "User object must have a name property of type string.",
-        context: { receivedValue: data.name },
-        cause: undefined
+    async getUser(id: string): Promise<Result<User | null, DatabaseError>> {
+      return tryAsync({
+        try: () => db.findById(id),
+        mapError: (error) => DatabaseError({
+          message: "Failed to fetch user",
+          context: { userId: id },
+          cause: error
+        })
       });
     }
-    return Ok(data);
-  } catch (e) {
-    return Err({
-      name: "ParseError",
-      message: "Invalid JSON provided.",
-      context: { rawString: json },
-      cause: e,
-    });
-  }
+  };
 }
 
-// 3. Handle the result
-const userResult = parseUser('{"name": "Alice"}');
+// Export type for the service
+export type UserService = ReturnType<typeof createUserService>;
 
-if (isOk(userResult)) {
-  console.log(`Welcome, ${userResult.data.name}!`);
-} else {
-  // `userResult.error` is a fully-typed ParseError object
-  console.error(`Error (${userResult.error.name}): ${userResult.error.message}`);
-  console.log("Context:", userResult.error.context);
-}
+// Create a live instance (dependency injection at build time)
+export const UserServiceLive = createUserService(databaseInstance);
 ```
 
----
-
-## Wrapping Functions That Throw
+## Why wellcrafted?
 
-When integrating with existing code that throws exceptions (like `JSON.parse`, fetch APIs, or database clients), you'll need a way to convert these throwing functions into safe `Result`-returning functions. This library provides `trySync` and `tryAsync` to handle this conversion seamlessly.
+JavaScript's `try-catch` has fundamental problems:
 
-### Synchronous Operations with `trySync`
+1. **Invisible Errors**: Function signatures don't show what errors can occur
+2. **Lost in Transit**: `JSON.stringify(new Error())` loses critical information  
+3. **No Type Safety**: TypeScript can't help with `catch (error)` blocks
+4. **Inconsistent**: Libraries throw different things (strings, errors, objects, undefined)
 
-Use `trySync` for synchronous functions that might throw. You provide the operation and a `mapError` function to transform the caught exception into your desired error type.
+wellcrafted solves these with simple, composable primitives that make errors:
+- **Explicit** in function signatures
+- **Serializable** across all boundaries
+- **Type-safe** with full TypeScript support
+- **Consistent** with structured error objects
 
-```ts
-import { trySync, Result } from "wellcrafted/result";
-import { type TaggedError } from "wellcrafted/error";
+## Service Pattern Best Practices
 
-type ParseError = TaggedError<"ParseError">;
+Based on real-world usage, here's the recommended pattern for creating services with wellcrafted:
 
-function parseJson(raw: string): Result<object, ParseError> {
-  return trySync({
-    try: () => JSON.parse(raw),
-    mapError: (error) => ({
-      name: "ParseError",
-      message: "Failed to parse JSON",
-      context: { raw },
-      cause: error
-    })
-  });
-}
+### Factory Function Pattern
 
-const result = parseJson('{"key": "value"}'); // Ok<{key: string}>
-const failedResult = parseJson('not json'); // Err<ParseError>
-```
-
-### Asynchronous Operations with `tryAsync`
-
-Use `tryAsync` for functions that return a `Promise`. It handles both rejected promises and synchronous throws within the async function.
-
-```ts
-import { tryAsync, Result } from "wellcrafted/result";
-import { type TaggedError } from "wellcrafted/error";
-
-type User = { id: number; name: string };
-type NetworkError = TaggedError<"NetworkError">;
-
-async function fetchUser(userId: number): Promise<Result<User, NetworkError>> {
-  return tryAsync({
-    try: async () => {
-      const response = await fetch(`https://api.example.com/users/${userId}`);
-      if (!response.ok) {
-        // You can throw a custom error object
-        throw { message: "Request failed", statusCode: response.status };
+```typescript
+import { createTaggedError } from "wellcrafted/error";
+
+// 1. Define service-specific errors
+const { RecorderServiceError, RecorderServiceErr } = createTaggedError("RecorderServiceError");
+type RecorderServiceError = ReturnType<typeof RecorderServiceError>;
+
+// 2. Create service with factory function
+export function createRecorderService() {
+  // Private state in closure
+  let isRecording = false;
+  
+  // Return object with methods
+  return {
+    startRecording(): Result<void, RecorderServiceError> {
+      if (isRecording) {
+        return RecorderServiceErr({
+          message: "Already recording",
+          context: { isRecording },
+          cause: undefined
+        });
       }
-      return response.json();
+      
+      isRecording = true;
+      return Ok(undefined);
     },
-    mapError: (error) => ({
-      name: "NetworkError",
-      message: "Failed to fetch user",
-      context: { userId },
-      cause: error
-    })
-  });
+    
+    stopRecording(): Result<Blob, RecorderServiceError> {
+      if (!isRecording) {
+        return RecorderServiceErr({
+          message: "Not currently recording", 
+          context: { isRecording },
+          cause: undefined
+        });
+      }
+      
+      isRecording = false;
+      return Ok(new Blob(["audio data"]));
+    }
+  };
 }
 
-const userResult = await fetchUser(1);
-```
+// 3. Export type
+export type RecorderService = ReturnType<typeof createRecorderService>;
 
-### Type Safety with Generics
+// 4. Create singleton instance
+export const RecorderServiceLive = createRecorderService();
+```
 
-When using `trySync` and `tryAsync`, you have two approaches to ensure your `mapError` function returns the correct TaggedError type:
+### Platform-Specific Services
 
-#### Approach 1: Explicit Generics
+For services that need different implementations per platform:
 
-Pass the success type and error type as generic parameters. This approach is clear and explicit about the expected types:
+```typescript
+// types.ts - shared interface
+export type FileService = {
+  readFile(path: string): Promise<Result<string, FileServiceError>>;
+  writeFile(path: string, content: string): Promise<Result<void, FileServiceError>>;
+};
 
-```ts
-// For tryAsync
-async function readConfig(path: string) {
-  return tryAsync<string, FileError>({  // 👈 <SuccessType, ErrorType>
-    try: async () => {
-      const content = await fs.readFile(path, 'utf-8');
-      return content;
+// desktop.ts
+export function createFileServiceDesktop(): FileService {
+  return {
+    async readFile(path) {
+      // Desktop implementation using Node.js APIs
     },
-    mapError: (error) => ({
-      name: "FileError",
-      message: "Failed to read configuration file", 
-      context: { path },
-      cause: error
-    })
-  });
+    async writeFile(path, content) {
+      // Desktop implementation
+    }
+  };
 }
 
-// For trySync
-function parseConfig(content: string) {
-  return trySync<Config, ParseError>({  // 👈 <SuccessType, ErrorType>
-    try: () => {
-      const parsed = JSON.parse(content);
-      validateConfig(parsed); // throws if invalid
-      return parsed as Config;
+// web.ts  
+export function createFileServiceWeb(): FileService {
+  return {
+    async readFile(path) {
+      // Web implementation using File API
     },
-    mapError: (error) => ({
-      name: "ParseError",
-      message: "Invalid configuration format",
-      context: { contentLength: content.length },
-      cause: error
-    })
-  });
+    async writeFile(path, content) {
+      // Web implementation
+    }
+  };
 }
-```
 
-#### Approach 2: Return Type Annotation on mapError
+// index.ts - runtime selection
+export const FileServiceLive = typeof window !== 'undefined' 
+  ? createFileServiceWeb()
+  : createFileServiceDesktop();
+```
 
-Annotate the return type of the `mapError` function. This approach can be cleaner when generics would format awkwardly:
+## Common Use Cases
 
-```ts
-// For tryAsync
-async function saveUser(user: User) {
-  return tryAsync({
-    try: async () => {
-      const result = await db.users.insert(user);
-      return result.id;
-    },
-    mapError: (error): DatabaseError => ({  // 👈 Annotate return type
-      name: "DatabaseError",
-      message: "Failed to save user to database",
-      context: { userId: user.id },
-      cause: error
-    })
-  });
-}
+<details>
+<summary><b>API Route Handler</b></summary>
 
-// For trySync
-function validateEmail(email: string) {
-  return trySync({
-    try: () => {
-      if (!email.includes('@')) {
-        throw new Error('Invalid email format');
-      }
-      return email.toLowerCase();
-    },
-    mapError: (error): ValidationError => ({  // 👈 Annotate return type
-      name: "ValidationError",
-      message: "Email validation failed",
-      context: { email },
-      cause: error
-    })
-  });
+```typescript
+export async function GET(request: Request) {
+  const result = await userService.getUser(params.id);
+  
+  if (result.error) {
+    switch (result.error.name) {
+      case "UserNotFoundError":
+        return new Response("Not found", { status: 404 });
+      case "DatabaseError":
+        return new Response("Server error", { status: 500 });
+    }
+  }
+  
+  return Response.json(result.data);
 }
 ```
+</details>
 
-**Key points:**
-- Both approaches ensure `mapError` returns your exact TaggedError type
-- Avoid using `as const` - always map to proper TaggedError objects
-- Choose explicit generics for clarity, or return type annotation for brevity
-- The important thing is ensuring type safety for your error handling
-
----
-
-## Partitioning Results
-
-When working with multiple asynchronous operations that return `Result` objects, you'll often need to separate the successful results from the failed ones. The `partitionResults` utility function makes this easy by splitting an array of Results into two separate arrays.
-
-### When to Use `partitionResults`
+<details>
+<summary><b>Form Validation</b></summary>
 
-Use `partitionResults` when you have:
-- Multiple async operations that might fail independently
-- A need to handle all errors collectively
-- Successful results that should be processed together
-
-### Common Pattern: Map → Filter → Partition
-
-This is a typical workflow when processing multiple commands or operations:
-
-```ts
-import { partitionResults } from "wellcrafted/result";
-
-// Example: Processing multiple commands that might fail
-const results = await Promise.all(
-  commands
-    .map((command) => {
-      const config = getCommandConfig(command.id);
-      if (!config) return; // Early return if config missing
-      return executeCommand({ command, config });
-    })
-    .filter((result) => result !== undefined) // Remove undefined values
-);
-
-const { oks, errs } = partitionResults(results);
-
-// Handle all errors at once
-if (errs.length > 0) {
-  const errorMessages = errs.map(({ error }) => error.message).join(', ');
-  showNotification(`${errs.length} operations failed: ${errorMessages}`);
-  return;
+```typescript
+function validateLoginForm(data: unknown): Result<LoginData, FormError> {
+  const errors: Record<string, string[]> = {};
+  
+  if (!isValidEmail(data?.email)) {
+    errors.email = ["Invalid email format"];
+  }
+  
+  if (Object.keys(errors).length > 0) {
+    return Err({
+      name: "FormError",
+      message: "Validation failed",
+      context: { fields: errors },
+      cause: undefined
+    });
+  }
+  
+  return Ok(data as LoginData);
 }
-
-return oks.map(ok => ok.data); // Return processed content
 ```
+</details>
 
-### Real-World Example: Batch File Processing
-
-```ts
-import { tryAsync, partitionResults } from "wellcrafted/result";
-import { type TaggedError } from "wellcrafted/error";
-import * as fs from 'fs/promises';
-
-type FileError = TaggedError<"FileError">;
-
-async function processFiles(filePaths: string[]) {
-  // Map each file path to a Result-returning operation
-  const results = await Promise.all(
-    filePaths
-      .map((path) => {
-        if (!path.endsWith('.txt')) return; // Skip non-text files
-        return tryAsync<string, FileError>({
-          try: async () => {
-            const content = await fs.readFile(path, 'utf-8');
-            return content.toUpperCase(); // Process the content
-          },
-          mapError: (error) => ({
-            name: "FileError",
-            message: "Failed to process file",
-            context: { path },
-            cause: error
-          })
-        });
-      })
-      .filter((result) => result !== undefined)
-  );
-
-  const { oks, errs } = partitionResults(results);
+<details>
+<summary><b>React Hook</b></summary>
 
-  // Report all errors together
-  if (errs.length > 0) {
-    console.error(`Failed to process ${errs.length} files:`);
-    errs.forEach(err => {
-      console.error(`- ${err.error.context.path}: ${err.error.message}`);
+```typescript
+function useUser(id: number) {
+  const [state, setState] = useState<{
+    loading: boolean;
+    user?: User;
+    error?: ApiError;
+  }>({ loading: true });
+
+  useEffect(() => {
+    fetchUser(id).then(result => {
+      if (result.error) {
+        setState({ loading: false, error: result.error });
+      } else {
+        setState({ loading: false, user: result.data });
+      }
     });
-  }
+  }, [id]);
 
-  // Process successful results
-  if (oks.length > 0) {
-    console.log(`Successfully processed ${oks.length} files`);
-    return oks.map(ok => ok.data); // Return processed content
-  }
-
-  return [];
+  return state;
 }
 ```
+</details>
 
-### Key Benefits
-
-1. **Batch Error Handling**: Instead of stopping at the first error, you can collect all failures and present them together
-2. **Type Safety**: The returned `oks` and `errs` arrays are properly typed as `Ok<T>[]` and `Err<E>[]` respectively
-3. **Clean Separation**: Successful and failed operations are cleanly separated for different handling logic
-4. **Composability**: Works seamlessly with the map → filter → partition pattern for complex data processing
+## Comparison with Alternatives
 
----
+| | wellcrafted | fp-ts | Effect | neverthrow |
+|---|---|---|---|---|
+| **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 |
 
 ## API Reference
 
-### Quick Reference Table
-
-| Function | Purpose | Example |
-|----------|---------|---------|
-| `Ok(data)` | Create success result | `Ok("hello")` |
-| `Err(error)` | Create failure result | `Err("failed")` |
-| `isOk(result)` | Check if success | `if (isOk(res)) { ... }` |
-| `isErr(result)` | Check if failure | `if (isErr(res)) { ... }` |
-| `trySync()` | Wrap throwing function | `trySync({ try: () => JSON.parse(str) })` |
-| `tryAsync()` | Wrap async throwing function | `tryAsync({ try: () => fetch(url) })` |
-| `partitionResults()` | Split Results into oks/errs | `const { oks, errs } = partitionResults(results)` |
-
-### Detailed API
-
-#### Types
-- **`Result<T, E>`**: The core union type, representing `Ok<T> | Err<E>`.
-- **`Ok<T>`**: Represents a success. Contains `{ data: T; error: null; }`.
-- **`Err<E>`**: Represents a failure. Contains `{ data: null; error: E; }`.
-- **`BaseError` / `TaggedError<T>`**: Helpers for creating a structured error system.
-
-#### Core Result Functions
-- **`Ok(data)`**: Creates a success `Result`.
-- **`Err(error)`**: Creates a failure `Result`.
-- **`isOk(result)`**: Type guard. Returns `true` if the result is an `Ok` variant.
-- **`isErr(result)`**: Type guard. Returns `true` if the result is an `Err` variant.
-- **`unwrap(result)`**: Unwraps a `Result`, returning data on `Ok` or throwing error on `Err`.
-- **`resolve(value)`**: Resolves a value that may or may not be a `Result`, returning the final value or throwing on `Err`.
-- **`isResult(value)`**: Type guard. Returns `true` if a value has the shape of a `Result`.
-
-#### Async/Sync Wrappers
-- **`trySync({ try, mapError })`**: Wraps a synchronous function that may throw.
-- **`tryAsync({ try, mapError })`**: Wraps an asynchronous function that may throw or reject.
-
-#### Error Utilities
-- **`extractErrorMessage(error)`**: Safely extracts a string message from any error value.
-
-#### Utility Functions
-- **`partitionResults(results)`**: Partitions an array of Results into separate arrays of `Ok` and `Err` variants.
-
----
-
-## Design Philosophy
-
-This library is built on a set of core principles designed to create a robust, predictable, and developer-friendly experience. Understanding these principles will help you get the most out of the library and see why its API is designed the way it is.
-
-### 1. Embrace JavaScript Primitives
-
-A fundamental disagreement we have with some otherwise excellent libraries is the idea that JavaScript's core abstractions need to be completely reinvented. While we have immense respect for the power and type-level ingenuity of ecosystems like Effect-TS, we believe the cost of onboarding developers to an entirely new programming paradigm (like generators for async control flow) is too high for most projects.
-
-This library is built on the philosophy of leaning into JavaScript's native primitives whenever they are "good enough." We prefer to build on the familiar foundations of `async/await`, `Promise`, and standard union types (`T | null`) because they are already well-understood by the vast majority of TypeScript developers. This drastically reduces the learning curve and makes the library easy to adopt incrementally.
+### Result Functions
+- **`Ok(data)`** - Create success result
+- **`Err(error)`** - Create failure result  
+- **`isOk(result)`** - Type guard for success
+- **`isErr(result)`** - Type guard for failure
+- **`trySync(options)`** - Wrap throwing function
+- **`tryAsync(options)`** - Wrap async function
+- **`partitionResults(results)`** - Split array into oks/errs
 
-We only introduce new abstractions where JavaScript has a clear and significant weakness. In our view, the two biggest pain points in modern TypeScript are:
-1.  **Error Handling**: The imperative nature of `try/catch` and the non-serializable, class-based `Error` object.
-2.  **Data Validation**: Ensuring that `unknown` data conforms to a known type at runtime.
+### 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
 
-This library provides `Result` to solve the first problem. It intentionally omits an `Option` type because native features like optional chaining (`?.`) and nullish coalescing (`??`) provide excellent and familiar ergonomics for handling optional values.
+### Types
+- **`Result<T, E>`** - Union of Ok<T> | Err<E>
+- **`TaggedError<T>`** - Structured error type
+- **`Brand<T, B>`** - Branded type wrapper
 
-### 2. Prioritize Ergonomics and Pragmatism
+## Learn More
 
-Flowing from the first principle, our API design prioritizes developer experience. This is most evident in our choice of the `{ data, error }` shape for the `Result` type. The ability to destructure `const { data, error } = ...` is a clean, direct, and pragmatic pattern that is already familiar to developers using popular libraries like Supabase and Astro Actions. We chose this pattern for its superior ergonomics, even if other patterns might be considered more "academically pure."
+- 📖 [Full Documentation](https://github.com/your-repo/wellcrafted/wiki)
+- 🚀 [Examples](https://github.com/your-repo/wellcrafted/tree/main/examples)
+- 💬 [Discussions](https://github.com/your-repo/wellcrafted/discussions)
 
-### 3. Lightweight, Zero-Dependency, and Tree-Shakable
+## License
 
-This library is designed to be as lightweight as possible. It ships with **zero runtime dependencies**, meaning it won't add any extra weight to your `node_modules` folder or your final bundle.
-
-Every function is exported as a pure, standalone module, making the entire library **tree-shakable**. If you only use the `Result` type and the `isOk` function, the rest of the library's code won't be included in your application's build.
-
-We believe a library should have a focused scope and not be overwhelming. While comprehensive ecosystems like Effect-TS are incredibly powerful, their scope can be daunting. This library aims to solve the specific and critical problem of type-safe error handling without pulling in a large, all-encompassing framework. It's a small tool that does one job well.
-
-### 4. Serialization-First
-
-A core requirement of this library is that all of its data structures, especially errors, must be reliably serializable. They need to behave identically whether you are passing them between functions, sending them over a network (HTTP), or passing them to a web worker. This is why the library fundamentally avoids classes for its error-handling system and instead promotes plain objects.
-
-### 5. Opinionated yet Flexible
-
-This library is opinionated in that it provides a clear, recommended path for best practices. We believe that a degree of standardization leads to more maintainable and predictable codebases. However, these opinions are not enforced at a technical level. The core `Result` type is deliberately decoupled from the error system, meaning you are free to use a different error implementation if your project requires it.
-
-## Inspirations and Relationship to Effect-TS
-
-This library's approach is heavily inspired by the powerful concepts pioneered by the **[Effect-TS](https://github.com/Effect-TS/effect)** ecosystem. Effect has indelibly shaped our thinking on how to structure services, handle errors, and compose applications in a type-safe way.
-
-However, this library represents a different set of trade-offs and priorities, based on a few key disagreements with the Effect-TS approach:
-
-1.  **Familiarity Over Novelty**: While we agree that Promises can be a flawed abstraction, we believe the cost of replacing them entirely is too high for most teams. Effect introduces a new, powerful, but unfamiliar execution model based on generators (`yield`), which requires a significant investment to learn. This library chooses to embrace the familiar patterns of `async/await` and Promises, even with their imperfections, to ensure a gentle learning curve. The goal is to provide 80% of the benefit with 20% of the learning curve.
-
-2.  **Simplicity and Lightweight Integration**: We aim for this library to be as lightweight as possible, easy to adopt incrementally, and simple to integrate with other tools. It is not an all-encompassing application framework but rather a focused tool to solve the specific problem of `Result`-based error handling.
-
-That said, the influence of Effect is clear. Functions like `trySync` and `tryAsync` are directly inspired by similar utilities in Effect. The core difference is that we aim to apply these powerful concepts on top of familiar JavaScript primitives, rather than creating a new ecosystem around them. This philosophy also informs our decision to omit an `Option<T>` type, as we believe that native TypeScript features (`T | null`, optional chaining, and nullish coalescing) are "good enough" and more idiomatic for the majority of use cases.
+MIT
 
 ---
 
-## FAQ
-
-### Why `{ data, error }` instead of a boolean flag like `{ ok: boolean, ... }`?
-
-Some libraries use a boolean flag for their discriminated union, like `{ ok: true, data: T } | { ok: false, error: E }`. While a valid pattern, we chose the `{ data, error }` shape for two main reasons:
-
-1.  **Ergonomics and Familiarity**: The destructuring pattern `const { data, error } = operation()` is clean and will feel familiar to developers using modern libraries like Supabase and Astro Actions. It provides immediate access to the inner values without an extra layer of property access. Checking a boolean flag first (`if (result.ok)`) and then accessing the value (`result.data`) is slightly more verbose.
-
-2.  **Lack of Standardization**: The boolean flag approach isn't standardized. Zod's `.safeParse`, for example, returns `{ success: boolean, ... }`. By adopting the `{ data, error }` pattern, we align with a simple, common, and intuitive structure for handling success and failure states in modern JavaScript.
-
-**Note**: The `{ data, error }` pattern is also a discriminated union—you can use either `data` or `error` as the discriminant key and check if either of them is null. This creates the same type-narrowing benefits as a boolean flag while maintaining cleaner destructuring ergonomics.
-
-### What's the difference between an `Err` variant and an `error` value?
-
-This is a key distinction in the library's terminology:
-
--   **`Err<E>` (The Variant/Container)**: This is one of the two possible "shapes" of a `Result` object. It's the wrapper itself, whose structure is `{ data: null, error: E }`. You can think of it as the box that signifies a failure.
-
--   **`error` (The Value/Payload)**: This is the actual *value* inside the `Err` container. It is the content of the `error` property on the `Err` object. This is the piece of data that describes what went wrong, and its type is `E`.
-
-When you use the `isErr()` type guard, you are checking if a `Result` is the `Err` variant. Once that check passes, you can then access the `.error` property to get the error value.
-
-### Why doesn't this library include an `Option<T>` type?
-
-An `Option<T>` type (sometimes called `Maybe`) is common in other languages to represent a value that might be missing. However, we've intentionally omitted it because **modern JavaScript and TypeScript already have excellent, first-class support for handling potentially missing values.**
-
-A custom `Option<T>` type would add a layer of abstraction that is largely unnecessary. Instead, you can and should use:
-
-1.  **Union Types with `null`**: Simply type your value as `T | null`. This is the idiomatic way to represent an optional value in TypeScript.
-
-2.  **Optional Chaining (`?.`)**: Safely access nested properties of an object that might be null or undefined.
-    ```ts
-    const street = user?.address?.street; // Returns undefined if user or address is null/undefined
-    ```
-
-3.  **Nullish Coalescing (`??`)**: Provide a default value for a `null` or `undefined` expression.
-    ```ts
-    const displayName = user.name ?? "Guest";
-    ```
-
-These built-in language features provide better ergonomics and are more familiar to JavaScript developers than a custom `Option` type would be. This library focuses on solving for `Result`, where the language does not have a built-in equivalent.
+Made with ❤️ by developers who believe error handling should be delightful.