Merge pull request #2 from cometloop/feat/docs

feat: add withObjects function; doc updates

Author: cometloop

README.md

@@ -2,7 +2,7 @@
 title: Comparison with try-catch
 ---
 
-See how `safe` compares to traditional try-catch error handling. {% .lead %}
+See how `@cometloop/safe` compares to traditional try-catch error handling — and how `createSafe` keeps call sites as clean as possible. {% .lead %}
 
 ---
 
@@ -43,18 +43,35 @@ async function processOrder(orderId: string) {
 
 ---
 
-## With safe utilities
+## With createSafe (recommended)
+
+The best way to use `@cometloop/safe` is with `createSafe`. Configure error handling once, wrap your functions, and the call site looks like normal code:
+
+```ts
+// Configure once — in a shared module like lib/safe.ts
+const appSafe = createSafe({
+  parseError: (e) => ({
+    code: e instanceof Error ? e.name : 'UNKNOWN',
+    message: e instanceof Error ? e.message : String(e),
+  }),
+  defaultError: { code: 'UNKNOWN', message: 'Unknown error' },
+})
+
+// Wrap functions once
+const safeFetchOrder = appSafe.wrapAsync(fetchOrder)
+const safeProcessPayment = appSafe.wrapAsync(processPayment)
+```
 
 ```ts
-// Benefits: typed errors, flat structure, explicit handling
+// Call site — clean and minimal, just like normal function calls
 async function processOrder(orderId: string) {
-  const [order, fetchError] = await safe.async(() => fetchOrder(orderId))
+  const [order, fetchError] = await safeFetchOrder(orderId)
   if (fetchError) {
     console.error('Failed to fetch order:', fetchError.message)
     return null
   }
 
-  const [payment, paymentError] = await safe.async(() => processPayment(order))
+  const [payment, paymentError] = await safeProcessPayment(order)
   if (paymentError) {
     console.error('Payment failed:', paymentError.message)
     return null
@@ -64,8 +81,9 @@ async function processOrder(orderId: string) {
 }
 ```
 
-**Benefits of safe:**
+**Benefits:**
 
+- **Clean call sites** — looks like calling a normal function, no extra noise
 - Errors are **typed** — TypeScript knows the exact error shape
 - **Flat structure** — no nesting, reads top to bottom
 - **Explicit** — errors are part of the return type, impossible to forget
@@ -97,17 +115,18 @@ if (result === null) {
 }
 ```
 
-**safe.wrap:**
+**createSafe + wrap:**
 
 ```ts
-const safeDivide = safe.wrap((a: number, b: number) => {
+const safeDivide = appSafe.wrap((a: number, b: number) => {
   if (b === 0) throw new Error('Division by zero')
   return a / b
 })
 
+// Call site is clean — just a function call
 const [result, error] = safeDivide(10, 2)
 if (error) {
-  // Unambiguous: this was an error
+  // Unambiguous: this was an error, fully typed
   console.error(error.message)
 }
 ```
@@ -134,34 +153,21 @@ async function getUser(id: string) {
 }
 ```
 
-**safe.async:**
+**createSafe + wrapAsync:**
 
 ```ts
-type ApiError = {
-  type: 'NETWORK' | 'HTTP' | 'PARSE' | 'UNKNOWN'
-  message: string
-}
-
-const getUser = async (id: string) => {
-  const [user, error] = await safe.async(
-    async () => {
-      const response = await fetch(`/api/users/${id}`)
-      if (!response.ok) throw new Error(`HTTP ${response.status}`)
-      return response.json()
-    },
-    (e): ApiError => ({
-      type: e instanceof TypeError ? 'NETWORK' : 'HTTP',
-      message: e instanceof Error ? e.message : 'Unknown error',
-    })
-  )
-
-  if (error) {
-    // error is fully typed as ApiError
-    console.error(`${error.type}: ${error.message}`)
-    return null
-  }
+// Error mapping is configured once in createSafe — not repeated here
+const safeGetUser = appSafe.wrapAsync(async (id: string) => {
+  const response = await fetch(`/api/users/${id}`)
+  if (!response.ok) throw new Error(`HTTP ${response.status}`)
+  return response.json()
+})
 
-  return user
+// Call site is minimal — just call the function
+const [user, error] = await safeGetUser('42')
+if (error) {
+  // error is fully typed — no `unknown`, no manual narrowing
+  console.error(`${error.code}: ${error.message}`)
 }
 ```
 

apps/documentation-website/src/app/docs/comparison/page.md

@@ -17,7 +17,6 @@ import * as Sentry from '@sentry/node'
 type AppError = {
   code: string
   message: string
-  timestamp: Date
   requestId?: string
   stack?: string
 }
@@ -28,14 +27,12 @@ export const appSafe = createSafe({
     return {
       code: error.name === 'Error' ? 'UNKNOWN_ERROR' : error.name,
       message: error.message,
-      timestamp: new Date(),
       stack: process.env.NODE_ENV === 'development' ? error.stack : undefined,
     }
   },
   defaultError: {
     code: 'UNKNOWN_ERROR',
     message: 'An unknown error occurred',
-    timestamp: new Date(),
   },
   onSuccess: (result) => {
     metrics.increment('operation.success')
@@ -44,7 +41,6 @@ export const appSafe = createSafe({
     logger.error('Operation failed', {
       code: error.code,
       message: error.message,
-      timestamp: error.timestamp,
     })
 
     Sentry.captureException(new Error(error.message), {
@@ -55,9 +51,12 @@ export const appSafe = createSafe({
   },
 })
 
-// Usage throughout your application
-const [user, error] = await appSafe.async(() => userService.findById(id))
-const [config, parseError] = appSafe.sync(() => JSON.parse(configString))
+// Wrap functions for reuse throughout your application
+const safeFindUser = appSafe.wrapAsync(userService.findById.bind(userService))
+const safeJsonParse = appSafe.wrap(JSON.parse)
+
+const [user, error] = await safeFindUser(id)
+const [config, parseError] = safeJsonParse(configString)
 ```
 
 ---
@@ -352,7 +351,6 @@ type TenantError = {
   code: string
   message: string
   tenantId: string
-  timestamp: Date
 }
 
 function createTenantSafe(tenantId: string): SafeInstance<TenantError> {
@@ -361,13 +359,11 @@ function createTenantSafe(tenantId: string): SafeInstance<TenantError> {
       code: e instanceof Error ? e.name : 'UNKNOWN',
       message: e instanceof Error ? e.message : String(e),
       tenantId,
-      timestamp: new Date(),
     }),
     defaultError: {
       code: 'UNKNOWN',
       message: 'Unknown error',
       tenantId,
-      timestamp: new Date(),
     },
     onSuccess: () => {
       metrics.increment('tenant.operation.success', { tenantId })
@@ -393,17 +389,18 @@ class TenantContext {
     this.safe = createTenantSafe(tenantId)
   }
 
-  getUsers = () =>
-    this.safe.async(() =>
-      db.users.findMany({ where: { tenantId: this.tenantId } })
-    )
+  private async _getUsers() {
+    return db.users.findMany({ where: { tenantId: this.tenantId } })
+  }
 
-  createDocument = (data: CreateDocumentDto) =>
-    this.safe.async(() =>
-      db.documents.create({
-        data: { ...data, tenantId: this.tenantId },
-      })
-    )
+  private async _createDocument(data: CreateDocumentDto) {
+    return db.documents.create({
+      data: { ...data, tenantId: this.tenantId },
+    })
+  }
+
+  getUsers = this.safe.wrapAsync(this._getUsers.bind(this))
+  createDocument = this.safe.wrapAsync(this._createDocument.bind(this))
 }
 
 // Middleware creates tenant context per request

apps/documentation-website/src/app/docs/create-safe-examples/page.md

@@ -2,15 +2,18 @@
 title: createSafe
 ---
 
-Creates a pre-configured safe instance with a fixed error mapping function and optional default hooks. The error type is automatically inferred from the `parseError` return type. {% .lead %}
+The recommended way to use `@cometloop/safe`. Creates a pre-configured safe instance so your call sites stay clean and minimal — just a normal function call, no extra configuration. {% .lead %}
 
 ---
 
 ## When to use createSafe
 
-- You want consistent error mapping across multiple operations
-- You need default logging/analytics hooks for all operations
-- You want to avoid repeating `parseError` on every call
+`createSafe` is the best way to use this library. The goal is simple: **move all error handling configuration out of your call sites** so they read like normal function calls.
+
+- You want call sites that are clean and minimal — no inline `parseError`, no options objects
+- You want consistent error mapping across multiple operations without repeating yourself
+- You need default logging/analytics hooks that run automatically
+- You want to wrap functions once and call them everywhere like any other function
 
 ---
 
@@ -27,6 +30,7 @@ type CreateSafeConfig<E, TResult = never> = {
   parseResult?: (result: unknown) => TResult // Optional: transforms successful results
   onSuccess?: (result: unknown) => void    // Optional: called on every success
   onError?: (error: E) => void             // Optional: called on every error
+  onSettled?: (result: unknown, error: E | null) => void // Optional: called after success or error
   onRetry?: (error: E, attempt: number) => void // Optional: called before each retry
   retry?: RetryConfig                      // Optional: default retry config (async only)
   abortAfter?: number                      // Optional: default timeout (async only)
@@ -38,38 +42,36 @@ type CreateSafeConfig<E, TResult = never> = {
 
 ## Basic usage
 
+Configure once, then every call site is just a function call:
+
 ```ts
 import { createSafe } from '@cometloop/safe'
 
 type AppError = {
   code: string
   message: string
-  timestamp: Date
 }
 
+// All the configuration lives here — once
 const appSafe = createSafe({
   parseError: (e): AppError => ({
     code: 'UNKNOWN_ERROR',
     message: e instanceof Error ? e.message : 'An unknown error occurred',
-    timestamp: new Date(),
   }),
   defaultError: {
     code: 'UNKNOWN_ERROR',
     message: 'An unknown error occurred',
-    timestamp: new Date(),
   },
 })
 
-// All methods now return AppError on failure
-const [data, error] = appSafe.sync(() => JSON.parse(jsonString))
-if (error) {
-  console.error(error.code, error.message) // error is typed as AppError
-}
+// Wrap your functions
+const safeJsonParse = appSafe.wrap(JSON.parse)
+const safeFetchUser = appSafe.wrapAsync(fetchUser)
 
-const [user, err] = await appSafe.async(() => fetchUser(id))
-if (err) {
-  console.error(err.code) // err is typed as AppError
-}
+// Call sites are clean — just like calling a normal function
+const [data, error] = safeJsonParse(jsonString)
+const [user, err] = await safeFetchUser(id)
+// error and err are fully typed as AppError
 ```
 
 ---
@@ -83,12 +85,10 @@ const loggingSafe = createSafe({
   parseError: (e): AppError => ({
     code: 'ERROR',
     message: e instanceof Error ? e.message : String(e),
-    timestamp: new Date(),
   }),
   defaultError: {
     code: 'ERROR',
     message: 'An unknown error occurred',
-    timestamp: new Date(),
   },
   onSuccess: (result) => {
     console.log('Operation succeeded:', result)
@@ -308,5 +308,5 @@ appSafe.sync(
 ```
 
 {% callout title="SafeInstance type" type="note" %}
-The returned instance has `sync`, `async`, `wrap`, and `wrapAsync` methods — all pre-configured with the error type. See [Types](/docs/types) for the full `SafeInstance<E>` definition.
+The returned instance has `sync`, `async`, `wrap`, `wrapAsync`, `all`, and `allSettled` methods — all pre-configured with the error type. The `all` and `allSettled` methods accept raw async functions (not pre-wrapped `Promise<SafeResult>` entries). See [Types](/docs/types) for the full `SafeInstance<E>` definition.
 {% /callout %}

apps/documentation-website/src/app/docs/create-safe/page.md

@@ -115,14 +115,16 @@ const dbSafe = createSafe({
   parseError: (e) => ({
     code: e instanceof Error ? e.name : 'UNKNOWN',
     message: e instanceof Error ? e.message : String(e),
-    timestamp: new Date(),
   }),
-  defaultError: { code: 'UNKNOWN', message: 'Unknown error', timestamp: new Date() },
+  defaultError: { code: 'UNKNOWN', message: 'Unknown error' },
 })
 
 // All operations use the same error mapper
-const [user, error] = await dbSafe.async(() => db.user.findById(id))
-const [order, error2] = await dbSafe.async(() => db.order.findById(orderId))
+const safeFindUser = dbSafe.wrapAsync(db.user.findById.bind(db.user))
+const safeFindOrder = dbSafe.wrapAsync(db.order.findById.bind(db.order))
+
+const [user, error] = await safeFindUser(id)
+const [order, error2] = await safeFindOrder(orderId)
 ```
 
 {% callout title="TypeScript inference" type="note" %}

apps/documentation-website/src/app/docs/error-mapping/page.md

@@ -159,16 +159,22 @@ const [length, error] = safe.sync(
 
 ### Error handling
 
-If `parseResult` throws, the error is caught and processed through `parseError`. For async operations with retry, a `parseResult` throw counts as a failure and triggers retry logic.
+If `parseResult` throws, the error is routed through the standard error path — just like any error thrown by the wrapped function. It goes through `parseError` (if provided), triggers `onError` and `onSettled`, and returns `[null, error]`.
 
 ```ts
 const [data, error] = safe.sync(
-  () => '{"valid": true}',
-  (e) => ({ code: 'PARSE_ERROR', message: String(e) }),
+  () => 42,
+  (e) => ({ code: 'TRANSFORM_FAILED', message: String(e) }),
   {
-    parseResult: (raw) => JSON.parse(raw),
+    parseResult: (n) => {
+      throw new Error('transform failed')
+    },
+    onError: (err) => {
+      // err is { code: 'TRANSFORM_FAILED', message: 'Error: transform failed' }
+    },
   }
 )
+// data is null, error is { code: 'TRANSFORM_FAILED', message: '...' }
 ```
 
 {% callout title="parseResult vs hooks" type="note" %}