@zudojs/errors

OVERVIEW

When something goes wrong in JavaScript you throw a value, usually an Error. A plain Error only carries a message and a stack trace. It cannot tell you whether the problem was the caller's fault or the server's, which HTTP status to send back, or whether the message is safe to show to a stranger.

@zudojs/errors fixes that with BaseError. Every error built on it carries a stable code, a category, a severity, an HTTP statusCode, an expose flag, and a bag of metadata. Every other Zudo package throws these, so one catch block can handle all of them the same way.

The package also ships helpers that convert anything that was thrown (a string, a TypeError, undefined) into a BaseError, and serializers that produce a client-safe JSON body from it.

INSTALLATION

The package has no dependencies, so this is the only install step.

QUICK START

This example throws a ready-made error, catches it, and turns it into a JSON body you could send back from an API.

You never told the error which status code to use. NotFoundError already knows it is a 404, that it is safe to show to clients, and that it belongs to the resource category. That is the whole idea: the error carries its own handling rules.

BASEERROR

An error class is a blueprint for error objects. new BaseError("...") makes an object that behaves like a normal Error (it has message, stack, and works with throw and instanceof) but with extra fields attached.

The constructor takes a message and an optional options object. Every option has a default, so the shortest call is just the message.

The fields, and what they mean for an API

Useful methods

Every BaseError has these methods. withMetadata returns a copy; it never changes the original.

CODES, CATEGORIES AND SEVERITY

These three enums are the vocabulary the whole framework shares. An enum is a fixed list of named string values; using ErrorCode.NOT_FOUND instead of typing "ERR_NOT_FOUND" means a typo becomes a compile error.

• → ErrorCode — the machine-readable identity of the error. Values look like "ERR_VALIDATION_FAILED". You may also pass any custom string as a code.
• → ErrorCategory — the area that failed. Values look like "validation", "database", "rate_limit".
• → ErrorSeverity — INFO, WARNING, ERROR, CRITICAL, FATAL, in increasing order.

Helper functions let you compare and validate these values. This example checks a severity and decides whether to page someone.

READY-MADE ERRORS

You rarely construct BaseError directly. The package ships subclasses whose code, category, severity, status and expose flag are already set. Each one comes with a class, a create… factory, an is… type guard, and a few named shortcuts.

This example uses the five you will reach for most in an API.

The full set

Every family below is exported from the package root. The status and exposure listed are the defaults; you can override either through options.

The subsystem families are thrown by the matching Zudo package (@zudojs/cache throws CacheError, and so on). You catch them; you rarely construct them yourself.

EventListenerLimitExceededError (new in 1.2.0) is the one member of the EventError family worth catching by name. It is raised when a single event pattern passes its configured handler limit — the signature of a subscribe-without-unsubscribe leak — and carries the pattern, the handler count and the limit, both as own readonly fields and inside metadata. Registering past a handler limit is a programming fault rather than bad input, so the class fixes its classification as internal: statusCode 500, expose false, isOperational false. It is never exposed to a caller — serializePublicError replaces its message with "An unexpected error occurred." and drops its metadata.

Before 1.2.0 the class did not exist here and nothing in the framework ever threw it, so a catch branch testing for it was unreachable. @zudojs/events now raises it, but only when a registry, emitter or bus is configured to enforce its handler limit; the default is still a one-shot warning that lets the registration through. The class is owned by @zudojs/errors and re-exported from @zudojs/events, so an import from either package resolves to the same constructor and instanceof matches across both.

SchemaError and RPCError: typed extras

Two families carry structured data beyond the message. SchemaError holds the list of validation issues. It is generic: SchemaError<TIssue = unknown> takes the shape of one issue as a type parameter. This package sits below @zudojs/schema and cannot know that shape, so the default is unknown; @zudojs/schema throws SchemaError<SchemaIssue>. SchemaErrorOptions<TIssue> and createSchemaError<TIssue> take the same parameter, and code that never names it keeps working unchanged.

RPCError now declares a readonly details and accepts it as an option. details is the structured, caller-safe part of an RPC error's wire payload: validation issues, { retryAfter } for a rate limit, or whatever a custom error sent. An @zudojs/rpc client sets it on the errors it rebuilds from a response, so you read error.details without a cast. toJSON() includes it when present.

New in 1.3.0: failed results, stopped buses, refused commits

Version 1.3.0 adds a handful of classes that other Zudo packages now throw. Before, those packages either returned a failure as if it were a normal value, or threw an error whose message described the wrong problem. Because the classes live here, instanceof works the same whether you import them from @zudojs/errors or from the package that throws them.

• → CommandFailedError and QueryFailedError are thrown by unwrapCommandResult() and unwrapQueryResult() in @zudojs/cqrs when the result's status is "failure". The failure payload is on error.failure and also on error.cause. They are 500s and are not exposed, because the payload is an internal value. New codes: ErrorCode.COMMAND_FAILED and ErrorCode.QUERY_FAILED.
• → EventBusStoppedError is thrown when you publish or subscribe on an @zudojs/events bus after stop(). Call start() to resume. EventBusDisposedError also moved here, and its code is now ERR_EVENT_BUS_DISPOSED (it was ERR_LIFECYCLE_DISPOSED).
• → TransactionRollbackOnlyError is thrown by @zudojs/transactions when you commit a transaction that was marked rollback-only. It used to be a TransactionRollbackError saying "rollback failed", which sent people looking for the wrong bug. It extends TransactionRollbackError, so existing instanceof checks and the error code still match. TransactionRollbackError itself now accepts an optional message option.
• → SerializationDepthError takes an optional third argument, { statusCode?, expose? }. Without it the error is still a hidden 500. The depth guards in @zudojs/validation (assertDepthWithinLimit, assertNoCircularReference) pass { statusCode: 400, expose: true }, so a request body nested too deep is now a 400 the client can see instead of a hidden server error. The message holds only the two numbers, so it is safe to expose.
• → New auth codes ErrorCode.TOKEN_REVOKED, ErrorCode.ACCOUNT_LOCKED and ErrorCode.ACCOUNT_DEACTIVATED. @zudojs/auth uses them for TokenRevokedError, AccountLockedError and AccountDeactivatedError, which all used to share ERR_FORBIDDEN.

This example builds each new error by hand so you can see what it carries. In an app you would normally catch them rather than construct them.

WRITING YOUR OWN ERROR

When none of the ready-made classes fits, extend BaseError. Extending means your class inherits everything BaseError has and adds its own defaults. Set the classification once in the constructor so every caller gets it for free.

This example defines a 402 error for a declined payment and shows what a client would receive.

METADATA

metadata is where you attach facts about the failure: which user, which record, which query. It must be JSON-safe (strings, numbers, booleans, null, arrays, plain objects). The constructor deep-copies and freezes it, so later changes to your original object do not leak in, and nobody can mutate it afterwards.

Some values are converted rather than rejected: Date becomes an ISO string, Map becomes an object, bigint becomes a string, and cyclic references become "[Circular]". Keys named __proto__, constructor or prototype are always dropped. Nesting is bounded as well: a subtree deeper than MAX_METADATA_DEPTH (32) levels is replaced with "[MaxDepth]" instead of being walked.

Secrets are the bigger concern. The serializers redact any key whose name looks sensitive (password, token, authorization, cookie, apiKey, ssn, and similar) at every depth. You can run the same redaction yourself.

SERIALIZING: toJSON VS PUBLIC OUTPUT

Serializing means turning the error object into plain data that can be logged or sent over the network. There are two audiences, and the package gives you a different function for each.

toJSON() — for your logs

error.toJSON() returns everything: name, message, all classification fields, metadata, the stack trace, and the full cause chain (cycle-safe, cut off after 8 levels counted across the whole chain). Because it is named toJSON, JSON.stringify(error) calls it automatically. It redacts metadata under sensitive keys (and sensitive keys in plain-object causes and issue values), but it does not honour expose. It is for trusted, internal output only.

Subclasses add their own fields on top: ValidationError adds issues (with submitted values replaced by a type description when the error is exposed), and RateLimitError adds retryAfterSeconds.

Two different depth limits apply, and both are bounded. The cause chain stops after 8 links. The walk into a plain-object or array cause — the one that redacts sensitive keys inside it — stops after MAX_METADATA_DEPTH (32) levels and writes "[MaxDepth]" in place of the deeper subtree, exactly as metadata cloning already did. Before 1.2.0 that second walk was unbounded, so attaching a deeply nested value as a cause — a parsed request body, for instance — could raise a RangeError from inside toJSON, serializeError with includeCause: true or ErrorHandler.toLogObject, which turned a logged error into a crash on the logging path. Those paths now stay safe whatever depth the input arrives at.

serializePublicError() — for clients

serializePublicError(error) returns only code, message, category, statusCode, and sometimes metadata. It never includes a stack or cause. If expose is false the message is replaced with "An unexpected error occurred." and metadata is left out entirely. If expose is true, metadata is included after redaction.

serializeError(error, options) is the internal counterpart: it redacts metadata by default and leaves out the stack and cause unless you pass includeStack: true or includeCause: true. Use new ErrorSerializer(options) when you want to configure once and call serialize / serializePublic many times.

HANDLING UNKNOWN ERRORS

In a catch block the value is typed unknown because JavaScript lets you throw anything: a string, null, a plain object, a TypeError from a library. normalizeToBaseError turns any of those into a BaseError so the rest of your code has one shape to deal with.

Values that are already a BaseError pass through unchanged. Everything else becomes a 500 that is not exposed and not operational, with the original value kept as cause.

tryCatchAsync does the same for functions that return a promise. toBaseError, normalizeUnknownError and normalizeError are older names for the same normalization and behave identically.

ErrorHandler: normalize, report, respond in one call

ErrorHandler bundles the steps an API needs at its outermost catch: normalize the thrown value, send it to a reporter (your logger or monitoring tool), and build the response body. If the reporter itself throws, the failure is swallowed (or passed to onReporterError) and you still get a result.

Use handle() instead of handlePublic() when you want the internal shape (it adds category, severity, isOperational, expose and redacted metadata). Use toLogObject(error) for the fullest log entry, including the cause chain.

Mapping third-party errors

If a library throws its own error class, register a rule so it becomes the right Zudo error instead of a generic 500. mapErrorType matches by instanceof.

API REFERENCE

Everything below is exported from @zudojs/errors. The error classes themselves are listed in Ready-made errors.

Classes

Functions

Types and constants

COMMON MISTAKES

• → Sending error.toJSON() to the client. The stack trace and raw metadata go out with it. Use serializePublicError or ErrorHandler.handlePublic.
• → Throwing a plain Error for a user mistake. It normalizes to a hidden 500, so the user sees "An unexpected error occurred." Throw ValidationError, NotFoundError, or another 4xx class instead.
• → Using 401 when you mean 403. 401 (AuthenticationError) is "not logged in"; 403 (AuthorizationError) is "logged in, not allowed". Clients often redirect to a login page on 401.
• → Expecting withMetadata to mutate. It returns a copy. Write error = error.withMetadata({...}) or throw the returned value.
• → Putting a secret under a harmless key. Redaction is name-based. metadata: { note: "pw is hunter2" } is not redacted.
• → Matching on messages in tests. Assert on error.code or use the is…Error guards; messages are free to change.

RELATED PACKAGES

• → @zudojs/http — turns these errors into real HTTP responses; the statusCode and expose rules above are what it follows.
• → @zudojs/validation — produces ValidationError with a filled issues list from a schema.
• → @zudojs/logger — where toJSON() / toLogObject() output usually ends up.
• → @zudojs/auth — throws AuthenticationError and AuthorizationError for you.
• → @zudojs/database — throws DatabaseError and the database timeout errors.

COMPLETE EXPORT INDEX

Every name @zudojs/errors exports from its package root at v1.3.0 — 629 in total, generated from the package’s own entry point rather than written by hand. The sections above explain the ones you reach for most; this is the exhaustive list, so nothing shipped is undocumented. Names not covered above are typically internal helpers and supporting types.