@zudojs/constants 0.1.0 → 1.0.1

package/dist/common/common.lifecycle.d.ts

@@ -3,27 +3,42 @@
  *
  * Lifecycle states, phases, valid transitions, and defaults.
  */
-/** Lifecycle states — a strongly-typed state machine. */
-export declare enum LifecycleState {
-    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. */
-export declare enum LifecyclePhase {
-    INITIALIZE = "initialize",
-    START = "start",
-    READY = "ready",
-    STOP = "stop",
-    DISPOSE = "dispose"
-}
+/**
+ * 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 declare const LifecycleState: Readonly<{
+    readonly IDLE: "idle";
+    readonly INITIALIZING: "initializing";
+    readonly INITIALIZED: "initialized";
+    readonly STARTING: "starting";
+    readonly STARTED: "started";
+    readonly READY: "ready";
+    readonly STOPPING: "stopping";
+    readonly STOPPED: "stopped";
+    readonly FAILED: "failed";
+    readonly DISPOSED: "disposed";
+}>;
+/** Type-safe lifecycle state — the union of all {@link LifecycleState} values. */
+export type LifecycleState = (typeof LifecycleState)[keyof typeof LifecycleState];
+/**
+ * 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 declare const LifecyclePhase: Readonly<{
+    readonly INITIALIZE: "initialize";
+    readonly START: "start";
+    readonly READY: "ready";
+    readonly STOP: "stop";
+    readonly DISPOSE: "dispose";
+}>;
+/** Type-safe lifecycle phase — the union of all {@link LifecyclePhase} values. */
+export type LifecyclePhase = (typeof LifecyclePhase)[keyof typeof LifecyclePhase];
 /** Valid state transitions for the lifecycle state machine. */
 export declare const LIFECYCLE_VALID_TRANSITIONS: Readonly<Record<LifecycleState, readonly LifecycleState[]>>;
 /** Default timeout for lifecycle operations (ms). */
@@ -34,10 +49,13 @@ export declare const LIFECYCLE_DEFAULT_START_TIMEOUT = 30000;
 export declare const LIFECYCLE_DEFAULT_STOP_TIMEOUT = 10000;
 /** Default global shutdown deadline (ms). */
 export declare const LIFECYCLE_DEFAULT_SHUTDOWN_TIMEOUT = 30000;
-/** Default concurrency limit for parallel component operations. */
-export declare const LIFECYCLE_DEFAULT_CONCURRENCY = 10;
-/** Default retry attempts. */
-export declare const LIFECYCLE_DEFAULT_RETRY_ATTEMPTS = 3;
+/**
+ * Default concurrency limit for parallel component operations
+ * (canonical: {@link Limits.MAX_CONCURRENCY}).
+ */
+export declare const LIFECYCLE_DEFAULT_CONCURRENCY: 10;
+/** Default retry attempts (canonical: {@link DefaultRetry.MAX_ATTEMPTS}). */
+export declare const LIFECYCLE_DEFAULT_RETRY_ATTEMPTS: 3;
 /** Default retry delay (ms). */
 export declare const LIFECYCLE_DEFAULT_RETRY_DELAY = 500;
 /** Maximum retry delay (ms). */

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.
  */