errore 0.12.0 → 0.13.0

package/README.md

@@ -26,6 +26,22 @@ console.log(user.username)  // user is User, fully narrowed
 npm install errore
 ```
 
+## LLM Skill
+
+errore ships with a skill file that teaches AI coding agents (Claude Code, Cursor, Windsurf, etc.) how to use the errore convention correctly. Install it with:
+
+```sh
+npx skills add remorses/errore
+```
+
+Then add this line to your project's `AGENTS.md` or `claude.md`:
+
+```
+This codebase uses the errore.org convention. ALWAYS read the errore skill before editing any code.
+```
+
+This ensures the agent reads the full errore philosophy and rules before making changes to your codebase.
+
 ## Quick Start
 
 Define typed errors with **variable interpolation** and return **Error or Value** directly:
@@ -46,10 +62,8 @@ 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 })
@@ -355,10 +369,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 +381,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 +781,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
 

package/SKILL.md

@@ -28,7 +28,7 @@ console.log(user.name)                  // TypeScript knows: User
 1. Always `import * as errore from 'errore'` — namespace import, never destructure
 2. Never throw for expected failures — return errors as values
 3. Never return `unknown | Error` — the union collapses to `unknown`, breaks narrowing
-4. Avoid `try-catch` for control flow — use `errore.tryAsync` / `errore.try` to convert exceptions to values
+4. Avoid `try-catch` for control flow — use `.catch()` for async boundaries, `errore.try` for sync boundaries
 5. Use `createTaggedError` for domain errors — gives you `_tag`, typed properties, `$variable` interpolation, `cause`, `findCause`, `toJSON`, and fingerprinting
 6. Let TypeScript infer return types — only add explicit annotations when they improve readability (complex unions, public APIs) or when inference produces a wider type than intended
 7. Use `cause` to wrap errors — `new MyError({ ..., cause: originalError })`
@@ -36,9 +36,12 @@ console.log(user.name)                  // TypeScript knows: User
 9. Use `const` + expressions, never `let` + try-catch — ternaries, IIFEs, `instanceof Error`
 10. Use early returns, never nested if-else — check error, return, continue flat
 11. Always include `Error` handler in `matchError` — required fallback for plain Error instances
-12. Use `errore.try` / `errore.tryAsync` 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 code should return errors as values, not throw.
-13. Keep the code inside `errore.try` / `errore.tryAsync` minimal — wrap only the single throwing call, not your business logic. The `try` callback should be a one-liner calling the external dependency.
-14. Always prefer `errore.try` over `errore.tryFn` — they are the same function, but `errore.try` is the canonical name
+12. Use `.catch()` for async boundaries, `errore.try` for sync boundaries — only at the lowest call stack level where you interact with uncontrolled dependencies (third-party libs, `JSON.parse`, `fetch`, file I/O). Your own code should return errors as values, not throw.
+13. Always wrap `.catch()` in a tagged domain error — `.catch((e) => new MyError({ cause: e }))`. The `.catch()` callback receives `any`, but wrapping in a typed error gives the union a concrete type. Never use `.catch((e) => e as Error)` — always wrap.
+14. Always pass `cause` in `.catch()` callbacks — `.catch((e) => new MyError({ cause: e }))`, never `.catch(() => new MyError())`. Without `cause`, the original error is lost and `isAbortError` can't walk the chain to detect aborts. The `cause` preserves the full error chain for debugging and abort detection.
+15. Always prefer `errore.try` over `errore.tryFn` — they are the same function, but `errore.try` is the canonical name
+16. Use `errore.isAbortError` to detect abort errors — never check `error.name === 'AbortError'` manually, because tagged abort errors have their tag as `.name`
+17. Custom abort errors MUST extend `errore.AbortError` — so `isAbortError` detects them in the cause chain even when wrapped by `.catch()`
 
 ## TypeScript Rules
 
@@ -91,13 +94,21 @@ These TypeScript practices complement errore's philosophy:
   const items = results.filter(isTruthy)
   ```
 
-- **`controller.abort(new Error())` not string** — always pass an Error instance to `abort()` so catch blocks receive a real Error with a stack trace, not a string:
+- **`controller.abort()` must use typed errors** — `abort(reason)` throws `reason` as-is. MUST pass a tagged error extending `errore.AbortError`, NEVER `new Error()` or a string — otherwise `isAbortError` can't detect it in the cause chain:
   ```ts
-  // BAD: catch receives a string, not an Error
+  // BAD: plain Error — isAbortError won't recognize it
+  controller.abort(new Error('timeout'))
+
+  // BAD: string — not an Error, breaks instanceof checks
   controller.abort('timeout')
 
-  // GOOD: catch receives an Error instance with cause chain
-  controller.abort(new Error('Request timed out'))
+  // GOOD: tagged error extending AbortError
+  class TimeoutError extends errore.createTaggedError({
+    name: 'TimeoutError',
+    message: 'Request timed out for $operation',
+    extends: errore.AbortError,
+  }) {}
+  controller.abort(new TimeoutError({ operation: 'fetch' }))
   ```
 
 - **Never silently suppress errors in catch blocks** — empty `catch {}` hides failures. With errore you rarely need catch at all, but at boundaries where you must, always handle or log:
@@ -106,10 +117,8 @@ These TypeScript practices complement errore's philosophy:
   try { await sendEmail(user.email) } catch {}
 
   // GOOD: log and continue if non-critical
-  const emailResult = await errore.tryAsync({
-    try: () => sendEmail(user.email),
-    catch: (e) => new EmailError({ email: user.email, cause: e }),
-  })
+  const emailResult = await sendEmail(user.email)
+    .catch((e) => new EmailError({ email: user.email, cause: e }))
   if (emailResult instanceof Error) {
     console.warn('Failed to send email:', emailResult.message)
   }
@@ -229,10 +238,8 @@ async function loadConfig(): Promise<Config> {
 
 // GOOD: flat with errore
 async function loadConfig(): Promise<Config> {
-  const raw = await errore.tryAsync({
-    try: () => fs.readFile('config.json', 'utf-8'),
-    catch: (e) => new ConfigError({ reason: 'Read failed', cause: e }),
-  })
+  const raw = await fs.readFile('config.json', 'utf-8')
+    .catch((e) => new ConfigError({ reason: 'Read failed', cause: e }))
   if (raw instanceof Error) return { port: 3000 }
 
   const parsed = errore.try({
@@ -411,47 +418,43 @@ async function fetchJson(url: string): Promise<any> {
 <!-- good -->
 ```ts
 async function fetchJson<T>(url: string): Promise<NetworkError | T> {
-  const response = await errore.tryAsync({
-    try: () => fetch(url),
-    catch: (e) => new NetworkError({ url, reason: 'Fetch failed', cause: e }),
-  })
+  const response = await fetch(url)
+    .catch((e) => new NetworkError({ url, reason: 'Fetch failed', cause: e }))
   if (response instanceof Error) return response
 
   if (!response.ok) {
     return new NetworkError({ url, reason: `HTTP ${response.status}` })
   }
 
-  const data = await errore.tryAsync({
-    try: () => response.json() as Promise<T>,
-    catch: (e) => new NetworkError({ url, reason: 'Invalid JSON', cause: e }),
-  })
+  const data = await (response.json() as Promise<T>)
+    .catch((e) => new NetworkError({ url, reason: 'Invalid JSON', cause: e }))
   return data
 }
 ```
 
-> `errore.tryAsync` catches exceptions and maps them to typed errors. Use `errore.try` for sync code. The `cause` preserves the original exception.
+> `.catch()` on a promise converts rejections to typed errors. TypeScript infers the union (`Response | NetworkError`) automatically. Use `errore.try` for sync boundaries (`JSON.parse`, etc.).
 
-### try/tryAsync Placement (Boundary Rule)
+### Boundary Rule (.catch for async, errore.try for sync)
 
-`errore.try` and `errore.tryAsync` should only appear at the **lowest level** of your call stack — right at the boundary with code you don't control (third-party libraries, `JSON.parse`, `fetch`, file I/O, etc.). Your own functions should never throw, so they never need to be wrapped in `try`.
+`.catch()` and `errore.try` should only appear at the **lowest level** of your call stack — right at the boundary with code you don't control (third-party libraries, `JSON.parse`, `fetch`, file I/O, etc.). Your own functions should never throw, so they never need `.catch()` or `try`.
 
-Keep the code inside the `try` callback **as small as possible** — ideally a single call to the external dependency. Don't put business logic inside `try`.
+For **async** boundaries: use `.catch((e) => new MyError({ cause: e }))` directly on the promise. TypeScript infers the union automatically.
 
-Always use `errore.try`, never `errore.tryFn` — they are the same function but `errore.try` is the canonical name.
+For **sync** boundaries: use `errore.try({ try: () => ..., catch: (e) => ... })`. Always prefer `errore.try` over `errore.tryFn` — same function, `try` is the canonical name.
+
+The `.catch()` callback receives `any` (Promise rejections are untyped), but wrapping in a typed error gives the union a concrete type — no `as` assertions needed.
 
 <!-- bad -->
 ```ts
-// wrapping too much code inside try — business logic should not be here
+// wrapping too much in a single .catch — business logic should not be here
 async function getUser(id: string): Promise<AppError | User> {
-  return errore.tryAsync({
-    try: async () => {
-      const res = await fetch(`/users/${id}`)
+  return fetch(`/users/${id}`)
+    .then(async (res) => {
       const data = await res.json()
       if (!data.active) throw new Error('inactive')
       return { ...data, displayName: `${data.first} ${data.last}` }
-    },
-    catch: (e) => new AppError({ id, cause: e }),
-  })
+    })
+    .catch((e) => new AppError({ id, cause: e }))
 }
 ```
 
@@ -459,30 +462,24 @@ async function getUser(id: string): Promise<AppError | User> {
 ```ts
 // wrapping your own code that already returns errors as values
 async function processOrder(id: string): Promise<OrderError | Order> {
-  return errore.tryAsync({
-    try: () => createOrder(id),  // createOrder already returns errors!
-    catch: (e) => new OrderError({ id, cause: e }),
-  })
+  return createOrder(id)  // createOrder already returns errors!
+    .catch((e) => new OrderError({ id, cause: e }))
 }
 ```
 
 <!-- good -->
 ```ts
-// try only wraps the external dependency (fetch), nothing else
-async function getUser(id: string): Promise<NetworkError | User> {
-  const res = await errore.tryAsync({
-    try: () => fetch(`/users/${id}`),
-    catch: (e) => new NetworkError({ url: `/users/${id}`, cause: e }),
-  })
+// .catch() only wraps the external dependency, nothing else
+async function getUser(id: string) {
+  const res = await fetch(`/users/${id}`)
+    .catch((e) => new NetworkError({ url: `/users/${id}`, cause: e }))
   if (res instanceof Error) return res
 
-  const data = await errore.tryAsync({
-    try: () => res.json() as Promise<UserPayload>,
-    catch: (e) => new NetworkError({ url: `/users/${id}`, cause: e }),
-  })
+  const data = await (res.json() as Promise<UserPayload>)
+    .catch((e) => new NetworkError({ url: `/users/${id}`, cause: e }))
   if (data instanceof Error) return data
 
-  // business logic is outside try — plain code, not wrapped
+  // business logic is outside .catch — plain code, not wrapped
   if (!data.active) return new InactiveUserError({ id })
   return { ...data, displayName: `${data.first} ${data.last}` }
 }
@@ -490,15 +487,15 @@ async function getUser(id: string): Promise<NetworkError | User> {
 
 <!-- good -->
 ```ts
-// your own functions return errors as values — no try needed
-async function processOrder(id: string): Promise<OrderError | Order> {
+// your own functions return errors as values — no .catch needed
+async function processOrder(id: string) {
   const order = await createOrder(id)
   if (order instanceof Error) return order
   return order
 }
 ```
 
-> Think of `errore.try` / `errore.tryAsync` as the **adapter** between the throwing world (external code) and the errore world (errors as values). Once you've converted exceptions to values at the boundary, everything above is plain `instanceof` checks.
+> Think of `.catch()` and `errore.try` as the **adapter** between the throwing world (external code) and the errore world (errors as values). Once you've converted exceptions to values at the boundary, everything above is plain `instanceof` checks.
 
 ### Optional Values (| null)
 
@@ -514,10 +511,8 @@ async function findUser(email: string): Promise<User | undefined> {
 <!-- good -->
 ```ts
 async function findUser(email: string): Promise<DbError | User | null> {
-  const result = await errore.tryAsync({
-    try: () => db.query(email),
-    catch: (e) => new DbError({ message: 'Query failed', cause: e }),
-  })
+  const result = await db.query(email)
+    .catch((e) => new DbError({ message: 'Query failed', cause: e }))
   if (result instanceof Error) return result
   return result ?? null
 }
@@ -668,17 +663,13 @@ import * as errore from 'errore'
 async function processRequest(id: string): Promise<DbError | Result> {
   await using cleanup = new errore.AsyncDisposableStack()
 
-  const db = await errore.tryAsync({
-    try: () => connectDb(),
-    catch: (e) => new DbError({ cause: e }),
-  })
+  const db = await connectDb()
+    .catch((e) => new DbError({ cause: e }))
   if (db instanceof Error) return db
   cleanup.defer(() => db.close())
 
-  const cache = await errore.tryAsync({
-    try: () => openCache(),
-    catch: (e) => new CacheError({ cause: e }),
-  })
+  const cache = await openCache()
+    .catch((e) => new CacheError({ cause: e }))
   if (cache instanceof Error) return cache
   cleanup.defer(() => cache.flush())
 
@@ -725,10 +716,8 @@ try {
 
 <!-- good -->
 ```ts
-const result = await errore.tryAsync({
-  try: () => externalService.call(id),
-  catch: (e) => new ServiceError({ id, cause: e }),
-})
+const result = await externalService.call(id)
+  .catch((e) => new ServiceError({ id, cause: e }))
 if (result instanceof Error) return result
 return result
 ```
@@ -982,6 +971,56 @@ const user = fetchResult instanceof RecordNotFoundError
 
 > A ternary expression replaces `let` + try-catch + conditional rethrow. One line, no mutation.
 
+### Abort & Cancellation
+
+`controller.abort(reason)` throws `reason` as-is — whatever you pass is what `.catch()` receives. This means you MUST pass a typed error extending `errore.AbortError`, never a plain `Error` or string.
+
+Always use `errore.isAbortError(error)` to detect abort errors. It walks the entire `.cause` chain, so it works even when the abort error is wrapped by `.catch()`.
+
+<!-- bad -->
+```ts
+// Plain Error — isAbortError can't detect it
+controller.abort(new Error('timeout'))
+
+// String — not an Error, breaks instanceof
+controller.abort('timeout')
+```
+
+<!-- good -->
+```ts
+import * as errore from 'errore'
+
+class TimeoutError extends errore.createTaggedError({
+  name: 'TimeoutError',
+  message: 'Request timed out for $operation',
+  extends: errore.AbortError,
+}) {}
+
+// Pass typed error to abort
+const controller = new AbortController()
+const timer = setTimeout(
+  () => controller.abort(new TimeoutError({ operation: 'fetch' })),
+  5000,
+)
+
+const res = await fetch(url, { signal: controller.signal })
+  .catch((e) => new NetworkError({ url, cause: e }))
+clearTimeout(timer)
+
+if (res instanceof Error) {
+  // Check if the underlying cause was an abort
+  if (errore.isAbortError(res)) {
+    const timeout = errore.findCause(res, TimeoutError)
+    if (timeout) console.log(timeout.operation)
+    return res
+  }
+  // Genuine network error
+  return res
+}
+```
+
+> `isAbortError` detects three kinds of abort: (1) native `DOMException` from bare `controller.abort()`, (2) direct `errore.AbortError` instances, (3) tagged errors that extend `errore.AbortError` — even when wrapped in another error's `.cause` chain.
+
 ## Pitfalls
 
 ### unknown | Error collapses to unknown
@@ -1067,10 +1106,14 @@ const result = myFn()
 if (result instanceof Error) return result
 // result is string
 
-// --- Wrap exceptions ---
-const data = await errore.tryAsync({
-  try: () => riskyCall(),
-  catch: (e) => new MyError({ resource: 'api', reason: 'call failed', cause: e }),
+// --- Wrap async exceptions (.catch) ---
+const data = await riskyAsyncCall()
+  .catch((e) => new MyError({ resource: 'api', reason: 'call failed', cause: e }))
+
+// --- Wrap sync exceptions (errore.try) ---
+const parsed = errore.try({
+  try: () => JSON.parse(input),
+  catch: (e) => new MyError({ resource: 'config', reason: 'parse failed', cause: e }),
 })
 
 // --- Check errors (plain instanceof, always) ---
@@ -1092,6 +1135,17 @@ errore.matchError(error, {
 error.findCause(DbError)             // instance method on tagged errors
 errore.findCause(error, DbError)     // standalone function
 
+// --- Abort / Cancellation ---
+class TimeoutError extends errore.createTaggedError({
+  name: 'TimeoutError',
+  message: 'Request timed out for $operation',
+  extends: errore.AbortError,          // MUST extend AbortError
+}) {}
+controller.abort(new TimeoutError({ operation: 'fetch' }))
+
+errore.isAbortError(error)             // true if abort-related (walks cause chain)
+errore.findCause(error, TimeoutError)  // extract the specific abort error
+
 // --- Error properties ---
 err._tag              // 'MyError'
 err.resource          // 'user' (from $resource)

package/dist/error.d.ts

@@ -122,6 +122,36 @@ export declare function matchError<E extends Error, R>(err: E, handlers: MatchHa
  * }, (e) => `Unknown: ${e.message}`);
  */
 export declare function matchErrorPartial<E extends Error, R>(err: E, handlers: Partial<MatchHandlersWithPlain<E, R>>, fallback: (e: E) => R): R;
+/**
+ * Base class for abort-related errors.
+ * Extend this in custom abort errors so `isAbortError` detects them
+ * even when wrapped in a cause chain.
+ *
+ * @example
+ * class TimeoutError extends errore.createTaggedError({
+ *   name: 'TimeoutError',
+ *   message: 'Request timed out for $operation',
+ *   extends: errore.AbortError,
+ * }) {}
+ *
+ * controller.abort(new TimeoutError({ operation: 'fetch' }))
+ */
+export declare class AbortError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Check if an error (or any error in its `.cause` chain) is an abort error.
+ * Detects native AbortError (DOMException), errore.AbortError, and any
+ * tagged error that extends errore.AbortError.
+ *
+ * @example
+ * const res = await fetch(url, { signal })
+ *   .catch((e) => new NetworkError({ url, cause: e }))
+ * if (errore.isAbortError(res)) {
+ *   // request was aborted — timeout, user cancel, etc.
+ * }
+ */
+export declare function isAbortError(error: unknown): boolean;
 declare const UnhandledError_base: TaggedErrorClass<"UnhandledError", {
     message: string;
     cause: unknown;

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"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"}

package/dist/error.js

@@ -178,6 +178,55 @@ export function matchErrorPartial(err, handlers, fallback) {
     }
     return fallback(err);
 }
+/**
+ * Base class for abort-related errors.
+ * Extend this in custom abort errors so `isAbortError` detects them
+ * even when wrapped in a cause chain.
+ *
+ * @example
+ * class TimeoutError extends errore.createTaggedError({
+ *   name: 'TimeoutError',
+ *   message: 'Request timed out for $operation',
+ *   extends: errore.AbortError,
+ * }) {}
+ *
+ * controller.abort(new TimeoutError({ operation: 'fetch' }))
+ */
+export class AbortError extends Error {
+    constructor(message = 'The operation was aborted', options) {
+        super(message, options);
+        this.name = 'AbortError';
+    }
+}
+/**
+ * Check if an error (or any error in its `.cause` chain) is an abort error.
+ * Detects native AbortError (DOMException), errore.AbortError, and any
+ * tagged error that extends errore.AbortError.
+ *
+ * @example
+ * const res = await fetch(url, { signal })
+ *   .catch((e) => new NetworkError({ url, cause: e }))
+ * if (errore.isAbortError(res)) {
+ *   // request was aborted — timeout, user cancel, etc.
+ * }
+ */
+export function isAbortError(error) {
+    const seen = new Set();
+    let current = error;
+    while (current instanceof Error) {
+        if (seen.has(current))
+            break;
+        seen.add(current);
+        // Native DOMException AbortError or direct AbortError (name = 'AbortError')
+        if (current.name === 'AbortError')
+            return true;
+        // Tagged errors extending AbortError (createTaggedError overrides name to _tag)
+        if (current instanceof AbortError)
+            return true;
+        current = current.cause;
+    }
+    return false;
+}
 /**
  * Default error type when catching unknown exceptions.
  */

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export type { Errore, InferError, InferValue, EnsureNotError } from './types.js'
 export { isError, isOk, tryFn, tryFn as try, tryAsync } from './core.js';
 export { map, mapError, andThen, andThenAsync, tap, tapAsync } from './transform.js';
 export { unwrap, unwrapOr, match, partition, flatten } from './extract.js';
-export { TaggedError, matchError, matchErrorPartial, isTaggedError, UnhandledError, findCause } from './error.js';
+export { TaggedError, matchError, matchErrorPartial, isTaggedError, UnhandledError, findCause, AbortError, isAbortError } from './error.js';
 export type { TaggedErrorInstance, TaggedErrorClass } from './error.js';
 export { createTaggedError } from './factory.js';
 export type { FactoryTaggedErrorClass, FactoryTaggedErrorInstance } from './factory.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAGxE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAGpF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG1E,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACjH,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAGvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChD,YAAY,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAGvF,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAGxE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAGpF,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAG1E,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC3I,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAGvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChD,YAAY,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAA;AAGvF,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -5,7 +5,7 @@ export { map, mapError, andThen, andThenAsync, tap, tapAsync } from './transform
 // Extraction
 export { unwrap, unwrapOr, match, partition, flatten } from './extract.js';
 // Tagged errors
-export { TaggedError, matchError, matchErrorPartial, isTaggedError, UnhandledError, findCause } from './error.js';
+export { TaggedError, matchError, matchErrorPartial, isTaggedError, UnhandledError, findCause, AbortError, isAbortError } from './error.js';
 // Factory API for tagged errors with $variable interpolation
 export { createTaggedError } from './factory.js';
 // Resource management (DisposableStack polyfills)

package/dist/index.test.js

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'vitest';
-import { isOk, tryFn, tryAsync, map, mapError, andThen, unwrap, unwrapOr, match, partition, TaggedError, matchError, matchErrorPartial, UnhandledError, createTaggedError, findCause, } from './index.js';
+import { isOk, tryFn, tryAsync, map, mapError, andThen, unwrap, unwrapOr, match, partition, TaggedError, matchError, matchErrorPartial, UnhandledError, createTaggedError, findCause, AbortError, isAbortError, } from './index.js';
 // ============================================================================
 // Tagged Error Definitions
 // ============================================================================
@@ -1139,3 +1139,106 @@ describe('findCause', () => {
         expect(findCause(b, UnrelatedError)).toBeUndefined();
     });
 });
+// ============================================================================
+// AbortError & isAbortError
+// ============================================================================
+describe('AbortError', () => {
+    test('has name AbortError', () => {
+        const err = new AbortError();
+        expect(err.name).toBe('AbortError');
+        expect(err.message).toBe('The operation was aborted');
+    });
+    test('accepts custom message', () => {
+        const err = new AbortError('Request cancelled');
+        expect(err.message).toBe('Request cancelled');
+        expect(err.name).toBe('AbortError');
+    });
+    test('accepts cause via options', () => {
+        const cause = new Error('underlying');
+        const err = new AbortError('aborted', { cause });
+        expect(err.cause).toBe(cause);
+    });
+    test('is instanceof Error', () => {
+        expect(new AbortError()).toBeInstanceOf(Error);
+    });
+});
+describe('isAbortError', () => {
+    test('detects direct AbortError', () => {
+        expect(isAbortError(new AbortError())).toBe(true);
+    });
+    test('detects native DOMException AbortError', () => {
+        const err = new DOMException('aborted', 'AbortError');
+        expect(isAbortError(err)).toBe(true);
+    });
+    test('detects AbortError in cause chain', () => {
+        const abort = new AbortError();
+        const wrapped = new Error('network failed', { cause: abort });
+        expect(isAbortError(wrapped)).toBe(true);
+    });
+    test('detects AbortError deep in cause chain', () => {
+        const abort = new AbortError();
+        const mid = new Error('mid', { cause: abort });
+        const outer = new Error('outer', { cause: mid });
+        expect(isAbortError(outer)).toBe(true);
+    });
+    test('detects tagged error extending AbortError', () => {
+        class TimeoutError extends createTaggedError({
+            name: 'TimeoutError',
+            message: 'Timed out after $duration',
+            extends: AbortError,
+        }) {
+        }
+        const err = new TimeoutError({ duration: '5s' });
+        // createTaggedError overrides name to 'TimeoutError', but instanceof still works
+        expect(err.name).toBe('TimeoutError');
+        expect(err).toBeInstanceOf(AbortError);
+        expect(isAbortError(err)).toBe(true);
+    });
+    test('detects tagged abort error in cause chain (wrapped by .catch)', () => {
+        class TimeoutError extends createTaggedError({
+            name: 'TimeoutError',
+            message: 'Timed out after $duration',
+            extends: AbortError,
+        }) {
+        }
+        class NetworkError extends createTaggedError({
+            name: 'NetworkError',
+            message: 'Request to $url failed',
+        }) {
+        }
+        // Simulates: fetch(url, { signal }).catch((e) => new NetworkError({ url, cause: e }))
+        const timeout = new TimeoutError({ duration: '5s' });
+        const network = new NetworkError({ url: '/api', cause: timeout });
+        expect(isAbortError(network)).toBe(true);
+        // Can also extract the specific error via findCause
+        expect(findCause(network, TimeoutError)).toBe(timeout);
+    });
+    test('returns false for non-abort errors', () => {
+        expect(isAbortError(new Error('oops'))).toBe(false);
+        expect(isAbortError(new TypeError('bad type'))).toBe(false);
+    });
+    test('returns false for non-errors', () => {
+        expect(isAbortError('string')).toBe(false);
+        expect(isAbortError(null)).toBe(false);
+        expect(isAbortError(undefined)).toBe(false);
+        expect(isAbortError(42)).toBe(false);
+    });
+    test('returns false for plain Error passed to abort (not extending AbortError)', () => {
+        // This is why the rule says: MUST use extends: errore.AbortError
+        const err = new Error('timeout');
+        const wrapped = new Error('network failed', { cause: err });
+        expect(isAbortError(wrapped)).toBe(false);
+    });
+    test('detects native DOMException AbortError in cause chain', () => {
+        const abort = new DOMException('aborted', 'AbortError');
+        const wrapped = new Error('fetch failed', { cause: abort });
+        expect(isAbortError(wrapped)).toBe(true);
+    });
+    test('handles circular cause gracefully', () => {
+        const a = new Error('a');
+        const b = new Error('b', { cause: a });
+        a.cause = b;
+        // Should not infinite loop
+        expect(isAbortError(b)).toBe(false);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "errore",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Type-safe errors as values for TypeScript. Like Go, but with full type inference.",
   "repository": {

package/src/error.ts

@@ -256,6 +256,54 @@ export function matchErrorPartial<E extends Error, R>(
   return fallback(err)
 }
 
+/**
+ * Base class for abort-related errors.
+ * Extend this in custom abort errors so `isAbortError` detects them
+ * even when wrapped in a cause chain.
+ *
+ * @example
+ * class TimeoutError extends errore.createTaggedError({
+ *   name: 'TimeoutError',
+ *   message: 'Request timed out for $operation',
+ *   extends: errore.AbortError,
+ * }) {}
+ *
+ * controller.abort(new TimeoutError({ operation: 'fetch' }))
+ */
+export class AbortError extends Error {
+  constructor(message = 'The operation was aborted', options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'AbortError'
+  }
+}
+
+/**
+ * Check if an error (or any error in its `.cause` chain) is an abort error.
+ * Detects native AbortError (DOMException), errore.AbortError, and any
+ * tagged error that extends errore.AbortError.
+ *
+ * @example
+ * const res = await fetch(url, { signal })
+ *   .catch((e) => new NetworkError({ url, cause: e }))
+ * if (errore.isAbortError(res)) {
+ *   // request was aborted — timeout, user cancel, etc.
+ * }
+ */
+export function isAbortError(error: unknown): boolean {
+  const seen = new Set<Error>()
+  let current: unknown = error
+  while (current instanceof Error) {
+    if (seen.has(current)) break
+    seen.add(current)
+    // Native DOMException AbortError or direct AbortError (name = 'AbortError')
+    if (current.name === 'AbortError') return true
+    // Tagged errors extending AbortError (createTaggedError overrides name to _tag)
+    if (current instanceof AbortError) return true
+    current = current.cause
+  }
+  return false
+}
+
 /**
  * Default error type when catching unknown exceptions.
  */

package/src/index.test.ts

@@ -17,6 +17,8 @@ import {
   UnhandledError,
   createTaggedError,
   findCause,
+  AbortError,
+  isAbortError,
 } from './index.js'
 
 // ============================================================================
@@ -608,6 +610,7 @@ describe('real-world: fetch user flow', () => {
       err: (e) => `Failed: ${e.message}`,
     })
 
+
     expect(message).toBe('Failed: Connection failed')
   })
 })
@@ -1021,6 +1024,7 @@ describe('createTaggedError factory', () => {
     const originalError = new Error('original')
     const err = new WrapperError({ item: 'data', cause: originalError })
 
+
     expect(err.cause).toBe(originalError)
     expect(err.message).toBe('Failed to process data')
   })
@@ -1471,3 +1475,123 @@ describe('findCause', () => {
     expect(findCause(b, UnrelatedError)).toBeUndefined()
   })
 })
+
+// ============================================================================
+// AbortError & isAbortError
+// ============================================================================
+
+describe('AbortError', () => {
+  test('has name AbortError', () => {
+    const err = new AbortError()
+    expect(err.name).toBe('AbortError')
+    expect(err.message).toBe('The operation was aborted')
+  })
+
+  test('accepts custom message', () => {
+    const err = new AbortError('Request cancelled')
+    expect(err.message).toBe('Request cancelled')
+    expect(err.name).toBe('AbortError')
+  })
+
+  test('accepts cause via options', () => {
+    const cause = new Error('underlying')
+    const err = new AbortError('aborted', { cause })
+    expect(err.cause).toBe(cause)
+  })
+
+  test('is instanceof Error', () => {
+    expect(new AbortError()).toBeInstanceOf(Error)
+  })
+})
+
+describe('isAbortError', () => {
+  test('detects direct AbortError', () => {
+    expect(isAbortError(new AbortError())).toBe(true)
+  })
+
+  test('detects native DOMException AbortError', () => {
+    const err = new DOMException('aborted', 'AbortError')
+    expect(isAbortError(err)).toBe(true)
+  })
+
+  test('detects AbortError in cause chain', () => {
+    const abort = new AbortError()
+    const wrapped = new Error('network failed', { cause: abort })
+    expect(isAbortError(wrapped)).toBe(true)
+  })
+
+  test('detects AbortError deep in cause chain', () => {
+    const abort = new AbortError()
+    const mid = new Error('mid', { cause: abort })
+    const outer = new Error('outer', { cause: mid })
+    expect(isAbortError(outer)).toBe(true)
+  })
+
+  test('detects tagged error extending AbortError', () => {
+    class TimeoutError extends createTaggedError({
+      name: 'TimeoutError',
+      message: 'Timed out after $duration',
+      extends: AbortError,
+    }) {}
+
+    const err = new TimeoutError({ duration: '5s' })
+    // createTaggedError overrides name to 'TimeoutError', but instanceof still works
+    expect(err.name).toBe('TimeoutError')
+    expect(err).toBeInstanceOf(AbortError)
+    expect(isAbortError(err)).toBe(true)
+  })
+
+  test('detects tagged abort error in cause chain (wrapped by .catch)', () => {
+    class TimeoutError extends createTaggedError({
+      name: 'TimeoutError',
+      message: 'Timed out after $duration',
+      extends: AbortError,
+    }) {}
+
+    class NetworkError extends createTaggedError({
+      name: 'NetworkError',
+      message: 'Request to $url failed',
+    }) {}
+
+    // Simulates: fetch(url, { signal }).catch((e) => new NetworkError({ url, cause: e }))
+    const timeout = new TimeoutError({ duration: '5s' })
+    const network = new NetworkError({ url: '/api', cause: timeout })
+
+    expect(isAbortError(network)).toBe(true)
+    // Can also extract the specific error via findCause
+    expect(findCause(network, TimeoutError)).toBe(timeout)
+  })
+
+  test('returns false for non-abort errors', () => {
+    expect(isAbortError(new Error('oops'))).toBe(false)
+    expect(isAbortError(new TypeError('bad type'))).toBe(false)
+  })
+
+  test('returns false for non-errors', () => {
+    expect(isAbortError('string')).toBe(false)
+    expect(isAbortError(null)).toBe(false)
+    expect(isAbortError(undefined)).toBe(false)
+    expect(isAbortError(42)).toBe(false)
+  })
+
+  test('returns false for plain Error passed to abort (not extending AbortError)', () => {
+    // This is why the rule says: MUST use extends: errore.AbortError
+    const err = new Error('timeout')
+    const wrapped = new Error('network failed', { cause: err })
+    expect(isAbortError(wrapped)).toBe(false)
+  })
+
+  test('detects native DOMException AbortError in cause chain', () => {
+    const abort = new DOMException('aborted', 'AbortError')
+    const wrapped = new Error('fetch failed', { cause: abort })
+    expect(isAbortError(wrapped)).toBe(true)
+  })
+
+  test('handles circular cause gracefully', () => {
+    const a = new Error('a')
+    const b = new Error('b', { cause: a })
+    ;(a as any).cause = b
+    // Should not infinite loop
+    expect(isAbortError(b)).toBe(false)
+  })
+})

package/src/index.ts

@@ -11,7 +11,7 @@ export { map, mapError, andThen, andThenAsync, tap, tapAsync } from './transform
 export { unwrap, unwrapOr, match, partition, flatten } from './extract.js'
 
 // Tagged errors
-export { TaggedError, matchError, matchErrorPartial, isTaggedError, UnhandledError, findCause } from './error.js'
+export { TaggedError, matchError, matchErrorPartial, isTaggedError, UnhandledError, findCause, AbortError, isAbortError } from './error.js'
 export type { TaggedErrorInstance, TaggedErrorClass } from './error.js'
 
 // Factory API for tagged errors with $variable interpolation