@zudojs/types 1.0.0 → 1.1.1

package/README.md

@@ -2,6 +2,12 @@
 
 Shared type guards, utility types, and type converters for the Zudojs framework.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-types](https://zudojs.oyinlola.site/docs/packages-types) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-types.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -55,9 +61,18 @@ clock.advance(1_000);
 - `Random` is branded, so `SeededRandom` — whose output is fully predictable
   from its seed — cannot be injected where unpredictability is required.
   Implement a secure generator through `defineSecureRandom()`.
-- `Random.int()` uses rejection sampling, not `% max`, so draws are uniform for
-  every bound rather than only powers of two.
+- `Random.int(max)` uses rejection sampling, not `% max`, so draws are uniform
+  for every bound rather than only powers of two. `max` must be an integer
+  from 1 to `MAX_RANDOM_INT_BOUND` (`Number.MAX_SAFE_INTEGER`); bounds above
+  2^32 draw 53 bits. Anything else throws a `RangeError`.
+- `SeededRandom` is mulberry32-backed: its `uuid()` values do not repeat after
+  16 draws and `int(2)` does not alternate.
 - `mapToObject` and `safeJsonParse` cannot be used to reach a prototype.
+  `safeJsonParse` drops `__proto__`, `constructor` and `prototype` keys at
+  every depth as a deliberate deny-list, so a payload with a legitimate
+  `constructor` field loses it.
+- `camelToSnake` / `camelToKebab` are Unicode-aware (`caféAuLait` becomes
+  `café_au_lait`) and keep characters other than `_`, `-` and whitespace.
 - `toNumber` requires a finite number and refuses blank strings, hexadecimal
   literals and `1e999`; `toBoolean(NaN)` falls back rather than returning true.
 - `isUuid` accepts versions 1–8 including UUIDv7; use `isUuidV4` where the
@@ -69,9 +84,11 @@ clock.advance(1_000);
 - Type guards (`isPlainObject`, `isDate`, `isEmail`, `isUuid`, etc.)
 - Utility types (`Maybe`, `DeepReadonly`, `Prettify`, etc.)
 - Type converters and case transformers
-- Branded type utilities
 - Injectable `Clock` and `Random` primitives, with deterministic test doubles
 
+Branded identifier types (`Brand<>`, `UserId`, `TenantId`, ...) are not in
+this package; they live in `@zudojs/constants`.
+
 ## Use Cases
 
 - Runtime type checking

package/dist/runtime/index.d.ts

@@ -6,5 +6,7 @@
  * silently became public API.
  */
 export type { Clock, ClockSeconds, Random, PseudoRandom, } from "./runtime.core.js";
-export { systemClock, systemClockSeconds, defineSecureRandom, systemRandom, FixedClock, SeededRandom, } from "./runtime.core.js";
+export { systemClock, systemClockSeconds, defineSecureRandom, systemRandom, FixedClock, } from "./runtime.core.js";
+export { SeededRandom } from "./runtime.seeded.js";
+export { MAX_RANDOM_INT_BOUND } from "./runtime.int.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -5,5 +5,7 @@
  * package without one, so anything newly exported from `runtime.core.ts`
  * silently became public API.
  */
-export { systemClock, systemClockSeconds, defineSecureRandom, systemRandom, FixedClock, SeededRandom, } from "./runtime.core.js";
+export { systemClock, systemClockSeconds, defineSecureRandom, systemRandom, FixedClock, } from "./runtime.core.js";
+export { SeededRandom } from "./runtime.seeded.js";
+export { MAX_RANDOM_INT_BOUND } from "./runtime.int.js";
 //# sourceMappingURL=index.js.map

package/dist/runtime/runtime.core.d.ts

@@ -34,7 +34,11 @@ export interface Random {
     readonly [SecureRandomBrand]: true;
     /** Returns a random UUID v4 string. */
     uuid(): string;
-    /** Returns a uniformly random integer in [0, max). */
+    /**
+     * Returns a uniformly random integer in [0, max).
+     *
+     * @throws RangeError unless `max` is a safe integer of at least 1.
+     */
     int(max: number): number;
     /** Returns a random string of the given length (alphanumeric). */
     string(length: number): string;
@@ -80,24 +84,5 @@ export declare class FixedClock implements Clock {
     set(time: number): void;
     advance(deltaMs: number): void;
 }
-/**
- * Deterministic generator useful for tests.
- *
- * Implements {@link PseudoRandom}, never {@link Random}: its output is fully
- * predictable from the seed, so injecting it where a secure generator is
- * expected would make every token guessable from a single observation.
- */
-export declare class SeededRandom implements PseudoRandom {
-    readonly deterministic = true;
-    private state;
-    constructor(seed?: number);
-    /** Returns a structurally valid v4 UUID derived from the seed. */
-    uuid(): string;
-    int(max: number): number;
-    string(length: number): string;
-    custom(length: number, alphabet: string): string;
-    /** Advances the linear congruential state. */
-    private next;
-}
 export {};
 //# sourceMappingURL=runtime.core.d.ts.map

package/dist/runtime/runtime.core.js

@@ -5,7 +5,8 @@
  * avoid direct `Date.now()` and `Math.random()` calls. Tests can substitute
  * deterministic implementations.
  */
-import { randomInt, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
+import { assertIntBound, cryptoWord, sampleInt } from "./runtime.int.js";
 /** Default Clock implementation backed by `Date.now()`. */
 export const systemClock = {
     now: () => Date.now(),
@@ -25,27 +26,13 @@ function cryptoUUID() {
 /**
  * Returns a uniformly random integer in [0, max).
  *
- * Rejection sampling, not `% max`. A modulo of a uniform 32-bit draw is only
- * uniform when `max` is a power of two; for other bounds the low values come
- * up more often, which is not acceptable from an interface documented as
- * cryptographically secure.
+ * Rejection sampling, not `% max`: a modulo of a uniform draw is only uniform
+ * when `max` divides the range. Bounds above `2**32` draw 53 bits, so every
+ * safe-integer bound terminates; anything else is a `RangeError`.
  */
 function cryptoInt(max) {
-    if (!Number.isInteger(max) || max <= 0) {
-        throw new RangeError("Random.int(max) requires a positive integer max");
-    }
-    if (typeof globalThis.crypto?.getRandomValues !== "function") {
-        return randomInt(max);
-    }
-    const range = 2 ** 32;
-    const limit = range - (range % max);
-    const buffer = new Uint32Array(1);
-    for (;;) {
-        globalThis.crypto.getRandomValues(buffer);
-        const draw = buffer[0];
-        if (draw < limit)
-            return draw % max;
-    }
+    assertIntBound(max, "Random");
+    return sampleInt(max, cryptoWord);
 }
 /** Builds a random string over an alphabet. */
 function randomString(length, alphabet, nextInt) {
@@ -97,46 +84,4 @@ export class FixedClock {
         this.current += deltaMs;
     }
 }
-/**
- * Deterministic generator useful for tests.
- *
- * Implements {@link PseudoRandom}, never {@link Random}: its output is fully
- * predictable from the seed, so injecting it where a secure generator is
- * expected would make every token guessable from a single observation.
- */
-export class SeededRandom {
-    deterministic = true;
-    state;
-    constructor(seed = 1) {
-        this.state = seed >>> 0 || 1;
-    }
-    /** Returns a structurally valid v4 UUID derived from the seed. */
-    uuid() {
-        const hex = (count) => Array.from({ length: count }, () => this.next().toString(16).padStart(8, "0").slice(-1)).join("");
-        return [
-            hex(8),
-            hex(4),
-            `4${hex(3)}`,
-            `${"89ab".charAt(this.int(4))}${hex(3)}`,
-            hex(12),
-        ].join("-");
-    }
-    int(max) {
-        if (!Number.isInteger(max) || max <= 0) {
-            throw new RangeError("PseudoRandom.int(max) requires a positive integer max");
-        }
-        return this.next() % max;
-    }
-    string(length) {
-        return this.custom(length, ALPHANUMERIC);
-    }
-    custom(length, alphabet) {
-        return randomString(length, alphabet, (max) => this.int(max));
-    }
-    /** Advances the linear congruential state. */
-    next() {
-        this.state = (Math.imul(this.state, 1103515245) + 12345) & 0x7fffffff;
-        return this.state;
-    }
-}
 //# sourceMappingURL=runtime.core.js.map

package/dist/runtime/runtime.int.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @zudojs/types/runtime — uniform integer sampling.
+ *
+ * Shared by the secure generator and the seeded test generator, so both
+ * accept the same bounds and both are uniform.
+ */
+/** Largest bound `int(max)` accepts: every result must be a safe integer. */
+export declare const MAX_RANDOM_INT_BOUND: number;
+/** Produces uniformly distributed unsigned 32-bit words. */
+export type WordSource = () => number;
+/**
+ * Validates an `int(max)` bound.
+ *
+ * @throws RangeError when `max` is not an integer in `[1, 2**53 - 1]`.
+ */
+export declare function assertIntBound(max: number, owner: string): void;
+/**
+ * Returns a uniformly random integer in `[0, max)` by rejection sampling.
+ *
+ * Bounds up to `2**32` draw one 32-bit word; larger bounds draw 53 bits from
+ * two words. The accept limit is the largest multiple of `max` inside the
+ * sampled range, which is never zero, so the loop terminates with
+ * probability 1 and in practice within a couple of draws.
+ *
+ * @param max - Exclusive upper bound, validated by {@link assertIntBound}.
+ * @param nextWord - Source of uniform unsigned 32-bit words.
+ */
+export declare function sampleInt(max: number, nextWord: WordSource): number;
+/** Returns one cryptographically secure unsigned 32-bit word. */
+export declare function cryptoWord(): number;
+//# sourceMappingURL=runtime.int.d.ts.map

package/dist/runtime/runtime.int.js

@@ -0,0 +1,54 @@
+/**
+ * @zudojs/types/runtime — uniform integer sampling.
+ *
+ * Shared by the secure generator and the seeded test generator, so both
+ * accept the same bounds and both are uniform.
+ */
+import { randomFillSync } from "node:crypto";
+/** Largest bound `int(max)` accepts: every result must be a safe integer. */
+export const MAX_RANDOM_INT_BOUND = Number.MAX_SAFE_INTEGER;
+const WORD = 2 ** 32;
+const HIGH_BITS = 2 ** 21;
+/**
+ * Validates an `int(max)` bound.
+ *
+ * @throws RangeError when `max` is not an integer in `[1, 2**53 - 1]`.
+ */
+export function assertIntBound(max, owner) {
+    if (!Number.isSafeInteger(max) || max <= 0) {
+        throw new RangeError(`${owner}.int(max) requires a positive integer max no larger than ${MAX_RANDOM_INT_BOUND}`);
+    }
+}
+/**
+ * Returns a uniformly random integer in `[0, max)` by rejection sampling.
+ *
+ * Bounds up to `2**32` draw one 32-bit word; larger bounds draw 53 bits from
+ * two words. The accept limit is the largest multiple of `max` inside the
+ * sampled range, which is never zero, so the loop terminates with
+ * probability 1 and in practice within a couple of draws.
+ *
+ * @param max - Exclusive upper bound, validated by {@link assertIntBound}.
+ * @param nextWord - Source of uniform unsigned 32-bit words.
+ */
+export function sampleInt(max, nextWord) {
+    const range = max <= WORD ? WORD : WORD * HIGH_BITS;
+    const limit = range - (range % max);
+    for (;;) {
+        const low = nextWord();
+        const draw = range === WORD ? low : (nextWord() % HIGH_BITS) * WORD + low;
+        if (draw < limit)
+            return draw % max;
+    }
+}
+const cryptoBuffer = new Uint32Array(1);
+/** Returns one cryptographically secure unsigned 32-bit word. */
+export function cryptoWord() {
+    if (typeof globalThis.crypto?.getRandomValues === "function") {
+        globalThis.crypto.getRandomValues(cryptoBuffer);
+    }
+    else {
+        randomFillSync(cryptoBuffer);
+    }
+    return cryptoBuffer[0];
+}
+//# sourceMappingURL=runtime.int.js.map

package/dist/runtime/runtime.seeded.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @zudojs/types/runtime — deterministic generator for tests.
+ */
+import type { PseudoRandom } from "./runtime.core.js";
+/**
+ * Deterministic generator useful for tests.
+ *
+ * Implements {@link PseudoRandom}, never `Random`: its output is fully
+ * predictable from the seed, so injecting it where a secure generator is
+ * expected would make every token guessable from a single observation.
+ *
+ * Backed by mulberry32, whose full 32-bit output is well distributed. The
+ * previous linear congruential generator exposed its low bits directly, so
+ * `uuid()` cycled after 16 values and `int(2)` alternated.
+ */
+export declare class SeededRandom implements PseudoRandom {
+    readonly deterministic = true;
+    private state;
+    constructor(seed?: number);
+    /** Returns a structurally valid v4 UUID derived from the seed. */
+    uuid(): string;
+    /** Returns a uniformly distributed integer in `[0, max)`. */
+    int(max: number): number;
+    /** Returns an alphanumeric string of the given length. */
+    string(length: number): string;
+    /** Returns a string of the given length drawn from `alphabet`. */
+    custom(length: number, alphabet: string): string;
+    /** Advances the mulberry32 state and returns an unsigned 32-bit word. */
+    private next;
+}
+//# sourceMappingURL=runtime.seeded.d.ts.map

package/dist/runtime/runtime.seeded.js

@@ -0,0 +1,70 @@
+/**
+ * @zudojs/types/runtime — deterministic generator for tests.
+ */
+import { assertIntBound, sampleInt } from "./runtime.int.js";
+const ALPHANUMERIC = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/**
+ * Deterministic generator useful for tests.
+ *
+ * Implements {@link PseudoRandom}, never `Random`: its output is fully
+ * predictable from the seed, so injecting it where a secure generator is
+ * expected would make every token guessable from a single observation.
+ *
+ * Backed by mulberry32, whose full 32-bit output is well distributed. The
+ * previous linear congruential generator exposed its low bits directly, so
+ * `uuid()` cycled after 16 values and `int(2)` alternated.
+ */
+export class SeededRandom {
+    deterministic = true;
+    state;
+    constructor(seed = 1) {
+        this.state = seed >>> 0 || 1;
+    }
+    /** Returns a structurally valid v4 UUID derived from the seed. */
+    uuid() {
+        let hex = "";
+        for (let i = 0; i < 4; i++) {
+            hex += this.next().toString(16).padStart(8, "0");
+        }
+        const variant = "89ab".charAt(this.int(4));
+        return [
+            hex.slice(0, 8),
+            hex.slice(8, 12),
+            `4${hex.slice(13, 16)}`,
+            `${variant}${hex.slice(17, 20)}`,
+            hex.slice(20, 32),
+        ].join("-");
+    }
+    /** Returns a uniformly distributed integer in `[0, max)`. */
+    int(max) {
+        assertIntBound(max, "PseudoRandom");
+        return sampleInt(max, () => this.next());
+    }
+    /** Returns an alphanumeric string of the given length. */
+    string(length) {
+        return this.custom(length, ALPHANUMERIC);
+    }
+    /** Returns a string of the given length drawn from `alphabet`. */
+    custom(length, alphabet) {
+        if (!Number.isInteger(length) || length < 0) {
+            throw new RangeError("Random.string(length) requires a non-negative integer");
+        }
+        if (alphabet.length === 0) {
+            throw new RangeError("alphabet must not be empty");
+        }
+        let out = "";
+        for (let i = 0; i < length; i++) {
+            out += alphabet.charAt(this.int(alphabet.length));
+        }
+        return out;
+    }
+    /** Advances the mulberry32 state and returns an unsigned 32-bit word. */
+    next() {
+        this.state = (this.state + 0x6d2b79f5) >>> 0;
+        let t = this.state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return (t ^ (t >>> 14)) >>> 0;
+    }
+}
+//# sourceMappingURL=runtime.seeded.js.map

package/dist/typeConverters/typeConverters.core.d.ts

@@ -11,8 +11,13 @@
  * boundary with `@zudojs/validation` or `@zudojs/schema` instead of relying on
  * this cast.
  *
- * Keys that would reach a prototype are dropped, so the parsed value cannot
- * seed a pollution chain downstream.
+ * `__proto__`, `constructor` and `prototype` keys are dropped at every depth.
+ * `JSON.parse` itself never routes them through a prototype, so this is a
+ * deliberate deny-list, not a parser fix: a downstream deep merge that walks
+ * `constructor.prototype` or `__proto__` would otherwise reach
+ * `Object.prototype`. A payload whose legitimate field is named
+ * `constructor` or `prototype` loses that field; parse it with plain
+ * `JSON.parse` and validate it instead.
  */
 export declare function safeJsonParse<T>(json: string, fallback: T): T;
 /**

package/dist/typeConverters/typeConverters.core.js

@@ -17,8 +17,13 @@ const UNSAFE_KEYS = new Set([
  * boundary with `@zudojs/validation` or `@zudojs/schema` instead of relying on
  * this cast.
  *
- * Keys that would reach a prototype are dropped, so the parsed value cannot
- * seed a pollution chain downstream.
+ * `__proto__`, `constructor` and `prototype` keys are dropped at every depth.
+ * `JSON.parse` itself never routes them through a prototype, so this is a
+ * deliberate deny-list, not a parser fix: a downstream deep merge that walks
+ * `constructor.prototype` or `__proto__` would otherwise reach
+ * `Object.prototype`. A payload whose legitimate field is named
+ * `constructor` or `prototype` loses that field; parse it with plain
+ * `JSON.parse` and validate it instead.
  */
 export function safeJsonParse(json, fallback) {
     try {
@@ -76,7 +81,7 @@ export function toNumber(value, fallback = NaN) {
         const trimmed = value.trim();
         if (trimmed.length === 0)
             return fallback;
-        if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/u.test(trimmed)) {
+        if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/u.test(trimmed)) {
             return fallback;
         }
         const parsed = Number(trimmed);
@@ -156,10 +161,17 @@ export function snakeToCamel(str) {
  * Split a camelCase or PascalCase identifier into its words.
  *
  * Runs of capitals are kept together, so `parseHTTPResponse` yields
- * `["parse", "HTTP", "Response"]` rather than one word per letter.
+ * `["parse", "HTTP", "Response"]` rather than one word per letter. Letter
+ * classes are Unicode-aware (`caféAuLait` keeps its `é`), existing `_`, `-`
+ * and whitespace separators are word boundaries, and any other character is
+ * kept in place rather than silently dropped.
  */
 function splitCamelWords(str) {
-    return str.match(/(?:[A-Z](?![a-z]))+|[A-Z]?[a-z0-9]+|[A-Z]|[0-9]+/gu) ?? [];
+    return str
+        .replace(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1\u0000$2")
+        .replace(/(\p{Lu})(\p{Lu}\p{Ll})/gu, "$1\u0000$2")
+        .split(/[\u0000\s_-]+/u)
+        .filter((word) => word.length > 0);
 }
 /**
  * Convert camelCase or PascalCase to snake_case.

package/dist/typeGuards/typeGuards.core.d.ts

@@ -49,10 +49,11 @@ export declare const MAX_EMAIL_LENGTH = 254;
 /**
  * Check if a value is a valid email string.
  *
- * This is the monorepo's single email check; `@zudojs/validation` re-exports
- * it as the `email` constraint. Two implementations previously disagreed
- * about the same address, so a value accepted at the edge could be rejected
- * halfway through a request.
+ * This is the monorepo's reference email check. `ValidationPattern.EMAIL`
+ * in `@zudojs/constants` (and therefore `createEmailAddress` and the schema
+ * `email` format) encodes the same acceptance set, including the 254
+ * character bound, and `@zudojs/validation`'s `email` constraint uses that
+ * pattern, so all three accept exactly the same addresses.
  */
 export declare function isEmail(value: unknown): value is string;
 /**
@@ -84,6 +85,10 @@ export declare function isIsoDateString(value: unknown): value is string;
 export declare function isIsoDateTimeString(value: unknown): value is string;
 /**
  * Check if a value is an array of a specific element type.
+ *
+ * Every index in `0..length-1` is read, so a hole is tested as `undefined`
+ * rather than skipped. `Array.prototype.every` skips holes, which made
+ * `new Array(3)` satisfy every guard and narrow three holes to `T[]`.
  */
 export declare function isArrayOfType<T>(value: unknown, guard: (item: unknown) => item is T): value is T[];
 /**

package/dist/typeGuards/typeGuards.core.js

@@ -76,10 +76,11 @@ export const MAX_EMAIL_LENGTH = 254;
 /**
  * Check if a value is a valid email string.
  *
- * This is the monorepo's single email check; `@zudojs/validation` re-exports
- * it as the `email` constraint. Two implementations previously disagreed
- * about the same address, so a value accepted at the edge could be rejected
- * halfway through a request.
+ * This is the monorepo's reference email check. `ValidationPattern.EMAIL`
+ * in `@zudojs/constants` (and therefore `createEmailAddress` and the schema
+ * `email` format) encodes the same acceptance set, including the 254
+ * character bound, and `@zudojs/validation`'s `email` constraint uses that
+ * pattern, so all three accept exactly the same addresses.
  */
 export function isEmail(value) {
     if (typeof value !== "string")
@@ -168,11 +169,19 @@ export function isIsoDateTimeString(value) {
 }
 /**
  * Check if a value is an array of a specific element type.
+ *
+ * Every index in `0..length-1` is read, so a hole is tested as `undefined`
+ * rather than skipped. `Array.prototype.every` skips holes, which made
+ * `new Array(3)` satisfy every guard and narrow three holes to `T[]`.
  */
 export function isArrayOfType(value, guard) {
     if (!Array.isArray(value))
         return false;
-    return value.every(guard);
+    for (let index = 0; index < value.length; index++) {
+        if (!guard(value[index]))
+            return false;
+    }
+    return true;
 }
 /**
  * Check if a value is defined (not null or undefined).

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/types",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Shared type guards, utility types, and type converters for the Zudojs framework.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",