Exception system with typed causes, extensible JSON encoding/decoding, and cycle-safe traversal of error and aggregate-error graphs.
npm install --save @matrixai/errorsimport { AbstractError, utils } from '@matrixai/errors';
class RequestError<T = unknown> extends AbstractError<T> {
public static description = 'Request failed';
}
const cause = new TypeError('Invalid input');
const error = new RequestError('Could not process request', { cause });
utils.checkError(error, (value) => value === cause);Subclasses inherit the static description, message, stack, data, cause, and
timestamp contracts. JSON reconstruction is class-directed: call the matching
class's fromJSON. Custom fields or recursive cause decoding remain the
subclass/application's responsibility; arbitrary objects are not automatically
reconstructed as exception classes.
One ES2022 ESM distribution runs in modern Node and can be bundled for browser documents and workers using ordinary npm-aware tooling. Runtime source does not import Node builtins, require a browser shim, select a second build, or use top-level await. Node 24 or newer is the development and declared Node engine baseline, not a requirement to provide Node APIs in a web runtime.
Generated timestamps use the global Performance API's epoch origin plus its
relative clock when usable. Missing, restricted, incomplete, non-finite, or
out-of-range performance clocks fall back to Date.now(). The clock is sampled
synchronously when an error needs a generated timestamp, not at module import.
Generated timestamps are weakly nondecreasing within one loaded clock module instance. Millisecond precision allows equality; a backwards clock adjustment can hold timestamps constant until the clock catches up. This does not provide unique IDs, accurate elapsed durations during fallback, cross-worker ordering, cross-process ordering, or coordination between duplicate package copies. Browser privacy-related clock precision restrictions still apply.
An explicitly supplied Date is preserved as-is and does not sample or advance
the generated clock. JSON reconstruction preserves the encoded timestamp rather
than replacing it with the current time.
The flake defines flake-parts with integrated devenv and direnv.
Review .envrc, then run direnv allow . or enter with
nix develop. Activation does not install dependencies, load credentials, or
change persistent shell options. Once activated, run npm install explicitly
through the serialized prepared-archive adapter, then run commands directly
without another direnv wrapper.
npm run lintfix
npm run build
npm test
nix build '.#checks.x86_64-linux.runtime'Tests use compiled imports and run with Vitest. Local tests build incrementally;
hermetic unit checks use prebuilt output. Test flags and paths pass through
npm test. JUnit is written to tmp/junit/junit.xml; npm test -- --coverage
also writes Cobertura under tmp/coverage. npm run lintfix is the
active-development lint gate. npm run lint is reserved for non-mutating
CI/parity verification. Documentation is handwritten Markdown; there is no
TypeDoc dependency or generation command.
MatrixAI lint comes from the selected public nixpkgs-matrixai package set, not an npm dependency or a direct js-lint flake input. One configured tool environment is shared by the development shell, flake formatter, and independent hermetic lint check. The bundled CLI owns configuration; TypeScript remains a consumer development dependency.
nix fmt
npm run lintfix
npm run lint
nix build '.#checks.x86_64-linux.lint'The first two commands share the formatting authority across applicable domains, including TypeScript, Markdown, shell, and Nix. The last two are non-mutating verification; the Nix lint gate works without an activated development shell.
The standards submodule and profile-selected runtime skills are initialized with:
git submodule update --init --depth 1
nix run './.matrixai/matrixai-standards#skills-materializer' -- --standards-root ./.matrixai/matrixai-standardsnix build '.#npm-package'
nix build '.#npm-package-unpacked'
nix build '.#checks.x86_64-linux.default'
nix build '.#checks.x86_64-linux.runtime'The default package and npm-package are the archive file itself.
npm-package-unpacked exposes the exact contents at its root. The archive
contains compiled ESM, declarations, source maps, metadata, README, and license;
it does not bundle dependencies, a runtime, or Nix store paths into metadata.
Both the source and packed manifests retain the canonical dependency
declarations and lifecycle scripts. Ordinary npm preparation remains supported.
Evaluation-visible schema-v1 npmPackage and npmDistribution descriptors
report manifest identity, dependency metadata, source provenance, archive
output, and runtime provider candidates. The source snapshot hash is not an
archive checksum. No prepared runtime providers are advertised:
ts-custom-error is a normal registry dependency, while MatrixAI lint comes
from the package set.
Hermetic installs use importNpmLock and its matching Node installation hook. The generic dependency adapter retains support for reviewed runtime Git providers, but this package needs no selected prepared archives. Lint has no npm archive selection or consumer Git input. Source pins are not replaced with local paths or published as Nix paths.
The default hermetic gate aggregates the unit-js and independent lint
checks. The separate runtime aggregate selects integration-browser, which
uses the shared Playwright harness against the compiled browser bundle in a
Chromium document and dedicated worker, without builtin aliases or Node
compatibility flags. These are local browser checks, not deployed-platform or
all-browser support claims.
See verification evidence for executed results and remaining limits. Publishing and tagging require explicit approval.