@zudojs/types 0.1.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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
@@ -13,26 +19,75 @@ npm install @zudojs/types
 ```typescript
 import {
   isPlainObject,
-  isDate,
   isEmail,
-  Maybe,
-  DeepReadonly,
+  isUuid,
+  systemClock,
+  systemRandom,
+  toNumber,
 } from "@zudojs/types";
+import type { Maybe, DeepReadonly } from "@zudojs/types";
 
 if (isPlainObject(value)) {
-  console.log(value.keys());
+  for (const key of Object.keys(value)) {
+    console.log(key, value[key]);
+  }
 }
 
 const id: Maybe<string> = null;
 const config: DeepReadonly<AppConfig> = { db: { host: "localhost" } };
+
+// Injectable runtime primitives, so tests can substitute deterministic ones.
+const token = systemRandom.string(32);
+const now = systemClock.now();
+
+// Converters refuse rather than guessing: "" and "0x10" fall back.
+const limit = toNumber(query.limit, 20);
+```
+
+Deterministic doubles for tests:
+
+```typescript
+import { FixedClock, SeededRandom } from "@zudojs/types";
+import type { PseudoRandom } from "@zudojs/types";
+
+const clock = new FixedClock(0);
+const random: PseudoRandom = new SeededRandom(42);
+
+clock.advance(1_000);
 ```
 
+## Safety Notes
+
+- `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(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
+  version matters. `isPromise` narrows only to a native `Promise` — use
+  `isThenable` for anything awaitable.
+
 ## Features
 
-- Type guards (`isPlainObject`, `isDate`, `isEmail`, etc.)
+- Type guards (`isPlainObject`, `isDate`, `isEmail`, `isUuid`, etc.)
 - Utility types (`Maybe`, `DeepReadonly`, `Prettify`, etc.)
-- Type converters and transformers
-- Branded type utilities
+- Type converters and case transformers
+- 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
 

package/dist/runtime/index.d.ts

@@ -1,2 +1,12 @@
-export * from "./runtime.core.js";
+/**
+ * @zudojs/types — Runtime primitives barrel.
+ *
+ * An explicit list rather than `export *`: this was the only barrel in the
+ * package without one, so anything newly exported from `runtime.core.ts`
+ * silently became public API.
+ */
+export type { Clock, ClockSeconds, Random, PseudoRandom, } 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

@@ -1,2 +1,11 @@
-export * from "./runtime.core.js";
+/**
+ * @zudojs/types — Runtime primitives barrel.
+ *
+ * An explicit list rather than `export *`: this was the only barrel in the
+ * package without one, so anything newly exported from `runtime.core.ts`
+ * silently became public API.
+ */
+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

@@ -13,21 +13,67 @@ export interface Clock {
 export interface ClockSeconds {
     nowSeconds(): number;
 }
-/** Returns cryptographically-secure random values. */
+/**
+ * Brand marking an implementation as cryptographically secure.
+ *
+ * Structural typing alone would let any object with the right method names
+ * satisfy `Random`, including a seeded test generator. The brand makes the
+ * claim explicit: an implementor opts in through {@link defineSecureRandom}.
+ */
+declare const SecureRandomBrand: unique symbol;
+/**
+ * Returns cryptographically-secure random values.
+ *
+ * Implementations of this interface are safe for tokens, identifiers and
+ * secrets. A deterministic generator must implement {@link PseudoRandom}
+ * instead, so a test double cannot be injected where unpredictability is the
+ * requirement.
+ */
 export interface Random {
+    /** @internal Marks the implementation as unpredictable. */
+    readonly [SecureRandomBrand]: true;
     /** Returns a random UUID v4 string. */
     uuid(): string;
-    /** Returns a 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;
     /** Returns a random string of the given length from the given alphabet. */
     custom(length: number, alphabet: string): string;
 }
+/**
+ * A reproducible generator for tests.
+ *
+ * Structurally identical to {@link Random} but nominally distinct, so it
+ * cannot be passed where a `Random` is required.
+ */
+export interface PseudoRandom {
+    /** Marks this as a deterministic generator, not a secure one. */
+    readonly deterministic: true;
+    uuid(): string;
+    int(max: number): number;
+    string(length: number): string;
+    custom(length: number, alphabet: string): string;
+}
 /** Default Clock implementation backed by `Date.now()`. */
 export declare const systemClock: Clock;
 /** Default ClockSeconds implementation backed by `Math.floor(Date.now() / 1000)`. */
 export declare const systemClockSeconds: ClockSeconds;
+/**
+ * Declare an implementation cryptographically secure.
+ *
+ * Call this only for a generator whose output is genuinely unpredictable —
+ * one backed by `node:crypto`, Web Crypto, or a hardware source. It is the
+ * single supported way to produce a {@link Random}.
+ *
+ * @param implementation - The generator's operations.
+ * @returns The implementation, branded as secure.
+ */
+export declare function defineSecureRandom(implementation: Omit<Random, typeof SecureRandomBrand>): Random;
 /** Default Random implementation backed by `node:crypto`. */
 export declare const systemRandom: Random;
 /** Deterministic Clock useful for tests. */
@@ -38,13 +84,5 @@ export declare class FixedClock implements Clock {
     set(time: number): void;
     advance(deltaMs: number): void;
 }
-/** Deterministic Random useful for tests. */
-export declare class SeededRandom implements Random {
-    private state;
-    constructor(seed?: number);
-    uuid(): string;
-    int(max: number): number;
-    string(length: number): string;
-    custom(length: number, alphabet: string): string;
-}
+export {};
 //# sourceMappingURL=runtime.core.d.ts.map

package/dist/runtime/runtime.core.js

@@ -5,6 +5,8 @@
  * avoid direct `Date.now()` and `Math.random()` calls. Tests can substitute
  * deterministic implementations.
  */
+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(),
@@ -13,37 +15,27 @@ export const systemClock = {
 export const systemClockSeconds = {
     nowSeconds: () => Math.floor(Date.now() / 1000),
 };
-/** Default Random implementation backed by `node:crypto`. */
-export const systemRandom = {
-    uuid: () => cryptoUUID(),
-    int: (max) => cryptoInt(max),
-    string: (length) => randomString(length, ALPHANUMERIC),
-    custom: (length, alphabet) => randomString(length, alphabet),
-};
 const ALPHANUMERIC = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/** Returns a v4 UUID, preferring the Web Crypto implementation. */
 function cryptoUUID() {
     if (typeof globalThis.crypto?.randomUUID === "function") {
         return globalThis.crypto.randomUUID();
     }
-    // node:crypto fallback (older Node, edge runtimes)
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { randomUUID } = require("node:crypto");
     return randomUUID();
 }
+/**
+ * Returns a uniformly random integer in [0, max).
+ *
+ * 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") {
-        const buf = new Uint32Array(1);
-        globalThis.crypto.getRandomValues(buf);
-        return buf[0] % max;
-    }
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { randomInt } = require("node:crypto");
-    return randomInt(max);
+    assertIntBound(max, "Random");
+    return sampleInt(max, cryptoWord);
 }
-function randomString(length, alphabet) {
+/** Builds a random string over an alphabet. */
+function randomString(length, alphabet, nextInt) {
     if (!Number.isInteger(length) || length < 0) {
         throw new RangeError("Random.string(length) requires a non-negative integer");
     }
@@ -52,10 +44,30 @@ function randomString(length, alphabet) {
     }
     let out = "";
     for (let i = 0; i < length; i++) {
-        out += alphabet.charAt(cryptoInt(alphabet.length));
+        out += alphabet.charAt(nextInt(alphabet.length));
     }
     return out;
 }
+/**
+ * Declare an implementation cryptographically secure.
+ *
+ * Call this only for a generator whose output is genuinely unpredictable —
+ * one backed by `node:crypto`, Web Crypto, or a hardware source. It is the
+ * single supported way to produce a {@link Random}.
+ *
+ * @param implementation - The generator's operations.
+ * @returns The implementation, branded as secure.
+ */
+export function defineSecureRandom(implementation) {
+    return implementation;
+}
+/** Default Random implementation backed by `node:crypto`. */
+export const systemRandom = defineSecureRandom({
+    uuid: () => cryptoUUID(),
+    int: (max) => cryptoInt(max),
+    string: (length) => randomString(length, ALPHANUMERIC, cryptoInt),
+    custom: (length, alphabet) => randomString(length, alphabet, cryptoInt),
+});
 /** Deterministic Clock useful for tests. */
 export class FixedClock {
     current;
@@ -72,33 +84,4 @@ export class FixedClock {
         this.current += deltaMs;
     }
 }
-/** Deterministic Random useful for tests. */
-export class SeededRandom {
-    state;
-    constructor(seed = 1) {
-        this.state = seed;
-    }
-    uuid() {
-        const hex = this.state.toString(16).padStart(8, "0");
-        this.state = (this.state * 1103515245 + 12345) & 0x7fffffff;
-        return `${hex}-${this.state.toString(16).padStart(8, "0")}-0000-0000-000000000000`;
-    }
-    int(max) {
-        if (!Number.isInteger(max) || max <= 0) {
-            throw new RangeError("SeededRandom.int(max) requires a positive integer max");
-        }
-        this.state = (this.state * 1103515245 + 12345) & 0x7fffffff;
-        return this.state % max;
-    }
-    string(length) {
-        return this.custom(length, ALPHANUMERIC);
-    }
-    custom(length, alphabet) {
-        let out = "";
-        for (let i = 0; i < length; i++) {
-            out += alphabet.charAt(this.int(alphabet.length));
-        }
-        return out;
-    }
-}
 //# 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

@@ -5,18 +5,43 @@
  */
 /**
  * Safely parse JSON with a fallback value.
+ *
+ * "Safe" here means only that malformed JSON yields the fallback rather than
+ * throwing. The result is cast to `T` without validation — parse a trust
+ * boundary with `@zudojs/validation` or `@zudojs/schema` instead of relying on
+ * this cast.
+ *
+ * `__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;
 /**
  * Convert a value to a string safely.
+ *
+ * Always returns a string. `JSON.stringify` returns the *value* `undefined`
+ * — not a string, and without throwing — for functions, symbols and
+ * `undefined`, so its result is checked rather than returned directly.
  */
 export declare function toString(value: unknown, fallback?: string): string;
 /**
- * Convert a value to a number safely.
+ * Convert a value to a finite number safely.
+ *
+ * Blank strings, hexadecimal literals and infinities all fall back rather than
+ * converting: a missing query parameter arriving as `""` becoming a real zero
+ * silently turns into a page size, a price or a limit.
  */
 export declare function toNumber(value: unknown, fallback?: number): number;
 /**
  * Convert a value to a boolean safely.
+ *
+ * `NaN` falls back rather than converting to true. It is what `toNumber`
+ * produces on failure, so chaining the two would otherwise turn a parse
+ * failure into the permissive answer for a flag.
  */
 export declare function toBoolean(value: unknown, fallback?: boolean): boolean;
 /**
@@ -25,6 +50,12 @@ export declare function toBoolean(value: unknown, fallback?: boolean): boolean;
 export declare function toArray<T>(value: T | T[]): T[];
 /**
  * Convert a Map to a plain object.
+ *
+ * Built on a null-prototype object with `defineProperty`. Assigning into an
+ * object literal routes a `__proto__` key through the prototype setter, so a
+ * Map built from request data — headers, form fields, query parameters — could
+ * replace the result's prototype with attacker-supplied values that
+ * `Object.keys` does not reveal.
  */
 export declare function mapToObject<K extends string | number | symbol, V>(map: Map<K, V>): Record<K, V>;
 /**
@@ -36,7 +67,11 @@ export declare function objectToMap<K extends string | number | symbol, V>(obj:
  */
 export declare function snakeToCamel(str: string): string;
 /**
- * Convert camelCase to snake_case.
+ * Convert camelCase or PascalCase to snake_case.
+ *
+ * Leading capitals do not produce a leading separator, and acronyms survive
+ * as single words — an identifier like `_hello_world` is not a valid column
+ * name, and `parse_h_t_t_p_response` is not a useful one.
  */
 export declare function camelToSnake(str: string): string;
 /**
@@ -44,7 +79,7 @@ export declare function camelToSnake(str: string): string;
  */
 export declare function kebabToCamel(str: string): string;
 /**
- * Convert camelCase to kebab-case.
+ * Convert camelCase or PascalCase to kebab-case.
  */
 export declare function camelToKebab(str: string): string;
 //# sourceMappingURL=typeConverters.core.d.ts.map