unknown-error 0.0.1 → 0.1.1

package/README.md

@@ -14,16 +14,7 @@ Turn any caught `unknown` into a real Error without throwing, even for hostile v
 - **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).
+Guides and the full reference are on the [docs site](https://jacobley.github.io/leyman/packages/unknown-error/). For why it exists and the design decisions behind it, see [WHY-UNKNOWN-ERROR.md](https://github.com/JacobLey/leyman/blob/main/tools/unknown-error/WHY-UNKNOWN-ERROR.md).
 
 ## Contents
 - [Install](#install)
@@ -36,6 +27,7 @@ For the problems with hand-written conversions, the full comparison and design d
   - [`NonError`](#nonerror)
   - [`walkErrors(value, options?)`](#walkerrorsvalue-options)
   - [`formatError(value, options?)`](#formaterrorvalue-options)
+- [Compared to alternatives](#compared-to-alternatives)
 
 ## Install
 
@@ -94,7 +86,19 @@ 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.
+An error-like object without a `stack` gets a stack pointing at the `toError` call, since the original location is unknown. Properties the new Error already has, own or inherited, are not copied, so a JSON-parsed `"__proto__"` key can't replace its prototype.
+
+A [`NonError`](#nonerror) message describes the value as follows:
+
+| Value | Message |
+|-------|---------|
+| String | The string itself |
+| `null`, `undefined`, number, boolean, symbol | `String(value)`, like `'null'` or `'Symbol(id)'` |
+| BigInt | `'10n'` |
+| Function | `'[Function name]'`, never its source |
+| Object or array | JSON, with circular references as `"[Circular]"` and BigInts as `"10n"` |
+
+When an object's JSON is empty (`toJSON` returns `undefined`) or throws, the message falls back to `String(value)`, then to the object's tag (`[object Object]`), and finally to `[unprintable value]`.
 
 ### `getErrorMessage(value)`
 
@@ -143,14 +147,14 @@ Only real Errors match. To match error-like objects too, convert them first: `ha
 
 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.
+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. Primitives have no identity, so the same string can be visited more than once.
 
 | 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>`.
+**Returns** `Generator<ErrorNode, void, undefined>`. The option and node types are exported as `WalkOptions`, `ErrorNode` and `ErrorRelation`.
 
 #### `ErrorNode`
 
@@ -188,3 +192,16 @@ console.log(formatError(new Error('request failed', { cause: new Error('ECONNREF
 ```
 
 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.
+
+## Compared to alternatives
+
+| | 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 | ✅ | ❌ | ❌ | — | ❌ |
+
+Each cell is checked by a [comparison test suite](https://github.com/JacobLey/leyman/blob/main/e2e/unknown-error-comparison/test/integration/comparison.spec.ts). For every case, and where hand-written conversions fall short, see [WHY-UNKNOWN-ERROR.md](https://github.com/JacobLey/leyman/blob/main/tools/unknown-error/WHY-UNKNOWN-ERROR.md#comparison).

package/WHY-UNKNOWN-ERROR.md

@@ -6,14 +6,14 @@
 
 ## 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:
+In TypeScript's `strict` mode, a `catch` variable is `unknown`, because 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.
+It handles the cases that come to mind first: an Error, or a thrown string. It fails on anything else, and throws inside the `catch` block that was meant to handle the error.
 
 ### Errors from another realm aren't `instanceof Error`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unknown-error",
-  "version": "0.0.1",
+  "version": "0.1.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"
@@ -13,7 +13,7 @@
     "url": "git+https://github.com/JacobLey/leyman.git",
     "directory": "tools/unknown-error"
   },
-  "homepage": "https://github.com/JacobLey/leyman/tree/main/tools/unknown-error#readme",
+  "homepage": "https://jacobley.github.io/leyman/packages/unknown-error/",
   "bugs": {
     "url": "https://github.com/JacobLey/leyman/issues"
   },
@@ -49,16 +49,16 @@
     "@leyman/eslint-config": "^0.0.1",
     "@leyman/expect": "^0.0.1",
     "@swc/cli": "^0.8.1",
-    "@swc/core": "^1.16.2",
+    "@swc/core": "^1.16.18",
     "@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",
+    "eslint": "^10.13.0",
     "expect-type": "^1.4.0",
-    "mocha": "^12.0.2",
-    "mocha-chain": "^1.0.1",
-    "npm-barrelify": "npm:barrelify@^1.3.3",
+    "mocha": "^12.0.3",
+    "mocha-chain": "^1.0.2",
+    "npm-barrelify": "npm:barrelify@^2.2.1",
     "typescript": "npm:@typescript/typescript6@^6.0.2"
   }
 }