errore 0.2.0 → 0.4.0

package/README.md

@@ -125,6 +125,69 @@ const posts = andThen(user, u => fetchPosts(u.id))
 const logged = tap(user, u => console.log('Got user:', u.name))
 ```
 
+### Composing Operations
+
+Chain multiple operations together:
+
+```ts
+import { map, andThen, mapError, isError } from 'errore'
+
+// Define operations that can fail
+function parseNumber(s: string): ValidationError | number { ... }
+function validatePositive(n: number): ValidationError | number { ... }
+function divide(a: number, b: number): DivisionError | number { ... }
+
+// Compose with nested calls
+const result = andThen(
+  andThen(parseNumber(input), validatePositive),
+  n => divide(100, n)
+)
+
+// Or step by step (often clearer)
+function calculate(input: string): ValidationError | DivisionError | number {
+  const parsed = parseNumber(input)
+  if (isError(parsed)) return parsed
+
+  const validated = validatePositive(parsed)
+  if (isError(validated)) return validated
+
+  return divide(100, validated)
+}
+
+// Transform errors at the end
+const appResult = mapError(
+  calculate(userInput),
+  e => new AppError({ source: e._tag, message: e.message })
+)
+```
+
+Real-world async composition:
+
+```ts
+async function processOrder(orderId: string): Promise<OrderError | Receipt> {
+  const order = await fetchOrder(orderId)
+  if (isError(order)) return order
+
+  const validated = validateOrder(order)
+  if (isError(validated)) return validated
+
+  const payment = await processPayment(validated)
+  if (isError(payment)) return payment
+
+  return generateReceipt(payment)
+}
+
+// Caller gets union of all possible errors
+const receipt = await processOrder('123')
+if (isError(receipt)) {
+  matchError(receipt, {
+    NotFoundError: e => `Order ${e.id} not found`,
+    ValidationError: e => `Invalid: ${e.field}`,
+    PaymentError: e => `Payment failed: ${e.reason}`,
+  })
+}
+```
+
 ### Extraction
 
 ```ts
@@ -201,6 +264,96 @@ This works because:
 2. Custom error classes extend `Error`
 3. After an `instanceof Error` check, TS excludes all Error subtypes
 
+## Result + Option Combined: `Error | T | null`
+
+One of errore's best features: you can naturally combine error handling with optional values. No wrapper nesting needed!
+
+In Rust, you'd need `Result<Option<T>, E>` or `Option<Result<T, E>>` and worry about the order. Here it's just a union:
+
+```ts
+// Result + Option in one natural type
+function findUser(id: string): NotFoundError | User | null {
+  if (id === 'bad') return new NotFoundError({ id })
+  if (id === 'missing') return null
+  return { id, name: 'Alice' }
+}
+
+const user = findUser('123')
+
+// Handle error first
+if (isError(user)) {
+  return user.message  // TypeScript: user is NotFoundError
+}
+
+// Handle null/missing case - use ?. and ?? naturally!
+const name = user?.name ?? 'Anonymous'
+
+// Or check explicitly
+if (user === null) {
+  return 'User not found'
+}
+
+// TypeScript knows: user is User
+console.log(user.name)
+```
+
+### Works with `undefined` too
+
+```ts
+function lookup(key: string): NetworkError | string | undefined {
+  if (key === 'fail') return new NetworkError({ url: '/api', message: 'Failed' })
+  if (key === 'missing') return undefined
+  return 'found-value'
+}
+
+const value = lookup('key')
+
+if (isError(value)) return value
+
+// ?? works naturally with undefined
+const result = value ?? 'default'
+```
+
+### Triple union: `Error | T | null | undefined`
+
+Even this works with full type inference:
+
+```ts
+function query(sql: string): ValidationError | { rows: string[] } | null | undefined {
+  if (sql === 'invalid') return new ValidationError({ field: 'sql', message: 'Bad' })
+  if (sql === 'empty') return null      // explicitly no data
+  if (sql === 'no-table') return undefined  // table doesn't exist
+  return { rows: ['a', 'b'] }
+}
+
+const result = query('SELECT *')
+
+if (isError(result)) {
+  return result.field  // TypeScript: ValidationError
+}
+
+if (result == null) {
+  return 'no data'  // handles both null and undefined
+}
+
+// TypeScript: { rows: string[] }
+console.log(result.rows)
+```
+
+### Why this is better than Rust/Zig
+
+| Language | Result + Option | Order matters? |
+|----------|-----------------|----------------|
+| Rust | `Result<Option<T>, E>` or `Option<Result<T, E>>` | Yes, must unwrap in order |
+| Zig | `!?T` (error union + optional) | Yes, specific syntax |
+| **errore** | `Error \| T \| null` | **No!** Check in any order |
+
+With errore:
+- Use `?.` and `??` naturally
+- Check `isError()` or `=== null` in any order
+- No unwrapping ceremony
+- TypeScript infers everything
+
 ## Comparison with Result Types
 
 | Result Pattern | errore |
@@ -210,6 +363,7 @@ This works because:
 | `result.value` | direct access after guard |
 | `result.map(fn)` | `map(result, fn)` |
 | `Result<User, Error>` | `Error \| User` |
+| `Result<Option<T>, E>` | `Error \| T \| null` |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "errore",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Type-safe errors as values for TypeScript. Like Go, but with full type inference.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",