@zudojs/constants

OVERVIEW

A constant is a value that never changes while your program runs. 200 is always "OK", a minute is always 60000 milliseconds, and "production" is always spelled that way. @zudojs/constants collects those values so every package in the framework, and your own code, spells them identically.

It also ships a handful of small helper functions that go with those values — checking whether a status code is an error, turning hours into milliseconds, building a Cache-Control header — plus a set of branded id types that stop you from passing a user id where an event id belongs.

Nothing here talks to a network, a disk, or a clock you did not give it. The package is data and pure functions. Its only dependency is @zudojs/errors, which supplies the base class for the two errors it throws.

INSTALLATION

Install the package. It pulls in @zudojs/errors on its own. It needs Node 24 or newer, and it is ESM only.

There is a single entry point. Every export on this page comes from "@zudojs/constants" — there are no per-module subpaths such as "@zudojs/constants/http".

QUICK START

This reads the current environment, picks a timeout, and decides what a status code means.

Every constant object is frozen, so HttpStatus.OK = 999 throws in strict mode instead of quietly corrupting the value for every other file that imported it.

CONSTANT OR PLAIN LITERAL?

You do not have to import a constant to write 200. The question is whether the name buys you something. It usually buys you one of three things.

• The compiler checks your spelling. Each constant map has a matching union type — HttpMethod, Environment, CacheStrategy, Priority, LifecycleState. Declare a parameter as that type and a typo stops the build.
• The number is hard to read. TimeMs.DAY says what 86400000 means, and you cannot lose a zero.
• Other packages must agree with you. If @zudojs/cache and your handler both mean the same 10 MB limit, both should read Limits.MAX_FILE_SIZE.

Where none of that applies — a one-off if (code === 418) in a single file — the literal is fine. Reach for the constant when the value crosses a file boundary.

The union types are the real payoff. Here a function accepts only the four environment names, so a typo is caught before the program runs.

Common mistake. Writing const method: HttpMethods = "GET". HttpMethods is a value, not a type, so TypeScript rejects it. The type is HttpMethod.

HTTP: METHODS, STATUS, HEADERS, TYPES

Four maps cover the wire format of an HTTP message: HttpMethods (GET, POST, …), HttpStatus (the numeric codes), HttpHeader (header names, correctly capitalised), and ContentTypes (MIME types). Each is a frozen object whose keys are shouty and whose values are the real strings or numbers.

Alongside them sit five range checks — isSuccessStatus, isRedirectStatus, isClientError, isServerError, isErrorStatus — that take any number, so they work on codes a third-party server invented too.

This reads a few of the constants and runs two of the checks.

Three ready-made sets answer membership questions: HTTP_METHODS (all nine), SAFE_HTTP_METHODS (GET, HEAD, OPTIONS — the ones that must not change anything) and IDEMPOTENT_HTTP_METHODS (safe to send twice: GET, HEAD, PUT, DELETE, OPTIONS, TRACE). They are immutable at run time: add, delete and clear throw a TypeError rather than silently letting a caller widen the rules.

buildContentType skips the charset for multipart/* types, because a multipart body takes a boundary parameter instead. It throws InvalidConstantError on an empty MIME type or a blank charset.

Common mistake. Typing a value as HttpStatusCode when it came from another server. HttpStatusCode is only the codes listed in HttpStatus; for anything else use AnyHttpStatusCode, which is just number. The same pairing exists for headers (AnyHttpHeaderName) and MIME types (AnyContentType).

ENVIRONMENT

An environment is which copy of your app is running: the one on your laptop, the one running tests, the staging clone, or the real thing. Node convention keeps that in the NODE_ENV environment variable, and resolveEnvironment() reads it for you.

It normalises case and accepts the common short forms dev and prod. Unset or empty means "development". A value it does not recognise also falls back to "development", but it warns once per distinct value so a typo in a deployment cannot pass unnoticed.

You can pass your own map of variables instead of reading process.env, which is what makes this testable.

In a deployment you usually want the typo to be loud rather than merely logged. Pass { strict: true } and an unrecognised value throws an InvalidConstantError; pass { silent: true } to drop the warning instead.

Common mistake. Calling resolveEnvironment("staging") to force a value. The first argument is a map of environment variables, not a name, so that call is a type error. Write resolveEnvironment({ NODE_ENV: "staging" }).

TIME, TIMEOUTS AND RETRIES

Every duration in the framework is a number of milliseconds. TimeMs names the common ones so you multiply instead of counting zeros: MILLISECOND, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH (30 days) and YEAR (365 days).

DefaultTimeout and DefaultRetry are starting points for settings you have no strong opinion about yet. toMilliseconds converts from a unit, and formatDuration turns milliseconds back into something a human reads in a log line.

This builds a TTL, converts a duration, and formats two for display.

DefaultTimeout

DefaultRetry holds MAX_ATTEMPTS (3), BASE_DELAY_MS (1000), MAX_DELAY_MS (30000) and BACKOFF_MULTIPLIER (2).

Common mistake. Confusing DefaultRetry.MAX_ATTEMPTS (3) with Limits.MAX_RETRY_ATTEMPTS (10). The first is what a caller gets when they configure nothing; the second is the highest number a caller is allowed to ask for.

VALIDATION PATTERNS AND LIMITS

A regular expression (regex) is a pattern that says which strings are acceptable. Getting one right for email or IPv6 is fiddly, so ValidationPattern keeps a tested set in one place. These are the framework's single source of truth: SCHEMA_STRING_FORMATS points at the same objects rather than redefining them.

ValidationLength holds maximum character counts and ValidationRange holds numeric bounds, so a check like "is this a legal port?" reads the same everywhere.

This checks a few values against the shared patterns and limits.

Common mistake. Copying a pattern into your own file and editing it. The copy drifts from the one @zudojs/schema and @zudojs/validation use, so the same string passes in one layer and fails in the next. Import it instead.

CACHE HEADERS AND PRIORITY

Cache-Control is the HTTP header that tells browsers and proxies whether they may keep a copy of a response, and for how long. CacheStrategies names the directives, CacheDuration holds sensible lifetimes in seconds (the unit that header uses), and buildCacheControl assembles the string.

This builds a header for a page that may be cached publicly for an hour.

Durations must be whole, non-negative numbers; anything else throws InvalidConstantError. CacheDuration runs NONE 0, SHORT 10, MEDIUM 300, LONG 3600, VERY_LONG 86400, WEEK 604800. There is also sharedMaxAge, which emits s-maxage for proxies.

Priority

When several jobs or events are waiting, priority decides which runs first. Priorities names five levels, PriorityWeight gives each a number, and comparePriority is a comparator you hand straight to Array.prototype.sort. It returns a negative number when the first argument is the more urgent one, so sorting puts urgent items first.

Common mistake. Passing CacheDuration values where milliseconds are expected. These are seconds, because Cache-Control counts in seconds. TimeMs is the millisecond family.

BRANDED IDENTIFIERS

A user id and an event id are both strings, so nothing stops you passing one where the other belongs. A branded type fixes that: it is the same string at run time, but TypeScript attaches an invisible label to it and refuses to swap one label for another.

You attach the label with a createX factory. Eight of them are plain relabelling — createUserId, createEventId, createRequestId, createCorrelationId, createSessionId, createMessageId, createMessageCausationId, createTokenId. Seven also validate, and throw InvalidConstantError if the string is wrong: createTimestamp (which also rejects impossible dates such as 30 February), createUrl, createEmailAddress, createHexString, createBase64String, createJsonString, and createTenantId (normalizes, then enforces [a-z0-9][a-z0-9_-]*, max 64 — TENANT_ID_PATTERN, MAX_TENANT_ID_LENGTH).

This labels two ids and shows the compiler catching a swap.

The labelled types are UserId, EventId, RequestId, CorrelationId, SessionId, TenantId, MessageId, MessageCausationId, TokenId, Timestamp, Url, EmailAddress, HexString, Base64String and JsonString. EntityId is a plain unbranded string, and Brand<T, B extends string> is the helper you use to make your own.

Common mistake. Writing someString as UserId instead of calling the factory. It compiles, but for the six validating types you skip the check and a malformed value travels on as if it had been verified.

SHARED FRAMEWORK VOCABULARY

The rest of the package exists so that separate packages agree with each other. You will mostly read these values rather than write them, and you need them when you implement or extend a framework piece yourself.

Limits, Defaults and sentinels

Limits holds ceilings such as MAX_PAGE_SIZE (100), DEFAULT_PAGE_SIZE (20), MAX_FILE_SIZE (10485760) and MAX_RETRY_ATTEMPTS (10). Defaults holds fallbacks such as PORT (3000), TIMEZONE ("UTC") and CONTENT_TYPE ("application/json").

A sentinel is a stand-in value that means "nothing here" without using null everywhere. Sentinel carries NULL, DELETED ("__DELETED__"), PLACEHOLDER and WILDCARD ("*"), and the loose constants NONE, UNINITIALIZED and EMPTY cover the same need for plain strings.

Lifecycle states

A lifecycle is the sequence a component moves through from created to shut down. LifecycleState names the ten states, LifecyclePhase names the five hooks you can implement, and LIFECYCLE_VALID_TRANSITIONS maps each state to the states it may move to next.

The defaults that go with it are LIFECYCLE_DEFAULT_TIMEOUT, LIFECYCLE_DEFAULT_START_TIMEOUT, LIFECYCLE_DEFAULT_STOP_TIMEOUT, LIFECYCLE_DEFAULT_SHUTDOWN_TIMEOUT, LIFECYCLE_DEFAULT_CONCURRENCY, LIFECYCLE_DEFAULT_RETRY_ATTEMPTS, LIFECYCLE_DEFAULT_RETRY_DELAY and LIFECYCLE_DEFAULT_RETRY_MAX_DELAY.

Schema and serialization

SchemaIssueCode is the stable list of reasons validation can fail ("invalid_type", "required", "too_small", and so on), which lets you branch on a code instead of matching a message. It ships alongside depth and size defaults and SCHEMA_FORBIDDEN_KEYS, an immutable set (not a Set instance; Set.prototype methods cannot mutate it) of the keys that must never be copied into an object.

The serialization group (SerializationFormat, SerializationContentType, SerializationLimits, SerializationTags, SERIALIZATION_SCHEMA_VERSION) does the same job for @zudojs/serialization: format names, MIME types, size guards, and the $type / $value / $encoding keys it writes into tagged JSON.

CLOCK AND RANDOM FOR TESTS

Code that calls Date.now() or Math.random() directly is hard to test, because the answer changes every run. The fix is to take the clock or the random source as a parameter. Clock and Random are those two small interfaces.

In production you pass systemClock and systemRandom. In a test you pass createMockClock(), whose time only moves when you move it, and createMockRandom(seed), which produces the same sequence for the same seed.

This function takes a clock, so a test can decide what time it is.

systemRandom is backed by node:crypto all the way through, including random(), so it is safe for tokens, session ids and salts. createMockRandom is a seeded generator for tests only — never use it for anything security related.

Common mistake. Reading randomInt(1, 100) as excluding 100. Both ends are included, so it can return 100.

API REFERENCE

Everything below is exported from "@zudojs/constants". Constant maps are listed by group rather than key by key.

Functions

Values and constant maps

Types

Errors

COMMON MISTAKES

• Importing from a subpath. import { HttpMethod } from "@zudojs/constants/http" fails to resolve, because the package declares a single entry point. Import everything from "@zudojs/constants".

• Passing a name to resolveEnvironment. resolveEnvironment("staging") is a type error; the argument is a map of environment variables. Write resolveEnvironment({ NODE_ENV: "staging" }).

• Mixing seconds and milliseconds. CacheDuration.LONG is 3600 seconds; TimeMs.HOUR is 3600000 milliseconds. Passing the first where milliseconds are expected gives you a 3.6 second timeout.

• Casting instead of calling the factory. value as EmailAddress skips the check that createEmailAddress(value) performs, so an invalid address gets the branded type anyway.

• Using the plural map as a type. const m: HttpMethods = "GET" does not compile. HttpMethods is the value; HttpMethod is the type.

• Assuming an unknown NODE_ENV is fatal. By default it warns once and falls back to "development", which in production is the wrong behaviour to discover late. Pass { strict: true } at start-up so a typo fails immediately.

RELATED PACKAGES

• @zudojs/errors — the only dependency; supplies BaseError and the codes the two errors here use.
• @zudojs/validation — when you need to actually run checks rather than just hold the patterns and limits.
• @zudojs/schema — consumes SchemaIssueCode and the schema limits to describe and parse data shapes.
• @zudojs/config — for values that change per deployment; constants are for values that never change.
• @zudojs/lifecycle — runs the state machine that LifecycleState and LIFECYCLE_VALID_TRANSITIONS describe.

COMPLETE EXPORT INDEX

Every name @zudojs/constants exports from its package root at v1.1.1 — 124 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.