@zudojs/constants 0.0.1 → 1.0.0

package/dist/http/httpContentType.type.js

@@ -3,6 +3,7 @@
  *
  * @module http/httpContentType
  */
+import { InvalidConstantError } from "../constantsErrors/constantsError.base.js";
 /**
  * Common MIME content types.
  */
@@ -31,21 +32,40 @@ export const ContentTypes = Object.freeze({
 });
 /**
  * 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 const Charset = Object.freeze({
     UTF_8: "utf-8",
-    ASCII: "ascii",
+    ASCII: "us-ascii",
     ISO_8859_1: "iso-8859-1",
     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 function buildContentType(mimeType, charset) {
-    return charset ? `${mimeType}; charset=${charset}` : mimeType;
+    if (mimeType.trim().length === 0) {
+        throw new InvalidConstantError("buildContentType: mimeType must not be empty");
+    }
+    if (charset !== undefined && charset.trim().length === 0) {
+        throw new InvalidConstantError("buildContentType: charset must not be empty");
+    }
+    if (charset === undefined ||
+        mimeType.toLowerCase().startsWith("multipart/")) {
+        return mimeType;
+    }
+    return `${mimeType}; charset=${charset}`;
 }
 //# sourceMappingURL=httpContentType.type.js.map

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

@@ -3,8 +3,6 @@
  *
  * @module http/httpHeader
  */
-/** Type-safe HTTP header name string. */
-export type HttpHeaderName = string;
 /**
  * Common HTTP header names.
  */
@@ -39,4 +37,11 @@ export declare const HttpHeader: Readonly<{
     readonly X_API_KEY: "X-Api-Key";
     readonly X_CORRELATION_ID: "X-Correlation-Id";
 }>;
+/** Type-safe HTTP header name — the union of all {@link HttpHeader} values. */
+export type HttpHeaderName = (typeof HttpHeader)[keyof typeof HttpHeader];
+/**
+ * Any HTTP header name — use when handling headers outside the
+ * {@link HttpHeader} catalogue (still autocompletes the known names).
+ */
+export type AnyHttpHeaderName = HttpHeaderName | (string & {});
 //# sourceMappingURL=httpHeader.type.d.ts.map

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

@@ -19,10 +19,10 @@ export declare const HttpMethods: Readonly<{
     readonly TRACE: "TRACE";
     readonly CONNECT: "CONNECT";
 }>;
-/** Set of all HTTP methods for quick membership checks. */
+/** Set of all HTTP methods for quick membership checks (immutable at runtime). */
 export declare const HTTP_METHODS: ReadonlySet<HttpMethod>;
-/** HTTP methods that are safe (no side effects). */
+/** HTTP methods that are safe (no side effects). Immutable at runtime. */
 export declare const SAFE_HTTP_METHODS: ReadonlySet<HttpMethod>;
-/** HTTP methods that are idempotent. */
+/** HTTP methods that are idempotent. Immutable at runtime. */
 export declare const IDEMPOTENT_HTTP_METHODS: ReadonlySet<HttpMethod>;
 //# sourceMappingURL=httpMethod.type.d.ts.map

package/dist/http/httpMethod.type.js

@@ -3,6 +3,7 @@
  *
  * @module http/httpMethod
  */
+import { ImmutableSet } from "../internal/immutableSet.js";
 /**
  * All supported HTTP methods as an object map for runtime use.
  */
@@ -17,16 +18,16 @@ export const HttpMethods = Object.freeze({
     TRACE: "TRACE",
     CONNECT: "CONNECT",
 });
-/** Set of all HTTP methods for quick membership checks. */
-export const HTTP_METHODS = new Set(Object.values(HttpMethods));
-/** HTTP methods that are safe (no side effects). */
-export const SAFE_HTTP_METHODS = new Set([
+/** Set of all HTTP methods for quick membership checks (immutable at runtime). */
+export const HTTP_METHODS = new ImmutableSet(Object.values(HttpMethods));
+/** HTTP methods that are safe (no side effects). Immutable at runtime. */
+export const SAFE_HTTP_METHODS = new ImmutableSet([
     HttpMethods.GET,
     HttpMethods.HEAD,
     HttpMethods.OPTIONS,
 ]);
-/** HTTP methods that are idempotent. */
-export const IDEMPOTENT_HTTP_METHODS = new Set([
+/** HTTP methods that are idempotent. Immutable at runtime. */
+export const IDEMPOTENT_HTTP_METHODS = new ImmutableSet([
     HttpMethods.GET,
     HttpMethods.HEAD,
     HttpMethods.PUT,

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

@@ -3,39 +3,79 @@
  *
  * @module http/httpStatus
  */
-/** Type-safe HTTP status code number. */
-export type HttpStatusCode = number;
 /**
  * Standard HTTP status codes organized by category.
  */
 export declare const HttpStatus: Readonly<{
+    readonly CONTINUE: 100;
+    readonly SWITCHING_PROTOCOLS: 101;
+    readonly PROCESSING: 102;
+    readonly EARLY_HINTS: 103;
     readonly OK: 200;
     readonly CREATED: 201;
     readonly ACCEPTED: 202;
+    readonly NON_AUTHORITATIVE_INFORMATION: 203;
     readonly NO_CONTENT: 204;
     readonly RESET_CONTENT: 205;
     readonly PARTIAL_CONTENT: 206;
+    readonly MULTI_STATUS: 207;
+    readonly ALREADY_REPORTED: 208;
+    readonly IM_USED: 226;
+    readonly MULTIPLE_CHOICES: 300;
     readonly MOVED_PERMANENTLY: 301;
     readonly FOUND: 302;
+    readonly SEE_OTHER: 303;
     readonly NOT_MODIFIED: 304;
     readonly TEMPORARY_REDIRECT: 307;
     readonly PERMANENT_REDIRECT: 308;
     readonly BAD_REQUEST: 400;
     readonly UNAUTHORIZED: 401;
+    readonly PAYMENT_REQUIRED: 402;
     readonly FORBIDDEN: 403;
     readonly NOT_FOUND: 404;
     readonly METHOD_NOT_ALLOWED: 405;
     readonly NOT_ACCEPTABLE: 406;
+    readonly PROXY_AUTHENTICATION_REQUIRED: 407;
+    readonly REQUEST_TIMEOUT: 408;
     readonly CONFLICT: 409;
     readonly GONE: 410;
+    readonly LENGTH_REQUIRED: 411;
+    readonly PRECONDITION_FAILED: 412;
+    readonly PAYLOAD_TOO_LARGE: 413;
+    readonly URI_TOO_LONG: 414;
+    readonly UNSUPPORTED_MEDIA_TYPE: 415;
+    readonly RANGE_NOT_SATISFIABLE: 416;
+    readonly EXPECTATION_FAILED: 417;
+    readonly IM_A_TEAPOT: 418;
+    readonly MISDIRECTED_REQUEST: 421;
     readonly UNPROCESSABLE_ENTITY: 422;
+    readonly LOCKED: 423;
+    readonly FAILED_DEPENDENCY: 424;
+    readonly TOO_EARLY: 425;
+    readonly UPGRADE_REQUIRED: 426;
+    readonly PRECONDITION_REQUIRED: 428;
     readonly TOO_MANY_REQUESTS: 429;
+    readonly REQUEST_HEADER_FIELDS_TOO_LARGE: 431;
+    readonly UNAVAILABLE_FOR_LEGAL_REASONS: 451;
     readonly INTERNAL_SERVER_ERROR: 500;
     readonly NOT_IMPLEMENTED: 501;
     readonly BAD_GATEWAY: 502;
     readonly SERVICE_UNAVAILABLE: 503;
     readonly GATEWAY_TIMEOUT: 504;
+    readonly HTTP_VERSION_NOT_SUPPORTED: 505;
+    readonly VARIANT_ALSO_NEGOTIATES: 506;
+    readonly INSUFFICIENT_STORAGE: 507;
+    readonly LOOP_DETECTED: 508;
+    readonly NOT_EXTENDED: 510;
+    readonly NETWORK_AUTHENTICATION_REQUIRED: 511;
 }>;
+/** Type-safe HTTP status code — the union of all {@link HttpStatus} values. */
+export type HttpStatusCode = (typeof HttpStatus)[keyof typeof HttpStatus];
+/**
+ * Any HTTP status code number — use when handling status codes outside the
+ * {@link HttpStatus} catalogue (e.g. from third-party servers).
+ */
+export type AnyHttpStatusCode = number;
 /**
  * Check whether a status code is in the 2xx success range.
  */

package/dist/http/httpStatus.type.js

@@ -7,36 +7,72 @@
  * Standard HTTP status codes organized by category.
  */
 export const HttpStatus = Object.freeze({
+    // 1xx Informational
+    CONTINUE: 100,
+    SWITCHING_PROTOCOLS: 101,
+    PROCESSING: 102,
+    EARLY_HINTS: 103,
     // 2xx Success
     OK: 200,
     CREATED: 201,
     ACCEPTED: 202,
+    NON_AUTHORITATIVE_INFORMATION: 203,
     NO_CONTENT: 204,
     RESET_CONTENT: 205,
     PARTIAL_CONTENT: 206,
+    MULTI_STATUS: 207,
+    ALREADY_REPORTED: 208,
+    IM_USED: 226,
     // 3xx Redirection
+    MULTIPLE_CHOICES: 300,
     MOVED_PERMANENTLY: 301,
     FOUND: 302,
+    SEE_OTHER: 303,
     NOT_MODIFIED: 304,
     TEMPORARY_REDIRECT: 307,
     PERMANENT_REDIRECT: 308,
     // 4xx Client Error
     BAD_REQUEST: 400,
     UNAUTHORIZED: 401,
+    PAYMENT_REQUIRED: 402,
     FORBIDDEN: 403,
     NOT_FOUND: 404,
     METHOD_NOT_ALLOWED: 405,
     NOT_ACCEPTABLE: 406,
+    PROXY_AUTHENTICATION_REQUIRED: 407,
+    REQUEST_TIMEOUT: 408,
     CONFLICT: 409,
     GONE: 410,
+    LENGTH_REQUIRED: 411,
+    PRECONDITION_FAILED: 412,
+    PAYLOAD_TOO_LARGE: 413,
+    URI_TOO_LONG: 414,
+    UNSUPPORTED_MEDIA_TYPE: 415,
+    RANGE_NOT_SATISFIABLE: 416,
+    EXPECTATION_FAILED: 417,
+    IM_A_TEAPOT: 418,
+    MISDIRECTED_REQUEST: 421,
     UNPROCESSABLE_ENTITY: 422,
+    LOCKED: 423,
+    FAILED_DEPENDENCY: 424,
+    TOO_EARLY: 425,
+    UPGRADE_REQUIRED: 426,
+    PRECONDITION_REQUIRED: 428,
     TOO_MANY_REQUESTS: 429,
+    REQUEST_HEADER_FIELDS_TOO_LARGE: 431,
+    UNAVAILABLE_FOR_LEGAL_REASONS: 451,
     // 5xx Server Error
     INTERNAL_SERVER_ERROR: 500,
     NOT_IMPLEMENTED: 501,
     BAD_GATEWAY: 502,
     SERVICE_UNAVAILABLE: 503,
     GATEWAY_TIMEOUT: 504,
+    HTTP_VERSION_NOT_SUPPORTED: 505,
+    VARIANT_ALSO_NEGOTIATES: 506,
+    INSUFFICIENT_STORAGE: 507,
+    LOOP_DETECTED: 508,
+    NOT_EXTENDED: 510,
+    NETWORK_AUTHENTICATION_REQUIRED: 511,
 });
 /**
  * Check whether a status code is in the 2xx success range.

package/dist/http/index.d.ts

@@ -4,7 +4,7 @@
  * @module http
  */
 export { type HttpMethod, HttpMethods, HTTP_METHODS, SAFE_HTTP_METHODS, IDEMPOTENT_HTTP_METHODS, } from "./httpMethod.type.js";
-export { type HttpStatusCode, HttpStatus, isSuccessStatus, isRedirectStatus, isClientError, isServerError, isErrorStatus, } from "./httpStatus.type.js";
-export { type HttpHeaderName, HttpHeader } from "./httpHeader.type.js";
-export { type ContentType, ContentTypes, Charset, buildContentType, } from "./httpContentType.type.js";
+export { type HttpStatusCode, type AnyHttpStatusCode, HttpStatus, isSuccessStatus, isRedirectStatus, isClientError, isServerError, isErrorStatus, } from "./httpStatus.type.js";
+export { type HttpHeaderName, type AnyHttpHeaderName, HttpHeader, } from "./httpHeader.type.js";
+export { type ContentType, type AnyContentType, ContentTypes, Charset, buildContentType, } from "./httpContentType.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/http/index.js

@@ -5,6 +5,6 @@
  */
 export { HttpMethods, HTTP_METHODS, SAFE_HTTP_METHODS, IDEMPOTENT_HTTP_METHODS, } from "./httpMethod.type.js";
 export { HttpStatus, isSuccessStatus, isRedirectStatus, isClientError, isServerError, isErrorStatus, } from "./httpStatus.type.js";
-export { HttpHeader } from "./httpHeader.type.js";
+export { HttpHeader, } from "./httpHeader.type.js";
 export { ContentTypes, Charset, buildContentType, } from "./httpContentType.type.js";
 //# sourceMappingURL=index.js.map

package/dist/internal/immutableSet.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Internal immutable Set implementation.
+ *
+ * `Object.freeze` does not protect the internal slots of a `Set`, so a
+ * "frozen" Set still allows `.add()`, `.delete()`, and `.clear()` at runtime.
+ * This subclass hard-disables all mutators, making it safe to expose
+ * security-sensitive sets (e.g. forbidden schema keys) as `ReadonlySet`.
+ *
+ * @module internal/immutableSet
+ */
+/**
+ * A `Set` whose mutating methods (`add`, `delete`, `clear`) always throw.
+ *
+ * Values are inserted via `super.add` during construction only; afterwards
+ * the collection is permanently immutable.
+ */
+export declare class ImmutableSet<T> extends Set<T> {
+    constructor(values?: Iterable<T>);
+    /** @throws {TypeError} always — this set is immutable. */
+    add(_value: T): this;
+    /** @throws {TypeError} always — this set is immutable. */
+    delete(_value: T): boolean;
+    /** @throws {TypeError} always — this set is immutable. */
+    clear(): void;
+}
+//# sourceMappingURL=immutableSet.d.ts.map

package/dist/internal/immutableSet.js

@@ -0,0 +1,40 @@
+/**
+ * Internal immutable Set implementation.
+ *
+ * `Object.freeze` does not protect the internal slots of a `Set`, so a
+ * "frozen" Set still allows `.add()`, `.delete()`, and `.clear()` at runtime.
+ * This subclass hard-disables all mutators, making it safe to expose
+ * security-sensitive sets (e.g. forbidden schema keys) as `ReadonlySet`.
+ *
+ * @module internal/immutableSet
+ */
+/**
+ * A `Set` whose mutating methods (`add`, `delete`, `clear`) always throw.
+ *
+ * Values are inserted via `super.add` during construction only; afterwards
+ * the collection is permanently immutable.
+ */
+export class ImmutableSet extends Set {
+    constructor(values) {
+        super();
+        if (values !== undefined) {
+            for (const value of values) {
+                super.add(value);
+            }
+        }
+        Object.freeze(this);
+    }
+    /** @throws {TypeError} always — this set is immutable. */
+    add(_value) {
+        throw new TypeError("Cannot add to an immutable Set");
+    }
+    /** @throws {TypeError} always — this set is immutable. */
+    delete(_value) {
+        throw new TypeError("Cannot delete from an immutable Set");
+    }
+    /** @throws {TypeError} always — this set is immutable. */
+    clear() {
+        throw new TypeError("Cannot clear an immutable Set");
+    }
+}
+//# sourceMappingURL=immutableSet.js.map

package/dist/runtime/clock.d.ts

@@ -13,15 +13,35 @@ export interface Clock {
     now(): number;
     /**
      * Returns current Date.
+     *
+     * Note: the capitalised method name is kept for backwards compatibility
+     * (it mirrors the global `Date` constructor it wraps).
      */
     Date(): Date;
 }
+/**
+ * A mock {@link Clock} whose time can be advanced or set explicitly.
+ */
+export interface MockClock extends Clock {
+    /**
+     * Advance the mock time by the given number of milliseconds.
+     */
+    advance(ms: number): void;
+    /**
+     * Set the mock time to an absolute point in time — either a timestamp in
+     * milliseconds or a `Date`.
+     */
+    set(time: number | Date): void;
+}
 /**
  * Default clock using real system time.
  */
 export declare const systemClock: Clock;
 /**
- * Creates a mock clock with a fixed time.
+ * Creates a mock clock with a controllable time.
+ *
+ * The clock starts at `fixedTime` and stays there until `advance(ms)` or
+ * `set(time)` is called.
  */
-export declare function createMockClock(fixedTime?: number): Clock;
+export declare function createMockClock(fixedTime?: number): MockClock;
 //# sourceMappingURL=clock.d.ts.map

package/dist/runtime/clock.js

@@ -11,13 +11,22 @@ export const systemClock = {
     Date: () => new Date(),
 };
 /**
- * Creates a mock clock with a fixed time.
+ * Creates a mock clock with a controllable time.
+ *
+ * The clock starts at `fixedTime` and stays there until `advance(ms)` or
+ * `set(time)` is called.
  */
 export function createMockClock(fixedTime = 0) {
     let time = fixedTime;
     return {
         now: () => time,
         Date: () => new Date(time),
+        advance: (ms) => {
+            time += ms;
+        },
+        set: (newTime) => {
+            time = typeof newTime === "number" ? newTime : newTime.getTime();
+        },
     };
 }
 //# sourceMappingURL=clock.js.map

package/dist/runtime/index.d.ts

@@ -4,7 +4,7 @@
  * @module runtime
  */
 export { systemClock, createMockClock } from "./clock.js";
-export type { Clock } from "./clock.js";
+export type { Clock, MockClock } from "./clock.js";
 export { systemRandom, createMockRandom } from "./random.js";
 export type { Random } from "./random.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/random.d.ts

@@ -25,11 +25,20 @@ export interface Random {
     randomBytes(length: number): Uint8Array;
 }
 /**
- * Default random using real system randomness.
+ * Default random backed by `node:crypto` (CSPRNG).
+ *
+ * Every method — including `random()` — draws from the platform CSPRNG, so
+ * this singleton is safe to use for tokens, session IDs, salts, and other
+ * security-sensitive values. `random()` builds a 53-bit float in `[0, 1)`
+ * from 64 bits of `crypto.getRandomValues` output.
  */
 export declare const systemRandom: Random;
 /**
  * Creates a mock random with a seeded sequence for deterministic testing.
+ *
+ * Uses a 32-bit linear congruential generator (Numerical Recipes constants)
+ * with `Math.imul` for exact 32-bit arithmetic. Outputs are always in
+ * `[0, 1)`. Not cryptographically secure — tests only.
  */
 export declare function createMockRandom(seed?: number): Random;
 //# sourceMappingURL=random.d.ts.map

package/dist/runtime/random.js

@@ -3,45 +3,60 @@
  *
  * @module runtime/random
  */
+import { getRandomValues, randomBytes as cryptoRandomBytes, randomInt as cryptoRandomInt, } from "node:crypto";
+/** Alphanumeric alphabet used by `randomString`. */
+const RANDOM_STRING_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789";
+/** Scratch buffer for `systemRandom.random()` (two 32-bit words = 64 bits). */
+const RANDOM_FLOAT_WORDS = new Uint32Array(2);
 /**
- * Default random using real system randomness.
+ * Default random backed by `node:crypto` (CSPRNG).
+ *
+ * Every method — including `random()` — draws from the platform CSPRNG, so
+ * this singleton is safe to use for tokens, session IDs, salts, and other
+ * security-sensitive values. `random()` builds a 53-bit float in `[0, 1)`
+ * from 64 bits of `crypto.getRandomValues` output.
  */
 export const systemRandom = {
-    random: () => Math.random(),
-    randomInt: (min, max) => Math.floor(Math.random() * (max - min + 1)) + min,
+    random: () => {
+        getRandomValues(RANDOM_FLOAT_WORDS);
+        // 21 high bits from word 0 and all 32 bits of word 1 = 53 bits of
+        // precision, mapped onto [0, 1) exactly like a double mantissa.
+        const high = RANDOM_FLOAT_WORDS[0] >>> 11;
+        const low = RANDOM_FLOAT_WORDS[1];
+        return (high * 0x100000000 + low) / 0x20000000000000;
+    },
+    randomInt: (min, max) => cryptoRandomInt(min, max + 1),
     randomString: (length) => {
-        const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
         let result = "";
         for (let i = 0; i < length; i++) {
-            result += chars[Math.floor(Math.random() * chars.length)];
+            result +=
+                RANDOM_STRING_CHARS[cryptoRandomInt(0, RANDOM_STRING_CHARS.length)];
         }
         return result;
     },
-    randomBytes: (length) => {
-        const bytes = new Uint8Array(length);
-        for (let i = 0; i < length; i++) {
-            bytes[i] = Math.floor(Math.random() * 256);
-        }
-        return bytes;
-    },
+    randomBytes: (length) => new Uint8Array(cryptoRandomBytes(length)),
 };
 /**
  * Creates a mock random with a seeded sequence for deterministic testing.
+ *
+ * Uses a 32-bit linear congruential generator (Numerical Recipes constants)
+ * with `Math.imul` for exact 32-bit arithmetic. Outputs are always in
+ * `[0, 1)`. Not cryptographically secure — tests only.
  */
 export function createMockRandom(seed = 1) {
-    let state = seed;
+    let state = seed >>> 0;
     function next() {
-        state = (state * 1664525 + 1013904223) & 0xffffffff;
-        return (state >>> 0) / 0xffffffff;
+        state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+        return state / 0x100000000;
     }
     return {
         random: next,
         randomInt: (min, max) => Math.floor(next() * (max - min + 1)) + min,
         randomString: (length) => {
-            const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
             let result = "";
             for (let i = 0; i < length; i++) {
-                result += chars[Math.floor(next() * chars.length)];
+                result +=
+                    RANDOM_STRING_CHARS[Math.floor(next() * RANDOM_STRING_CHARS.length)];
             }
             return result;
         },

package/dist/time/time.constant.d.ts

@@ -47,7 +47,13 @@ export declare const DefaultTimeout: Readonly<{
  * Default retry configuration values.
  */
 export declare const DefaultRetry: Readonly<{
-    /** Maximum number of retry attempts */
+    /**
+     * Default number of retry attempts used when nothing is configured.
+     *
+     * Distinct from `Limits.MAX_RETRY_ATTEMPTS` (10; also surfaced as
+     * `ValidationRange.MAX_RETRIES`), which is the upper bound on what a caller
+     * may configure — this is merely the out-of-the-box default.
+     */
     readonly MAX_ATTEMPTS: 3;
     /** Base delay between retries in ms */
     readonly BASE_DELAY_MS: 1000;

package/dist/time/time.constant.js

@@ -47,7 +47,13 @@ export const DefaultTimeout = Object.freeze({
  * Default retry configuration values.
  */
 export const DefaultRetry = Object.freeze({
-    /** Maximum number of retry attempts */
+    /**
+     * Default number of retry attempts used when nothing is configured.
+     *
+     * Distinct from `Limits.MAX_RETRY_ATTEMPTS` (10; also surfaced as
+     * `ValidationRange.MAX_RETRIES`), which is the upper bound on what a caller
+     * may configure — this is merely the out-of-the-box default.
+     */
     MAX_ATTEMPTS: 3,
     /** Base delay between retries in ms */
     BASE_DELAY_MS: 1_000,
@@ -87,11 +93,11 @@ export function formatDuration(ms) {
     if (ms < TimeMs.SECOND)
         return `${ms}ms`;
     if (ms < TimeMs.MINUTE)
-        return `${Math.round(ms / TimeMs.SECOND)}s`;
+        return `${Math.floor(ms / TimeMs.SECOND)}s`;
     if (ms < TimeMs.HOUR) {
-        const s = Math.floor(ms / TimeMs.SECOND);
-        const r = Math.round(((ms % TimeMs.SECOND) / TimeMs.SECOND) * 10) / 10;
-        return r >= 0.5 ? `${s + 1}m` : `${s}s`;
+        const m = Math.floor(ms / TimeMs.MINUTE);
+        const s = Math.floor((ms % TimeMs.MINUTE) / TimeMs.SECOND);
+        return s > 0 ? `${m}m ${s}s` : `${m}m`;
     }
     if (ms < TimeMs.DAY) {
         const h = Math.floor(ms / TimeMs.HOUR);

package/dist/validation/validation.constant.d.ts

@@ -11,9 +11,9 @@ export declare const ValidationLength: Readonly<{
     readonly SHORT: 64;
     /** Standard name field */
     readonly NAME: 128;
-    /** Email address */
-    readonly EMAIL: 255;
-    /** Display name or title */
+    /** Email address (RFC 5321 maximum total length) */
+    readonly EMAIL: 254;
+    /** Display name or title (canonical: {@link Limits.MAX_DISPLAY_LENGTH}) */
     readonly DISPLAY: 255;
     /** Short description */
     readonly DESCRIPTION_SHORT: 500;
@@ -40,7 +40,7 @@ export declare const ValidationRange: Readonly<{
     readonly MAX_PERCENTAGE: 100;
     /** Minimum page number (1-based) */
     readonly MIN_PAGE: 1;
-    /** Maximum page size */
+    /** Maximum page size (canonical: {@link Limits.MAX_PAGE_SIZE}) */
     readonly MAX_PAGE_SIZE: 100;
     /** Minimum pagination offset */
     readonly MIN_OFFSET: 0;
@@ -48,7 +48,14 @@ export declare const ValidationRange: Readonly<{
     readonly MAX_TIMEOUT_SECONDS: 3600;
     /** Minimum retry count */
     readonly MIN_RETRIES: 0;
-    /** Maximum retry count */
+    /**
+     * Maximum retry count a caller may configure (upper validation bound;
+     * canonical: {@link Limits.MAX_RETRY_ATTEMPTS}).
+     *
+     * Note: this is intentionally larger than `DefaultRetry.MAX_ATTEMPTS` (3),
+     * which is the out-of-the-box default — this constant caps what users may
+     * request, the other is what they get if they configure nothing.
+     */
     readonly MAX_RETRIES: 10;
 }>;
 //# sourceMappingURL=validation.constant.d.ts.map