@owlmeans/error 0.1.18-rc.2 → 0.1.18-rc.21

package/README.md

@@ -1,78 +1,264 @@
 # @owlmeans/error
 
-Serializable error base class with type registration for cross-process error propagation.
-
-## Overview
-
-- `ResilientError` base class survives JSON serialization/deserialization across service boundaries
-- Error class registry ensures custom error types are correctly reconstructed after transport
-- Helpers for marshaling errors to strings and back
+Serializable error base class with a type registry, so a typed error thrown in one process is
+caught as the same class in another. An app uses it for every error that has to cross a service
+boundary (HTTP, socket, queue) or reach a UI as a translated message: declare a `ResilientError`
+subclass, register it in the shared module both sides import, and normalize whatever you catch
+with `ResilientError.ensure`. It is not for wiring faults — an unknown alias or a missing service
+is a `SyntaxError` that must crash the process. Before declaring a new family, reuse the ones
+framework packages already ship: authentication and authorization failures from
+[`@owlmeans/auth`](../auth), storage failures from [`@owlmeans/resource`](../resource).
 
 ## Installation
 
 ```bash
-bun add @owlmeans/error
+bun add @owlmeans/error@^0.1.18-rc.18
 ```
 
+## Concepts
+
+- **Resilient error** — a `ResilientError` carries a `type` (the class's static `typeName`) next to
+  its `message`; the pair identifies the failure anywhere it travels.
+- **Error family** — a base subclass that prefixes every message (`invoice:`) and subclasses that
+  add their own prefix and re-stamp `type`, so the final message reads `invoice:not-found:<id>`.
+- **Registry** — `ResilientError.converters`, filled by `registerErrorClass`; only a registered
+  class comes back as itself after transport.
+- **Marshalling** — `marshal` flattens `type`, `message` and the original stack into one plain
+  `Error` whose message is joined by `SEPARATOR` (`|||`); `ensure` recognises that prefix and
+  rebuilds the registered class.
+- **Errors namespace** — importing the package registers the `errors` i18n library; UIs resolve a
+  message by the error's `type`, never by the thrown string.
+
 ## Usage
 
-Define and register a custom error type:
+### Declare and register an error family
 
-```typescript
+Keep errors in the shared (`common`) module that both the server and the client import, and
+register every class at module load.
+
+```ts
 import { ResilientError } from '@owlmeans/error'
 
-export class ProjectResourceError extends ResilientError {
-  static typeName = 'viable-project:error'
+export class InvoiceError extends ResilientError {
+  public static override typeName = 'MyAppInvoiceError'
+
+  constructor(message: string = 'error') {
+    super(InvoiceError.typeName, `invoice:${message}`)
+  }
+}
+
+export class InvoiceNotFound extends InvoiceError {
+  public static override typeName = `NotFound${InvoiceError.typeName}`
+
+  constructor(message: string = 'error') {
+    super(`not-found:${message}`)
+    this.type = InvoiceNotFound.typeName
+  }
+}
+
+export class InvoiceLocked extends InvoiceError {
+  public static override typeName = `Locked${InvoiceError.typeName}`
 
   constructor(message: string = 'error') {
-    super(`viable-project:${message}`)
-    this.type = ProjectResourceError.typeName
+    super(`locked:${message}`)
+    this.type = InvoiceLocked.typeName
   }
 }
 
-ResilientError.registerErrorClass(ProjectResourceError)
+ResilientError.registerErrorClass(InvoiceError)
+ResilientError.registerErrorClass(InvoiceNotFound)
+ResilientError.registerErrorClass(InvoiceLocked)
+
+throw new InvoiceNotFound('inv-42') // message: 'invoice:not-found:inv-42'
 ```
 
-Marshal errors across service boundaries:
+A subclass of a subclass calls `super` with the message alone — the parent adds its own prefix and
+`type`, so the subclass re-stamps `this.type` afterwards.
+
+### Normalize what you caught
 
-```typescript
-import { marshalError, ResilientError } from '@owlmeans/error'
+`ensure` accepts an `Error` or a string and always returns a `ResilientError`, so a handler can
+branch on the registered classes it knows and fall through for the rest.
 
-// Server side: serialize for transport
-const serialized = marshalError(caughtError)
+```ts
+import { ResilientError } from '@owlmeans/error'
+import { InvoiceLocked, InvoiceNotFound } from '@my-app/common'
 
-// Client side: reconstruct the typed error
-const restored = ResilientError.ensure(receivedError)
+export const settle = async (invoiceId: string) => {
+  try {
+    await payInvoice(invoiceId)
+  } catch (e) {
+    const err = ResilientError.ensure(e as Error)
+    if (err instanceof InvoiceNotFound || err instanceof InvoiceLocked) {
+      return { settled: false, reason: err.type }
+    }
+    throw err
+  }
+}
 ```
 
-## API
+A small helper keeps catch blocks typed when the caught value is `unknown`:
+
+```ts
+import { ResilientError } from '@owlmeans/error'
+
+export const asError = <T extends ResilientError>(err: unknown): T =>
+  typeof err === 'string' || err instanceof Error
+    ? ResilientError.ensure(err) as T
+    : ResilientError.ensure(`Unknown error ${String(err)}`) as T
+```
+
+### Cross a service boundary
+
+The HTTP transports already do this: `@owlmeans/server-api` answers a thrown error with
+`ResilientError.marshal(ResilientError.ensure(error)).message` as the body, and `@owlmeans/api`
+turns a string body back into the registered class with `ResilientError.ensure`. So a backend throw
+is caught as the same class around `context.entrypoint(invoiceProtocols.settle).call(...)` in the
+client. A boundary you own — a WebSocket close reason, a stored failure record — does the same by hand:
+
+```ts
+import { enuserError, marshalError } from '@owlmeans/error'
+import { InvoiceError } from '@my-app/common'
+
+// Producer: send only the flattened string.
+socket.close(1011, marshalError(caught).message)
+
+// Consumer: rebuild the registered class, typed to the family you expect.
+socket.addEventListener('close', event => {
+  const err = enuserError<InvoiceError>(event.reason)
+  if (err instanceof InvoiceError) {
+    showInvoiceProblem(err.type)
+  }
+})
+```
+
+The round trip is worth a test for any error whose identity the far side depends on:
+
+```ts
+import { expect, test } from 'bun:test'
+import { ResilientError } from '@owlmeans/error'
+import { InvoiceNotFound } from '@my-app/common'
+
+test('an invoice miss survives the hop as its own class', () => {
+  const restored = ResilientError.ensure(
+    ResilientError.marshal(new InvoiceNotFound('inv-42')).message
+  )
 
-### `ResilientError`
+  expect(restored).toBeInstanceOf(InvoiceNotFound)
+  expect(restored.message).toBe('invoice:not-found:inv-42')
+})
+```
 
-Base class for all OwlMeans errors.
+### Rebuild state after unmarshalling
 
-- `static typeName: string` — override in subclasses to identify the error type
-- `static registerErrorClass(cls)` — register a subclass for automatic reconstruction from JSON
-- `static ensure(err, throwOnUnknown?)` — convert any error to `ResilientError`
-- `static marshal(err)` — serialize an error to a transportable `Error` object
-- `type: string` — error type identifier set in the constructor
+Only `type`, `message` and the stack travel. A subclass that exposes structured data derives it
+from the message in `finalizeUnmarshal()`, which runs after the message is restored.
 
-### `marshalError(err): Error`
+```ts
+import { ResilientError } from '@owlmeans/error'
 
-Convenience: ensures the error is a `ResilientError`, then marshals it.
+export class QuotaExceeded extends ResilientError {
+  public static override typeName = 'MyAppQuotaExceeded'
+
+  public limit?: number
+
+  constructor(message: string = 'error') {
+    super(QuotaExceeded.typeName, `quota:${message}`)
+    this.finalizeUnmarshal()
+  }
+
+  override finalizeUnmarshal(): void {
+    const tail = Number(this.message.split(':').pop())
+    this.limit = Number.isFinite(tail) ? tail : undefined
+  }
+}
 
-### `enuserError<T>(err): T`
+ResilientError.registerErrorClass(QuotaExceeded)
+```
 
-Ensures an unknown caught value is a `ResilientError`. Alias for `ResilientError.ensure`.
+### Translate errors in the UI
 
-### `ValueOrError<T>`
+Panel components resolve an error through `errors.<type>` — a form- or screen-scoped
+`<name>.errors.<type>` key first, then `errors.<type>` in the screen's namespace, then the shared
+`errors` library. Ship a translation for every type you declare, in every supported language:
 
-```typescript
-type ValueOrError<T> = T | ResilientError
+```json
+{
+  "errors": {
+    "MyAppInvoiceError": "The invoice could not be processed",
+    "NotFoundMyAppInvoiceError": "This invoice no longer exists",
+    "LockedMyAppInvoiceError": "The invoice is being settled, try again shortly"
+  }
+}
 ```
 
-## Related Packages
+## API
+
+### Classes
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `ResilientError` | class | Base class of every framework error; `constructor(type, message, stack?)` |
+| `ResilientError.typeName` | static property | Type identifier; override in each subclass (`'ResilientError'` on the base) |
+| `ResilientError.separator` | static property | Marshalling separator, initialised from `SEPARATOR` |
+| `ResilientError.converters` | static property | The registry of `Converter` entries |
+| `ResilientError.registerErrorClass(Class, errorClass?)` | static method | Registers a subclass so it survives a round trip; returns its `Converter` |
+| `ResilientError.ensure(err, throwOnUnknown?)` | static method | Turns an `Error` or string into a `ResilientError`, unmarshalling registered classes |
+| `ResilientError.marshal(err)` | static method | Flattens an error into a plain `Error` whose message is `type`, `message` and stack joined by `SEPARATOR` |
+| `error.type` | instance property | The error's type identifier |
+| `error.oiriginalStack` | instance property | The stack captured at the original throw (spelling as in source) |
+| `error.marshal()` | instance method | `ResilientError.marshal(this)` |
+| `error.finalizeUnmarshal()` | instance method | Hook run after unmarshalling; no-op by default |
+
+### Functions and constants
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `enuserError<T>(err, throwOnUnknown?)` | function | `ResilientError.ensure`, typed to the subclass you expect |
+| `marshalError(err)` | function | `ensure` then `marshal`, for a boundary that only carries an `Error` or a string |
+| `SEPARATOR` | constant | Three pipe characters — joins the marshalled fields |
+| `RESILENT_ERROR` | constant | `'ResilientError'` — the base type name |
+
+### Types
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `ValueOrError<T>` | type | `T \| ResilientError`, for a result that carries either |
+| `Converter` | interface | `{ match, convert, isMarshaled, unmarshal }` — one registry entry |
+| `ResilientErrorConstructor<T>` | interface | The constructor shape `registerErrorClass` accepts: `new (message, stack?)` plus `typeName` |
+
+### Side effect
+
+Importing the package registers the `errors` i18n library (via `addI18nLib` from
+`@owlmeans/i18n`) for `en`, `pl`, `ru`, `be`, `uk`, `es` and `de`. There are no subpath exports.
+
+## Common pitfalls
+
+- Register every subclass. An unregistered error comes back as a bare `ResilientError` whose
+  `type` is the whole `Type|||message|||stack` string.
+- `ensure` on an unregistered, unmarshalled throw shifts the fields: `new Error('boom')` arrives
+  with `type: 'boom'` and the stack as its `message`. Read `.type` only on errors that came back
+  through the registered path.
+- `SyntaxError` is rethrown by `ensure`, never converted. Do not throw one for a runtime condition a
+  caller is expected to handle.
+- The second argument of `registerErrorClass` and `ensure`'s `throwOnUnknown` have no effect — a
+  catch-all converter is matched first. Register the class alone and treat `ensure` as one-argument.
+- A subclass constructor must accept `(message, stack?)`: unmarshalling calls `new Class(message,
+  stack)`. Keep extra state in the message and rebuild it in `finalizeUnmarshal()`.
+- Registration happens at import time. The module declaring the errors must be loaded on the
+  receiving side before an error is ensured, or the class cannot be rebuilt.
+- Keep `typeName` unique per process; show users the translation of `errors.<type>`, never the
+  thrown message.
+
+## Related packages
 
+- [`@owlmeans/i18n`](../i18n) — the registry the `errors` library is added to
+- [`@owlmeans/client-i18n`](../client-i18n) — React hooks that resolve `errors.<type>` keys
+- [`@owlmeans/auth`](../auth) — the authentication and authorization error hierarchy
+- [`@owlmeans/resource`](../resource) — resource errors built on `ResilientError`
+- [`@owlmeans/server-api`](../server-api) — marshals thrown errors into HTTP responses
+- [`@owlmeans/api`](../api) — rebuilds marshalled errors from HTTP responses
+- [`@owlmeans/client-panel`](../client-panel) — panel and form components that translate errors by type
 - [`@owlmeans/context`](../context) — context and services that propagate errors through the app
 
 <!-- owlmeans:agent-guidance:start -->
@@ -83,7 +269,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.25
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/error",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.513Z",
+  "version": "0.1.18-rc.21",
+  "generatedAt": "2026-09-15T13:06:05.536Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/error/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: error
-description: How to use @owlmeans/error — base error classes (ResilientError), error normalization, and i18n-aware error types. Auto-invoked when importing from this package or throwing/catching framework errors.
+description: How to use @owlmeans/error — ResilientError, the error class registry, marshalling errors across a service boundary and back, and the i18n namespace error messages resolve through. Auto-invoked when importing from this package, declaring a typed framework error, or normalizing a caught error.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,44 +8,111 @@ user-invocable: false
 # @owlmeans/error
 
 **Layer:** Core
-**Install:** `"@owlmeans/error": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/error": "^0.1.18-rc.21"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `ResilientError` | Base error class — all framework errors extend this |
-| `ErrorNormalizer` | Normalize unknown errors into ResilientError instances |
-| `ErrorTypes` | Built-in error type aliases |
-| i18n helpers | Resolve error messages through the i18n layer |
+| `ResilientError` | Base class — every framework error extends it |
+| `ResilientError.registerErrorClass(Class)` | Register a subclass so it survives a round trip |
+| `ResilientError.ensure(err)` | Turn anything caught into a `ResilientError` |
+| `ResilientError.marshal(err)` / `err.marshal()` | Flatten into a plain `Error` a transport can carry |
+| `enuserError(err)` | `ensure`, typed to the subclass you expect |
+| `marshalError(err)` | `ensure` then `marshal`, for a boundary that only sends `Error` |
+| `SEPARATOR` (`'\|\|\|'`), `RESILENT_ERROR` | The marshalling separator and the base type name |
+| `Converter` | `{ match, convert, isMarshaled, unmarshal }` — one registry entry |
+| `ResilientErrorConstructor` | The constructor shape `registerErrorClass` accepts |
+| `ValueOrError<T>` | `T \| ResilientError`, for a result that carries either |
 
-## Usage
+## Declaring an error
 
-Subclass `ResilientError` for typed framework errors with i18n-resolvable messages:
+A subclass owns a static `typeName` and prefixes its messages, so the pair `type` + `message` is
+enough to identify what went wrong anywhere the error travels. **Register it** — registration is
+what makes a marshaled error come back as the class it was thrown as. Skip it and the far side gets
+an unusable `ResilientError` whose `type` is the whole marshaled string (see below).
 
 ```typescript
 import { ResilientError } from '@owlmeans/error'
 
-export class AgentApiError extends ResilientError {
-  public static override typeName = 'AgentApiError'
-  public constructor(message: string = 'unknown') {
-    super(AgentApiError.typeName, `agent-api:${message}`)
+export class ApiError extends ResilientError {
+  public static override typeName = 'ApiError'
+
+  constructor(message: string = 'error') {
+    super(ApiError.typeName, `api:${message}`)
+  }
+}
+
+export class RateLimitError extends ApiError {
+  public static override typeName = `${ApiError.typeName}:RateLimit`
+
+  constructor(message: string = 'error') {
+    super(`rate-limit:${message}`)
+    this.type = RateLimitError.typeName
   }
 }
 
-// In a handler:
-throw new AgentApiError('rate-limited')
+ResilientError.registerErrorClass(ApiError)
+ResilientError.registerErrorClass(RateLimitError)
+
+throw new RateLimitError('per-minute')
 ```
 
-Catch and normalize:
+A subclass of a subclass calls `super` with the message alone and then re-stamps `this.type` — the
+parent supplies its own prefix, so the final message reads `api:rate-limit:per-minute`.
+
+`registerErrorClass` takes a second, native-class argument, and `ensure` takes a second
+`throwOnUnknown` argument. **Neither has any effect** — a catch-all converter is pushed onto the
+registry when this package loads and it is the first entry `ensure` tests for conversion, so no
+later converter and no `throwOnUnknown` branch is ever reached. Register the class alone, and treat
+`ensure` as taking one argument.
+
+## Normalizing what you caught
+
+`ensure` gives you a `ResilientError` for anything caught, but only a **registered, marshaled**
+error survives with its identity intact. Route errors that must keep their type through
+`marshal`/`ensure`; do not rely on `ensure` alone to normalize an arbitrary throw.
+
 ```typescript
-import { ErrorNormalizer } from '@owlmeans/error'
-try { ... } catch (e) {
-  const err = ErrorNormalizer.normalize(e)
-  // err is now a ResilientError with stable .type and .message
+try { /* ... */ } catch (e) {
+  const err = ResilientError.ensure(e as Error)
+  if (err instanceof RateLimitError) { /* the registered class came back */ }
 }
 ```
 
+What `ensure` actually does, in order:
+
+| Input | Result |
+|-------|--------|
+| A `ResilientError` | returned untouched |
+| A `SyntaxError` | rethrown — never converted |
+| An `Error` marshaled from a **registered** class | unmarshaled into that class, `type` and `message` restored |
+| Anything else | a bare `ResilientError` whose **`type` is the original `message`** and whose **`message` is the original stack** |
+
+That last row is the trap: the fields are shifted, so an unregistered marshaled error arrives with
+`type` set to the whole `Type|||message|||stack` string, and a plain `new Error('boom')` arrives with
+`type: 'boom'`. Read `.type` only where the error came back through the registered path; keep the
+original around when you need its message.
+
+**`SyntaxError` is never converted — it is rethrown.** A `SyntaxError` in this framework means the
+process is wired wrong (an unknown alias, a missing service, a route cycle), and it must crash
+rather than reach a user as a handled failure. Do not throw one for a runtime condition a caller is
+expected to handle.
+
+## Crossing a service boundary
+
+`marshal` flattens `type`, `message` and the original stack into one `Error` message joined by
+`SEPARATOR`. On the far side `ensure` recognises the prefix and rebuilds the registered class, so a
+typed error thrown in a backend is caught as the same class in a client. Override
+`finalizeUnmarshal()` on a subclass that needs to rebuild state from its message after that.
+
+## Messages are i18n keys
+
+Importing this package registers the `errors` translation library for every bundled locale. UIs
+resolve an error by its `type` — `errors.<type>`, with a form- or screen-scoped key tried first —
+so the message a user reads comes from the translations, never from the thrown string. Ship a
+translation for each error type you declare.
+
 ## Depends On
 
-- `@owlmeans/i18n` — for resolving error messages by key
+- `@owlmeans/i18n` — the translation library the `errors` namespace is registered in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/error",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18-rc.21",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@owlmeans/i18n": "^0.1.18-rc.2"
+    "@owlmeans/i18n": "^0.1.18-rc.21"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",