@zudojs/validation 0.1.0 → 1.0.1

package/dist/validationConstraints/structure/validationConstraints.size.js

@@ -0,0 +1,101 @@
+/**
+ * @zudojs/validation — Size checking.
+ *
+ * Estimates serialized payload size to prevent memory exhaustion
+ * from excessively large payloads.
+ */
+import { SerializationPayloadTooLargeError } from "@zudojs/errors";
+import { MAX_MEASURABLE_DEPTH } from "./validationConstraints.depth.js";
+import { TraversalLimitError, traverse, } from "./validationConstraints.traverse.js";
+/** Bytes charged for a single node, excluding its children. */
+function chargeFor(value) {
+    if (value === null || value === undefined)
+        return 4;
+    switch (typeof value) {
+        case "string":
+            return value.length * 2 + 2;
+        case "number":
+            // JSON emits up to 21 characters for a double; charge the worst case
+            // rather than a flat 8, which under-counted every numeric field.
+            return 21;
+        case "boolean":
+            return 5;
+        case "bigint":
+            return value.toString().length + 2;
+        case "symbol":
+        case "function":
+            return 0;
+    }
+    if (ArrayBuffer.isView(value))
+        return value.byteLength;
+    if (value instanceof Date)
+        return 26;
+    if (value instanceof RegExp)
+        return value.source.length + 4;
+    if (Array.isArray(value))
+        return 2 + Math.max(0, value.length - 1);
+    if (value instanceof Map)
+        return 2 + Math.max(0, value.size * 3 - 1);
+    if (value instanceof Set)
+        return 2 + Math.max(0, value.size - 1);
+    const keys = Object.keys(value);
+    return (2 +
+        keys.reduce((total, key) => total + key.length + 4, 0) +
+        Math.max(0, keys.length - 1));
+}
+/**
+ * Estimate the byte size of a value as JSON without allocating a string.
+ *
+ * A value referenced from several places is charged once per occurrence, the
+ * way a serializer expands it. Counting it once let a compact payload built
+ * from shared subtrees estimate at a few hundred bytes while serializing to
+ * hundreds of megabytes.
+ *
+ * @param value - The value to measure.
+ * @param maxBytes - Stop counting past this budget; the budget is returned.
+ * @returns The estimated serialized size in bytes.
+ */
+export function estimateSerializedSize(value, maxBytes = Number.POSITIVE_INFINITY) {
+    try {
+        return traverse(value, {
+            maxDepth: MAX_MEASURABLE_DEPTH,
+            maxCost: maxBytes,
+            charge: chargeFor,
+        }).cost;
+    }
+    catch (error) {
+        if (error instanceof TraversalLimitError) {
+            return error.halt === "budget" ? error.observed : maxBytes;
+        }
+        throw error;
+    }
+}
+/**
+ * Assert that a value's estimated serialized size is within limits.
+ *
+ * Aborts as soon as the budget is passed, so an oversized payload is rejected
+ * without first being measured in full.
+ *
+ * @param value - The value to check.
+ * @param maxSize - Maximum permitted size in bytes.
+ * @throws {SerializationPayloadTooLargeError} when the estimate exceeds maxSize.
+ */
+export function assertSizeWithinLimit(value, maxSize) {
+    try {
+        traverse(value, {
+            maxDepth: MAX_MEASURABLE_DEPTH,
+            maxCost: maxSize,
+            charge: chargeFor,
+        });
+    }
+    catch (error) {
+        if (error instanceof TraversalLimitError && error.halt === "budget") {
+            throw new SerializationPayloadTooLargeError(error.observed, maxSize);
+        }
+        if (error instanceof TraversalLimitError && error.halt === "depth") {
+            throw new SerializationPayloadTooLargeError(error.observed, maxSize);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=validationConstraints.size.js.map

package/dist/validationConstraints/structure/validationConstraints.traverse.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @zudojs/validation — Bounded object-graph traversal.
+ *
+ * The depth, size and circular-reference guards all walk the same graph and
+ * all previously got the same three details wrong.
+ *
+ * The visited set must track the current *path*, not everything ever seen:
+ * marking on descent and unmarking on ascent detects a genuine cycle while
+ * still counting a shared subtree once per occurrence, the way a serializer
+ * would expand it.
+ *
+ * The walk must be bounded, and abort the moment a bound is passed. A guard
+ * that measures the whole input before comparing it to a limit is not a
+ * guard — it does the expensive work regardless.
+ *
+ * And the walk must be iterative. A recursive walker overflows the stack on
+ * exactly the deeply nested input the depth guard exists to reject, so the
+ * check would fail inside itself before it could report anything.
+ */
+/** Why a traversal stopped early. */
+export type TraversalHalt = "depth" | "budget" | "cycle";
+/** Signals that a traversal hit one of its bounds. */
+export declare class TraversalLimitError extends Error {
+    readonly halt: TraversalHalt;
+    readonly path: string;
+    readonly observed: number;
+    constructor(halt: TraversalHalt, path: string, observed: number);
+}
+/** What the caller wants from each node. */
+export interface TraversalVisitor {
+    /** Maximum nesting depth to descend before halting. */
+    readonly maxDepth: number;
+    /** Cumulative budget; halts once `charge` totals more than this. */
+    readonly maxCost?: number;
+    /** Whether a cycle should halt the walk rather than be skipped. */
+    readonly failOnCycle?: boolean;
+    /** Cost contributed by a single node, excluding its children. */
+    charge?(value: unknown): number;
+}
+/** What a completed traversal observed. */
+export interface TraversalReport {
+    /** Deepest nesting level reached. */
+    readonly depth: number;
+    /** Total cost accumulated across every visited node. */
+    readonly cost: number;
+}
+/**
+ * Walk a value graph within explicit depth and cost bounds.
+ *
+ * @param root - The value to walk.
+ * @param visitor - Bounds and per-node cost.
+ * @param rootPath - Label for the root node in error paths.
+ * @returns What the traversal observed, when it completed within bounds.
+ * @throws {TraversalLimitError} as soon as a bound is exceeded.
+ */
+export declare function traverse(root: unknown, visitor: TraversalVisitor, rootPath?: string): TraversalReport;
+//# sourceMappingURL=validationConstraints.traverse.d.ts.map

package/dist/validationConstraints/structure/validationConstraints.traverse.js

@@ -0,0 +1,118 @@
+/**
+ * @zudojs/validation — Bounded object-graph traversal.
+ *
+ * The depth, size and circular-reference guards all walk the same graph and
+ * all previously got the same three details wrong.
+ *
+ * The visited set must track the current *path*, not everything ever seen:
+ * marking on descent and unmarking on ascent detects a genuine cycle while
+ * still counting a shared subtree once per occurrence, the way a serializer
+ * would expand it.
+ *
+ * The walk must be bounded, and abort the moment a bound is passed. A guard
+ * that measures the whole input before comparing it to a limit is not a
+ * guard — it does the expensive work regardless.
+ *
+ * And the walk must be iterative. A recursive walker overflows the stack on
+ * exactly the deeply nested input the depth guard exists to reject, so the
+ * check would fail inside itself before it could report anything.
+ */
+/** Signals that a traversal hit one of its bounds. */
+export class TraversalLimitError extends Error {
+    halt;
+    path;
+    observed;
+    constructor(halt, path, observed) {
+        super(`Traversal halted (${halt}) at ${path}`);
+        this.halt = halt;
+        this.path = path;
+        this.observed = observed;
+        this.name = "TraversalLimitError";
+    }
+}
+/** Whether a value has children worth descending into. */
+function isContainer(value) {
+    return (typeof value === "object" && value !== null && !ArrayBuffer.isView(value));
+}
+/** The child values of a container, as [pathSegment, value] pairs. */
+function childrenOf(value) {
+    if (Array.isArray(value)) {
+        return value.map((child, index) => [`[${index}]`, child]);
+    }
+    if (value instanceof Map) {
+        const children = [];
+        let index = 0;
+        for (const [key, entry] of value) {
+            children.push([`.key(${index})`, key], [`[${String(key)}]`, entry]);
+            index++;
+        }
+        return children;
+    }
+    if (value instanceof Set) {
+        return [...value].map((entry, index) => [`.item(${index})`, entry]);
+    }
+    if (value instanceof Date || value instanceof RegExp)
+        return [];
+    const record = value;
+    return Object.keys(record).map((key) => [`.${key}`, record[key]]);
+}
+/**
+ * Walk a value graph within explicit depth and cost bounds.
+ *
+ * @param root - The value to walk.
+ * @param visitor - Bounds and per-node cost.
+ * @param rootPath - Label for the root node in error paths.
+ * @returns What the traversal observed, when it completed within bounds.
+ * @throws {TraversalLimitError} as soon as a bound is exceeded.
+ */
+export function traverse(root, visitor, rootPath = "root") {
+    const maxCost = visitor.maxCost ?? Number.POSITIVE_INFINITY;
+    const onPath = new Set();
+    const stack = [{ value: root, depth: 0, path: rootPath }];
+    let cost = 0;
+    let deepest = 0;
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame.leave) {
+            onPath.delete(frame.leave);
+            continue;
+        }
+        const { value, depth, path } = frame;
+        cost += visitor.charge?.(value) ?? 0;
+        if (cost > maxCost)
+            throw new TraversalLimitError("budget", path, cost);
+        if (depth > deepest)
+            deepest = depth;
+        if (!isContainer(value))
+            continue;
+        // A container occupies the level below the one it sits at, so an empty
+        // `{}` at depth d reaches d + 1 — the same level at which the depth
+        // guard below refuses to descend into it. Reporting only leaf depths
+        // made `getSerializationDepth({})` 0 while `assertDepthWithinLimit({},
+        // 0)` threw.
+        if (depth + 1 > deepest)
+            deepest = depth + 1;
+        if (onPath.has(value)) {
+            if (visitor.failOnCycle) {
+                throw new TraversalLimitError("cycle", path, depth);
+            }
+            continue;
+        }
+        if (depth >= visitor.maxDepth) {
+            throw new TraversalLimitError("depth", path, depth + 1);
+        }
+        onPath.add(value);
+        stack.push({ value: undefined, depth, path, leave: value });
+        const children = childrenOf(value);
+        for (let index = children.length - 1; index >= 0; index--) {
+            const [segment, child] = children[index];
+            stack.push({
+                value: child,
+                depth: depth + 1,
+                path: `${path}${segment}`,
+            });
+        }
+    }
+    return { depth: deepest, cost };
+}
+//# sourceMappingURL=validationConstraints.traverse.js.map

package/dist/validationConstraints/validationConstraints.base.d.ts

@@ -7,21 +7,36 @@ export interface ValidationConstraint<T> {
     readonly validate: (value: T) => boolean;
     readonly message: string;
     readonly code: string;
+    /**
+     * Narrows an arbitrary value to the type `validate` expects.
+     *
+     * Constraints are frequently handed values straight off a trust boundary,
+     * where the declared type parameter guarantees nothing. Without a guard,
+     * `everyItem(...)` called on a number throws a raw `TypeError` out of the
+     * validator, turning a 400 into a 500.
+     */
+    readonly guard?: (value: unknown) => value is T;
 }
 /**
  * Options for creating a validation constraint.
  */
-export interface ConstraintOptions {
+export interface ConstraintOptions<T = unknown> {
     readonly name?: string;
     readonly code?: string;
     readonly message?: string;
+    readonly guard?: (value: unknown) => value is T;
 }
 /**
  * Creates a reusable validation constraint.
  */
-export declare function createConstraint<T>(validate: (value: T) => boolean, options?: ConstraintOptions): ValidationConstraint<T>;
+export declare function createConstraint<T>(validate: (value: T) => boolean, options?: ConstraintOptions<T>): ValidationConstraint<T>;
 /**
  * Executes a constraint against a value.
+ *
+ * The rejected value is deliberately *not* attached to the issue. Issues flow
+ * into `ValidationError`, which is exposed with a 400, so echoing the input
+ * would return rejected passwords, tokens and PII to the caller and write them
+ * to any log that serializes the error.
  */
 export declare function checkConstraint<T>(constraint: ValidationConstraint<T>, value: T, path?: readonly (string | number)[]): ValidationResult<T>;
 /**
@@ -35,7 +50,7 @@ export declare function combineConstraints<T>(...constraints: readonly Validatio
 /**
  * Creates a negated constraint.
  */
-export declare function not<T>(constraint: ValidationConstraint<T>, options?: ConstraintOptions): ValidationConstraint<T>;
+export declare function not<T>(constraint: ValidationConstraint<T>, options?: ConstraintOptions<T>): ValidationConstraint<T>;
 /**
  * Requires a value to be defined.
  */

package/dist/validationConstraints/validationConstraints.base.js

@@ -3,30 +3,61 @@ import { failure, success, } from "../validationResult/validationResult.type.js"
  * Creates a reusable validation constraint.
  */
 export function createConstraint(validate, options = {}) {
-    const name = options.name ?? "custom";
-    const code = options.code ?? "constraint_failed";
-    const message = options.message ?? "Validation constraint failed.";
+    const guard = options.guard;
+    /**
+     * `validate` is public, so it is called directly as often as it is called
+     * through `checkConstraints`. Applying the guard here rather than only at
+     * the call site means no entry point can be handed a wrong-typed value and
+     * throw a raw `TypeError` back at a trust boundary.
+     */
+    const guarded = guard
+        ? (value) => guard(value) && validate(value)
+        : validate;
     return Object.freeze({
-        name,
-        validate,
-        message,
-        code,
+        name: options.name ?? "custom",
+        validate: guarded,
+        message: options.message ?? "Validation constraint failed.",
+        code: options.code ?? "constraint_failed",
+        ...(guard ? { guard } : {}),
     });
 }
 /**
- * Executes a constraint against a value.
+ * Run a constraint against a value of unknown type.
+ *
+ * Returns false rather than throwing when the value is the wrong shape, so a
+ * mistyped field reports as a validation failure instead of escaping as an
+ * unhandled error.
  */
-export function checkConstraint(constraint, value, path = []) {
-    if (constraint.validate(value)) {
-        return success(value);
+function runConstraint(constraint, value) {
+    if (constraint.guard && !constraint.guard(value))
+        return false;
+    try {
+        return constraint.validate(value);
     }
-    const validationIssue = {
+    catch {
+        return false;
+    }
+}
+/** Builds the issue describing a failed constraint. */
+function toIssue(constraint, path) {
+    return {
         path: [...path],
         code: constraint.code,
         message: constraint.message,
-        received: value,
     };
-    return failure([validationIssue]);
+}
+/**
+ * Executes a constraint against a value.
+ *
+ * The rejected value is deliberately *not* attached to the issue. Issues flow
+ * into `ValidationError`, which is exposed with a 400, so echoing the input
+ * would return rejected passwords, tokens and PII to the caller and write them
+ * to any log that serializes the error.
+ */
+export function checkConstraint(constraint, value, path = []) {
+    if (runConstraint(constraint, value))
+        return success(value);
+    return failure([toIssue(constraint, path)]);
 }
 /**
  * Executes multiple constraints against a value.
@@ -34,25 +65,19 @@ export function checkConstraint(constraint, value, path = []) {
 export function checkConstraints(constraints, value, path = []) {
     const issues = [];
     for (const constraint of constraints) {
-        if (!constraint.validate(value)) {
-            issues.push({
-                path: [...path],
-                code: constraint.code,
-                message: constraint.message,
-                received: value,
-            });
+        if (!runConstraint(constraint, value)) {
+            issues.push(toIssue(constraint, path));
         }
     }
-    if (issues.length > 0) {
+    if (issues.length > 0)
         return failure(issues);
-    }
     return success(value);
 }
 /**
  * Combines constraints into a single constraint.
  */
 export function combineConstraints(...constraints) {
-    return createConstraint((value) => constraints.every((constraint) => constraint.validate(value)), {
+    return createConstraint((value) => constraints.every((constraint) => runConstraint(constraint, value)), {
         name: constraints.map((constraint) => constraint.name).join("_and_") ||
             "combined",
         code: "combined_constraint_failed",
@@ -63,7 +88,7 @@ export function combineConstraints(...constraints) {
  * Creates a negated constraint.
  */
 export function not(constraint, options = {}) {
-    return createConstraint((value) => !constraint.validate(value), {
+    return createConstraint((value) => !runConstraint(constraint, value), {
         name: options.name ?? `not_${constraint.name}`,
         code: options.code ?? "negated_constraint_failed",
         message: options.message ?? `Value must not satisfy ${constraint.name}.`,

package/dist/validationErrors/validationError.base.js

@@ -3,6 +3,33 @@
  */
 import { formatIssues, toFieldErrors, } from "../validationResult/validationResult.type.js";
 import { BaseError, ErrorCode, ErrorCategory, ErrorSeverity, } from "@zudojs/errors";
+/**
+ * Maps a package-specific validation code to the shared error registry code.
+ *
+ * `ValidationErrorCode` and `ErrorCode` are different enums. Casting one into
+ * the other put a value on `BaseError.code` that the errors package does not
+ * recognise, so any status mapping or registry lookup keyed on it missed.
+ */
+function toErrorCode(code) {
+    switch (code) {
+        case ValidationErrorCode.REQUIRED:
+            return ErrorCode.MISSING_FIELD;
+        case ValidationErrorCode.INVALID_TYPE:
+            return ErrorCode.INVALID_FIELD;
+        case ValidationErrorCode.INVALID_FORMAT:
+            return ErrorCode.INVALID_FORMAT;
+        case ValidationErrorCode.INVALID_VALUE:
+            return ErrorCode.INVALID_VALUE;
+        case ValidationErrorCode.INVALID_INPUT:
+            return ErrorCode.INVALID_INPUT;
+        case ValidationErrorCode.SCHEMA_FAILED:
+            return ErrorCode.SCHEMA_VALIDATION;
+        case ValidationErrorCode.CONSTRAINT_FAILED:
+        case ValidationErrorCode.UNKNOWN:
+        default:
+            return ErrorCode.VALIDATION_FAILED;
+    }
+}
 /** Error codes used by the validation package. */
 export var ValidationErrorCode;
 (function (ValidationErrorCode) {
@@ -23,7 +50,7 @@ export class ValidationError extends BaseError {
     timestamp;
     constructor(message, issues = [], options = {}) {
         super(message, {
-            code: options.code ?? ErrorCode.VALIDATION_FAILED,
+            code: toErrorCode(options.code),
             category: ErrorCategory.VALIDATION,
             severity: ErrorSeverity.WARNING,
             statusCode: 400,

package/dist/validationFactory/validationFactory.core.d.ts

@@ -1,4 +1,4 @@
-import type { ValidationConstraint } from "../validationConstraints/index.js";
+import type { ConstraintOptions, ValidationConstraint } from "../validationConstraints/index.js";
 import type { ValidationResult } from "../validationResult/validationResult.type.js";
 import type { ValidationSchema } from "../validationSchema/validationSchema.core.js";
 import { type ValidationParser, type AsyncValidationParser } from "../validationParser/validationParser.core.js";
@@ -21,11 +21,7 @@ export declare class ValidationFactory {
     normalizer<T>(normalizer: Normalizer<T>): ValidationNormalizer<T>;
     asyncNormalizer<T>(normalizer: AsyncNormalizer<T>): AsyncValidationNormalizer<T>;
     composer<T>(steps: readonly ValidationStep<T>[], options?: ValidationComposerOptions): ValidationComposer<T>;
-    constraint<T>(validateValue: (value: T) => boolean, options?: {
-        readonly name?: string;
-        readonly code?: string;
-        readonly message?: string;
-    }): ValidationConstraint<T>;
+    constraint<T>(validateValue: (value: T) => boolean, options?: ConstraintOptions<T>): ValidationConstraint<T>;
     validate<T>(schema: ValidationSchema<T>, value: unknown): ValidationResult<T>;
     validateAsync<T>(schema: ValidationSchema<T>, value: unknown): Promise<ValidationResult<T>>;
     check<T>(constraints: readonly ValidationConstraint<T>[], value: T): ValidationResult<T>;
@@ -35,6 +31,11 @@ export declare class ValidationFactory {
 }
 /** Creates a new validation factory. */
 export declare function createValidationFactory(options?: ValidationFactoryOptions): ValidationFactory;
-/** Default validation factory instance. */
-export declare const validationFactory: ValidationFactory;
+/**
+ * Create a factory that shares a registry with an existing one.
+ *
+ * Prefer this to a process-wide singleton: a shared factory means one module
+ * calling `registry.clear()` silently removes rules another module registered.
+ */
+export declare function createScopedValidationFactory(parent: ValidationFactory): ValidationFactory;
 //# sourceMappingURL=validationFactory.core.d.ts.map

package/dist/validationFactory/validationFactory.core.js

@@ -1,4 +1,4 @@
-import { checkConstraints } from "../validationConstraints/index.js";
+import { checkConstraints, createConstraint, } from "../validationConstraints/index.js";
 import { validate, validateAsync, } from "../validationSchema/validationSchema.core.js";
 import { createValidationParser, createAsyncValidationParser, } from "../validationParser/validationParser.core.js";
 import { createValidationTransformer, createAsyncValidationTransformer, } from "../validationTransformer/validationTransformer.core.js";
@@ -33,12 +33,7 @@ export class ValidationFactory {
         return createValidationComposer(steps, options);
     }
     constraint(validateValue, options = {}) {
-        return {
-            name: options.name ?? "custom",
-            code: options.code ?? "constraint_failed",
-            message: options.message ?? "Validation constraint failed.",
-            validate: validateValue,
-        };
+        return createConstraint(validateValue, options);
     }
     validate(schema, value) {
         return validate(schema, value);
@@ -65,6 +60,13 @@ export class ValidationFactory {
 export function createValidationFactory(options = {}) {
     return new ValidationFactory(options);
 }
-/** Default validation factory instance. */
-export const validationFactory = createValidationFactory();
+/**
+ * Create a factory that shares a registry with an existing one.
+ *
+ * Prefer this to a process-wide singleton: a shared factory means one module
+ * calling `registry.clear()` silently removes rules another module registered.
+ */
+export function createScopedValidationFactory(parent) {
+    return new ValidationFactory({ registry: parent.registry });
+}
 //# sourceMappingURL=validationFactory.core.js.map

package/dist/validationNormalizer/validationNormalizer.core.js

@@ -17,13 +17,12 @@ export function createNormalizer(normalizer, options = {}) {
             try {
                 return success(normalizer(value));
             }
-            catch (error) {
+            catch {
                 return failure([
                     {
                         path: [],
                         code: "normalization_failed",
                         message: options.errorMessage ?? "Value normalization failed.",
-                        received: error instanceof Error ? error.message : error,
                     },
                 ]);
             }
@@ -47,13 +46,12 @@ export function createAsyncNormalizer(normalizer, options = {}) {
             try {
                 return success(await normalizer(value));
             }
-            catch (error) {
+            catch {
                 return failure([
                     {
                         path: [],
                         code: "normalization_failed",
                         message: options.errorMessage ?? "Value normalization failed.",
-                        received: error instanceof Error ? error.message : error,
                     },
                 ]);
             }

package/dist/validationNormalizer/validationNormalizer.helpers.d.ts

@@ -11,17 +11,50 @@ export declare function normalizeLowercase(value: string): string;
 export declare function normalizeUppercase(value: string): string;
 /** Normalizes Unicode text using NFC normalization. */
 export declare function normalizeUnicode(value: string): string;
-/** Normalizes an email address. */
+/**
+ * Normalizes Unicode text using NFKC, folding compatibility forms.
+ *
+ * Use this wherever the result identifies something. NFC is canonical only:
+ * it leaves ligatures and fullwidth forms distinct from their ASCII
+ * spellings, so two visually identical identifiers survive as two values.
+ */
+export declare function normalizeUnicodeCompatibility(value: string): string;
+/**
+ * Case-folds a string for identifier comparison.
+ *
+ * `toLowerCase` is a locale-sensitive display transform. Folding through
+ * upper- then lower-case is the closest stable approximation available
+ * without ICU, and is what identifier comparison needs.
+ */
+export declare function foldCase(value: string): string;
+/**
+ * Normalizes an email address.
+ *
+ * Only the domain is lowercased. The local part is case-sensitive per RFC
+ * 5321, and folding it can merge two distinct mailboxes.
+ */
 export declare function normalizeEmail(value: string): string;
 /** Normalizes a URL by removing surrounding whitespace. */
 export declare function normalizeUrl(value: string): string;
-/** Normalizes an identifier by trimming and lowercasing it. */
+/**
+ * Normalizes an identifier by trimming, compatibility-folding and case-folding.
+ *
+ * The output identifies an account or a resource, so it uses NFKC and a case
+ * fold rather than NFC and `toLowerCase`: otherwise two spellings that render
+ * identically normalize to two different identifiers.
+ */
 export declare function normalizeIdentifier(value: string): string;
 /** Removes surrounding quotes from a string. */
 export declare function normalizeQuotes(value: string): string;
 /** Removes Unicode byte-order marks from the beginning of text. */
 export declare function removeBom(value: string): string;
-/** Normalizes an array by applying a normalizer to every item. */
+/**
+ * Normalizes an array by applying a normalizer to every item.
+ *
+ * The normalizer is invoked with the value only. Passing it straight to `map`
+ * would also hand it the index and the array, which silently overrides the
+ * optional second parameter of functions like `parseInt`.
+ */
 export declare function normalizeArray<T>(values: readonly T[], normalizer: (value: T) => T): T[];
 /** Normalizes an array asynchronously. */
 export declare function normalizeArrayAsync<T>(values: readonly T[], normalizer: (value: T) => T | Promise<T>): Promise<T[]>;