@zudojs/constants 0.0.1 → 1.0.0

package/dist/common/common.lifecycle.js

@@ -3,29 +3,40 @@
  *
  * Lifecycle states, phases, valid transitions, and defaults.
  */
-/** Lifecycle states — a strongly-typed state machine. */
-export var LifecycleState;
-(function (LifecycleState) {
-    LifecycleState["IDLE"] = "idle";
-    LifecycleState["INITIALIZING"] = "initializing";
-    LifecycleState["INITIALIZED"] = "initialized";
-    LifecycleState["STARTING"] = "starting";
-    LifecycleState["STARTED"] = "started";
-    LifecycleState["READY"] = "ready";
-    LifecycleState["STOPPING"] = "stopping";
-    LifecycleState["STOPPED"] = "stopped";
-    LifecycleState["FAILED"] = "failed";
-    LifecycleState["DISPOSED"] = "disposed";
-})(LifecycleState || (LifecycleState = {}));
-/** Lifecycle phases — the discrete hooks a component can implement. */
-export var LifecyclePhase;
-(function (LifecyclePhase) {
-    LifecyclePhase["INITIALIZE"] = "initialize";
-    LifecyclePhase["START"] = "start";
-    LifecyclePhase["READY"] = "ready";
-    LifecyclePhase["STOP"] = "stop";
-    LifecyclePhase["DISPOSE"] = "dispose";
-})(LifecyclePhase || (LifecyclePhase = {}));
+import { DefaultRetry } from "../time/time.constant.js";
+import { Limits } from "./common.constant.js";
+/**
+ * Lifecycle states — a strongly-typed state machine.
+ *
+ * Declared as a frozen `as const` object (not a TS `enum`) to match the rest
+ * of the package; `LifecycleState` is also exported as the union type of its
+ * values, so it can be used in both value and type positions.
+ */
+export const LifecycleState = Object.freeze({
+    IDLE: "idle",
+    INITIALIZING: "initializing",
+    INITIALIZED: "initialized",
+    STARTING: "starting",
+    STARTED: "started",
+    READY: "ready",
+    STOPPING: "stopping",
+    STOPPED: "stopped",
+    FAILED: "failed",
+    DISPOSED: "disposed",
+});
+/**
+ * Lifecycle phases — the discrete hooks a component can implement.
+ *
+ * Declared as a frozen `as const` object; `LifecyclePhase` is also the union
+ * type of its values.
+ */
+export const LifecyclePhase = Object.freeze({
+    INITIALIZE: "initialize",
+    START: "start",
+    READY: "ready",
+    STOP: "stop",
+    DISPOSE: "dispose",
+});
 /** Valid state transitions for the lifecycle state machine. */
 export const LIFECYCLE_VALID_TRANSITIONS = Object.freeze({
     [LifecycleState.IDLE]: Object.freeze([
@@ -73,10 +84,13 @@ export const LIFECYCLE_DEFAULT_START_TIMEOUT = 30_000;
 export const LIFECYCLE_DEFAULT_STOP_TIMEOUT = 10_000;
 /** Default global shutdown deadline (ms). */
 export const LIFECYCLE_DEFAULT_SHUTDOWN_TIMEOUT = 30_000;
-/** Default concurrency limit for parallel component operations. */
-export const LIFECYCLE_DEFAULT_CONCURRENCY = 10;
-/** Default retry attempts. */
-export const LIFECYCLE_DEFAULT_RETRY_ATTEMPTS = 3;
+/**
+ * Default concurrency limit for parallel component operations
+ * (canonical: {@link Limits.MAX_CONCURRENCY}).
+ */
+export const LIFECYCLE_DEFAULT_CONCURRENCY = Limits.MAX_CONCURRENCY;
+/** Default retry attempts (canonical: {@link DefaultRetry.MAX_ATTEMPTS}). */
+export const LIFECYCLE_DEFAULT_RETRY_ATTEMPTS = DefaultRetry.MAX_ATTEMPTS;
 /** Default retry delay (ms). */
 export const LIFECYCLE_DEFAULT_RETRY_DELAY = 500;
 /** Maximum retry delay (ms). */

package/dist/common/common.schema.d.ts

@@ -3,46 +3,75 @@
  *
  * Schema-related constants, issue codes, and default limits.
  */
-/** Schema issue codes — machine-readable, stable identifiers. */
-export declare enum SchemaIssueCode {
-    INVALID_TYPE = "invalid_type",
-    REQUIRED = "required",
-    INVALID_LITERAL = "invalid_literal",
-    INVALID_ENUM = "invalid_enum",
-    INVALID_UNION = "invalid_union",
-    INVALID_STRING = "invalid_string",
-    INVALID_FORMAT = "invalid_format",
-    INVALID_NUMBER = "invalid_number",
-    TOO_SMALL = "too_small",
-    TOO_LARGE = "too_large",
-    INVALID_LENGTH = "invalid_length",
-    INVALID_KEY = "invalid_key",
-    INVALID_ELEMENT = "invalid_element",
-    UNKNOWN_KEYS = "unknown_keys",
-    CIRCULAR_REFERENCE = "circular_reference",
-    MAX_DEPTH_EXCEEDED = "max_depth_exceeded",
-    CUSTOM = "custom",
-    PREPROCESS_FAILED = "preprocess_failed",
-    TRANSFORM_FAILED = "transform_failed",
-    REFINE_FAILED = "refine_failed",
-    COERCION_FAILED = "coercion_failed"
-}
-/** Default maximum depth for schema validation. */
+/**
+ * Schema issue codes — machine-readable, stable identifiers.
+ *
+ * Declared as a frozen `as const` object (not a TS `enum`) to match the rest
+ * of the package; `SchemaIssueCode` is also exported as the union type of its
+ * values, so it can be used in both value and type positions.
+ */
+export declare const SchemaIssueCode: Readonly<{
+    readonly INVALID_TYPE: "invalid_type";
+    readonly REQUIRED: "required";
+    readonly INVALID_LITERAL: "invalid_literal";
+    readonly INVALID_ENUM: "invalid_enum";
+    readonly INVALID_UNION: "invalid_union";
+    readonly INVALID_STRING: "invalid_string";
+    readonly INVALID_FORMAT: "invalid_format";
+    readonly INVALID_NUMBER: "invalid_number";
+    readonly TOO_SMALL: "too_small";
+    readonly TOO_LARGE: "too_large";
+    readonly INVALID_LENGTH: "invalid_length";
+    readonly INVALID_KEY: "invalid_key";
+    readonly INVALID_ELEMENT: "invalid_element";
+    readonly UNKNOWN_KEYS: "unknown_keys";
+    readonly CIRCULAR_REFERENCE: "circular_reference";
+    readonly MAX_DEPTH_EXCEEDED: "max_depth_exceeded";
+    readonly CUSTOM: "custom";
+    readonly PREPROCESS_FAILED: "preprocess_failed";
+    readonly TRANSFORM_FAILED: "transform_failed";
+    readonly REFINE_FAILED: "refine_failed";
+    readonly COERCION_FAILED: "coercion_failed";
+}>;
+/** Type-safe schema issue code — the union of all {@link SchemaIssueCode} values. */
+export type SchemaIssueCode = (typeof SchemaIssueCode)[keyof typeof SchemaIssueCode];
+/**
+ * Default maximum depth for schema validation (recursion guard).
+ *
+ * Intentionally distinct from `Limits.MAX_NESTING_DEPTH` (10 — bound on
+ * acceptable user data shape) and `SerializationLimits.MAX_DEPTH` (128 —
+ * serializer recursion guard).
+ */
 export declare const SCHEMA_DEFAULT_MAX_DEPTH = 100;
-/** Default maximum string length. */
-export declare const SCHEMA_DEFAULT_MAX_STRING_LENGTH = 255;
+/**
+ * Default maximum string length
+ * (canonical: {@link Limits.MAX_DISPLAY_LENGTH}).
+ */
+export declare const SCHEMA_DEFAULT_MAX_STRING_LENGTH: 255;
 /** Default maximum array length. */
 export declare const SCHEMA_DEFAULT_MAX_ARRAY_LENGTH = 1000;
 /** Default maximum object key count. */
 export declare const SCHEMA_DEFAULT_MAX_OBJECT_KEYS = 100;
-/** Object keys that are forbidden for prototype pollution protection. */
+/**
+ * Object keys that are forbidden for prototype pollution protection.
+ *
+ * Backed by an immutable Set: `add`/`delete`/`clear` throw at runtime, so
+ * this security guard cannot be weakened by accident (or on purpose).
+ */
 export declare const SCHEMA_FORBIDDEN_KEYS: ReadonlySet<string>;
-/** Common string format regex patterns. */
+/**
+ * Common string format regex patterns.
+ *
+ * These reference {@link ValidationPattern} — the single source of truth for
+ * validation regexes — rather than redefining them.
+ */
 export declare const SCHEMA_STRING_FORMATS: Readonly<{
     readonly EMAIL: RegExp;
     readonly URL: RegExp;
+    /** UUID — any version (use UUID_V4 for strict v4). */
     readonly UUID: RegExp;
     readonly UUID_V4: RegExp;
+    /** ISO 8601 date-time with optional fraction and Z/±hh:mm offset. */
     readonly DATETIME: RegExp;
     readonly DATE: RegExp;
     readonly TIME: RegExp;

package/dist/common/common.schema.js

@@ -3,53 +3,86 @@
  *
  * Schema-related constants, issue codes, and default limits.
  */
-/** Schema issue codes — machine-readable, stable identifiers. */
-export var SchemaIssueCode;
-(function (SchemaIssueCode) {
-    SchemaIssueCode["INVALID_TYPE"] = "invalid_type";
-    SchemaIssueCode["REQUIRED"] = "required";
-    SchemaIssueCode["INVALID_LITERAL"] = "invalid_literal";
-    SchemaIssueCode["INVALID_ENUM"] = "invalid_enum";
-    SchemaIssueCode["INVALID_UNION"] = "invalid_union";
-    SchemaIssueCode["INVALID_STRING"] = "invalid_string";
-    SchemaIssueCode["INVALID_FORMAT"] = "invalid_format";
-    SchemaIssueCode["INVALID_NUMBER"] = "invalid_number";
-    SchemaIssueCode["TOO_SMALL"] = "too_small";
-    SchemaIssueCode["TOO_LARGE"] = "too_large";
-    SchemaIssueCode["INVALID_LENGTH"] = "invalid_length";
-    SchemaIssueCode["INVALID_KEY"] = "invalid_key";
-    SchemaIssueCode["INVALID_ELEMENT"] = "invalid_element";
-    SchemaIssueCode["UNKNOWN_KEYS"] = "unknown_keys";
-    SchemaIssueCode["CIRCULAR_REFERENCE"] = "circular_reference";
-    SchemaIssueCode["MAX_DEPTH_EXCEEDED"] = "max_depth_exceeded";
-    SchemaIssueCode["CUSTOM"] = "custom";
-    SchemaIssueCode["PREPROCESS_FAILED"] = "preprocess_failed";
-    SchemaIssueCode["TRANSFORM_FAILED"] = "transform_failed";
-    SchemaIssueCode["REFINE_FAILED"] = "refine_failed";
-    SchemaIssueCode["COERCION_FAILED"] = "coercion_failed";
-})(SchemaIssueCode || (SchemaIssueCode = {}));
-/** Default maximum depth for schema validation. */
+import { ImmutableSet } from "../internal/immutableSet.js";
+import { ValidationPattern } from "../validation/validation.pattern.type.js";
+import { Limits } from "./common.constant.js";
+/**
+ * Schema issue codes — machine-readable, stable identifiers.
+ *
+ * Declared as a frozen `as const` object (not a TS `enum`) to match the rest
+ * of the package; `SchemaIssueCode` is also exported as the union type of its
+ * values, so it can be used in both value and type positions.
+ */
+export const SchemaIssueCode = Object.freeze({
+    INVALID_TYPE: "invalid_type",
+    REQUIRED: "required",
+    INVALID_LITERAL: "invalid_literal",
+    INVALID_ENUM: "invalid_enum",
+    INVALID_UNION: "invalid_union",
+    INVALID_STRING: "invalid_string",
+    INVALID_FORMAT: "invalid_format",
+    INVALID_NUMBER: "invalid_number",
+    TOO_SMALL: "too_small",
+    TOO_LARGE: "too_large",
+    INVALID_LENGTH: "invalid_length",
+    INVALID_KEY: "invalid_key",
+    INVALID_ELEMENT: "invalid_element",
+    UNKNOWN_KEYS: "unknown_keys",
+    CIRCULAR_REFERENCE: "circular_reference",
+    MAX_DEPTH_EXCEEDED: "max_depth_exceeded",
+    CUSTOM: "custom",
+    PREPROCESS_FAILED: "preprocess_failed",
+    TRANSFORM_FAILED: "transform_failed",
+    REFINE_FAILED: "refine_failed",
+    COERCION_FAILED: "coercion_failed",
+});
+/**
+ * Default maximum depth for schema validation (recursion guard).
+ *
+ * Intentionally distinct from `Limits.MAX_NESTING_DEPTH` (10 — bound on
+ * acceptable user data shape) and `SerializationLimits.MAX_DEPTH` (128 —
+ * serializer recursion guard).
+ */
 export const SCHEMA_DEFAULT_MAX_DEPTH = 100;
-/** Default maximum string length. */
-export const SCHEMA_DEFAULT_MAX_STRING_LENGTH = 255;
+/**
+ * Default maximum string length
+ * (canonical: {@link Limits.MAX_DISPLAY_LENGTH}).
+ */
+export const SCHEMA_DEFAULT_MAX_STRING_LENGTH = Limits.MAX_DISPLAY_LENGTH;
 /** Default maximum array length. */
 export const SCHEMA_DEFAULT_MAX_ARRAY_LENGTH = 1000;
 /** Default maximum object key count. */
 export const SCHEMA_DEFAULT_MAX_OBJECT_KEYS = 100;
-/** Object keys that are forbidden for prototype pollution protection. */
-export const SCHEMA_FORBIDDEN_KEYS = Object.freeze(new Set(["__proto__", "constructor", "prototype"]));
-/** Common string format regex patterns. */
+/**
+ * Object keys that are forbidden for prototype pollution protection.
+ *
+ * Backed by an immutable Set: `add`/`delete`/`clear` throw at runtime, so
+ * this security guard cannot be weakened by accident (or on purpose).
+ */
+export const SCHEMA_FORBIDDEN_KEYS = new ImmutableSet([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/**
+ * Common string format regex patterns.
+ *
+ * These reference {@link ValidationPattern} — the single source of truth for
+ * validation regexes — rather than redefining them.
+ */
 export const SCHEMA_STRING_FORMATS = Object.freeze({
-    EMAIL: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
-    URL: /^https?:\/\/.+/,
-    UUID: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
-    UUID_V4: /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
-    DATETIME: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/,
-    DATE: /^\d{4}-\d{2}-\d{2}$/,
+    EMAIL: ValidationPattern.EMAIL,
+    URL: ValidationPattern.URL,
+    /** UUID — any version (use UUID_V4 for strict v4). */
+    UUID: ValidationPattern.UUID,
+    UUID_V4: ValidationPattern.UUID_V4,
+    /** ISO 8601 date-time with optional fraction and Z/±hh:mm offset. */
+    DATETIME: ValidationPattern.ISO_DATE_TIME,
+    DATE: ValidationPattern.ISO_DATE,
     TIME: /^\d{2}:\d{2}(:\d{2})?$/,
-    IPV4: /^(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)$/,
-    IPV6: /^([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$/i,
-    HEX_COLOR: /^#[0-9a-f]{6}$/i,
-    PHONE: /^\+?[\d\s\-()]+$/,
+    IPV4: ValidationPattern.IPV4,
+    IPV6: ValidationPattern.IPV6,
+    HEX_COLOR: ValidationPattern.HEX_COLOR,
+    PHONE: ValidationPattern.PHONE,
 });
 //# sourceMappingURL=common.schema.js.map

package/dist/common/common.serialization.d.ts

@@ -10,18 +10,31 @@ export declare const SerializationFormat: Readonly<{
     readonly BINARY: "binary";
     readonly MESSAGEPACK: "messagepack";
 }>;
-/** MIME content types for serialized data. */
+/**
+ * MIME content types for serialized data
+ * (canonical values: {@link ContentTypes}).
+ */
 export declare const SerializationContentType: Readonly<{
     readonly JSON: "application/json";
     readonly TEXT: "text/plain";
     readonly OCTET: "application/octet-stream";
-    readonly MSGPACK: "application/msgpack";
+    /** De facto standard MessagePack MIME type. */
+    readonly MSGPACK: "application/x-msgpack";
 }>;
 /** Default limits for serialization operations. */
 export declare const SerializationLimits: Readonly<{
-    /** Default maximum serialized payload size (10 MB). */
-    readonly MAX_SIZE: number;
-    /** Default maximum object nesting depth. */
+    /**
+     * Default maximum serialized payload size (10 MB;
+     * canonical: {@link Limits.MAX_FILE_SIZE}).
+     */
+    readonly MAX_SIZE: 10485760;
+    /**
+     * Default maximum object nesting depth (serializer recursion guard).
+     *
+     * Intentionally distinct from `Limits.MAX_NESTING_DEPTH` (10 — bound on
+     * acceptable user data shape) and `SCHEMA_DEFAULT_MAX_DEPTH` (100 — schema
+     * validation recursion guard).
+     */
     readonly MAX_DEPTH: 128;
     /** Maximum number of registered type transformers. */
     readonly MAX_TRANSFORMERS: 256;

package/dist/common/common.serialization.js

@@ -3,6 +3,8 @@
  *
  * @module common/common.serialization
  */
+import { ContentTypes } from "../http/httpContentType.type.js";
+import { Limits } from "./common.constant.js";
 /** Canonical serialization format names. */
 export const SerializationFormat = Object.freeze({
     JSON: "json",
@@ -10,18 +12,31 @@ export const SerializationFormat = Object.freeze({
     BINARY: "binary",
     MESSAGEPACK: "messagepack",
 });
-/** MIME content types for serialized data. */
+/**
+ * MIME content types for serialized data
+ * (canonical values: {@link ContentTypes}).
+ */
 export const SerializationContentType = Object.freeze({
-    JSON: "application/json",
-    TEXT: "text/plain",
-    OCTET: "application/octet-stream",
-    MSGPACK: "application/msgpack",
+    JSON: ContentTypes.JSON,
+    TEXT: ContentTypes.TEXT_PLAIN,
+    OCTET: ContentTypes.OCTET_STREAM,
+    /** De facto standard MessagePack MIME type. */
+    MSGPACK: "application/x-msgpack",
 });
 /** Default limits for serialization operations. */
 export const SerializationLimits = Object.freeze({
-    /** Default maximum serialized payload size (10 MB). */
-    MAX_SIZE: 10 * 1024 * 1024,
-    /** Default maximum object nesting depth. */
+    /**
+     * Default maximum serialized payload size (10 MB;
+     * canonical: {@link Limits.MAX_FILE_SIZE}).
+     */
+    MAX_SIZE: Limits.MAX_FILE_SIZE,
+    /**
+     * Default maximum object nesting depth (serializer recursion guard).
+     *
+     * Intentionally distinct from `Limits.MAX_NESTING_DEPTH` (10 — bound on
+     * acceptable user data shape) and `SCHEMA_DEFAULT_MAX_DEPTH` (100 — schema
+     * validation recursion guard).
+     */
     MAX_DEPTH: 128,
     /** Maximum number of registered type transformers. */
     MAX_TRANSFORMERS: 256,

package/dist/common/index.d.ts

@@ -4,7 +4,7 @@
  * @module common
  */
 export { type Brand, type EntityId, type UserId, type EventId, type RequestId, type CorrelationId, type SessionId, type TenantId, type MessageId, type MessageCausationId, type TokenId, type Timestamp, type Url, type EmailAddress, type HexString, type Base64String, type JsonString, } from "./common.type.js";
-export { NONE, UNINITIALIZED, EMPTY, Limits, Defaults, Sentinel, createUserId, createEventId, createRequestId, createCorrelationId, createTimestamp, } from "./common.constant.js";
+export { NONE, UNINITIALIZED, EMPTY, Limits, Defaults, Sentinel, createUserId, createEventId, createRequestId, createCorrelationId, createSessionId, createTenantId, createMessageId, createMessageCausationId, createTokenId, createTimestamp, createUrl, createEmailAddress, createHexString, createBase64String, createJsonString, } from "./common.constant.js";
 export { SerializationFormat, SerializationContentType, SerializationLimits, SerializationTags, SERIALIZATION_SCHEMA_VERSION, } from "./common.serialization.js";
 export { SchemaIssueCode, SCHEMA_DEFAULT_MAX_DEPTH, SCHEMA_DEFAULT_MAX_STRING_LENGTH, SCHEMA_DEFAULT_MAX_ARRAY_LENGTH, SCHEMA_DEFAULT_MAX_OBJECT_KEYS, SCHEMA_FORBIDDEN_KEYS, SCHEMA_STRING_FORMATS, } from "./common.schema.js";
 export { LifecycleState, LifecyclePhase, LIFECYCLE_VALID_TRANSITIONS, 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, LIFECYCLE_DEFAULT_RETRY_MAX_DELAY, } from "./common.lifecycle.js";

package/dist/common/index.js

@@ -4,7 +4,7 @@
  * @module common
  */
 export {} from "./common.type.js";
-export { NONE, UNINITIALIZED, EMPTY, Limits, Defaults, Sentinel, createUserId, createEventId, createRequestId, createCorrelationId, createTimestamp, } from "./common.constant.js";
+export { NONE, UNINITIALIZED, EMPTY, Limits, Defaults, Sentinel, createUserId, createEventId, createRequestId, createCorrelationId, createSessionId, createTenantId, createMessageId, createMessageCausationId, createTokenId, createTimestamp, createUrl, createEmailAddress, createHexString, createBase64String, createJsonString, } from "./common.constant.js";
 export { SerializationFormat, SerializationContentType, SerializationLimits, SerializationTags, SERIALIZATION_SCHEMA_VERSION, } from "./common.serialization.js";
 export { SchemaIssueCode, SCHEMA_DEFAULT_MAX_DEPTH, SCHEMA_DEFAULT_MAX_STRING_LENGTH, SCHEMA_DEFAULT_MAX_ARRAY_LENGTH, SCHEMA_DEFAULT_MAX_OBJECT_KEYS, SCHEMA_FORBIDDEN_KEYS, SCHEMA_STRING_FORMATS, } from "./common.schema.js";
 export { LifecycleState, LifecyclePhase, LIFECYCLE_VALID_TRANSITIONS, 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, LIFECYCLE_DEFAULT_RETRY_MAX_DELAY, } from "./common.lifecycle.js";

package/dist/environment/environment.constant.d.ts

@@ -6,15 +6,39 @@
 import { type Environment } from "./environment.type.js";
 /** Node environment variable name for detecting the current environment. */
 export declare const NODE_ENV_KEY: "NODE_ENV";
+/**
+ * Options for {@link resolveEnvironment}.
+ */
+export interface ResolveEnvironmentOptions {
+    /**
+     * Throw an {@link InvalidConstantError} instead of warning and falling back
+     * to `"development"` when NODE_ENV holds an unrecognized value.
+     */
+    readonly strict?: boolean;
+    /**
+     * Suppress the one-time `console.warn` emitted for unrecognized NODE_ENV
+     * values (ignored in strict mode, which throws instead).
+     */
+    readonly silent?: boolean;
+}
 /**
  * Read the current environment from process.env.
  *
- * Defaults to development when NODE_ENV is unset or invalid.
+ * - Unset/empty NODE_ENV resolves to `"development"` silently.
+ * - An unrecognized value (e.g. a typo such as `"prodution"`) resolves to
+ *   `"development"` but emits a `console.warn` once per distinct value per
+ *   process, so a misconfigured production deployment does not silently run
+ *   with development behaviour. Pass `{ silent: true }` to suppress the
+ *   warning, or `{ strict: true }` to throw an {@link InvalidConstantError}
+ *   instead.
  *
  * @param envOverride - Optional env map override (useful for testing)
+ * @param options - `strict`: throw on unrecognized values; `silent`: do not warn
  * @returns The resolved Environment value
+ * @throws {InvalidConstantError} in strict mode, when NODE_ENV is set to an
+ * unrecognized value
  */
-export declare function resolveEnvironment(envOverride?: Record<string, string | undefined>): Environment;
+export declare function resolveEnvironment(envOverride?: Record<string, string | undefined>, options?: ResolveEnvironmentOptions): Environment;
 /**
  * Check whether the current environment is production.
  */

package/dist/environment/environment.constant.js

@@ -3,18 +3,33 @@
  *
  * @module environment/environment
  */
-import { Environments } from "./environment.type.js";
+import {} from "./environment.type.js";
+import { InvalidConstantError } from "../constantsErrors/constantsError.base.js";
 /** Node environment variable name for detecting the current environment. */
 export const NODE_ENV_KEY = "NODE_ENV";
+/**
+ * Unrecognized NODE_ENV values that have already been warned about, so each
+ * distinct typo is reported once per process rather than on every call.
+ */
+const warnedUnrecognizedValues = new Set();
 /**
  * Read the current environment from process.env.
  *
- * Defaults to development when NODE_ENV is unset or invalid.
+ * - Unset/empty NODE_ENV resolves to `"development"` silently.
+ * - An unrecognized value (e.g. a typo such as `"prodution"`) resolves to
+ *   `"development"` but emits a `console.warn` once per distinct value per
+ *   process, so a misconfigured production deployment does not silently run
+ *   with development behaviour. Pass `{ silent: true }` to suppress the
+ *   warning, or `{ strict: true }` to throw an {@link InvalidConstantError}
+ *   instead.
  *
  * @param envOverride - Optional env map override (useful for testing)
+ * @param options - `strict`: throw on unrecognized values; `silent`: do not warn
  * @returns The resolved Environment value
+ * @throws {InvalidConstantError} in strict mode, when NODE_ENV is set to an
+ * unrecognized value
  */
-export function resolveEnvironment(envOverride) {
+export function resolveEnvironment(envOverride, options) {
     const raw = (envOverride ?? process.env)[NODE_ENV_KEY];
     if (typeof raw === "string" && raw.trim().length > 0) {
         const normalised = raw.trim().toLowerCase();
@@ -26,6 +41,15 @@ export function resolveEnvironment(envOverride) {
             return "test";
         if (normalised === "staging")
             return "staging";
+        if (options?.strict === true) {
+            throw new InvalidConstantError(`Unrecognized ${NODE_ENV_KEY} value: ${JSON.stringify(raw)}`, { metadata: { value: raw } });
+        }
+        if (options?.silent !== true && !warnedUnrecognizedValues.has(raw)) {
+            warnedUnrecognizedValues.add(raw);
+            console.warn(`[@zudojs/constants] Unrecognized ${NODE_ENV_KEY} value ${JSON.stringify(raw)}; ` +
+                `falling back to "development". Expected one of: development, test, staging, production ` +
+                `(or the aliases dev, prod).`);
+        }
     }
     return "development";
 }

package/dist/environment/environment.type.d.ts

@@ -14,7 +14,7 @@ export declare const Environments: Readonly<{
     readonly STAGING: "staging";
     readonly PRODUCTION: "production";
 }>;
-/** Set of all valid environments for quick membership checks. */
+/** Set of all valid environments for quick membership checks (immutable at runtime). */
 export declare const ENVIRONMENTS: ReadonlySet<Environment>;
 /**
  * Check whether a string is a valid Environment value.

package/dist/environment/environment.type.js

@@ -3,6 +3,7 @@
  *
  * @module environment/environment
  */
+import { ImmutableSet } from "../internal/immutableSet.js";
 /**
  * All supported environments as an object map.
  */
@@ -12,8 +13,8 @@ export const Environments = Object.freeze({
     STAGING: "staging",
     PRODUCTION: "production",
 });
-/** Set of all valid environments for quick membership checks. */
-export const ENVIRONMENTS = new Set(Object.values(Environments));
+/** Set of all valid environments for quick membership checks (immutable at runtime). */
+export const ENVIRONMENTS = new ImmutableSet(Object.values(Environments));
 /**
  * Check whether a string is a valid Environment value.
  */

package/dist/environment/index.d.ts

@@ -4,5 +4,5 @@
  * @module environment
  */
 export { type Environment, Environments, ENVIRONMENTS, isValidEnvironment, } from "./environment.type.js";
-export { NODE_ENV_KEY, resolveEnvironment, isProduction, isDevelopment, isTest, } from "./environment.constant.js";
+export { NODE_ENV_KEY, type ResolveEnvironmentOptions, resolveEnvironment, isProduction, isDevelopment, isTest, } from "./environment.constant.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/http/httpContentType.type.d.ts

@@ -3,8 +3,6 @@
  *
  * @module http/httpContentType
  */
-/** Type-safe MIME content type string. */
-export type ContentType = string;
 /**
  * Common MIME content types.
  */
@@ -31,21 +29,37 @@ export declare const ContentTypes: Readonly<{
     readonly VIDEO_MP4: "video/mp4";
     readonly WILDCARD: "*/*";
 }>;
+/** Type-safe MIME content type — the union of all {@link ContentTypes} values. */
+export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
+/**
+ * Any MIME content type string — use when handling types outside the
+ * {@link ContentTypes} catalogue (still autocompletes the known types).
+ */
+export type AnyContentType = ContentType | (string & {});
 /**
  * Common charset values.
+ *
+ * These are IANA/MIME charset labels for use in `Content-Type` headers
+ * (e.g. `charset=us-ascii`) — they are NOT Node.js `Buffer` encoding names
+ * (Node uses `"ascii"`, `"utf16le"`, `"latin1"`, etc.).
  */
 export declare const Charset: Readonly<{
     readonly UTF_8: "utf-8";
-    readonly ASCII: "ascii";
+    readonly ASCII: "us-ascii";
     readonly ISO_8859_1: "iso-8859-1";
     readonly UTF_16: "utf-16";
 }>;
 /**
  * Build a Content-Type header value with optional charset.
  *
+ * The charset is omitted for `multipart/*` types, where a charset parameter
+ * is not meaningful (multipart types take a `boundary` parameter instead).
+ *
  * @param mimeType - The MIME type (e.g. ContentTypes.JSON)
  * @param charset - Optional charset (e.g. Charset.UTF_8)
  * @returns Full Content-Type string (e.g. "application/json; charset=utf-8")
+ * @throws {InvalidConstantError} if `mimeType` is empty, or `charset` is
+ * provided but empty/blank.
  */
-export declare function buildContentType(mimeType: ContentType, charset?: string): string;
+export declare function buildContentType(mimeType: AnyContentType, charset?: string): string;
 //# sourceMappingURL=httpContentType.type.d.ts.map