Structured, discriminable errors — the E half of Result<T, E>.
import * as Failure from './failure.ts'; const FileMissing = Failure.define('FileMissing', (d: { path: string }) => `no ${d.path}`); FileMissing.is(FileMissing({ path: 'a.ts' })); // true
A structured, discriminable error.
-
code: Code
The discriminant. Narrow on this, never on
instanceof. -
data: Data
Structured payload supplied by the throw site.
-
toJSON(): SerializedFailure
Serializes to plain JSON so
console.log(JSON.stringify(failure))is not{}.
Span/log attributes a failure declares for tracing: failure.code plus whatever its
factory's trace mapper (see define) explicitly allowlisted from data. A
failure whose factory declared no mapper yields the code alone — unmapped payload
fields never leave the process, which is what makes redaction (passwords, tokens) the
default rather than a discipline.
Flattens an error's cause chain into an array, error first and the root cause last.
define() overload for failures that carry no payload.
Renders an error and its whole cause chain as indented, human-readable lines.
Coerces any caught value into a Failure, leaving existing Failures untouched.
Revives a SerializedFailure into a real Failure, reconstructing the cause chain.
Narrows a Failure to one of several codes — the multi-code sibling of Factory.is.
Builds a .catch() handler for a failure that genuinely has no consequence — but says so
under QUNITX_DEBUG instead of vanishing. This is the raw handler; the ergonomic spelling
at call sites is Task(promise).ignore(context), which wraps exactly this function.
Whether value is a Failure — from this realm or any other.
Whether value is a Failure — from this realm or any other.
True for a factory made by define. A factory carries the code it produces and its
own is guard; a plain error-mapper carries neither, so an API can accept both in one
position and tell them apart exactly, without guessing from arity.
Whether value is a Failure — from this realm or any other.
Whether value is a Failure — from this realm or any other.
Reports a declared failure to the observation seam — onObserved plus the
OBSERVED_CHANNEL_NAME channel. Task's consuming methods call this at their
classification points; call it yourself only for a synchronous Result flow that never
crossed a Task, so a tracing adapter sees those failures too.
Installs a process-wide observer for every ignored failure — the interception seam for
"list everything the program decided not to handle". Costs one null check on the failure
path only (nothing on success, nothing per Task), and retains nothing itself: whether the
suppressed failures accumulate, sample, or stream somewhere is the observer's decision.
Pass null to detach.
Installs a process-wide observer for every handled declared failure — the portable
(browser-friendly) counterpart of subscribing to OBSERVED_CHANNEL_NAME. Single
slot, one null check on the failure path, nothing retained; pass null to detach.
The deepest cause in the chain — the original failure, whatever wrapped it since.
Toggles ignored-failure reporting at runtime, overriding the QUNITX_DEBUG default.
Converts a Failure (or any error) into plain JSON.
Per-kind options accepted by define().
-
trace: (data: Data) => TraceAttributes
Allowlist mapper from the typed payload to span/log attributes, consumed by attributes. Deliberately not a redaction filter: only what the mapper returns is ever exposed, so sensitive fields are private by omission, not by scrubbing.
A callable failure constructor produced by define(), carrying its own type guard.
-
code: Code
The literal code this factory produces. Useful as a
switchcase and in registries. -
is(value: unknown): value is Failure<Code, Data>
Cross-realm type guard narrowing to this exact failure — the flat rethrow line's guard after a
Result.try.
Options accepted by the Failure constructor and by every generated factory.
-
cause: unknown
The error this failure was derived from. Preserved verbatim and walked by
causes(). -
stackAnchor: (...args: never[]) => unknown
The function to truncate the stack at, so the top frame is the code that reported the failure rather than the plumbing that built it. Defaults to the constructor.
-
stackless: boolean
Skips stack capture. Only worth setting for failures produced in a hot loop and consumed immediately — the capture, not the allocation, is what a Failure costs. See the performance section of the docs before reaching for it.
The wire form of a Failure — what toJSON emits and fromJSON accepts.
-
cause: SerializedFailure
| { name: string; message: string; stack?: string; }The serialized cause chain: a nested Failure, or a plain error's identifying fields.
-
code: string
The discriminant. Survives the wire, unlike a prototype.
-
data: unknown
The structured payload, JSON round-tripped by
toJSONso it cannot fail later. -
failure: true
Wire marker.
Symbol.forkeys survive neitherJSON.stringifynorstructuredClone, so the serialized form carries an explicit field in the brand's place. -
message: string
The human-readable sentence, already interpolated from
data. -
stack: string
The producing process's stack. Frameless — the header line alone — when the failure was built
{ stackless: true }; the field itself is absent only ifstackwas never set.
Any Failure at all — the type to reach for when a signature accepts failures it does not
enumerate, e.g. Result<T, Failure.Any> at a boundary that only logs.
The callback shape onIgnored installs: every ignored failure arrives with the label its call site declared.
The callback shape onObserved installs: every declared failure a consumer classified arrives right as it is handed to application code.
The Failure type a factory produces: Failure.Of<typeof FileMissing>.
The attribute primitives tracing systems accept (OpenTelemetry's span-attribute values) —
what a trace mapper returns and attributes yields.
Name of the diagnostics_channel that observed publishes to on Node and Deno.
Messages are { error: Failure.Any }. This is what a tracing adapter subscribes to —
e.g. OpenTelemetry, in its entirety:
The failure from() produces for a throwable that is not already a Failure.