@mtth/stl-errors 0.2.0

package/lib/index.js

@@ -0,0 +1,197 @@
+import { findError } from './cause.js';
+import { errorMessage, format } from './common.js';
+import { errorCode, errorCodes, errors, isStandardError } from './factories.js';
+import { failure, isStatusError, statusError, statusErrors, } from './status.js';
+export { collectErrorCodes, errorCauseExtractor, findError, findErrorCode, findErrorWithCode, setCauseExtractors, statusErrorCauseExtractor, } from './cause.js';
+export { errorMessage } from './common.js';
+export { errorCode, errorCodes, errorFactories, errors, isStandardError, mergeErrorCodes, newError, OK_CODE, } from './factories.js';
+export { failure, isErrorStatus, isInternalProblem, isServerProblem, isStatusError, OK_STATUS, rethrowWithStatus, statusError, statusErrors, statusFromGrpcCode, statusFromHttpCode, statusProtocolCode, statusToGrpcCode, statusToHttpCode, } from './status.js';
+// Assertions
+/** Asserts the input predicate, throwing `ERR_ILLEGAL` if not. */
+export function assert(pred, fmt, ...args) {
+    if (pred) {
+        return;
+    }
+    throw errors.illegal({
+        message: 'Assertion failed: ' + format(fmt, ...args),
+        stackFrom: assert,
+    });
+}
+/** Asserts that an error matches a predicate. */
+export function assertCause(pred, err) {
+    if (pred) {
+        return;
+    }
+    throw errors.illegal({
+        message: 'Cause assertion failed: ' + errorMessage(err),
+        cause: err,
+        stackFrom: assertCause,
+    });
+}
+export function assertErrorCode(code, err) {
+    if (isStandardError(err, code)) {
+        return;
+    }
+    throw errors.illegal({
+        message: 'Error code assertion failed: ' + errorMessage(err),
+        cause: err,
+        tags: { want: code, got: errorCode(err) },
+        stackFrom: assertErrorCode,
+    });
+}
+/** Asserts that the argument's `typeof` matches the given name. */
+export function assertType(name, arg) {
+    assert(typeof arg == name, 'Expected type %s but got %j', name, arg);
+}
+export function newChecker(expected, pred) {
+    check.orAbsent = orAbsent;
+    return check;
+    function check(arg, caller) {
+        if (caller && (arg === null || arg === undefined)) {
+            return undefined;
+        }
+        assert(pred(arg), 'Expected %s but got %j', expected, arg);
+        return arg;
+    }
+    function orAbsent(arg) {
+        return check(arg, orAbsent);
+    }
+}
+export const check = {
+    isString: newChecker('a string', (a) => typeof a == 'string'),
+    isNumber: newChecker('a number', (a) => typeof a == 'number' && !isNaN(a)),
+    isNumeric: newChecker('a number', (a) => {
+        let n;
+        switch (typeof a) {
+            case 'number':
+                n = a;
+                break;
+            case 'string':
+                n = +a;
+                break;
+        }
+        return n != null && !isNaN(n);
+    }),
+    isInteger: newChecker('an integer', (a) => typeof a == 'number' && a === (a | 0)),
+    isNonNegativeInteger: newChecker('an integer', (a) => typeof a == 'number' && a === (a | 0) && a >= 0),
+    isBoolean: newChecker('a boolean', (a) => typeof a == 'boolean'),
+    isObject: newChecker('an object', (a) => a && typeof a === 'object'),
+    isRecord: newChecker('a record', (a) => a && typeof a === 'object' && !Array.isArray(a)),
+    isArray: newChecker('an array', (a) => Array.isArray(a)),
+    isBuffer: newChecker('a buffer', (a) => Buffer.isBuffer(a)),
+    /** Asserts that the input is not null or undefined and returns it. */
+    isPresent(arg) {
+        assert(arg != null, 'Absent value');
+        return arg;
+    },
+};
+// Failures
+/**
+ * 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 function extractStatusError(root, statuses) {
+    const match = findError(root, (e) => {
+        if (isStatusError(e)) {
+            return e.status;
+        }
+        const code = errorCode(e);
+        return code == null ? undefined : statuses?.[code];
+    });
+    if (!match) {
+        return statusError('UNKNOWN', root);
+    }
+    const { error: err, value: status } = match;
+    return isStatusError(err) ? err : statusError(status, errors.coerced(err));
+}
+/**
+ * Walks an error's causal chain to find the first status error and returns its
+ * status. If no match is found, returns `UNKNOWN`.
+ */
+export function deriveStatus(root) {
+    return extractStatusError(root).status;
+}
+/**
+ * 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 function deriveFailure(root, opts) {
+    const err = extractStatusError(root, opts?.statuses);
+    return failure(err, { annotations: opts?.annotators?.map((fn) => fn(err)) });
+}
+// Conveniences
+/** Returns `ERR_INTERNAL` with `UNIMPLEMENTED` status. */
+export function unimplemented(...args) {
+    return statusErrors.unimplemented(errors.internal({
+        message: 'Unimplemented',
+        tags: { arguments: args },
+        stackFrom: unimplemented,
+    }));
+}
+/** Returns an `ERR_ILLEGAL` error with `value` tag set to the input. */
+export function absurd(val) {
+    return errors.illegal({
+        message: format('Absurd value: %j', val),
+        tags: { value: val },
+        stackFrom: absurd,
+    });
+}
+/** Returns an `ERR_ILLEGAL` error with `value` tag set to the input. */
+export function unexpected(val) {
+    return errors.illegal({
+        message: format('Unexpected value: %j', val),
+        tags: { value: val },
+        stackFrom: unexpected,
+    });
+}
+/**
+ * Returns the `value` tag of an `ERR_ILLEGAL` error. This is typically useful
+ * to inspect errors produced by `unexpected` in tests.
+ */
+export function illegalErrorValue(err) {
+    assert(isStandardError(err, errorCodes.Illegal), 'Unexpected error: %j', err);
+    return err.tags.value;
+}
+/** Returns an `ERR_ILLEGAL` error. */
+export function unreachable() {
+    return errors.illegal({ message: 'Unexpected call', stackFrom: unreachable });
+}
+/** Throws `ERR_ILLEGAL`. */
+export function fail(opts) {
+    throw errors.illegal({ stackFrom: fail, ...opts });
+}
+export function validate(pred, arg1, ...args) {
+    if (pred) {
+        return;
+    }
+    let fmt;
+    let opts;
+    if (typeof arg1 == 'string') {
+        opts = {};
+        fmt = arg1;
+    }
+    else {
+        opts = arg1;
+        fmt = args.shift();
+    }
+    const err = errors.invalid({
+        ...opts,
+        message: fmt == null ? undefined : format(fmt, ...args),
+        stackFrom: validate,
+    });
+    throw statusErrors.invalidArgument(err);
+}
+// Other
+/**
+ * Similar to `assertCause` but does not wrap errors which do not match the
+ * predicate. Non-error instances are still coerced.
+ */
+export function rethrowUnless(pred, err) {
+    if (pred) {
+        return;
+    }
+    throw err instanceof Error ? err : errors.coerced(err);
+}

package/lib/status.d.ts

@@ -0,0 +1,191 @@
+import { CoercedError } from './factories.js';
+import { ErrorCode } from './types.js';
+declare const statuses: {
+    /** Status representing other errors. */
+    readonly UNKNOWN: {
+        readonly grpc: 2;
+        readonly http: 500;
+    };
+    /**
+     * Generic internal failure status. This status is used by default for
+     * standard errors which do not have one set explicitly. In general you
+     * shouldn't need to set it except when masking an existing status.
+     */
+    readonly INTERNAL: {
+        readonly grpc: 13;
+        readonly http: 500;
+    };
+    /**
+     * The operation is not implemented or is not supported/enabled in this
+     * service.
+     */
+    readonly UNIMPLEMENTED: {
+        readonly grpc: 12;
+        readonly http: 501;
+    };
+    /** The service is currently unavailable. */
+    readonly UNAVAILABLE: {
+        readonly grpc: 14;
+        readonly http: 503;
+    };
+    /** The deadline expired before the operation could complete. */
+    readonly DEADLINE_EXCEEDED: {
+        readonly grpc: 4;
+        readonly http: 504;
+    };
+    /**
+     * The operation was aborted, typically due to a concurrency issue such as a
+     * sequencer check failure or transaction abort.
+     */
+    readonly ABORTED: {
+        readonly grpc: 10;
+        readonly http: 504;
+    };
+    /** The client specified an invalid argument. */
+    readonly INVALID_ARGUMENT: {
+        readonly grpc: 3;
+        readonly http: 400;
+    };
+    /**
+     * The request does not have valid authentication credentials for the
+     * operation.
+     */
+    readonly UNAUTHENTICATED: {
+        readonly grpc: 16;
+        readonly http: 401;
+    };
+    /** The caller does not have permission to execute the specified operation. */
+    readonly PERMISSION_DENIED: {
+        readonly grpc: 7;
+        readonly http: 403;
+    };
+    /** Some requested entity (e.g., file or directory) was not found. */
+    readonly NOT_FOUND: {
+        readonly grpc: 5;
+        readonly http: 404;
+    };
+    /**
+     * The entity that a client attempted to create (e.g., file or directory)
+     * already exists.
+     */
+    readonly ALREADY_EXISTS: {
+        readonly grpc: 6;
+        readonly http: 409;
+    };
+    /**
+     * The operation was rejected because the system is not in a state required
+     * for the operation's execution.
+     */
+    readonly FAILED_PRECONDITION: {
+        readonly grpc: 9;
+        readonly http: 422;
+    };
+    /** Some resource has been exhausted. */
+    readonly RESOURCE_EXHAUSTED: {
+        readonly grpc: 8;
+        readonly http: 429;
+    };
+    /** The operation was cancelled, typically by the caller. */
+    readonly CANCELLED: {
+        readonly grpc: 1;
+        readonly http: 499;
+    };
+};
+export type StatusProtocol = 'grpc' | 'http';
+export type ErrorStatus = keyof typeof statuses;
+/**
+ * Non-error status, useful for example when including an ok case within
+ * aggregations or metrics.
+ */
+export declare const OK_STATUS = "OK";
+export type OkStatus = typeof OK_STATUS;
+export declare function isErrorStatus(arg: string): arg is ErrorStatus;
+/** A wrapping error which decorates another with a status. */
+export interface StatusError<E extends Error = Error> extends Error {
+    /** The error status. */
+    readonly status: ErrorStatus;
+    /** The underlying error, to which the status is added. */
+    readonly contents: E;
+    /**
+     * Protocol code overrides. This can be useful when the generic status is not
+     * as granular as the underlying protocol's error codes.
+     */
+    readonly protocolCodes: StatusProtocolCodes;
+}
+export type StatusProtocolCodes = {
+    readonly [P in StatusProtocol]?: number;
+};
+export interface StatusErrorOptions {
+    readonly protocolCodes?: StatusProtocolCodes;
+}
+/**
+ * Returns true iff the status corresponds to an internal issue (500 code). This
+ * should be used to avoid surfacing internal error details to clients.
+ */
+export declare function isInternalProblem(status: ErrorStatus): boolean;
+/**
+ * Returns true iff the status corresponds to a server-side issue. This is all
+ * statuses corresponding to 5XX codes, except UNIMPLEMENTED (technically 501).
+ */
+export declare function isServerProblem(status: ErrorStatus): boolean;
+export declare function statusError<E>(status: ErrorStatus, err: E, opts?: StatusErrorOptions): StatusError<E extends Error ? E : CoercedError>;
+export type StatusErrorFactory = <E extends Error>(err: E, opts?: StatusErrorOptions) => StatusError<E>;
+export type StatusErrorFactories = {
+    readonly [K in Exclude<ErrorStatus, 'UNKNOWN'> as ConstantToCamelCase<K>]: StatusErrorFactory;
+};
+/** Type-level case-change from `CONSTANT_CASE` to `camelCase`. */
+type ConstantToCamelCase<S extends string> = S extends `${infer T}_${infer U}` ? `${Lowercase<T>}${Capitalize<ConstantToCamelCase<U>>}` : Lowercase<S>;
+export declare const statusErrors: StatusErrorFactories;
+export declare function isStatusError(err: unknown): err is StatusError;
+/**
+ * Returns the default numeric gRPC code for a given status. See `protocolCodes`
+ * for transmitting more granular values.
+ */
+export declare function statusToGrpcCode(status: ErrorStatus): number;
+export declare function statusFromGrpcCode(code: number): ErrorStatus | OkStatus;
+/**
+ * Returns the default numeric HTTP code for a given status. See `protocolCodes`
+ * for transmitting more granular values.
+ */
+export declare function statusToHttpCode(status: ErrorStatus): number;
+export declare function statusFromHttpCode(code: number): ErrorStatus | OkStatus;
+/** Returns the best numeric error code for a given error and protocol. */
+export declare function statusProtocolCode(protocol: StatusProtocol, err: StatusError): number;
+export declare function inferErrorStatus(err: unknown): ErrorStatus;
+/** A failure is the public representation of an error. */
+export interface Failure {
+    /** Standard error status. */
+    readonly status: ErrorStatus;
+    /** The error that caused the failure. */
+    readonly error: {
+        /** Human-readable message about the error. */
+        readonly message: string;
+        /** Application-specific error code for programmatic handling. */
+        readonly code?: string;
+        /** Structured metadata. */
+        readonly tags?: {
+            readonly [key: string]: unknown;
+        };
+    };
+}
+/** Generates a new failure from a status error. */
+export declare function failure(err: StatusError, opts?: {
+    /** Annotations to append to the failure's message */
+    readonly annotations?: ReadonlyArray<string>;
+}): Failure;
+/** Mapping from status to error code(s). */
+export type StatusMapping = {
+    readonly [S in ErrorStatus]?: ErrorCode | Iterable<ErrorCode>;
+};
+/**
+ * Wraps and rethrows an (internal) error with the status specified in the input
+ * mapping. If the error is not an internal one or doesn't match, this method
+ * rethrows the original error. Note that this method does not walk the error's
+ * causal chain to avoid swallowing downstream errors.
+ */
+export declare function rethrowWithStatus(err: unknown, mapping: StatusMapping): never;
+/** Map from error code to status. */
+export interface ErrorStatuses {
+    readonly [code: ErrorCode]: ErrorStatus;
+}
+export {};

package/lib/status.js

@@ -0,0 +1,238 @@
+import { camelCase, sentenceCase } from 'change-case';
+import { errorMessage } from './common.js';
+import { errorCode, errorCodes, errors, isStandardError, } from './factories.js';
+// https://grpc.github.io/grpc/core/md_doc_statuscodes.html
+// https://cloud.yandex.com/en/docs/api-design-guide/concepts/errors
+const statuses = {
+    // Private (internal) statuses. Their corresponding status errors do not
+    // expose any information about their contents when serialized to failures.
+    /** Status representing other errors. */
+    UNKNOWN: { grpc: 2, http: 500 },
+    /**
+     * Generic internal failure status. This status is used by default for
+     * standard errors which do not have one set explicitly. In general you
+     * shouldn't need to set it except when masking an existing status.
+     */
+    INTERNAL: { grpc: 13, http: 500 },
+    // Public statuses
+    // 5XX
+    /**
+     * The operation is not implemented or is not supported/enabled in this
+     * service.
+     */
+    UNIMPLEMENTED: { grpc: 12, http: 501 },
+    /** The service is currently unavailable. */
+    UNAVAILABLE: { grpc: 14, http: 503 },
+    /** The deadline expired before the operation could complete. */
+    DEADLINE_EXCEEDED: { grpc: 4, http: 504 },
+    /**
+     * The operation was aborted, typically due to a concurrency issue such as a
+     * sequencer check failure or transaction abort.
+     */
+    ABORTED: { grpc: 10, http: 504 },
+    // 4XX
+    /** The client specified an invalid argument. */
+    INVALID_ARGUMENT: { grpc: 3, http: 400 },
+    /**
+     * The request does not have valid authentication credentials for the
+     * operation.
+     */
+    UNAUTHENTICATED: { grpc: 16, http: 401 },
+    /** The caller does not have permission to execute the specified operation. */
+    PERMISSION_DENIED: { grpc: 7, http: 403 },
+    /** Some requested entity (e.g., file or directory) was not found. */
+    NOT_FOUND: { grpc: 5, http: 404 },
+    /**
+     * The entity that a client attempted to create (e.g., file or directory)
+     * already exists.
+     */
+    ALREADY_EXISTS: { grpc: 6, http: 409 },
+    /**
+     * The operation was rejected because the system is not in a state required
+     * for the operation's execution.
+     */
+    FAILED_PRECONDITION: { grpc: 9, http: 422 },
+    /** Some resource has been exhausted. */
+    RESOURCE_EXHAUSTED: { grpc: 8, http: 429 },
+    /** The operation was cancelled, typically by the caller. */
+    CANCELLED: { grpc: 1, http: 499 },
+    // TODO: Add data loss status?
+};
+/**
+ * Non-error status, useful for example when including an ok case within
+ * aggregations or metrics.
+ */
+export const OK_STATUS = 'OK';
+function findContents(arg) {
+    let err = arg;
+    while (isStatusError(err)) {
+        err = err.contents;
+    }
+    return err;
+}
+export function isErrorStatus(arg) {
+    return !!statuses[arg];
+}
+const isStatusErrorMarker = '@mtth/stl-errors:isStatusError+v1';
+class RealStatusError extends Error {
+    constructor(status, contents, protocolCodes, stackFrom) {
+        super(statusErrorMessage(status, contents));
+        this.status = status;
+        this.contents = contents;
+        this.protocolCodes = protocolCodes;
+        this.name = 'StatusError';
+        Object.defineProperty(this, isStatusErrorMarker, { value: true });
+        if (typeof Error.captureStackTrace == 'function') {
+            Error.captureStackTrace(this, stackFrom);
+        }
+    }
+}
+function statusErrorMessage(status, err) {
+    let ret = `${sentenceCase(status)} error`;
+    if (isInternalProblem(status) || !err) {
+        return ret;
+    }
+    const cause = findContents(err);
+    const code = errorCode(cause);
+    if (code && code !== errorCodes.Coerced) {
+        ret += ` [${code}]`;
+    }
+    const msg = errorMessage(cause);
+    if (msg) {
+        if (msg.startsWith(ret)) {
+            // Avoid repeating the prefix.
+            return msg;
+        }
+        ret += `: ${msg}`;
+    }
+    return ret;
+}
+/**
+ * Returns true iff the status corresponds to an internal issue (500 code). This
+ * should be used to avoid surfacing internal error details to clients.
+ */
+export function isInternalProblem(status) {
+    return statuses[status].http === 500;
+}
+/**
+ * Returns true iff the status corresponds to a server-side issue. This is all
+ * statuses corresponding to 5XX codes, except UNIMPLEMENTED (technically 501).
+ */
+export function isServerProblem(status) {
+    const code = statuses[status].http;
+    return code === 500 || code > 501; // UNIMPLEMENTED is not a server problem.
+}
+export function statusError(status, err, opts) {
+    const contents = err instanceof Error ? err : errors.coerced(err);
+    return new RealStatusError(status, contents, opts?.protocolCodes ?? {}, statusError);
+}
+export const statusErrors = (() => {
+    const obj = Object.create(null);
+    for (const key of Object.keys(statuses)) {
+        const status = key;
+        if (status === 'UNKNOWN') {
+            continue;
+        }
+        function newError(err, opts) {
+            const codes = opts?.protocolCodes ?? {};
+            return new RealStatusError(status, err, codes, newError);
+        }
+        obj[camelCase(status)] = newError;
+    }
+    return obj;
+})();
+export function isStatusError(err) {
+    return err && err[isStatusErrorMarker];
+}
+const statusesByGrpcCode = new Map(Object.entries(statuses).map(([k, v]) => [v.grpc, k]));
+/**
+ * Returns the default numeric gRPC code for a given status. See `protocolCodes`
+ * for transmitting more granular values.
+ */
+export function statusToGrpcCode(status) {
+    return statuses[status].grpc;
+}
+export function statusFromGrpcCode(code) {
+    if (code === 0) {
+        return OK_STATUS;
+    }
+    return statusesByGrpcCode.get(code) ?? 'UNKNOWN';
+}
+const statusesByHttpCode = new Map(Object.entries(statuses).map(([k, v]) => [v.http, k]));
+/**
+ * Returns the default numeric HTTP code for a given status. See `protocolCodes`
+ * for transmitting more granular values.
+ */
+export function statusToHttpCode(status) {
+    return statuses[status].http;
+}
+export function statusFromHttpCode(code) {
+    if (code < 400) {
+        return OK_STATUS;
+    }
+    return statusesByHttpCode.get(code) ?? 'UNKNOWN';
+}
+/** Returns the best numeric error code for a given error and protocol. */
+export function statusProtocolCode(protocol, err) {
+    return (err.protocolCodes[protocol] ??
+        (protocol === 'grpc' ? statusToGrpcCode : statusToHttpCode)(err.status));
+}
+export function inferErrorStatus(err) {
+    return isStatusError(err) ? err.status : 'UNKNOWN';
+}
+/** Generates a new failure from a status error. */
+export function failure(err, opts) {
+    let message = err.message.trimEnd();
+    if (opts?.annotations) {
+        for (const a of opts.annotations) {
+            message = annotating(message, a.trim());
+        }
+    }
+    const data = { status: err.status, error: { message } };
+    if (isInternalProblem(err.status)) {
+        return data;
+    }
+    const contents = findContents(err);
+    if (!contents) {
+        return data;
+    }
+    if (isStandardError(contents)) {
+        data.error.code = contents.code;
+        const tags = { ...contents.tags };
+        if (Object.keys(tags).length) {
+            data.error.tags = tags;
+        }
+    }
+    return data;
+}
+const punctuatedPattern = /[.!?]$/;
+function annotating(msg, annotation) {
+    return annotation
+        ? punctuatedPattern.test(msg)
+            ? `${msg} ${annotation}`
+            : `${msg}. ${annotation}`
+        : msg;
+}
+/**
+ * Wraps and rethrows an (internal) error with the status specified in the input
+ * mapping. If the error is not an internal one or doesn't match, this method
+ * rethrows the original error. Note that this method does not walk the error's
+ * causal chain to avoid swallowing downstream errors.
+ */
+export function rethrowWithStatus(err, mapping) {
+    if (!isStandardError(err)) {
+        throw err;
+    }
+    for (const [status, val] of Object.entries(mapping)) {
+        if (!isErrorStatus(status)) {
+            throw errors.illegal({ message: 'Invalid status: ' + status });
+        }
+        const codes = typeof val == 'string' ? [val] : val;
+        for (const code of codes) {
+            if (code === err.code) {
+                throw statusError(status, err);
+            }
+        }
+    }
+    throw err;
+}

package/lib/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Structured code string, useful for programmatic error handling. See also the
+ * `TaggedErrorCode` variant which supports strongly-typed error retrieval.
+ */
+export type ErrorCode = `ERR_${string}`;
+export type ErrorPrefix = 'ERR_' | `ERR_${string}_`;
+/** An error with associated code and, optionally, cause and structured data. */
+export interface StandardError<T extends ErrorTags = ErrorTags> extends Error, HasErrorTags<T> {
+    /**
+     * The error's code. This code should uniquely identify the type of failure
+     * represented by the error.
+     */
+    readonly code: ErrorCode;
+    /** The underlying cause(s) of the error, if any. */
+    readonly cause?: unknown | ReadonlyArray<unknown>;
+}
+/** Convenience type generating an error type from its code. */
+export type StandardErrorForCode<C extends ErrorCode> = StandardError<ErrorTagsFor<C>>;
+/** Error with attached structured metadata. */
+export interface HasErrorTags<T extends ErrorTags> {
+    /**
+     * Metadata tied for the error. This is particularly useful for programmatic
+     * handling of errors.
+     */
+    readonly tags: T;
+}
+/**
+ * Generic structured metadata type. Errors constructed via `errorFactories`
+ * will have a more specific type.
+ */
+export interface ErrorTags {
+    readonly [key: string]: unknown;
+    readonly [key: symbol]: unknown;
+}
+/**
+ * Virtual (type-level) key used to store tag information. We don't use a symbol
+ * to allow type-checking to work across compatible versions of this library.
+ */
+declare const errorCodeTag = "@mtth/stl-errors:errorCodeTag+v1";
+/**
+ * An error code with attached type information about the error's tags. This
+ * information can be picked up during retrieval (e.g. `isStandardError`) to
+ * make the type of matching error's tags as specific as possible.
+ */
+export type TaggedErrorCode<T extends ErrorTags> = ErrorCode & {
+    readonly [errorCodeTag]: T;
+};
+export type ErrorTagsFor<C extends ErrorCode> = C extends TaggedErrorCode<infer T> ? T : ErrorTags;
+/** Standard error creation options. */
+export interface ErrorOptions {
+    /** A human readable description of the error. */
+    readonly message?: string;
+    /** Structured data to attach to the error. */
+    readonly tags?: ErrorTags;
+    /**
+     * Optional underlying error(s) which caused this one. If not an error or
+     * array of errors, the cause will be normalized to one.
+     */
+    readonly cause?: unknown | ReadonlyArray<unknown>;
+    /**
+     * Advanced option to customize the error's stack trace. Passing in a function
+     * will make it start at this frame. Passing in `false` will disable it
+     * altogether. `true` (the default) will generate a standard stack trace. Note
+     * that errors without a stack trace are ~90% cheaper to create (whether the
+     * stack is accessed or not).
+     */
+    readonly stackFrom?: boolean | Function;
+}
+export type DeepErrorCodes<O> = {
+    readonly [K in keyof O]: O[K] extends ErrorCode | ErrorCodes ? O[K] : DeepErrorCodes<O[K]>;
+} & ReadonlySet<ErrorCode>;
+export type ErrorCodes<S extends string = string> = {
+    readonly [K in S]: ErrorCode;
+} & ReadonlySet<string>;
+export {};