unknown-error 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Ley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+<div style="text-align:center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# unknown-error
+Turn any caught `unknown` into a real Error without throwing, even for hostile values, other realms and deep or circular cause chains.
+
+[![npm package](https://badge.fury.io/js/unknown-error.svg)](https://www.npmjs.com/package/unknown-error)
+[![License](https://img.shields.io/npm/l/unknown-error.svg)](https://github.com/JacobLey/leyman/blob/main/tools/unknown-error/LICENSE)
+
+</div>
+
+- **Never throws**: Safe on Proxies that throw from every trap, throwing getters, and `toJSON` or `toString` that throw. Handling an error can't raise a new one inside your `catch`.
+- **Any realm, any runtime**: Recognizes Errors from `vm`, iframes and workers, where `instanceof Error` fails. Runs in Node.js, Deno, Bun and browsers, using `Error.isError` where it exists.
+- **Keeps what it can**: Rebuilds error-shaped objects (from JSON, RPC or `postMessage`) with their name, stack, cause and `code`. Describes anything else readably, including circular objects and BigInts, instead of `[object Object]`.
+- **Whole error trees**: Walks `cause` chains and `AggregateError` entries without recursion, so circular or 100,000-deep chains end instead of overflowing the stack.
+- **Doesn't modify your errors**: Errors are returned as they are, never patched in place.
+
+| | unknown-error | [normalize-exception](https://www.npmjs.com/package/normalize-exception) | [ensure-error](https://www.npmjs.com/package/ensure-error) | [serialize-error](https://www.npmjs.com/package/serialize-error) | [pony-cause](https://www.npmjs.com/package/pony-cause) |
+|---|---|---|---|---|---|
+| Never throws on hostile values | ✅ | ✅ | ❌ | ❌ | — |
+| Errors from other realms | ✅ | ✅ | ❌ | ✅ | ❌ |
+| Readable circular and BigInt values | ✅ | ❌ | ❌ | ❌ | — |
+| Leaves your errors unmodified | ✅ | ❌ | ❌ | ✅ | — |
+| Causes and `AggregateError` | ✅ | ✅ | ✅ | — | Causes only |
+| 10,000-deep cause chains | ✅ | ❌ | ❌ | — | ❌ |
+
+For the problems with hand-written conversions, the full comparison and design decisions, see [WHY-UNKNOWN-ERROR.md](https://github.com/JacobLey/leyman/blob/main/tools/unknown-error/WHY-UNKNOWN-ERROR.md).
+
+## Contents
+- [Install](#install)
+- [Example](#example)
+- [Usage](#usage)
+- [API](#api)
+  - [`toError(value)`](#toerrorvalue)
+  - [`getErrorMessage(value)`](#geterrormessagevalue)
+  - [`hasCode(value, code)`](#hascodevalue-code)
+  - [`NonError`](#nonerror)
+  - [`walkErrors(value, options?)`](#walkerrorsvalue-options)
+  - [`formatError(value, options?)`](#formaterrorvalue-options)
+
+## Install
+
+```sh
+npm i unknown-error
+```
+
+## Example
+
+```ts
+import { formatError, getErrorMessage, hasCode, toError } from 'unknown-error';
+
+export const loadConfig = async (): Promise<Config> => {
+    try {
+        return await readConfig();
+    } catch (err) {
+        if (hasCode(err, 'ENOENT')) {
+            // `err` is `Error & { readonly code: 'ENOENT' }`
+            return defaultConfig;
+        }
+        console.error(formatError(err));
+        throw new Error(`Failed to read config: ${getErrorMessage(err)}`, { cause: toError(err) });
+    }
+};
+```
+
+## Usage
+
+ESM only. Runs in Node.js 24 or later, Deno, Bun and browsers, with no Node.js APIs. From CommonJS, load it with a dynamic import: `const { toError } = await import('unknown-error');`
+
+Errors are recognized with [`Error.isError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/isError) where the runtime has it: Node.js 24, Chrome 134, Firefox 138, Safari 18.4 and later. In older browsers, they are recognized by `instanceof Error` or their `[object Error]` tag instead, which works across realms too, but also lets through a Proxy around an Error and an object with a forged `Symbol.toStringTag`.
+
+In Safari and in Node.js before 24.3, `Error.isError` returns `false` for a `DOMException`, so there a `DOMException` is rebuilt as a plain Error with the same name and message rather than returned as-is.
+
+Every function takes `unknown`, so pass the `catch` variable straight in. None of them throw, whatever the value.
+
+## API
+
+### `toError(value)`
+
+Converts any caught value to an Error.
+
+| `value` | Result |
+|---------|--------|
+| An Error, including one from another realm | The same Error, unmodified |
+| An object with a string `message` | A new `Error` with the object's `message`, `name`, `stack` and `cause`, and its other own properties (like `code`) copied over |
+| Anything else | A new [`NonError`](#nonerror) describing it |
+
+**Returns** `Error`.
+
+```ts
+toError(new TypeError('x'));                         // the same TypeError
+toError({ name: 'HttpError', message: 'Not found', status: 404 });
+// HttpError: Not found, with `status: 404`
+toError('boom');                                     // NonError: boom
+toError({ count: 1n });                              // NonError: {"count":"1n"}
+```
+
+An error-like object without a `stack` gets a stack pointing at the `toError` call, since the original location is unknown.
+
+### `getErrorMessage(value)`
+
+The message of `toError(value)`.
+
+**Returns** `string`. A `message` that isn't a string is stringified, and one whose getter throws gives `'[unreadable message]'`.
+
+```ts
+getErrorMessage(new Error('boom')); // 'boom'
+getErrorMessage(404);               // '404'
+```
+
+### `hasCode(value, code)`
+
+Whether `value` is an Error whose `code` property equals `code`. A type guard, so it narrows `value` to `Error & { readonly code: typeof code }`.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | `unknown` | — | A caught value. |
+| `code` | `string \| number` | — | The code to match, like `'ENOENT'`. |
+
+**Returns** `boolean`.
+
+Only real Errors match. To match error-like objects too, convert them first: `hasCode(toError(err), 'E_TIMEOUT')`.
+
+### `NonError`
+
+`class NonError extends Error`. Wraps a thrown value that was neither an Error nor shaped like one.
+
+#### `new NonError(thrown, options?)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `thrown` | `unknown` | — | The value that was thrown. |
+| `options` | `ErrorOptions` | — | Standard Error options, such as `cause`. |
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `'NonError'` | |
+| `message` | `string` | A description of `thrown`: strings as-is, objects as JSON (with circular references and BigInts handled), functions as `[Function name]`. Cut to 1,000 characters. |
+| `thrown` | `unknown` | The original value. |
+
+### `walkErrors(value, options?)`
+
+Visits `value`, its `cause` chain and the `errors` of any `AggregateError`, depth first: an error, then its cause, then its `errors` in order.
+
+Every value is converted with `toError`, so a cause that isn't an Error still appears. A value already visited is skipped, so circular chains end.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `value` | `unknown` | — | A caught value. |
+| `options.maxDepth` | `number` | `32` | Deepest level to visit. The root is level `0`. Pass `Infinity` for no limit. |
+
+**Returns** `Generator<ErrorNode>`.
+
+#### `ErrorNode`
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `error` | `Error` | The value, converted with `toError`. |
+| `depth` | `number` | Distance from the root, which is `0`. |
+| `relation` | `'root' \| 'cause' \| 'aggregate'` | How it relates to its parent: the value passed in, its parent's `cause`, or an entry in its parent's `errors`. |
+| `truncated` | `boolean` | `true` when `maxDepth` stopped the walk here, so this error's own cause and errors were skipped. |
+
+```ts
+const error = new AggregateError([new Error('a'), 'b'], 'all', { cause: new Error('why') });
+
+for (const { error: node, depth, relation } of walkErrors(error)) {
+    console.log(depth, relation, node.message);
+}
+// 0 root all
+// 1 cause why
+// 1 aggregate a
+// 1 aggregate b
+```
+
+### `formatError(value, options?)`
+
+Formats an error with every cause and `AggregateError` entry, each indented under its parent. Takes the same options as [`walkErrors`](#walkerrorsvalue-options).
+
+**Returns** `string`.
+
+```ts
+console.log(formatError(new Error('request failed', { cause: new Error('ECONNREFUSED') })));
+// Error: request failed
+//     at ...
+//     Caused by: Error: ECONNREFUSED
+//         at ...
+```
+
+Causes are labelled `Caused by:`, and `AggregateError` entries `-`. Each error is printed as its `stack`, with a `Name: message` line added first when the stack doesn't start with one (as in Firefox and Safari). Where `maxDepth` cut the walk short, a `… more causes omitted` line says so.

package/WHY-UNKNOWN-ERROR.md

@@ -0,0 +1,91 @@
+<div style="text-align:center">
+
+# Why unknown-error?
+
+</div>
+
+## The Problem
+
+In TypeScript's `strict` mode, a `catch` variable is `unknown`, and with reason: JavaScript can throw anything. To log it, report it or wrap it, you need an Error, so nearly every codebase ends up with something like this:
+
+```ts
+const toError = (value: unknown): Error =>
+    value instanceof Error ? value : new Error(String(value));
+```
+
+It handles the cases that come to mind first: an Error, or a thrown string. It falls apart on the rest, and it fails inside the `catch` block that was meant to handle the failure.
+
+### Errors from another realm aren't `instanceof Error`
+
+Each realm (a `vm` context, an iframe, some test runners) has its own `Error` class. An Error from another realm fails `instanceof Error`, so the code above turns a perfectly good `TypeError` into `new Error("TypeError: x")`, losing its name, stack, cause and properties.
+
+### Errors that crossed a boundary are plain objects
+
+An error sent through JSON, `postMessage` or an RPC framework arrives as `{ name, message, stack, code }`. `String()` turns it into `Error: [object Object]`.
+
+### Thrown objects become `[object Object]`
+
+`throw { status: 404, reason: 'missing' }` is bad practice, but libraries do it. `String()` loses everything, and `JSON.stringify` throws on circular references and BigInts, which is why most conversions don't use it.
+
+### The handler itself can throw
+
+The thrown value controls what runs when you inspect it. A Proxy can throw from every trap, a `message` getter can throw, and so can `toString` and `toJSON`. `String(value)`, `value.message` and even `value instanceof Error` (which reads the prototype) run that code, so the conversion throws inside your `catch` and replaces the original error with a new one.
+
+### Cause chains and AggregateError are trees
+
+`cause` can be anything, including a non-Error or another realm's Error, and it can be circular. `AggregateError` adds a list of errors at each level. Code that follows `cause` with a `while` loop hangs on a cycle, and code that recurses overflows the call stack on a deep enough chain.
+
+## Why Existing Solutions Fall Short
+
+Every claim below is checked by the [comparison suite](https://github.com/JacobLey/leyman/blob/main/e2e/unknown-error-comparison/test/integration/comparison.spec.ts), which runs each library through the same cases.
+
+- **[`normalize-exception`](https://www.npmjs.com/package/normalize-exception)** comes closest. It handles other realms, error-like objects and hostile values, and normalizes causes and `AggregateError` entries. But it modifies the error you pass in (replacing a non-Error `cause` in place), describes circular objects and objects containing BigInts as `[object Object]`, and recurses, so a 10,000-deep cause chain overflows the stack.
+- **[`ensure-error`](https://www.npmjs.com/package/ensure-error)** uses `instanceof`, so it wraps another realm's Error in a `NonError` whose message is `{}`. It doesn't recognize error-like objects, throws on a Proxy or a throwing `message` getter, and also patches your error in place. It recurses too, and builds a new stack at every level, which gets slow on deep chains when `Error.stackTraceLimit` is raised (as Mocha does).
+- **[`serialize-error`](https://www.npmjs.com/package/serialize-error)** is built to turn errors into JSON and back. Its `deserializeError` rebuilds error-like objects well, but prefixes thrown strings (`Non-error value: boom`), throws on hostile values, and doesn't walk causes.
+- **[`pony-cause`](https://www.npmjs.com/package/pony-cause)** only formats `cause` chains of real Errors: it drops causes that aren't Errors (including other realms' Errors), ignores `AggregateError`, and recurses.
+- **Hand-written conversions** like the one above fail most of these cases, and throw on three of them.
+
+## How unknown-error Is Different
+
+- **Every read is guarded.** Property reads, key listing and stringifying all catch errors from getters and Proxy traps, with fallbacks down to a fixed `[unprintable value]`. No function in the package throws, whatever it's given.
+- **`Error.isError` where it exists.** It recognizes Errors from any realm, and can't be fooled by a Proxy or run any of its traps. Where it's missing (Chrome before 134, Firefox before 138, Safari before 18.4), a guarded `instanceof` and object-tag check takes over.
+- **Your errors are never modified.** An Error is returned as it is. Error-like objects are copied into a new Error, and everything else is wrapped in a `NonError` that keeps the original value as `thrown`.
+- **Readable descriptions.** Non-Errors are described as JSON with circular references marked `[Circular]` and BigInts kept as `1n`, falling back to `toString` and then the object's tag.
+- **A walk, not recursion.** `walkErrors` uses an explicit stack, skips anything it has already visited, and stops at `maxDepth` (32 by default), marking where it stopped. `formatError` is built on it.
+
+## Comparison
+
+From the [comparison suite](https://github.com/JacobLey/leyman/blob/main/e2e/unknown-error-comparison/test/integration/comparison.spec.ts). ✅ handles it, ❌ doesn't, 💥 throws, — has no API for it.
+
+| Case | unknown-error | normalize-exception | ensure-error | serialize-error | pony-cause | Hand-written |
+|---|---|---|---|---|---|---|
+| Uses a thrown string as the message, unchanged | ✅ | ✅ | ❌ quotes it | ❌ prefixes it | — | ✅ |
+| Converts a thrown `null` | ✅ | ✅ | ✅ | ✅ | — | ✅ |
+| Keeps an Error from another realm | ✅ | ✅ | ❌ | ✅ | — | ❌ |
+| Rebuilds an error-like object with its name, message, code and stack | ✅ | ✅ | ❌ | ✅ | — | ❌ |
+| Describes a circular object | ✅ | ❌ | ❌ | ❌ | — | ❌ |
+| Describes an object containing a BigInt | ✅ | ❌ | ❌ | ❌ | — | ❌ |
+| Converts an object whose `toJSON` and `toString` throw | ✅ | ✅ | ✅ | ✅ | — | 💥 |
+| Converts a Proxy that throws from every trap | ✅ | ✅ | 💥 | 💥 | — | 💥 |
+| Reads the message of an Error whose `message` getter throws | ✅ | ✅ | 💥 | 💥 | — | 💥 |
+| Leaves the Error passed in unmodified | ✅ | ❌ | ❌ | ✅ | — | ✅ |
+| Includes a cause that is not an Error | ✅ | ✅ | ✅ | — | ❌ | — |
+| Includes a cause from another realm | ✅ | ✅ | ❌ | — | ❌ | — |
+| Ends a circular cause chain | ✅ | ✅ | ✅ | — | ✅ | — |
+| Includes nested `AggregateError` entries | ✅ | ✅ | ✅ | — | ❌ | — |
+| Handles a 10,000-deep cause chain | ✅ | 💥 | 💥 | — | 💥 | — |
+
+## Design Decisions
+
+- **Rebuild error-like objects, don't wrap them.** An object with a string `message` is almost always an error that lost its prototype on the way (through JSON or `postMessage`), so it becomes a plain `Error` with its name, stack, cause and other properties. Wrapping it in a `NonError` would bury its message in JSON.
+- **Only real Errors match `hasCode`.** It narrows to `Error & { code }`, which would be a lie for a plain object. Convert first, with `hasCode(toError(err), code)`, to match error-like objects.
+- **A depth limit by default.** A cause chain dozens of levels deep is almost always a bug (like an error wrapped on every retry), and printing all of it buries the useful part. `maxDepth` is 32, the walk says where it stopped, and `Infinity` turns the limit off.
+- **A fallback for `Error.isError`, not a requirement.** It is the only way to recognize an Error from another realm without running a Proxy's traps, but browsers only shipped it in 2025 (Chrome 134, Firefox 138, Safari 18.4), so older ones lack it. Without it, `instanceof Error` and the `[object Error]` tag still recognize Errors from any realm, inside a `try` so a Proxy can't make them throw. The cost is that a Proxy around an Error, or an object with a forged `Symbol.toStringTag`, also passes. It is read on every call, so a polyfill loaded later is used.
+
+## Non-Goals
+
+- **Serializing errors.** To send an error over JSON, use [`serialize-error`](https://www.npmjs.com/package/serialize-error). unknown-error rebuilds what it receives on the other side.
+- **Error class hierarchies.** It converts and inspects errors, and has no opinion on how you define them.
+- **Recovering the throw location of non-Errors.** A thrown string has no stack. A `NonError`'s stack points at the `toError` call, the closest place that is known.
+
+Back to the [README](https://www.npmjs.com/package/unknown-error).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './to-error.js';
+export * from './walk.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './to-error.js';
+export * from './walk.js';
+
+//# sourceMappingURL=index.js.map

package/dist/lib/safe.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Helpers that inspect a thrown value without ever throwing themselves.
+ *
+ * Anything can be thrown, including objects with throwing getters, a throwing `toString` and Proxies
+ * that throw from every trap. Every read of a caught value goes through these helpers, so that
+ * handling an error can't raise a new one from inside a `catch`.
+ */
+/**
+ * Whether `value` can have properties: objects, arrays and functions.
+ *
+ * @param value - any value
+ * @returns `true` for non-null objects and functions
+ */
+export declare const isObject: (value: unknown) => value is object;
+/**
+ * Whether `value` is an Error, including one from another realm (`vm`, iframes). Never throws.
+ *
+ * Uses `Error.isError` where the runtime has it, which recognizes every realm's Errors without
+ * running any Proxy trap. It is read on each call rather than once, so a polyfill loaded later is
+ * still used.
+ *
+ * @param value - any value
+ * @returns whether `value` is an Error
+ */
+export declare const isError: (value: unknown) => value is Error;
+/**
+ * Reads a property, returning `undefined` when a getter or Proxy trap throws.
+ *
+ * @param value - object to read from
+ * @param key - property to read
+ * @returns the property's value, or `undefined` if reading it threw
+ */
+export declare const safeGet: (value: object, key: PropertyKey) => unknown;
+/**
+ * Checks for a property (own or inherited), returning `false` when a Proxy `has` trap throws.
+ *
+ * @param value - object to check
+ * @param key - property to look for
+ * @returns whether the property exists
+ */
+export declare const hasProperty: (value: object, key: PropertyKey) => boolean;
+/**
+ * Lists own enumerable string keys, returning none when a Proxy `ownKeys` trap throws.
+ *
+ * @param value - object to list
+ * @returns its keys
+ */
+export declare const safeKeys: (value: object) => string[];
+/**
+ * Describes any value as a string, without throwing.
+ *
+ * @param value - any value
+ * @returns a readable description
+ */
+export declare const safeStringify: (value: unknown) => string;
+//# sourceMappingURL=safe.d.ts.map

package/dist/lib/safe.js

@@ -0,0 +1,88 @@
+export const isObject = (value)=>typeof value === 'object' && value !== null || typeof value === 'function';
+const isErrorFallback = (value)=>{
+    if (!isObject(value)) {
+        return false;
+    }
+    try {
+        return value instanceof Error || Object.prototype.toString.call(value) === '[object Error]';
+    } catch  {
+        return false;
+    }
+};
+export const isError = (value)=>{
+    const native = Error.isError;
+    return typeof native === 'function' ? native(value) : isErrorFallback(value);
+};
+export const safeGet = (value, key)=>{
+    try {
+        return Reflect.get(value, key);
+    } catch  {
+        return undefined;
+    }
+};
+export const hasProperty = (value, key)=>{
+    try {
+        return Reflect.has(value, key);
+    } catch  {
+        return false;
+    }
+};
+export const safeKeys = (value)=>{
+    try {
+        return Object.keys(value);
+    } catch  {
+        return [];
+    }
+};
+const toJson = (value)=>{
+    const ancestors = [];
+    return JSON.stringify(value, function(_key, nested) {
+        if (typeof nested === 'bigint') {
+            return `${nested}n`;
+        }
+        if (!isObject(nested)) {
+            return nested;
+        }
+        while(ancestors.length > 0 && ancestors.at(-1) !== this){
+            ancestors.pop();
+        }
+        if (ancestors.includes(nested)) {
+            return '[Circular]';
+        }
+        ancestors.push(nested);
+        return nested;
+    });
+};
+const stringifyObject = (value)=>{
+    try {
+        const json = toJson(value);
+        if (json !== undefined) {
+            return json;
+        }
+    } catch  {}
+    try {
+        return String(value);
+    } catch  {}
+    try {
+        return Object.prototype.toString.call(value);
+    } catch  {}
+    return '[unprintable value]';
+};
+export const safeStringify = (value)=>{
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'bigint') {
+        return `${value}n`;
+    }
+    if (typeof value === 'function') {
+        const name = safeGet(value, 'name');
+        return typeof name === 'string' && name ? `[Function ${name}]` : '[Function (anonymous)]';
+    }
+    if (isObject(value)) {
+        return stringifyObject(value);
+    }
+    return String(value);
+};
+
+//# sourceMappingURL=safe.js.map

package/dist/lib/to-error.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Wraps a thrown value that was neither an Error nor shaped like one.
+ *
+ * The message describes the value, and the value itself is kept as `thrown`.
+ */
+export declare class NonError extends Error {
+    readonly thrown: unknown;
+    /**
+     * @param thrown - the value that was thrown
+     * @param options - standard Error options, such as `cause`
+     */
+    constructor(thrown: unknown, options?: ErrorOptions);
+}
+/**
+ * Converts any caught value to an Error. Never throws.
+ *
+ * - Errors, including those from another realm (`vm`, iframes), are returned as-is.
+ * - Objects with a string `message` are rebuilt as an Error, keeping their name, stack, cause and
+ *   other properties such as `code`.
+ * - Anything else is wrapped in a {@link NonError}.
+ *
+ * @param value - a caught value
+ * @returns `value` when it is already an Error, otherwise a new Error describing it
+ */
+export declare const toError: (value: unknown) => Error;
+/**
+ * Reads the message of any caught value. Never throws.
+ *
+ * @param value - a caught value
+ * @returns the message of `toError(value)`
+ */
+export declare const getErrorMessage: (value: unknown) => string;
+/**
+ * Whether `value` is an Error with the given `code`, such as Node's `ENOENT`.
+ *
+ * @param value - a caught value
+ * @param code - code to match
+ * @returns `true` when `value` is an Error whose `code` is `code`, narrowing its type
+ */
+export declare const hasCode: <const Code extends number | string>(value: unknown, code: Code) => value is Error & {
+    readonly code: Code;
+};
+//# sourceMappingURL=to-error.d.ts.map

package/dist/lib/to-error.js

@@ -0,0 +1,59 @@
+import { hasProperty, isError, isObject, safeGet, safeKeys, safeStringify } from '#safe';
+const MAX_MESSAGE_LENGTH = 1000;
+export class NonError extends Error {
+    thrown;
+    constructor(thrown, options){
+        const message = safeStringify(thrown);
+        super(message.length > MAX_MESSAGE_LENGTH ? `${message.slice(0, MAX_MESSAGE_LENGTH)}…` : message, options);
+        this.name = 'NonError';
+        this.thrown = thrown;
+    }
+}
+const fromErrorLike = (value, message)=>{
+    const error = hasProperty(value, 'cause') ? new Error(message, {
+        cause: safeGet(value, 'cause')
+    }) : new Error(message);
+    const name = safeGet(value, 'name');
+    if (typeof name === 'string') {
+        error.name = name;
+    }
+    const stack = safeGet(value, 'stack');
+    if (typeof stack === 'string') {
+        error.stack = stack;
+    }
+    for (const key of safeKeys(value)){
+        if (!Reflect.has(error, key)) {
+            Object.defineProperty(error, key, {
+                configurable: true,
+                enumerable: true,
+                value: safeGet(value, key),
+                writable: true
+            });
+        }
+    }
+    return error;
+};
+export const toError = (value)=>{
+    if (isError(value)) {
+        return value;
+    }
+    if (isObject(value)) {
+        const message = safeGet(value, 'message');
+        if (typeof message === 'string') {
+            return fromErrorLike(value, message);
+        }
+    }
+    return new NonError(value);
+};
+export const getErrorMessage = (value)=>{
+    const error = toError(value);
+    try {
+        const { message } = error;
+        return typeof message === 'string' ? message : safeStringify(message);
+    } catch  {
+        return '[unreadable message]';
+    }
+};
+export const hasCode = (value, code)=>isError(value) && safeGet(value, 'code') === code;
+
+//# sourceMappingURL=to-error.js.map

package/dist/lib/walk.d.ts

@@ -0,0 +1,61 @@
+/**
+ * How an error relates to the one above it in the tree.
+ */
+export type ErrorRelation = 'aggregate' | 'cause' | 'root';
+/**
+ * One error in the tree that `walkErrors` visits.
+ */
+export interface ErrorNode {
+    /**
+     * The value, converted with `toError`.
+     */
+    readonly error: Error;
+    /**
+     * Distance from the root, which is `0`.
+     */
+    readonly depth: number;
+    /**
+     * `root` for the value passed in, `cause` for an error's `cause`, `aggregate` for an entry in an
+     * error's `errors` (as on `AggregateError`).
+     */
+    readonly relation: ErrorRelation;
+    /**
+     * `true` when `maxDepth` stopped the walk here, so this error's own cause and errors were skipped.
+     */
+    readonly truncated: boolean;
+}
+/**
+ * Options for `walkErrors` and `formatError`.
+ */
+export interface WalkOptions {
+    /**
+     * Deepest level to visit. The root is level `0`.
+     *
+     * @default 32
+     */
+    readonly maxDepth?: number;
+}
+/**
+ * Visits an error, its `cause` chain and the `errors` of any `AggregateError`, depth first. Never
+ * throws.
+ *
+ * Every value is converted with `toError`, so a cause that isn't an Error still appears. A value
+ * already visited is skipped, so a circular chain ends.
+ *
+ * @param value - a caught value
+ * @param options - {@link WalkOptions}
+ * @yields {ErrorNode} each error in the tree, starting with `value` itself
+ */
+export declare const walkErrors: (value: unknown, options?: WalkOptions) => Generator<ErrorNode, void, undefined>;
+/**
+ * Formats an error with every cause and `AggregateError` entry, indented by depth. Never throws.
+ *
+ * Each error is printed as its stack, with causes labelled `Caused by:` and `AggregateError` entries
+ * labelled `-`.
+ *
+ * @param value - a caught value
+ * @param options - {@link WalkOptions}
+ * @returns a multi-line report
+ */
+export declare const formatError: (value: unknown, options?: WalkOptions) => string;
+//# sourceMappingURL=walk.d.ts.map

package/dist/lib/walk.js

@@ -0,0 +1,88 @@
+import { hasProperty, isObject, safeGet, safeStringify } from '#safe';
+import { getErrorMessage, toError } from '#to-error';
+const DEFAULT_MAX_DEPTH = 32;
+const INDENT_WIDTH = 4;
+const childrenOf = (error, depth)=>{
+    const children = [];
+    if (hasProperty(error, 'cause')) {
+        children.push({
+            depth,
+            relation: 'cause',
+            value: safeGet(error, 'cause')
+        });
+    }
+    const errors = safeGet(error, 'errors');
+    try {
+        if (Array.isArray(errors)) {
+            for (const value of errors){
+                children.push({
+                    depth,
+                    value,
+                    relation: 'aggregate'
+                });
+            }
+        }
+    } catch  {}
+    return children;
+};
+export const walkErrors = function*(value, options = {}) {
+    const { maxDepth = DEFAULT_MAX_DEPTH } = options;
+    const seen = new WeakSet();
+    const pending = [
+        {
+            depth: 0,
+            relation: 'root',
+            value
+        }
+    ];
+    for(let next = pending.pop(); next; next = pending.pop()){
+        if (isObject(next.value)) {
+            if (seen.has(next.value)) {
+                continue;
+            }
+            seen.add(next.value);
+        }
+        const error = toError(next.value);
+        const children = childrenOf(error, next.depth + 1);
+        const isTruncated = next.depth >= maxDepth && children.length > 0;
+        yield {
+            error,
+            depth: next.depth,
+            relation: next.relation,
+            truncated: isTruncated
+        };
+        if (!isTruncated) {
+            pending.push(...children.toReversed());
+        }
+    }
+};
+const labels = {
+    aggregate: '- ',
+    cause: 'Caused by: ',
+    root: ''
+};
+const describe = (error)=>{
+    const name = safeGet(error, 'name');
+    const message = getErrorMessage(error);
+    const nameText = typeof name === 'string' ? name : safeStringify(name);
+    const header = message ? `${nameText}: ${message}` : nameText;
+    const stack = safeGet(error, 'stack');
+    if (typeof stack !== 'string' || stack === '') {
+        return header;
+    }
+    return stack.startsWith(header) ? stack : `${header}\n${stack}`;
+};
+export const formatError = (value, options = {})=>{
+    const lines = [];
+    for (const { error, depth, relation, truncated } of walkErrors(value, options)){
+        const indent = ' '.repeat(INDENT_WIDTH * depth);
+        const [first = '', ...rest] = describe(error).split('\n');
+        lines.push(`${indent}${labels[relation]}${first}`, ...rest.map((line)=>indent + line));
+        if (truncated) {
+            lines.push(`${indent}    … more causes omitted (maxDepth: ${depth})`);
+        }
+    }
+    return lines.join('\n');
+};
+
+//# sourceMappingURL=walk.js.map

package/dist/to-error.d.ts

@@ -0,0 +1,2 @@
+export { getErrorMessage, hasCode, NonError, toError } from '#to-error';
+//# sourceMappingURL=to-error.d.ts.map

package/dist/to-error.js

@@ -0,0 +1,3 @@
+export { getErrorMessage, hasCode, NonError, toError } from '#to-error';
+
+//# sourceMappingURL=to-error.js.map

package/dist/walk.d.ts

@@ -0,0 +1,3 @@
+export { formatError, walkErrors } from '#walk';
+export type { ErrorNode, ErrorRelation, WalkOptions } from '#walk';
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.js

@@ -0,0 +1,3 @@
+export { formatError, walkErrors } from '#walk';
+
+//# sourceMappingURL=walk.js.map

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "unknown-error",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Turn any caught `unknown` into a real Error without throwing, even for hostile values, other realms and deep or circular cause chains",
+  "engines": {
+    "node": ">=24"
+  },
+  "type": "module",
+  "author": "JacobLey",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JacobLey/leyman.git",
+    "directory": "tools/unknown-error"
+  },
+  "homepage": "https://github.com/JacobLey/leyman/tree/main/tools/unknown-error#readme",
+  "bugs": {
+    "url": "https://github.com/JacobLey/leyman/issues"
+  },
+  "keywords": [
+    "error",
+    "unknown",
+    "catch",
+    "normalize",
+    "to-error",
+    "error-message",
+    "cause",
+    "aggregate-error",
+    "typescript"
+  ],
+  "sideEffects": false,
+  "types": "./dist/index.js",
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/tsconfig.tsbuildinfo",
+    "WHY-UNKNOWN-ERROR.md"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "imports": {
+    "#safe": "./dist/lib/safe.js",
+    "#to-error": "./dist/lib/to-error.js",
+    "#walk": "./dist/lib/walk.js"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.14",
+    "@leyman/eslint-config": "^0.0.1",
+    "@leyman/expect": "^0.0.1",
+    "@swc/cli": "^0.8.1",
+    "@swc/core": "^1.16.2",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^24.19.0",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "c8": "^12.0.0",
+    "eslint": "^10.12.0",
+    "expect-type": "^1.4.0",
+    "mocha": "^12.0.2",
+    "mocha-chain": "^1.0.1",
+    "npm-barrelify": "npm:barrelify@^1.3.3",
+    "typescript": "npm:@typescript/typescript6@^6.0.2"
+  }
 }