@mtth/stl-errors 0.2.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025, Matthieu Monsch.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# Standard errors
+
+## Motivation
+
+Good error handling is a prerequisite for good telemetry. To help with this,
+`@mtth/stl-errors` provides a simple `StandardError` interface which exposes
+powerful building blocks:
+
++ Namespaced error codes;
++ Causal chains;
++ Optional structured data.
+
+## Quickstart
+
+Standard errors are best created via `errorFactories` which provides type-safe
+error creation functions along with their codes:
+
+```typescript
+import {errorFactories} from '@mtth/stl-errors';
+
+const [errors, codes] = errorFactories({
+  definitions: {
+    invalidFoo: (foo: string) => ({
+      message: `The input foo ${foo} was invalid`,
+      tags: {foo},
+    }),
+    missingBar: 'The bar was missing',
+  },
+});
+
+// Error with code `ERR_INVALID_FOO` (`codes.InvalidFoo`).
+const err1 = errors.invalidFoo('fff');
+
+// Error with code `ERR_MISSING_BAR` (`codes.MissingBar`).
+const err2 = errors.missingBar();
+```

package/lib/cause.d.ts

@@ -0,0 +1,44 @@
+import { ErrorCode, ErrorTags, StandardError, TaggedErrorCode } from './types.js';
+export type CauseExtractor = (err: unknown) => ReadonlyArray<unknown> | undefined;
+export interface ErrorMatch<V, E = unknown> {
+    readonly value: V;
+    readonly error: E;
+}
+export declare class ErrorFinder {
+    readonly extractors: CauseExtractor[];
+    constructor(extractors: ReadonlyArray<CauseExtractor>);
+    /** DFS on causes. */
+    private walk;
+    find<V, E = unknown>(root: unknown, fn: (e: unknown) => V | undefined): ErrorMatch<V, E> | undefined;
+}
+export declare function errorCauseExtractor(err: unknown): ReadonlyArray<unknown> | undefined;
+export declare function statusErrorCauseExtractor(err: unknown): ReadonlyArray<unknown> | undefined;
+/**
+ * Resets the list of global extractors used by `findError` and similar methods.
+ * The default finder contains only the `libraryCauseExtractor`. This function
+ * returns the previous extractors so that they can be restored.
+ */
+export declare function setCauseExtractors(newExtractors: ReadonlyArray<CauseExtractor>): ReadonlyArray<CauseExtractor>;
+/** Finds an error using the current list of global extractors. */
+export declare function findError<V, E = unknown>(root: unknown, fn: (err: unknown) => V | undefined): ErrorMatch<V, E> | undefined;
+/**
+ * Returns the first code contained by this error. This is useful for example to
+ * "see through" status errors.
+ */
+export declare function findErrorCode(root: unknown): ErrorCode | undefined;
+/**
+ * Minimal interface to allow passing both sets and maps as error code arguments
+ * in `findErrorWithCode` and efficiently implement the corresponding check.
+ */
+export interface ErrorCodeCollection {
+    has(code: ErrorCode): boolean;
+}
+/** Convenience method to find a internal error by code. */
+export declare function findErrorWithCode<T extends ErrorTags>(root: unknown, code: TaggedErrorCode<T>): ErrorMatch<TaggedErrorCode<T>, StandardError<T>> | undefined;
+export declare function findErrorWithCode<E = StandardError>(root: unknown, code: ErrorCode | ErrorCodeCollection): ErrorMatch<ErrorCode, E> | undefined;
+/**
+ * Returns a set with all error codes explicitly found in an error's causal
+ * chain. Note that unlike with `errorCode`, implicit `ERR_INTERNAL` codes are
+ * not added here.
+ */
+export declare function collectErrorCodes(root: unknown): ReadonlySet<ErrorCode>;

package/lib/cause.js

@@ -0,0 +1,104 @@
+import { errorCode, isStandardError } from './factories.js';
+import { isStatusError } from './status.js';
+export class ErrorFinder {
+    constructor(extractors) {
+        this.extractors = [...extractors];
+    }
+    /** DFS on causes. */
+    *walk(err) {
+        yield err;
+        for (const fn of this.extractors) {
+            const causes = fn(err);
+            if (causes) {
+                for (const cause of causes) {
+                    yield* this.walk(cause);
+                }
+                return;
+            }
+        }
+    }
+    find(root, fn) {
+        if (!root) {
+            return undefined;
+        }
+        const seen = new WeakSet();
+        for (const cause of this.walk(root)) {
+            if (cause && typeof cause == 'object') {
+                if (seen.has(cause)) {
+                    // Circular reference.
+                    continue;
+                }
+                seen.add(cause);
+            }
+            const val = fn(cause);
+            if (val !== undefined) {
+                return { value: val, error: cause };
+            }
+        }
+        return undefined;
+    }
+}
+export function errorCauseExtractor(err) {
+    if (!isStandardError(err)) {
+        return undefined;
+    }
+    const { cause } = err;
+    return cause === undefined
+        ? undefined
+        : Array.isArray(cause)
+            ? cause
+            : [cause];
+}
+export function statusErrorCauseExtractor(err) {
+    return isStatusError(err) ? [err.contents] : undefined;
+}
+let globalFinder = new ErrorFinder([
+    errorCauseExtractor,
+    statusErrorCauseExtractor,
+]);
+/**
+ * Resets the list of global extractors used by `findError` and similar methods.
+ * The default finder contains only the `libraryCauseExtractor`. This function
+ * returns the previous extractors so that they can be restored.
+ */
+export function setCauseExtractors(newExtractors) {
+    const oldExtractors = globalFinder.extractors;
+    globalFinder = new ErrorFinder(newExtractors);
+    return oldExtractors;
+}
+/** Finds an error using the current list of global extractors. */
+export function findError(root, fn) {
+    return globalFinder.find(root, fn);
+}
+/**
+ * Returns the first code contained by this error. This is useful for example to
+ * "see through" status errors.
+ */
+export function findErrorCode(root) {
+    const match = findError(root, (err) => isStandardError(err) ? err.code : undefined);
+    return match?.value;
+}
+export function findErrorWithCode(root, code) {
+    return findError(root, (err) => {
+        const errCode = errorCode(err);
+        if (errCode == null) {
+            return undefined;
+        }
+        const ok = typeof code == 'string' ? errCode === code : code.has(errCode);
+        return ok ? errCode : undefined;
+    });
+}
+/**
+ * Returns a set with all error codes explicitly found in an error's causal
+ * chain. Note that unlike with `errorCode`, implicit `ERR_INTERNAL` codes are
+ * not added here.
+ */
+export function collectErrorCodes(root) {
+    const codes = new Set();
+    findError(root, (err) => {
+        if (isStandardError(err)) {
+            codes.add(err.code);
+        }
+    });
+    return codes;
+}

package/lib/common.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns the error message of a standard error, the message property of other
+ * objects, the input if it is a string, and nothing otherwise.
+ */
+export declare function errorMessage(err: unknown): string | undefined;
+/** Formats a string. */
+export declare function format(fmt: string, ...args: any[]): string;

package/lib/common.js

@@ -0,0 +1,43 @@
+/**
+ * Returns the error message of a standard error, the message property of other
+ * objects, the input if it is a string, and nothing otherwise.
+ */
+export function errorMessage(err) {
+    if (typeof err == 'string') {
+        return err;
+    }
+    if (!err || typeof err != 'object') {
+        return undefined;
+    }
+    return '' + err.message;
+}
+/** Formats a string. */
+export function format(fmt, ...args) {
+    const formatPattern = /(%?)(%([jds]))/g;
+    if (args.length) {
+        fmt = fmt.replace(formatPattern, (match, esc, _ptn, flag) => {
+            let arg = args.shift();
+            switch (flag) {
+                case 's':
+                    arg = '' + arg;
+                    break;
+                case 'd':
+                    arg = Number(arg);
+                    break;
+                case 'j':
+                    arg = JSON.stringify(arg);
+                    break;
+            }
+            if (!esc) {
+                return arg;
+            }
+            args.unshift(arg);
+            return match;
+        });
+    }
+    if (args.length) {
+        fmt += ' ' + args.join(' ');
+    }
+    fmt = fmt.replace(/%{2,2}/g, '%');
+    return '' + fmt;
+}

package/lib/factories.d.ts

@@ -0,0 +1,98 @@
+import { DeepErrorCodes, ErrorCode, ErrorOptions, ErrorPrefix, ErrorTags, HasErrorTags, StandardError, StandardErrorForCode, TaggedErrorCode } from './types.js';
+/** Returns whether the argument is a standard error. */
+export declare function isStandardError<T extends ErrorTags>(arg: unknown, code: TaggedErrorCode<T>): arg is StandardError<T>;
+export declare function isStandardError(arg: unknown, code?: ErrorCode | ReadonlySet<ErrorCode>): arg is StandardError;
+/** Standard success code to use as counterpart to error codes. */
+export declare const OK_CODE = "OK";
+/**
+ * Returns an error's code if it is a standard error and `undefined` otherwise.
+ */
+export declare function errorCode(err: unknown): ErrorCode | undefined;
+/**
+ * Constructs a new standard error directly from options. In general prefer
+ * using error factories. This can be useful when recreating errors from another
+ * system (for example to translate remote gRPC errors into local standard
+ * ones). This function will throw if `code` is not a valid error code.
+ */
+export declare function newError<T extends ErrorTags>(name: string, code: ErrorCode | string, opts: ErrorOptions & HasErrorTags<T>): StandardError<T>;
+export declare function newError(name: string, code: ErrorCode | string, opts?: ErrorOptions): StandardError;
+/** Combines error codes into a single object. */
+export declare function mergeErrorCodes<O>(obj: O): DeepErrorCodes<O>;
+/**
+ * Generates an object containing error factory methods for each of the input
+ * codes. This is particularly useful to concisely generate strongly-typed error
+ * creation methods and tagged codes.
+ */
+export declare function errorFactories<P extends ErrorPrefix, O extends object>(params: ErrorFactoriesParams<P, O>): [ErrorFactoriesFor<O>, ErrorCodesFor<O>];
+export interface ErrorFactoriesParams<P extends ErrorPrefix, O extends object> {
+    readonly definitions: O;
+    /** Custom prefix for all defined error codes. The default is `ERR_`. */
+    readonly prefix?: P;
+    /**
+     * Custom error name. The default is inferred from the prefix if present. For
+     * example `ERR_FOO_BAR_` would yield name `FooBarError`.
+     */
+    readonly name?: string;
+    /** Omit stack for all defined errors. */
+    readonly omitStack?: boolean;
+}
+export type ErrorFactoriesFor<O> = {
+    readonly [K in keyof O]: O[K] extends (...args: infer A) => StandardError<infer T> | (ErrorOptions & HasErrorTags<infer T>) ? (...args: A) => StandardError<T> : O[K] extends (...args: infer A) => ErrorOptions ? (...args: A) => StandardError : O[K] extends string ? () => StandardError : O[K] extends ErrorOptions ? ErrorFactory : never;
+};
+export interface ErrorFactory {
+    (opts?: ErrorOptions): StandardError;
+    <T extends ErrorTags>(opts: ErrorOptions & HasErrorTags<T>): StandardError<T>;
+}
+export type ErrorCodesFor<O> = {
+    readonly [K in keyof O & string as Capitalize<K>]: O[K] extends (...args: any[]) => StandardError<infer T> | (ErrorOptions & HasErrorTags<infer T>) ? TaggedErrorCode<T> : ErrorCode;
+} & ReadonlySet<ErrorCode>;
+/** Standard error factories. */
+export declare const errors: ErrorFactoriesFor<{
+    /** Generic internal error. */
+    internal: {
+        message: string;
+    };
+    /** Generic illegal state error, used for assertions in particular. */
+    illegal: {
+        message: string;
+    };
+    /** Generic invalid argument error. */
+    invalid: {
+        message: string;
+    };
+    /**
+     * Coerces non standard errors into one. The original value is available via
+     * its `cause` and its message, if any, as top-level message. If the input
+     * is already a standard error, it is returned unchanged.
+     */
+    coerced: (err: unknown) => StandardError<ErrorTags> | {
+        message: string | undefined;
+        cause: unknown;
+        stackFrom: boolean;
+    };
+}>, errorCodes: ErrorCodesFor<{
+    /** Generic internal error. */
+    internal: {
+        message: string;
+    };
+    /** Generic illegal state error, used for assertions in particular. */
+    illegal: {
+        message: string;
+    };
+    /** Generic invalid argument error. */
+    invalid: {
+        message: string;
+    };
+    /**
+     * Coerces non standard errors into one. The original value is available via
+     * its `cause` and its message, if any, as top-level message. If the input
+     * is already a standard error, it is returned unchanged.
+     */
+    coerced: (err: unknown) => StandardError<ErrorTags> | {
+        message: string | undefined;
+        cause: unknown;
+        stackFrom: boolean;
+    };
+}>;
+/** Convenience type for standard errors with code `ERR_COERCED`. */
+export type CoercedError = StandardErrorForCode<typeof errorCodes.Coerced>;

package/lib/factories.js

@@ -0,0 +1,197 @@
+import { constantCase, pascalCase } from 'change-case';
+import { errorMessage } from './common.js';
+const standardErrorMarker = '@mtth/stl-errors:StandardError+v1';
+export function isStandardError(arg, code) {
+    const err = arg;
+    if (!err?.[standardErrorMarker]) {
+        return false;
+    }
+    if (!code) {
+        return true;
+    }
+    return typeof code == 'string' ? code === err.code : code.has(err.code);
+}
+/** Standard success code to use as counterpart to error codes. */
+export const OK_CODE = 'OK';
+/**
+ * Returns an error's code if it is a standard error and `undefined` otherwise.
+ */
+export function errorCode(err) {
+    return isStandardError(err) ? err.code : undefined;
+}
+export function newError(name, code, opts) {
+    return new RealStandardError(name, code, opts);
+}
+/** Base class for standard errors. */
+class RealStandardError extends Error {
+    constructor(name, code, opts) {
+        assertUndefined(codeValidationError(code));
+        const msg = opts?.message;
+        const limit = Error.stackTraceLimit;
+        if (opts?.stackFrom === false) {
+            Error.stackTraceLimit = 0;
+        }
+        try {
+            super(msg);
+        }
+        finally {
+            Error.stackTraceLimit = limit;
+        }
+        if (typeof Error.captureStackTrace == 'function' &&
+            typeof opts?.stackFrom == 'function') {
+            Error.captureStackTrace(this, opts?.stackFrom);
+        }
+        Object.defineProperty(this, standardErrorMarker, { value: true });
+        if (name) {
+            // Non-enumerable name.
+            Object.defineProperty(this, 'name', { value: name });
+        }
+        this.code = code; // Validated above.
+        this.tags = opts?.tags ?? {};
+        let cause;
+        if (opts && Array.isArray(opts.cause)) {
+            const errs = opts.cause.filter((e) => e);
+            cause = errs.length <= 1 ? errs[0] : errs;
+        }
+        else {
+            cause = opts?.cause;
+        }
+        if (cause) {
+            this.cause = cause;
+        }
+    }
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message ? this.message : undefined,
+            tags: Object.keys(this.tags).length ? this.tags : undefined,
+        };
+    }
+}
+const CODE_PREFIX = 'ERR_';
+function codeValidationError(s) {
+    if (!s.startsWith(CODE_PREFIX)) {
+        return new Error('Invalid error code prefix');
+    }
+    if (s === CODE_PREFIX) {
+        return new Error('Empty error code suffix');
+    }
+    return suffixValidationError(s.substring(CODE_PREFIX.length));
+}
+const partPattern = /^[A-Z][A-Z0-9]*$/;
+const PART_SEPARATOR = '_';
+function suffixValidationError(s) {
+    const parts = s.split(PART_SEPARATOR);
+    if (!parts.length) {
+        return new Error('Empty error code suffix');
+    }
+    for (const part of parts) {
+        if (!partPattern.test(part)) {
+            return new Error('Invalid error code suffix: ' + s);
+        }
+    }
+    return undefined;
+}
+function assertUndefined(err) {
+    if (err) {
+        throw err;
+    }
+}
+/** Combines error codes into a single object. */
+export function mergeErrorCodes(obj) {
+    const codes = new Set();
+    walk(obj, codes, [codes]);
+    return codes;
+    function walk(src, dst, sets) {
+        for (const [key, val] of Object.entries(src)) {
+            if (typeof val == 'string' || val instanceof Set) {
+                for (const v of typeof val == 'string' ? [val] : val.values()) {
+                    assertUnique(v);
+                    for (const s of sets) {
+                        s.add(v);
+                    }
+                }
+                dst[key] = val;
+            }
+            else {
+                const nested = new Set();
+                walk(val, nested, [...sets, nested]);
+                dst[key] = nested;
+            }
+        }
+    }
+    function assertUnique(code) {
+        if (codes.has(code)) {
+            throw errors.illegal({ message: 'Duplicate error code: ' + code });
+        }
+    }
+}
+function upperCaseFirst(s) {
+    return s ? s.charAt(0).toUpperCase() + s.slice(1) : '';
+}
+/**
+ * Generates an object containing error factory methods for each of the input
+ * codes. This is particularly useful to concisely generate strongly-typed error
+ * creation methods and tagged codes.
+ */
+export function errorFactories(params) {
+    const { definitions, omitStack } = params;
+    const prefix = params.prefix ?? CODE_PREFIX;
+    const codes = new Set();
+    const factories = Object.create(null);
+    for (const [key, val] of Object.entries(definitions)) {
+        const code = prefix + constantCase(key);
+        assertUndefined(codeValidationError(code));
+        const name = params.name ?? inferName(prefix);
+        codes[upperCaseFirst(key)] = code;
+        codes.add(code);
+        function newError(...args) {
+            const stackFrom = omitStack ? false : newError;
+            let opts;
+            if (typeof val == 'function') {
+                const ret = val(...args);
+                if (isStandardError(ret)) {
+                    return ret;
+                }
+                opts = { stackFrom, ...ret };
+            }
+            else {
+                opts =
+                    typeof val == 'string'
+                        ? { stackFrom, message: val }
+                        : { stackFrom, ...val };
+                const arg = args[0];
+                if (arg !== undefined) {
+                    Object.assign(opts, arg);
+                }
+            }
+            return new RealStandardError(name, code, opts);
+        }
+        factories[key] = newError;
+    }
+    return [factories, codes];
+}
+const DEFAULT_NAME = 'StandardError';
+function inferName(p) {
+    const s = p.substring(CODE_PREFIX.length);
+    return s ? pascalCase(s) + 'Error' : DEFAULT_NAME;
+}
+/** Standard error factories. */
+export const [errors, errorCodes] = errorFactories({
+    definitions: {
+        /** Generic internal error. */
+        internal: { message: 'Internal error' },
+        /** Generic illegal state error, used for assertions in particular. */
+        illegal: { message: 'Illegal state' },
+        /** Generic invalid argument error. */
+        invalid: { message: 'Invalid argument' },
+        /**
+         * Coerces non standard errors into one. The original value is available via
+         * its `cause` and its message, if any, as top-level message. If the input
+         * is already a standard error, it is returned unchanged.
+         */
+        coerced: (err) => isStandardError(err)
+            ? err
+            : { message: errorMessage(err), cause: err, stackFrom: false },
+    },
+});

package/lib/index.d.ts

@@ -0,0 +1,108 @@
+import { ErrorStatus, ErrorStatuses, Failure, StatusError } from './status.js';
+import { ErrorCode, ErrorOptions, ErrorTags, StandardError, TaggedErrorCode } from './types.js';
+export { CauseExtractor, collectErrorCodes, errorCauseExtractor, ErrorCodeCollection, ErrorMatch, findError, findErrorCode, findErrorWithCode, setCauseExtractors, statusErrorCauseExtractor, } from './cause.js';
+export { errorMessage } from './common.js';
+export { CoercedError, errorCode, errorCodes, ErrorCodesFor, errorFactories, ErrorFactoriesFor, ErrorFactoriesParams, ErrorFactory, errors, isStandardError, mergeErrorCodes, newError, OK_CODE, } from './factories.js';
+export { ErrorStatus, ErrorStatuses, Failure, failure, isErrorStatus, isInternalProblem, isServerProblem, isStatusError, OK_STATUS, OkStatus, rethrowWithStatus, StatusError, statusError, StatusErrorFactories, StatusErrorFactory, StatusErrorOptions, statusErrors, statusFromGrpcCode, statusFromHttpCode, StatusMapping, StatusProtocol, statusProtocolCode, StatusProtocolCodes, statusToGrpcCode, statusToHttpCode, } from './status.js';
+export { DeepErrorCodes, ErrorCode, ErrorCodes, ErrorOptions, ErrorPrefix, ErrorTags, ErrorTagsFor, HasErrorTags, StandardError, StandardErrorForCode, TaggedErrorCode, } from './types.js';
+/** Asserts the input predicate, throwing `ERR_ILLEGAL` if not. */
+export declare function assert(pred: unknown, fmt: string, ...args: any[]): asserts pred;
+/** Asserts that an error matches a predicate. */
+export declare function assertCause(pred: unknown, err: unknown): asserts pred;
+/** Asserts that an error has a given error code. */
+export declare function assertErrorCode<T extends ErrorTags>(code: TaggedErrorCode<T>, err: unknown): asserts err is StandardError<T>;
+export declare function assertErrorCode(code: ErrorCode | ReadonlySet<ErrorCode>, err: unknown): asserts err is StandardError;
+/** Asserts that the argument's `typeof` matches the given name. */
+export declare function assertType<N extends keyof TypeNames>(name: N, arg: unknown): asserts arg is TypeNames[N];
+interface TypeNames {
+    bigint: bigint;
+    boolean: boolean;
+    function: Function;
+    number: number;
+    object: {} | null;
+    string: string;
+    symbol: symbol;
+    undefined: undefined;
+}
+/** Throws `ERR_ILLEGAL` when predicates are not met. */
+export type StrictChecker<R> = (arg: unknown) => R;
+/** Extends `StrictChecker` with a convenience method to skip missing values. */
+export interface Checker<R> extends StrictChecker<R> {
+    /**
+     * Transforms `null` and `undefined` values into `undefined` rather than
+     * throwing.
+     */
+    readonly orAbsent: StrictChecker<R | undefined>;
+}
+export declare function newChecker<R>(expected: string, pred: (arg: unknown) => unknown): Checker<R>;
+export declare const check: {
+    readonly isString: Checker<string>;
+    readonly isNumber: Checker<number>;
+    readonly isNumeric: Checker<number>;
+    readonly isInteger: Checker<number>;
+    readonly isNonNegativeInteger: Checker<number>;
+    readonly isBoolean: Checker<boolean>;
+    readonly isObject: Checker<object>;
+    readonly isRecord: Checker<{
+        [key: string]: unknown;
+    }>;
+    readonly isArray: Checker<unknown[]>;
+    readonly isBuffer: Checker<Buffer<ArrayBufferLike>>;
+    /** Asserts that the input is not null or undefined and returns it. */
+    readonly isPresent: <V>(arg: V) => Exclude<V, null | undefined>;
+};
+/**
+ * Extracts the first status error from an error's causal chain. The optional
+ * statuses argument can be used to automatically promote certain error codes to
+ * have a given status. If no match was found, an `UNKNOWN` status error is
+ * returned instead.
+ */
+export declare function extractStatusError(root: unknown, statuses?: ErrorStatuses): StatusError;
+/**
+ * Walks an error's causal chain to find the first status error and returns its
+ * status. If no match is found, returns `UNKNOWN`.
+ */
+export declare function deriveStatus(root: unknown): ErrorStatus;
+/**
+ * Derives the best failure from an error. See `extractStatusError` for
+ * information on how the failure's underlying status error is extracted. If not
+ * status error was present, the root is used.
+ */
+export declare function deriveFailure(root: unknown, opts?: {
+    /**
+     * Mapping from error code to status use to automatically wrap errors
+     * matching one of the codes with the corresponding status.
+     */
+    readonly statuses?: ErrorStatuses;
+    /**
+     * List of functions used to compute the returned failure's annotations. The
+     * input error is the one the failure wil be generated from.
+     */
+    readonly annotators?: ReadonlyArray<(err: StatusError) => string>;
+}): Failure;
+/** Returns `ERR_INTERNAL` with `UNIMPLEMENTED` status. */
+export declare function unimplemented(...args: any[]): Error;
+/** Returns an `ERR_ILLEGAL` error with `value` tag set to the input. */
+export declare function absurd(val: never): Error;
+/** Returns an `ERR_ILLEGAL` error with `value` tag set to the input. */
+export declare function unexpected(val: unknown): Error;
+/**
+ * Returns the `value` tag of an `ERR_ILLEGAL` error. This is typically useful
+ * to inspect errors produced by `unexpected` in tests.
+ */
+export declare function illegalErrorValue(err: unknown): unknown | undefined;
+/** Returns an `ERR_ILLEGAL` error. */
+export declare function unreachable(): Error;
+/** Throws `ERR_ILLEGAL`. */
+export declare function fail(opts?: ErrorOptions): never;
+/**
+ * Validates the input predicate, similar to `assert` but throwing `ERR_INVALID`
+ * with `INVALID_ARGUMENT` status on failure.
+ */
+export declare function validate(pred: unknown, fmt: string, ...args: any[]): asserts pred;
+export declare function validate(pred: unknown, opts: Omit<ErrorOptions, 'message' | 'stackFrom'>, fmt: string, ...args: any[]): asserts pred;
+/**
+ * Similar to `assertCause` but does not wrap errors which do not match the
+ * predicate. Non-error instances are still coerced.
+ */
+export declare function rethrowUnless(pred: unknown, err: unknown): asserts pred;