result-error-handling

name

result-error-handling

description

This skill should be used when working with Result<T,E>, BrepError, or error paths in brepjs — deciding whether to throw or return a Result, constructing errors with codes, or handling failures. Trigger phrases include "should this throw or return err", "Called unwrap() on an Err", "add a new error code", "BrepErrorCode", "kernelCall", "unsupportedError", "BrepWrapperError", "the operation failed silently", "error was swallowed", "how do I unwrap this Result", or writing a new *Fns.ts function that can fail.

Result types and error handling

Every fallible operation in brepjs returns Result<T, BrepError> instead of throwing. The type, all combinators, and the extraction helpers live in src/core/result.ts (zero internal imports — a pure foundation module). Error kinds, the code catalog, and per-kind constructors live in src/core/errors.ts.

The two failure channels

Pick the channel before writing any error-handling code:

Situation	Channel	Mechanism
Expected failure (bad input, kernel op failed, unsupported capability, file won't parse)	Result	err(validationError(...)), kernelCall(...), etc.
Programmer bug / broken invariant ("this can never happen")	Throw	bug(location, message) from src/utils/bug.ts — throws BrepBugError, never meant to be caught
Out-of-bounds index that is valid by construction (under noUncheckedIndexedAccess)	Throw	safeIndex(arr, i, context) in src/core/errors.ts — the sanctioned arr[i]! replacement
Cooperative cancellation	Throw	if (signal?.aborted) throw signal.reason (see src/topology/booleanFns.ts)

The rule for Layers 2–3 (.claude/commands/new-operation.md, CLAUDE.md): never throw for expected failures — return ok(...) or err(...). No ESLint rule enforces this mechanically, so it must be applied by discipline in every new *Fns.ts function. The exceptions above (bug(), safeIndex(), abort rethrows) are the only tolerated throws.

The one sanctioned Result→throw boundary is the fluent shape() facade in src/topology/wrapperFns.ts: every chainable method funnels through an internal unwrapOrThrow that throws BrepWrapperError on Err. See "The throwing boundary" below.

Constructing errors

Prefer kernelCall for kernel operations

src/core/kernelCall.ts is the standard error-construction path in *Fns.ts files. It wraps try/catch, casts the result, translates cryptic OCCT messages, and auto-attaches a suggestion:

// src/topology/shapeFns.ts
return kernelCall(
  () => getKernel().downcast(shape.wrapped),
  BrepErrorCode.CLONE_FAILED,
  'Failed to clone shape'
) as Result<T>;

Three variants:

Helper	Returns	Use when
kernelCall(fn, code, message, kind?)	Result<AnyShape>	Kernel call returns a KernelShape; auto-runs castShape()
kernelCallRaw<T>(fn, code, message, kind?)	Result<T>	Kernel call returns anything else (string, number, array)
kernelCallScoped(fn, code, message, kind?)	Result<AnyShape>	fn(scope) needs intermediate kernel allocations — the DisposalScope is disposed even on the error path (see the memory-and-disposal skill)

On exception, the error message becomes `${message}: ${translated}` where translateKernelError() (src/core/kernelErrorTranslation.ts) maps ~12 cryptic OCCT patterns (BRepAlgoAPI failures, fillet radius too large, degenerate geometry, ...) into actionable text with the original appended as (kernel: ...). Translation applies only when kind is 'KERNEL_OPERATION' (the default). ERROR_CODE_SUGGESTIONS in the same file maps a dozen codes (FUSE_FAILED, CUT_FAILED, *_NOT_3D, SWEEP_FAILED, LOFT_FAILED, DRAFT_FAILED, ...) to suggestion strings that ride along automatically.

Manual construction: pick the kind-matching constructor

BrepError is a plain object: { kind, code, message, suggestion?, cause?, metadata? } (src/core/errors.ts). There are 9 kinds, each with a constructor sharing the signature (code, message, cause?, metadata?, suggestion?):

Kind	Constructor	Use for
VALIDATION	validationError	Bad input parameters (check these first, before touching the kernel)
KERNEL_OPERATION	kernelError	Kernel op failed (prefer kernelCall unless building the error by hand)
TYPE_CAST	typeCastError	Result was not the expected shape type (e.g. boolean returned non-3D)
COMPUTATION	computationError	Geometric computation failed (intersection, skeleton, center of mass)
IO	ioError	Import/export failure
QUERY	queryError	Shape query failure (e.g. finder not unique)
MODULE_INIT	moduleInitError	Initialisation failure
UNSUPPORTED	unsupportedError	Capability not supported by the current kernel (ADR-0006) — see the kernel-abstraction skill
SKETCHER_STATE	sketcherStateError	Currently unused in src; exists for sketcher state transitions

Always thread context through:

• cause: the original exception. Dropping it destroys kernel diagnostics.
• metadata: structured context. Real example from src/topology/modifierFns.ts:

return err(
  kernelError('FILLET_FAILED', `Fillet operation failed: ${raw}`, e, {
    operation: 'fillet',
    edgeCount: selectedCount,
    radius,
  })
);

• suggestion: a recovery hint. The shape() wrapper folds it into the thrown message ("...\nSuggestion: ..."), so it reaches users.

Error codes

BrepErrorCode (src/core/errors.ts) is an as const catalog of ~124 codes grouped by category, with a matching literal-union type. Use BrepErrorCode.X instead of a raw string whenever the code exists — but know two caveats:

1. BrepError.code is typed string, not the union — a raw-string typo compiles fine. The catalog is advisory; checking it is on the author.
2. The catalog is incomplete: dozens of codes exist in src only as raw string literals (FILLET_FAILED, WIRE_NOT_CLOSED, THREAD_INVALID_PITCH, and whole families). Grep before assuming a code is new.

To add a new code:

1. Add the constant to BrepErrorCode in src/core/errors.ts under its category group (kernel-op, validation, IO, ...).
2. Use it via the kind-matching constructor, or pass it to kernelCall.
3. Optionally add an entry to ERROR_CODE_SUGGESTIONS in src/core/kernelErrorTranslation.ts so kernelCall auto-attaches a recovery hint.
4. Optionally add a row to the tables in docs/errors.md (hand-maintained, no CI check — see the staleness warning below).

Consuming Results

Need	Use	Notes
Branch on outcome	isOk(r) / isErr(r)	Type guards; narrow to Ok<T> / Err<E>
Handle both arms as an expression	match(r, { ok: v => ..., err: e => ... })
Extract in a test or script	unwrap(r)	Throws with [kind] CODE: message formatting on Err
Extract with fallback	unwrapOr(r, default) / unwrapOrElse(r, fn)	Never use to paper over failures the caller should see
Chain fallible steps	andThen (alias flatMap), or pipeline(input).then(fn).then(fn).result	Both short-circuit on first Err
Transform value / error	map / mapErr / mapBoth
Combine many	collect(results) (alias all), zip(a, b)	collect short-circuits on first Err; zip is re-exported from src/index.ts as zipResults
Side-effect without consuming	tap / tapErr	tapErr is the idiomatic "log and pass through"
Wrap throwing code	tryCatch(fn, mapError) / tryCatchAsync	Use at boundaries with throwing third-party code
Void success	OK constant (Ok<Unit>)	For operations with nothing to return
Nullable → Result	fromNullable(value, errorFn)

The unwrap() policy (CLAUDE.md, docs/getting-started.md): sanctioned in tests (the standard extractor), scripts/examples, and internal calls that are infallible by construction — e.g. unwrap(resolvePlane('XY', origin)) in src/core/planeOps.ts, where the input is a known-valid literal. Never use it on a user-facing fallible path in production code; use isOk()/match() there.

Note the kernel-free subpath brepjs/core (src/core.ts) exports only a subset of combinators — no pipeline, mapBoth, tap/tapErr, fromNullable, or/orElse, zip. The full set is on the main brepjs entry.

For Results inside disposal scopes, withScopeResult / withScopeResultAsync in src/core/disposal.ts combine DisposalScope cleanup with a Result-returning body (documented in src/core/README.md).

The throwing boundary: shape() and BrepWrapperError

The fluent shape() wrapper (src/topology/wrapperFns.ts) auto-unwraps every Result and throws BrepWrapperError on Err. The class carries code, kind, suggestion?, metadata?, and its message includes the suggestion when present. Gotcha: error.name is set to 'BrepError' even though the class is BrepWrapperError — match with instanceof BrepWrapperError (exported from src/index.ts), not by name. The catch pattern is shown in docs/cheat-sheet.md.

Escape hatches on the wrapper: .applyResult(fn) unwraps a user-supplied Result-returning function; .done() / .val exit back to plain handles. docs/which-api.md frames the fluent-vs-functional trade-off around exactly this Result-handling difference.

Silent failures: symptom → cause → fix

Symptom	Likely cause	Fix
Operation "succeeds" but geometry is missing/wrong downstream	An Err was discarded (result assigned, never checked)	Check every Result; use tapErr to log, match to handle, or propagate with early return on isErr
Failure invisible until far away	unwrapOr(r, fallback) masking a real error	Reserve unwrapOr for genuinely optional values; otherwise propagate the Err
Called unwrap() on an Err: [KERNEL_OPERATION] ...	unwrap() on a fallible path	Read the formatted [kind] CODE: message; handle with isOk/match at that call site
Error message is cryptic OCCT text with no context	Hand-rolled try/catch instead of kernelCall, or cause dropped	Route kernel calls through kernelCall/kernelCallRaw/kernelCallScoped; always pass the caught exception as cause
Plain Error thrown from a *Fns.ts function	Layer 2+ rule violated	Convert to err(<kind>Error(code, message, cause)); reserve throws for bug()
Typo'd error code compiles and ships	code is typed string	Use BrepErrorCode.X; add the constant if it does not exist
Async code fails against the wrong kernel with confusing errors	withKernel(id, fn) is sync-only — after the first await the callback silently uses the default kernel	Use getKernel(id) directly in async code (CLAUDE.md gotcha)
Bad geometry with an Ok result	Not an error-channel problem — the kernel produced a valid-but-wrong shape	See the debugging-geometry skill

Additional resources

• src/core/result.ts — the full Result API; short and readable, treat it as the reference.
• src/core/errors.ts — kinds, catalog, constructors, safeIndex; ground truth for codes.
• src/core/kernelCall.ts and src/core/kernelErrorTranslation.ts — the standard construction path and translation/suggestion tables.
• docs/errors.md — user-facing per-code reference with recovery advice. Partially stale: its kind list omits UNSUPPORTED, and its code tables drift from errors.ts in both directions. When they disagree, src/core/errors.ts wins.
• The adding-operations skill — the full recipe for a new *Fns.ts operation (validate → err(validationError(...)) → kernelCall → ok).
• The writing-tests skill — asserting on Err results and using unwrap in tests.