errore 0.12.0 → 0.14.0

package/README.md

@@ -26,6 +26,20 @@ console.log(user.username)  // user is User, fully narrowed
 npm install errore
 ```
 
+## Agent Skill
+
+errore ships with a skill file that teaches AI coding agents the errore convention. Install it with:
+
+```sh
+npx skills add remorses/errore
+```
+
+Then add this to your `AGENTS.md`:
+
+```
+This codebase uses the errore.org convention. ALWAYS read the errore skill before editing any code.
+```
+
 ## Quick Start
 
 Define typed errors with **variable interpolation** and return **Error or Value** directly:
@@ -46,14 +60,12 @@ class DbError extends errore.createTaggedError({
 
 // Function returns Error | Value (no wrapper!)
 async function getUser(id: string): Promise<NotFoundError | DbError | User> {
-  const result = await errore.tryAsync({
-    try: () => db.query(id),
-    catch: e => new DbError({ reason: e.message, cause: e })
-  })
-  
+  const result = await db.query(id)
+    .catch((e) => new DbError({ reason: e.message, cause: e }))
+
   if (result instanceof Error) return result
   if (!result) return new NotFoundError({ id })
-  
+
   return result
 }
 
@@ -84,7 +96,7 @@ import * as errore from 'errore'
 // Base class with shared functionality
 class AppError extends Error {
   statusCode: number = 500
-  
+
   toResponse() {
     return { error: this.message, code: this.statusCode }
   }
@@ -105,7 +117,7 @@ class ValidationError extends errore.createTaggedError({
 
 class UnauthorizedError extends errore.createTaggedError({
   name: 'UnauthorizedError',
-  message: '$message',
+
   extends: AppError
 }) {}
 
@@ -118,28 +130,28 @@ async function updateUser(
   if (!session) {
     return new UnauthorizedError({ message: 'Not logged in' })
   }
-  
+
   const user = await db.users.find(userId)
   if (!user) {
     return new NotFoundError({ resource: `User ${userId}` })
   }
-  
+
   if (data.email && !isValidEmail(data.email)) {
     return new ValidationError({ field: 'email', reason: 'Invalid email format' })
   }
-  
+
   return db.users.update(userId, data)
 }
 
 // API handler
 app.post('/users/:id', async (req, res) => {
   const result = await updateUser(req.params.id, req.body)
-  
+
   if (result instanceof Error) {
     // All errors have toResponse() from AppError base
     return res.status(result.statusCode).json(result.toResponse())
   }
-  
+
   return res.json(result)
 })
 ```
@@ -172,6 +184,13 @@ class EmptyError extends errore.createTaggedError({
 }) {}
 new EmptyError()  // no args required
 
+// Message omitted — caller provides it at construction time
+class GenericError extends errore.createTaggedError({
+  name: 'GenericError',
+}) {}
+new GenericError({ message: 'caller decides the message' })
+// fingerprint is stable regardless of what message is passed
+
 // With cause for error chaining
 class WrapperError extends errore.createTaggedError({
   name: 'WrapperError',
@@ -195,6 +214,8 @@ err.statusCode  // 500 (inherited from AppError)
 err instanceof AppError  // true
 ```
 
+**Reserved variable names:** `$_tag`, `$name`, `$stack`, `$cause` cannot be used in message templates — they conflict with Error internals.
+
 ### Error Wrapping and Context
 
 Wrap errors with additional context while **preserving the original error** via `cause`:
@@ -203,11 +224,11 @@ Wrap errors with additional context while **preserving the original error** via
 // Wrap with context, preserve original in cause
 async function processUser(id: string): Promise<ServiceError | ProcessedUser> {
   const user = await getUser(id)  // returns NotFoundError | User
-  
+
   if (user instanceof Error) {
     return new ServiceError({ id, cause: user })
   }
-  
+
   return process(user)
 }
 
@@ -215,7 +236,7 @@ async function processUser(id: string): Promise<ServiceError | ProcessedUser> {
 const result = await processUser('123')
 if (result instanceof Error) {
   console.log(result.message)  // "Failed to process user 123"
-  
+
   if (result.cause instanceof NotFoundError) {
     console.log(result.cause.id)  // access original error's properties
   }
@@ -283,9 +304,9 @@ This solves the problem where `result.cause instanceof MyError` only checks one
 
 ```ts
 // A -> B -> C chain
-const c = new DbError({ message: 'connection reset' })
+const c = new DbError({ reason: 'connection reset' })
 const b = new ServiceError({ id: '123', cause: c })
-const a = new ApiError({ message: 'request failed', cause: b })
+const a = new NotFoundError({ id: '456', cause: b })
 
 // Manual check only finds B
 a.cause instanceof DbError  // false — only checks one level
@@ -355,10 +376,11 @@ const parsed = errore.try({
   catch: e => new ParseError({ reason: e.message, cause: e })
 })
 
-// Async
-const response = await errore.tryAsync(() => fetch(url))
+// Async — prefer .catch() for promises (no wrapper needed)
+const response = await fetch(url)
+  .catch((e) => new NetworkError({ url, cause: e }))
 
-// Async - with custom error
+// Async — errore.tryAsync also works, but .catch() is preferred
 const response = await errore.tryAsync({
   try: () => fetch(url),
   catch: e => new NetworkError({ url, cause: e })
@@ -366,6 +388,8 @@ const response = await errore.tryAsync({
 ```
 
 > **Best practices for `try` / `tryAsync`:**
+> - **For async code, prefer `.catch()`** — `promise.catch((e) => new MyError({ cause: e }))` is simpler and avoids the wrapper. `errore.tryAsync` still works but `.catch()` is the idiomatic choice.
+> - **Use `errore.try` for sync code** — there's no equivalent of `.catch()` for synchronous throwing calls, so `errore.try(() => JSON.parse(input))` is the right tool.
 > - **Use as low as possible in the call stack** — only at boundaries with uncontrolled dependencies (third-party libs, `JSON.parse`, `fetch`, file I/O). Your own functions should return errors as values, never throw.
 > - **Keep the callback minimal** — wrap only the single throwing call, not your business logic. The `try` callback should be a one-liner.
 > - **Always prefer `errore.try` over `errore.tryFn`** — they are the same function, but `try` is the canonical name.
@@ -764,7 +788,7 @@ if (user instanceof Error) return user
 console.log(user.name)
 ```
 
-The `errore` package just provides conveniences: `createTaggedError` for less boilerplate, `matchError` for exhaustive pattern matching, `tryAsync` for catching exceptions. But the core pattern—**errors as union types**—works with zero dependencies.
+The `errore` package just provides conveniences: `createTaggedError` for less boilerplate, `matchError` for exhaustive pattern matching, `try` for catching sync exceptions (and `.catch()` for async promises). But the core pattern—**errors as union types**—works with zero dependencies.
 
 ### Perfect for Libraries