Results & Observability

Two complementary surfaces: a result type for running code that can fail without try/catch, and an observability seam for piping every NiceError to your logger or telemetry.

Running code that can fail — niceTry

niceTry / niceTryAsync turn a throwing function into a typed result whose failure branch is always a NiceError.

import { niceTry, niceTryAsync, type TNiceResult } from "@nice-code/error";

const r = niceTry(() => JSON.parse(input));
if (!r.ok) report(r.error); // r.error is a NiceError (isUnhandled === true for a raw throw)
else use(r.output);

const r2 = await niceTryAsync(() => fetchUser(id)); // accepts a sync or async fn

The catch runs through castNiceError, so a thrown domain error passes through untouched while everything else becomes an isUnhandled wrapper.

TNiceResult and its builders

type TNiceResult<OUT, ERR extends NiceError = NiceError> =
  | { ok: true; output: OUT }
  | { ok: false; error: ERR };

Build results by hand with niceOk / niceErr when a function returns a TNiceResult directly:

import { niceOk, niceErr } from "@nice-code/error";

function parsePort(raw: string): TNiceResult<number> {
  const n = Number(raw);
  return Number.isInteger(n) ? niceOk(n) : niceErr(err_config.fromId("bad_port", { raw }));
}

@nice-code/action’s action outcome is a structural superset of TNiceResult (it adds an expected discriminant), so the two compose — see Error Handling.

Observability — tap every error

onNiceError fires for every NiceError at creation; route it to Sentry, OTel, or your devtools.

import { onNiceError, setNiceErrorLogger } from "@nice-code/error";

const off = onNiceError((error) => report(error.toStructuredLog()));
// ...later
off(); // remove the tap

error.toStructuredLog() returns a flat, log-friendly object distinct from toJsonObject() (the wire form):

{ domain, ids, message, httpStatusCode, isUnhandled, timeCreated, originError? }

Routing the library’s own diagnostics

The library’s internal warnings default to console. Redirect them through your own logger:

setNiceErrorLogger({ warn: myLogger.warn, debug: myLogger.debug, error: myLogger.error });

Internal subpath

The headline @nice-code/error surface is what most apps need. Lower-level helpers — wire-format inspection, the err_cast_not_nice fallback domain, isNiceErrorObject, context-state types — live behind an explicit subpath for libraries built on top of nice-error:

import { isNiceErrorObject, err_cast_not_nice } from "@nice-code/error/internal";

Next: Packing →