errore 0.9.0 → 0.10.0

package/README.md

@@ -4,13 +4,20 @@ Type-safe errors as values for TypeScript. Like Go, but with full type inference
 
 ## Why?
 
-Instead of wrapping values in a `Result<T, E>` type, functions simply return `E | T`. TypeScript's type narrowing handles the rest:
+Instead of wrapping values in a `Result<T, E>` type, functions simply return `E | T`. TypeScript's **type narrowing** handles the rest:
 
 ```ts
 // Go-style: errors as values
-const user = await fetchUser(id)
-if (user instanceof Error) return user  // TypeScript narrows type
-console.log(user.name)                  // user is now User, not Error | User
+const user = await getUser(id)
+if (user instanceof NotFoundError) {
+  console.error('Missing:', user.id)
+  return
+}
+if (user instanceof DbError) {
+  console.error('DB failed:', user.reason)
+  return
+}
+console.log(user.username)  // user is User, fully narrowed
 ```
 
 ## Install
@@ -21,6 +28,8 @@ npm install errore
 
 ## Quick Start
 
+Define typed errors with **variable interpolation** and return **Error or Value** directly:
+
 ```ts
 import * as errore from 'errore'
 
@@ -67,7 +76,7 @@ console.log(user.name)
 
 ## Example: API Error Handling
 
-A complete example with custom base class, HTTP status codes, and error reporting:
+A complete example with **custom base class** and HTTP status codes:
 
 ```ts
 import * as errore from 'errore'
@@ -139,7 +148,7 @@ app.post('/users/:id', async (req, res) => {
 
 ### createTaggedError
 
-Create typed errors with `$variable` interpolation in the message:
+Create typed errors with **variable interpolation** in the message:
 
 ```ts
 import * as errore from 'errore'
@@ -186,8 +195,136 @@ err.statusCode  // 500 (inherited from AppError)
 err instanceof AppError  // true
 ```
 
+### Error Wrapping and Context
+
+Wrap errors with additional context while **preserving the original error** via `cause`:
+
+```ts
+// 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)
+}
+
+// Access original error via cause
+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
+  }
+}
+```
+
+The error definitions:
+
+```ts
+class NotFoundError extends errore.createTaggedError({
+  name: 'NotFoundError',
+  message: 'User $id not found'
+}) {}
+
+class ServiceError extends errore.createTaggedError({
+  name: 'ServiceError',
+  message: 'Failed to process user $id'
+}) {}
+```
+
+**Browser console** prints the full cause chain:
+
+```
+ServiceError: Failed to process user 123
+    at processUser (app.js:12)
+    at main (app.js:20)
+Caused by: NotFoundError: User 123 not found
+    at getUser (app.js:5)
+    at processUser (app.js:8)
+```
+
+### findCause
+
+Walk the `.cause` chain to find an ancestor matching a specific error class. Similar to Go's `errors.As` — checks the error itself first, then traverses `.cause` recursively:
+
+```ts
+import * as errore from 'errore'
+
+class NotFoundError extends errore.createTaggedError({
+  name: 'NotFoundError',
+  message: 'User $id not found'
+}) {}
+
+class ServiceError extends errore.createTaggedError({
+  name: 'ServiceError',
+  message: 'Failed to process user $id'
+}) {}
+
+// Deep chain: ServiceError -> NotFoundError
+const notFound = new NotFoundError({ id: '123' })
+const service = new ServiceError({ id: '123', cause: notFound })
+
+// Instance method on tagged errors
+const found = service.findCause(NotFoundError)
+found?.id  // '123' — type-safe access
+
+// Standalone function for any Error
+const found2 = errore.findCause(service, NotFoundError)
+found2?.id  // '123'
+```
+
+This solves the problem where `result.cause instanceof MyError` only checks one level deep. `findCause` walks the entire chain:
+
+```ts
+// A -> B -> C chain
+const c = new DbError({ message: 'connection reset' })
+const b = new ServiceError({ id: '123', cause: c })
+const a = new ApiError({ message: 'request failed', cause: b })
+
+// Manual check only finds B
+a.cause instanceof DbError  // false — only checks one level
+
+// findCause walks the full chain
+a.findCause(DbError)  // finds C ✓
+```
+
+Returns `undefined` if no matching ancestor is found. Safe against circular `.cause` references.
+
+### Custom Base Class with `extends`
+
+Use `extends` to inherit from a custom base class. The error will pass `instanceof` for both the base class and the specific error class:
+
+```ts
+class AppError extends Error {
+  statusCode = 500
+  toResponse() { return { error: this.message, code: this.statusCode } }
+}
+
+class NotFoundError extends errore.createTaggedError({
+  name: 'NotFoundError',
+  message: 'Resource $id not found',
+  extends: AppError
+}) {
+  statusCode = 404
+}
+
+const err = new NotFoundError({ id: '123' })
+err instanceof NotFoundError  // true
+err instanceof AppError       // true
+err instanceof Error          // true
+
+err.statusCode    // 404
+err.toResponse()  // { error: 'Resource 123 not found', code: 404 }
+```
+
 ### Type Guards
 
+Use **instanceof checks** to narrow union types:
+
 ```ts
 const result: NetworkError | User = await fetchUser(id)
 
@@ -200,14 +337,16 @@ if (result instanceof Error) {
 
 ### Try Functions
 
+**Wrap exceptions** as error values:
+
 ```ts
 import * as errore from 'errore'
 
 // Sync - wraps exceptions in UnhandledError
-const parsed = errore.tryFn(() => JSON.parse(input))
+const parsed = errore.try(() => JSON.parse(input))
 
 // Sync - with custom error type
-const parsed = errore.tryFn({
+const parsed = errore.try({
   try: () => JSON.parse(input),
   catch: e => new ParseError({ reason: e.message, cause: e })
 })
@@ -224,6 +363,8 @@ const response = await errore.tryAsync({
 
 ### Transformations
 
+**Transform and chain** operations:
+
 ```ts
 import * as errore from 'errore'
 
@@ -242,6 +383,8 @@ const logged = errore.tap(user, u => console.log('Got user:', u.name))
 
 ### Extraction
 
+**Extract values** or throw, **split arrays** by success/error:
+
 ```ts
 import * as errore from 'errore'
 
@@ -264,7 +407,7 @@ const [users, errors] = errore.partition(results)
 
 ### Error Matching
 
-Always assign `matchError` results to a variable. Keep callbacks pure (return values only) and move side effects outside:
+**Exhaustive pattern matching** with `matchError`. Always assign results to a variable and keep callbacks pure:
 
 ```ts
 import * as errore from 'errore'
@@ -298,7 +441,7 @@ ValidationError.is(value)  // specific class
 
 ## How Type Safety Works
 
-TypeScript narrows types after `instanceof Error` checks:
+TypeScript **narrows types** after `instanceof Error` checks:
 
 ```ts
 function example(result: NetworkError | User): string {
@@ -318,7 +461,7 @@ This works because:
 
 ## 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!
+Naturally combine **error handling with optional values**. No wrapper nesting needed!
 
 ```ts
 import * as errore from 'errore'
@@ -362,14 +505,80 @@ console.log(user.name)
 | Zig | `!?T` (error union + optional) | Yes, specific syntax |
 | **errore** | `Error \| T \| null` | **No!** Check in any order |
 
-With errore:
+With errore you **check in any order**:
 - Use `?.` and `??` naturally
 - Check `instanceof Error` or `=== null` in any order
 - No unwrapping ceremony
 - TypeScript infers everything
 
+## Why This Is Better Than Go
+
+Go's error handling uses **two separate return values**:
+
+```go
+user, err := fetchUser(id)
+// Oops! Forgot to check err
+fmt.Println(user.Name)  // Compiles fine, crashes at runtime
+```
+
+The compiler can't save you here. You can ignore `err` entirely and use `user` directly.
+
+With errore, **forgetting to check is impossible**:
+
+```ts
+const user = await fetchUser(id)  // type: NotFoundError | User
+
+console.log(user.id)  // TS Error: Property 'id' does not exist on type 'NotFoundError'
+```
+
+Since errore uses a **single union variable** instead of two separate values, TypeScript forces you to narrow the type before accessing value-specific properties. You literally cannot use the value without first doing an `instanceof Error` check.
+
+> **Note:** Properties that exist on both `Error` and your value type (like `name`, `message`) can still be accessed without narrowing. This is a small set of 4 fields: `name`, `message`, `stack`, `cause`.
+
+### The Remaining Gap
+
+There's still one case errore can't catch: **ignored return values**:
+
+```ts
+// Oops! Completely ignoring the return value
+updateUser(id, data)  // No error, but we should check!
+```
+
+For this, use **TypeScript's built-in checks** or a linter:
+
+**TypeScript `tsconfig.json`:**
+```json
+{
+  "compilerOptions": {
+    "noUnusedLocals": true
+  }
+}
+```
+
+This catches unused variables, though not ignored return values directly.
+
+**oxlint `no-unused-expressions`:**
+
+`oxlint.json`:
+```json
+{
+  "rules": {
+    "no-unused-expressions": "error"
+  }
+}
+```
+
+Or via CLI:
+```bash
+oxlint --deny no-unused-expressions
+```
+
+Combined with errore's type safety, these tools give you near-complete protection against ignored errors.
+
 ## Comparison with Result Types
 
+**Direct returns** vs wrapper methods:
+
 | Result Pattern | errore |
 |---------------|--------|
 | `Result.ok(value)` | just `return value` |
@@ -379,9 +588,150 @@ With errore:
 | `Result<User, Error>` | `Error \| User` |
 | `Result<Option<T>, E>` | `Error \| T \| null` |
 
+## Vs neverthrow / better-result
+
+These libraries wrap values in a **Result container**. You construct results with `ok()` and `err()`, then unwrap them with `.value` and `.error`:
+
+```ts
+// neverthrow
+import { ok, err, Result } from 'neverthrow'
+
+function getUser(id: string): Result<User, NotFoundError> {
+  const user = db.find(id)
+  if (!user) return err(new NotFoundError({ id }))
+  return ok(user)  // must wrap
+}
+
+const result = getUser('123')
+if (result.isErr()) {
+  console.log(result.error)  // must unwrap
+  return
+}
+console.log(result.value.name)  // must unwrap
+```
+
+```ts
+// errore
+function getUser(id: string): User | NotFoundError {
+  const user = db.find(id)
+  if (!user) return new NotFoundError({ id })
+  return user  // just return
+}
+
+const user = getUser('123')
+if (user instanceof Error) {
+  console.log(user)  // it's already the error
+  return
+}
+console.log(user.name)  // it's already the user
+```
+
+**The key insight**: `T | Error` already encodes success/failure. TypeScript's type narrowing does the rest. No wrapper needed.
+
+| Feature | neverthrow | errore |
+|---------|------------|--------|
+| Type-safe errors | ✓ | ✓ |
+| Exhaustive handling | ✓ | ✓ |
+| Works with null | `Result<T \| null, E>` | `T \| E \| null` |
+| Learning curve | New API (`ok`, `err`, `map`, `andThen`, ...) | Just `instanceof` |
+| Bundle size | ~3KB min | **~0 bytes** |
+| Interop | Requires wrapping/unwrapping at boundaries | Native TypeScript |
+
+neverthrow also requires an [eslint plugin](https://github.com/mdbetancourt/eslint-plugin-neverthrow) to catch unhandled results. With errore, TypeScript itself prevents you from using a value without checking the error first.
+
+## Vs Effect.ts
+
+Effect is not just error handling—it's a **complete functional programming framework** with dependency injection, concurrency primitives, resource management, streaming, and more.
+
+```ts
+// Effect.ts - a paradigm shift
+import { Effect, pipe } from 'effect'
+
+const program = pipe(
+  fetchUser(id),
+  Effect.flatMap(user => fetchPosts(user.id)),
+  Effect.map(posts => posts.filter(p => p.published)),
+  Effect.catchTag('NotFoundError', () => Effect.succeed([]))
+)
+
+const result = await Effect.runPromise(program)
+```
+
+```ts
+// errore - regular TypeScript
+const user = await fetchUser(id)
+if (user instanceof Error) return []
+
+const posts = await fetchPosts(user.id)
+if (posts instanceof Error) return []
+
+return posts.filter(p => p.published)
+```
+
+Effect is powerful if you need its full feature set. But if you just want type-safe errors:
+
+| | Effect | errore |
+|-|--------|--------|
+| Learning curve | Steep (new paradigm) | Minimal (just `instanceof`) |
+| Codebase impact | Pervasive (everything becomes an Effect) | Surgical (adopt incrementally) |
+| Bundle size | ~50KB+ | **~0 bytes** |
+| Use case | Full FP framework | Just error handling |
+
+**Use Effect** when you want dependency injection, structured concurrency, and the full functional programming experience.
+
+**Use errore** when you just want type-safe errors without rewriting your codebase.
+
+## Zero-Dependency Philosophy
+
+errore is more a **way of writing code** than a library. The core pattern requires nothing:
+
+```ts
+// You can write this without installing errore at all
+class NotFoundError extends Error {
+  readonly _tag = 'NotFoundError'
+  constructor(public id: string) {
+    super(`User ${id} not found`)
+  }
+}
+
+async function getUser(id: string): Promise<User | NotFoundError> {
+  const user = await db.find(id)
+  if (!user) return new NotFoundError(id)
+  return user
+}
+
+const user = await getUser('123')
+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.
+
+### Perfect for Libraries
+
+Ideal for library authors. Return **plain TypeScript unions** instead of forcing users to adopt your error handling framework:
+
+```ts
+// ❌ Library that forces a dependency on users
+import { Result } from 'some-result-lib'
+export function parse(input: string): Result<AST, ParseError>
+
+// Users must now install and learn 'some-result-lib'
+```
+
+```ts
+// ✓ Library using plain TypeScript unions
+export function parse(input: string): AST | ParseError
+
+// Users handle errors with standard instanceof checks
+// No new dependencies, no new concepts to learn
+```
+
+Your library stays lightweight. Users get type-safe errors without adopting an opinionated wrapper. Everyone wins.
+
 ## Import Style
 
-> **Note:** Always use `import * as errore from 'errore'` instead of named imports. This makes code easier to move between files, and more readable for people unfamiliar with errore since every function call is clearly namespaced (e.g. `errore.isOk()` instead of just `isOk()`).
+> **Note:** Always use `import * as errore from 'errore'` instead of named imports. This makes code easier to move between files, and more readable since every function call is **clearly namespaced** (e.g. `errore.isOk()` instead of just `isOk()`).
 
 ## License
 

package/dist/error.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Walk the .cause chain of an error to find an ancestor matching a specific error class.
+ * Checks the error itself first, then traverses .cause recursively.
+ * Similar to Go's `errors.As`.
+ *
+ * @example
+ * const notFound = findCause(err, NotFoundError)
+ * if (notFound) {
+ *   console.log(notFound.id) // type-safe access
+ * }
+ *
+ * @example
+ * // With optional chaining
+ * const id = findCause(err, NotFoundError)?.id
+ */
+export declare function findCause<T extends Error>(error: Error, ErrorClass: new (...args: any[]) => T): T | undefined;
 /**
  * Any tagged error (for generic constraints)
  */
@@ -14,6 +30,8 @@ type ErrorClass = new (...args: any[]) => Error;
 export type TaggedErrorInstance<Tag extends string, Props, Base extends Error = Error> = Base & {
     readonly _tag: Tag;
     toJSON(): object;
+    /** Walk the .cause chain to find an ancestor matching a specific error class. */
+    findCause<T extends Error>(ErrorClass: new (...args: any[]) => T): T | undefined;
 } & Readonly<Props>;
 /**
  * Class type produced by TaggedError factory

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

@@ -7,6 +7,34 @@ const serializeCause = (cause) => {
     }
     return cause;
 };
+/**
+ * Walk the .cause chain of an error to find an ancestor matching a specific error class.
+ * Checks the error itself first, then traverses .cause recursively.
+ * Similar to Go's `errors.As`.
+ *
+ * @example
+ * const notFound = findCause(err, NotFoundError)
+ * if (notFound) {
+ *   console.log(notFound.id) // type-safe access
+ * }
+ *
+ * @example
+ * // With optional chaining
+ * const id = findCause(err, NotFoundError)?.id
+ */
+export function findCause(error, ErrorClass) {
+    const seen = new Set();
+    let current = error;
+    while (current instanceof Error) {
+        if (seen.has(current))
+            break;
+        seen.add(current);
+        if (current instanceof ErrorClass)
+            return current;
+        current = current.cause;
+    }
+    return undefined;
+}
 /**
  * Type guard for any tagged error
  */
@@ -71,6 +99,9 @@ export const TaggedError = Object.assign((tag, BaseClass) => () => {
                 this.stack = `${this.stack}\nCaused by: ${indented}`;
             }
         }
+        findCause(ErrorClass) {
+            return findCause(this, ErrorClass);
+        }
         toJSON() {
             return {
                 ...this,

package/dist/factory.d.ts

@@ -62,6 +62,8 @@ export type FactoryTaggedErrorInstance<Tag extends string, Msg extends string, B
     readonly _tag: Tag;
     readonly message: string;
     toJSON(): object;
+    /** Walk the .cause chain to find an ancestor matching a specific error class. */
+    findCause<T extends Error>(ErrorClass: new (...args: any[]) => T): T | undefined;
 } & Readonly<VarProps<Msg>>;
 /**
  * Class type returned by createTaggedError factory.

package/dist/factory.d.ts.map

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

package/dist/factory.js

@@ -1,21 +1,4 @@
-/**
- * Factory API for creating tagged errors with $variable interpolation in messages.
- *
- * Extracts variable names from the message template and requires them in the constructor.
- * Use `class X extends createTaggedError({...}) {}` so X is both a value and a type.
- *
- * @example
- * class NotFoundError extends createTaggedError({
- *   name: 'NotFoundError',
- *   message: 'User $id not found in $database'
- * }) {}
- *
- * throw new NotFoundError({ id: '123', database: 'users' })
- * // err._tag = 'NotFoundError'
- * // err.message = 'User 123 not found in users'
- * // err.id = '123'
- * // err.database = 'users'
- */
+import { findCause } from './error.js';
 /**
  * Serialize cause for JSON output
  */
@@ -143,6 +126,9 @@ export function createTaggedError(opts) {
                 this.stack = `${this.stack}\nCaused by: ${indented}`;
             }
         }
+        findCause(ErrorClass) {
+            return findCause(this, ErrorClass);
+        }
         toJSON() {
             const json = {
                 _tag: this._tag,

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 } from './error.js';
+export { TaggedError, matchError, matchErrorPartial, isTaggedError, UnhandledError, findCause } 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,MAAM,YAAY,CAAA;AACtG,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"}
+{"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"}

package/dist/index.js

@@ -5,6 +5,6 @@ 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 } from './error.js';
+export { TaggedError, matchError, matchErrorPartial, isTaggedError, UnhandledError, findCause } from './error.js';
 // Factory API for tagged errors with $variable interpolation
 export { createTaggedError } from './factory.js';

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}