229 lines
14 KiB
Markdown
229 lines
14 KiB
Markdown
# error
|
|
|
|
## Purpose
|
|
|
|
Foundation error substrate for the Suaveplan monorepo — `SuaveplanError` base class, stable code registry via `defineCodes`, cause-chain traversal, Zod-validated wire format (JSON + binary), redaction at the serialization boundary, OTel span-event adapter, and i18n resolver hook. Has zero `@suaveplan/*` runtime dependencies (carve-out for the types-only `@suaveplan/types`).
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Zero workspace and runtime dependencies
|
|
|
|
The `@suaveplan/error` package's `dependencies` MUST be limited to `tslib`, `zod`, and `@suaveplan/types`. No `peerDependencies`. No other `@suaveplan/*` packages at runtime. The `@suaveplan/types` carve-out is permitted exclusively because it ships zero runtime code (types-only build, byte-size guarded by its own conformance test) and therefore cannot reintroduce the circular foundation-of-foundations hazard the rule otherwise prevents.
|
|
|
|
**Verified by:** `tests/no-disallowed.test.ts` and the `package.json` dep-set under `bunx turbo ls --filter=@suaveplan/error...`.
|
|
|
|
#### Scenario: Dep-graph guard
|
|
|
|
- **WHEN** `bunx turbo ls --filter=@suaveplan/error...` is run
|
|
- **THEN** the only `@suaveplan/*` packages in the forward closure are `@suaveplan/error` itself and `@suaveplan/types`
|
|
|
|
#### Scenario: No Node / browser built-ins
|
|
|
|
- **WHEN** the built `dist/` is grep'd
|
|
- **THEN** it MUST NOT reference `node:fs`, `node:path`, `node:url`, `process`, `Buffer`, `document`, `window`, or any DOM / Node-only API
|
|
|
|
### Requirement: SuaveplanError base class
|
|
|
|
The package SHALL export an abstract `SuaveplanError` class extending the built-in `Error`, carrying `{ code, message, cause?, context?, timestamp, traceId? }`. `code` SHALL be a string of the form `PACKAGE.DOMAIN.REASON` (plain uppercase ASCII, dots as separators). The `code` field is generic so subclasses can narrow the code union.
|
|
|
|
**Verified by:** `src/base/suaveplan-error.test.ts` and `src/base/package-error.test.ts`.
|
|
|
|
#### Scenario: Subclass narrows code union
|
|
|
|
- **WHEN** a consumer defines `class MyError extends SuaveplanError<"MY.X.Y" | "MY.X.Z">`
|
|
- **THEN** TypeScript infers `err.code` as `"MY.X.Y" | "MY.X.Z"` (not `string`) inside `instanceof MyError` branches
|
|
|
|
#### Scenario: Stack trace preserved
|
|
|
|
- **WHEN** a `SuaveplanError` subclass is thrown
|
|
- **THEN** `err.stack` contains the subclass name (not `Error`) AND the originating call site
|
|
|
|
#### Scenario: Timestamp is injectable
|
|
|
|
- **WHEN** a subclass is constructed with `{ clock: () => 1234 }`
|
|
- **THEN** `err.timestamp === 1234`
|
|
|
|
#### Scenario: Default timestamp uses Date.now
|
|
|
|
- **WHEN** a subclass is constructed with no `clock` option
|
|
- **THEN** `err.timestamp` equals the `Date.now()` reading at construction time
|
|
|
|
### Requirement: Stable error-code registry helper
|
|
|
|
The package SHALL export a `defineCodes<TNamespace, TReasons>()` helper that returns a frozen `Record<TReasons, \`${TNamespace}.${TReasons}\`>` with full literal-type inference. Rebuilding the registry MUST preserve existing codes; removal requires a `@deprecated` marker that emits a TypeScript deprecation warning at call sites.
|
|
|
|
**Verified by:** `src/codes/define-codes.test.ts` and `src/codes/error-codes.ts`.
|
|
|
|
#### Scenario: Registry is frozen
|
|
|
|
- **WHEN** a consumer attempts `codes.REASON = "X.Y.Z"`
|
|
- **THEN** the assignment throws in strict mode (object is frozen)
|
|
|
|
#### Scenario: Code values are literal-typed
|
|
|
|
- **WHEN** a consumer writes `const codes = defineCodes("PKG", ["A", "B"] as const)`
|
|
- **THEN** `codes.A` has type `"PKG.A"` (not `string`)
|
|
|
|
### Requirement: Cause-chain traversal is cycle-safe and depth-bounded
|
|
|
|
The package SHALL export `walkCauses(err, { maxDepth?: number })` as a generator yielding each error in the chain. Default `maxDepth` is 32. Cycles MUST be detected via a `WeakSet` and terminate iteration without throwing. The same cycle-and-depth discipline SHALL apply to `toJSON` serialization: when traversal encounters a cycle OR exceeds `maxDepth`, the cause field is replaced with the `TruncatedCause` sentinel (see "TruncatedCause sentinel" requirement) rather than throwing or looping.
|
|
|
|
**Verified by:** `src/causes/walk-causes.test.ts` and `src/conformance.spec-conformance.test.ts` (toJSON cycle + depth-cap scenarios).
|
|
|
|
#### Scenario: Linear chain fully traversed
|
|
|
|
- **WHEN** `a.cause = b; b.cause = c; c.cause = d`
|
|
- **THEN** `Array.from(walkCauses(a))` returns `[a, b, c, d]`
|
|
|
|
#### Scenario: Cycle terminates iteration
|
|
|
|
- **WHEN** `a.cause = b; b.cause = a` and `walkCauses(a)` is consumed
|
|
- **THEN** iteration yields `a` then `b` and ends (does not throw, does not loop forever)
|
|
|
|
#### Scenario: Depth cap enforced
|
|
|
|
- **WHEN** a chain of 100 errors is walked with `{ maxDepth: 10 }`
|
|
- **THEN** exactly 10 errors are yielded
|
|
|
|
#### Scenario: toJSON cycle yields TruncatedCause sentinel
|
|
|
|
- **WHEN** `a.cause = b; b.cause = a` and `toJSON(a)` runs
|
|
- **THEN** `result.cause.cause.code === "ERROR.CAUSE.TRUNCATED"` AND iteration does not loop forever
|
|
|
|
### Requirement: Lossless wire serialization
|
|
|
|
The package SHALL export `toJSON(err)` and `fromJSON(value)` producing a Zod-validated wire payload. `fromJSON` returns a `ReconstructedError` POJO carrying the `__suaveplanError: 1` discriminator — NOT a real `SuaveplanError` instance, since the base class is `abstract` and consumer-defined subclasses are not on the wire. Round-tripping a `SuaveplanError` subclass through JSON MUST preserve `code`, `message`, `context` (redactions applied), `timestamp`, `traceId`, `name`, and the cause chain (up to `maxDepth`). The binary form (`toBinary` / `fromBinary`) is a deterministic UTF-8 encoding of the canonicalised JSON form (no external encoder dep); both halves of a round-trip produce structurally identical output.
|
|
|
|
**Verified by:** `src/serialize/serialize.test.ts` and `src/conformance.spec-conformance.test.ts` (discriminator round-trip scenario).
|
|
|
|
#### Scenario: JSON round-trip preserves structural fields and discriminator
|
|
|
|
- **WHEN** an error with `{ code, message, context, cause }` is serialized via `toJSON` and parsed back via `fromJSON`
|
|
- **THEN** the reconstructed value carries `__suaveplanError === 1` AND every wire field (`code`, `message`, `context` post-redaction, `timestamp`, `traceId`, `name`, `cause`) is structurally equal to the original AND the result is NOT `instanceof SuaveplanError` (intentionally — base class is abstract)
|
|
|
|
#### Scenario: Binary round-trip matches JSON round-trip
|
|
|
|
- **WHEN** the same error is passed through `toBinary`/`fromBinary`
|
|
- **THEN** the resulting error is structurally equal to the JSON round-trip output
|
|
|
|
#### Scenario: Zod rejects malformed wire payload
|
|
|
|
- **WHEN** `fromJSON({ code: 123 })` is called (wrong type)
|
|
- **THEN** it throws a `SuaveplanError` subclass with `code === "ERROR.WIRE.MALFORMED"` AND `cause instanceof ZodError`
|
|
|
|
### Requirement: Redaction at the serialization boundary
|
|
|
|
The package SHALL export `markSensitive(value)` producing a tagged wrapper. During `toJSON` / `toBinary`, tagged values MUST be replaced with the literal string `"[REDACTED]"` AT ANY DEPTH within `err.context` — including values nested inside arrays and sub-objects. The redaction walk MUST be cycle-safe (a circular context graph terminates without throwing or looping). In-memory access to the original value via `err.context` is UNAFFECTED.
|
|
|
|
**Verified by:** `src/redact/sensitive.test.ts`, `src/serialize/serialize.test.ts`, and `src/conformance.spec-conformance.test.ts` (deep + cycle-safe redaction scenarios).
|
|
|
|
#### Scenario: Sensitive field redacted on the wire
|
|
|
|
- **WHEN** `err.context.token = markSensitive("abc")` and `toJSON(err)` runs
|
|
- **THEN** the serialized payload contains `context.token === "[REDACTED]"` (string)
|
|
|
|
#### Scenario: Nested sensitive value redacted
|
|
|
|
- **WHEN** `err.context.user = { profile: { token: markSensitive("abc") } }` and `toJSON(err)` runs
|
|
- **THEN** `result.context.user.profile.token === "[REDACTED]"`
|
|
|
|
#### Scenario: Sensitive value inside array redacted
|
|
|
|
- **WHEN** `err.context.tokens = [markSensitive("a"), markSensitive("b")]` and `toJSON(err)` runs
|
|
- **THEN** `result.context.tokens === ["[REDACTED]", "[REDACTED]"]`
|
|
|
|
#### Scenario: Cyclic context terminates redaction
|
|
|
|
- **WHEN** `err.context.self` is set to a cycle (`ctx.self = ctx`) and `toJSON(err)` runs
|
|
- **THEN** redaction completes without throwing or looping (cycle short-circuits via `WeakSet`)
|
|
|
|
#### Scenario: In-memory value remains accessible
|
|
|
|
- **WHEN** `err.context.token = markSensitive("abc")` (unserialized)
|
|
- **THEN** `unwrapSensitive(err.context.token) === "abc"`
|
|
|
|
### Requirement: OTel span event adapter
|
|
|
|
The package SHALL export `toSpanEvent(err)` returning `{ name: "exception", attributes: { "exception.type", "exception.message", "exception.stacktrace", "exception.code", "exception.traceId"? } }` with all values already string-serialized. No OpenTelemetry SDK is imported.
|
|
|
|
**Verified by:** `src/otel/to-span-event.test.ts`.
|
|
|
|
#### Scenario: Span event matches OTel spec
|
|
|
|
- **WHEN** `toSpanEvent(err)` is called
|
|
- **THEN** the returned `name === "exception"` AND `attributes["exception.type"] === err.constructor.name` AND `attributes["exception.message"] === err.message` AND `attributes["exception.stacktrace"] === err.stack ?? ""` AND `attributes["exception.code"] === err.code`
|
|
|
|
### Requirement: i18n-ready messages
|
|
|
|
No user-visible string literal SHALL be embedded in a `throw` site. Subclasses MUST instead reference an i18n key (of the form `error.<package>.<domain>.<reason>`) which the default implementation renders by returning the key itself. Consumers can plug in a translator via `setMessageResolver(fn)`.
|
|
|
|
**Verified by:** `src/i18n/resolver.test.ts` and `src/base/suaveplan-error.test.ts` (resolver-applied scenarios).
|
|
|
|
#### Scenario: Default resolver returns the key
|
|
|
|
- **WHEN** no resolver has been set and a subclass formats `"error.pkg.domain.reason"`
|
|
- **THEN** the rendered message equals `"error.pkg.domain.reason"` verbatim
|
|
|
|
#### Scenario: Custom resolver applied
|
|
|
|
- **WHEN** `setMessageResolver((key, params) => translations[key](params))` has been set
|
|
- **THEN** subclass construction calls the resolver and stores the returned string on `err.message`
|
|
|
|
### Requirement: Test coverage at 100%
|
|
|
|
The package MUST maintain `statements: 100`, `branches: 100`, `functions: 100`, `lines: 100` thresholds in `vitest.config.ts`. No `istanbul ignore` pragmas are permitted (they do not survive the esbuild transform). Defensive code whose false branch is unreachable MUST be rewritten as an `as` assertion with an invariant comment rather than a runtime `if`.
|
|
|
|
**Verified by:** `vitest.config.ts` thresholds and the full package test suite under `bunx turbo test:coverage --filter=@suaveplan/error`.
|
|
|
|
#### Scenario: Coverage thresholds enforced
|
|
|
|
- **WHEN** `bunx turbo test:coverage --filter=@suaveplan/error` runs
|
|
- **THEN** it exits non-zero if any of statements / branches / functions / lines drops below 100
|
|
|
|
#### Scenario: Property-based round-trip
|
|
|
|
- **WHEN** fast-check generates arbitrary `SuaveplanError` subclass instances
|
|
- **THEN** every instance survives `toJSON` → `fromJSON` structurally equal (modulo redactions) AND every instance survives `toBinary` → `fromBinary` structurally equal
|
|
|
|
### Requirement: TruncatedCause sentinel
|
|
|
|
When `toJSON` encounters either (a) a cause-chain depth that exceeds `maxDepth` OR (b) an already-seen object (cycle), the cause field SHALL be replaced with a sentinel `WireError` of shape `{ __suaveplanError: 1, code: "ERROR.CAUSE.TRUNCATED", name: "TruncatedCause", message: "[cause chain truncated]", timestamp: 0 }`. The sentinel is structurally a valid `WireError` (passes Zod validation) and is therefore safely consumable by `fromJSON` downstream. The sentinel MUST NOT introduce a real `Error` throw; truncation is a non-fatal terminal event in the chain.
|
|
|
|
**Verified by:** `src/conformance.spec-conformance.test.ts` (depth + cycle sentinel scenarios) and `src/serialize/serialize.test.ts`.
|
|
|
|
#### Scenario: Depth-cap emits sentinel
|
|
|
|
- **WHEN** `toJSON(err, { maxDepth: 1 })` runs on an error with `cause.cause.cause` of depth 3
|
|
- **THEN** the chain at the cap position contains the `TruncatedCause` sentinel AND the sentinel's `code === "ERROR.CAUSE.TRUNCATED"`
|
|
|
|
#### Scenario: Cycle emits sentinel
|
|
|
|
- **WHEN** `toJSON(a)` runs on `a.cause = b; b.cause = a` (cycle)
|
|
- **THEN** the chain terminates at the cycle with the sentinel AND no infinite loop occurs
|
|
|
|
#### Scenario: Sentinel survives round-trip
|
|
|
|
- **WHEN** a `toJSON` output containing a `TruncatedCause` sentinel is passed back through `fromJSON`
|
|
- **THEN** the reconstructed value carries the sentinel intact (`code === "ERROR.CAUSE.TRUNCATED"`, `name === "TruncatedCause"`) without throwing `WIRE.MALFORMED`
|
|
|
|
### Requirement: Wire format version discriminator
|
|
|
|
The wire payload SHALL carry a `__suaveplanError: 1` discriminator literal validated by Zod's `z.literal(1)`. This identifies the payload as a `@suaveplan/error` wire envelope and pins the format version. `WIRE_VERSION` is the single source-of-truth constant in `src/constants/index.ts`. `fromJSON` MUST reject payloads where `__suaveplanError` is missing OR not equal to `WIRE_VERSION` with `code === "ERROR.WIRE.MALFORMED"` (Zod-driven). When `WIRE_VERSION` is bumped (future), payload migration is the consumer's responsibility — there is no implicit version negotiation in this package.
|
|
|
|
**Verified by:** `src/serialize/wire.schemas.ts` (Zod literal), `src/serialize/serialize.test.ts`, and `src/conformance.spec-conformance.test.ts` (discriminator scenarios).
|
|
|
|
#### Scenario: Discriminator preserved through round-trip
|
|
|
|
- **WHEN** an error is passed through `toJSON` then `fromJSON`
|
|
- **THEN** the reconstructed value has `__suaveplanError === 1`
|
|
|
|
#### Scenario: Missing discriminator rejected
|
|
|
|
- **WHEN** `fromJSON({ code: "X.Y.Z", message: "m", timestamp: 0, name: "E" })` runs (no `__suaveplanError`)
|
|
- **THEN** it throws with `code === "ERROR.WIRE.MALFORMED"`
|
|
|
|
#### Scenario: Wrong discriminator rejected
|
|
|
|
- **WHEN** `fromJSON({ __suaveplanError: 2, ...rest })` runs
|
|
- **THEN** it throws with `code === "ERROR.WIRE.MALFORMED"` (Zod literal mismatch)
|