@azure-net/node-kit 0.1.2 → 0.2.2

package/VALIDATION.md

@@ -865,3 +865,62 @@ similar names do not guarantee interchangeable acceptance sets or error shapes.
   [type tests](tests/validation.types.ts), [result tests](tests/validation-result.test.mjs),
   [value tests](tests/validation-values.test.mjs), and
   [string-format tests](tests/validation-strings.test.mjs).
+
+## Parsing before validation
+
+`parse(input, options?)` converts values using the built-in type descriptors, then
+runs the ordinary validator and returns `ValidationResult<T>`. `parseAndThrow`
+returns the validated `T` or throws `ValidationError`. Their asynchronous equivalents
+are `parseAsync` and `parseAndThrowAsync`. Locale, context and cancellation options
+are the same as for validation. Ordinary `validate` methods remain strict.
+
+```ts
+class CollectionQueryValidator extends Validator<{ page: number; ids: number[] }> {
+  protected rules() {
+    return {
+      page: [rules.number(), rules.integer(), rules.positive()],
+      ids: [rules.array([rules.number(), rules.integer()])]
+    };
+  }
+}
+
+const query = CollectionQueryValidator.parseAndThrow({
+  page: '2',
+  ids: ['10', '20']
+});
+// { page: 2, ids: [10, 20] }
+```
+
+The caller assembles the structure (for example using Hono `req.query('page')`
+and `req.queries('ids')`). Parsing never interprets URLSearchParams, bracket keys,
+JSON strings or comma-separated values and never wraps scalars in arrays.
+
+- Finite decimal numeric strings (including exponent notation) become numbers.
+  Empty/whitespace strings, hexadecimal, Infinity and unsafe integer results are
+  left unchanged. Floating-point values retain JavaScript number precision.
+- Boolean conversion accepts exactly `"true"` and `"false"`, not truthiness or 0/1.
+- Bigint accepts integer decimal strings and safe integer numbers.
+- String conversion accepts finite numbers, booleans and bigints, never objects.
+- Date conversion accepts valid ISO date/date-time strings; omitted timezone means
+  UTC. Invalid calendar dates are not normalized into a different date.
+- Homogeneous primitive enums/literals select their primitive type. Membership is
+  still checked during validation. Mixed enums are not coerced.
+- A structural type rule is required, e.g. `number()` plus `integer()`. Constraints
+  like `positive()` or `integer()` alone do not identify an unambiguous input type.
+- Object, array, tuple and record values are traversed by their schemas. Record keys
+  stay strings. Nested validators and lazy schema descriptions are supported.
+- Map/Set inputs must already be Map/Set instances. Converted keys/elements that
+  would collapse distinct entries cause that collection to remain unchanged.
+- Ordinary unions and overlapping intersection branches are not guessed. A
+  discriminated union can parse the branch selected by the existing discriminator.
+- Null/undefined remain unchanged; missing fields are not filled with defaults.
+- Failed conversions leave the original value for ordinary validation to reject.
+  Custom callbacks run only in validation, against the converted data.
+
+The parser uses copy-on-write: unchanged branches may share references with input,
+changed branches are copied without invoking getters. It is not a deep-cloning or
+sanitizing API. Unknown keys remain subject to the ordinary unknown-key policy.
+Depth/node limits bound parsing; if exceeded, the conversion is discarded and the
+original input is validated. Cycles are not expanded indefinitely. Primitive
+conversion strings are bounded to 4096 characters. Cached plans contain schemas
+only, never request values or contexts.

package/dist/validation/Validator.d.ts

@@ -16,6 +16,10 @@ export declare abstract class Validator<T extends object, TContext = unknown> {
     static validateAndThrow<T extends object, C = unknown>(this: ValidatorConstructor<T, C>, input: unknown, ...[options]: ValidationArguments<C>): T;
     static validateAsync<T extends object, C = unknown>(this: ValidatorConstructor<T, C>, input: unknown, ...[options]: ValidationArguments<C>): Promise<ValidationResult<T>>;
     static validateAndThrowAsync<T extends object, C = unknown>(this: ValidatorConstructor<T, C>, input: unknown, ...[options]: ValidationArguments<C>): Promise<T>;
+    static parse<T extends object, C = unknown>(this: ValidatorConstructor<T, C>, input: unknown, ...[options]: ValidationArguments<C>): ValidationResult<T>;
+    static parseAndThrow<T extends object, C = unknown>(this: ValidatorConstructor<T, C>, input: unknown, ...[options]: ValidationArguments<C>): T;
+    static parseAsync<T extends object, C = unknown>(this: ValidatorConstructor<T, C>, input: unknown, ...[options]: ValidationArguments<C>): Promise<ValidationResult<T>>;
+    static parseAndThrowAsync<T extends object, C = unknown>(this: ValidatorConstructor<T, C>, input: unknown, ...[options]: ValidationArguments<C>): Promise<T>;
     /** Both Validator.create(options) and new Validator.create(options) return a base class. */
     static readonly create: {
         (options?: ValidatorCreateOptions): typeof Validator;

package/dist/validation/Validator.js

@@ -1,3 +1,4 @@
+import { parseInput } from "./parsing/Parse.js";
 import { validateAsync, validateSync } from "./Engine.js";
 import { ValidationError } from "./Result.js";
 import { validatorDefinition } from "./Symbols.js";
@@ -83,6 +84,24 @@ export class Validator {
             throw new ValidationError(result);
         return result.data;
     }
+    static parse(input, ...[options]) {
+        return validateSync(parseInput(input, Validator.schema(this), Validator.config(this)), Validator.schema(this), Validator.config(this), options ?? {});
+    }
+    static parseAndThrow(input, ...[options]) {
+        const result = validateSync(parseInput(input, Validator.schema(this), Validator.config(this)), Validator.schema(this), Validator.config(this), options ?? {});
+        if (!result.isValid)
+            throw new ValidationError(result);
+        return result.data;
+    }
+    static async parseAsync(input, ...[options]) {
+        return validateAsync(parseInput(input, Validator.schema(this), Validator.config(this)), Validator.schema(this), Validator.config(this), options ?? {});
+    }
+    static async parseAndThrowAsync(input, ...[options]) {
+        const result = await validateAsync(parseInput(input, Validator.schema(this), Validator.config(this)), Validator.schema(this), Validator.config(this), options ?? {});
+        if (!result.isValid)
+            throw new ValidationError(result);
+        return result.data;
+    }
     /** Both Validator.create(options) and new Validator.create(options) return a base class. */
     static create = function (options = {}) {
         const configuration = settings(options);

package/dist/validation/parsing/Conversions.d.ts

@@ -0,0 +1,5 @@
+import type { BuiltinRule } from "../Types.js";
+export type Scalar = "number" | "string" | "boolean" | "bigint" | "date";
+/** Uses immutable built-in identifiers, never options.code or message keys. */
+export declare function scalarType(rule: BuiltinRule): Scalar | undefined;
+export declare function convert(value: unknown, type: Scalar): unknown;

package/dist/validation/parsing/Conversions.js

@@ -0,0 +1,64 @@
+import { DateHelper } from "../../tools/DateHelper.js";
+const numberCodes = new Set(["number", "finite", "int32", "uint32", "float32"]);
+const bigintCodes = new Set(["bigint", "int64", "uint64"]);
+/** Uses immutable built-in identifiers, never options.code or message keys. */
+export function scalarType(rule) {
+    if (rule.kind !== "test" || !rule.structural)
+        return undefined;
+    if (numberCodes.has(rule.code))
+        return "number";
+    if (bigintCodes.has(rule.code))
+        return "bigint";
+    if (["string", "boolean", "date"].includes(rule.code))
+        return rule.code;
+    const values = rule.code === "enum"
+        ? rule.params.values
+        : rule.code === "literal"
+            ? [rule.params.expected]
+            : undefined;
+    if (!values?.length)
+        return undefined;
+    const type = typeof values[0];
+    return ["number", "string", "boolean", "bigint"].includes(type) &&
+        values.every((value) => typeof value === type)
+        ? type
+        : undefined;
+}
+const numeric = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
+export function convert(value, type) {
+    if (value === null || value === undefined)
+        return value;
+    if (type === "string") {
+        return typeof value === "boolean" ||
+            typeof value === "bigint" ||
+            (typeof value === "number" && Number.isFinite(value))
+            ? String(value)
+            : value;
+    }
+    if (type === "bigint" && typeof value === "number")
+        return Number.isSafeInteger(value) ? BigInt(value) : value;
+    if (typeof value !== "string" || value.length > 4096)
+        return value;
+    if (type === "boolean")
+        return value === "true" ? true : value === "false" ? false : value;
+    if (type === "number") {
+        if (!numeric.test(value))
+            return value;
+        const number = Number(value);
+        return Number.isFinite(number) &&
+            (!Number.isInteger(number) || Number.isSafeInteger(number))
+            ? number
+            : value;
+    }
+    if (type === "bigint")
+        return /^[+-]?\d+$/.test(value) ? BigInt(value) : value;
+    if (type === "date") {
+        if (value !== value.trim() || DateHelper.compare(value, value) !== 0)
+            return value;
+        const iso = value.replace(" ", "T");
+        return new Date(iso.includes("T") && !/(?:Z|[+-]\d{2}:\d{2})$/.test(iso)
+            ? `${iso}Z`
+            : iso);
+    }
+    return value;
+}

package/dist/validation/parsing/Parse.d.ts

@@ -0,0 +1,5 @@
+import type { AnyRule, ValidatorOptions } from "../Types.js";
+type Shape = Readonly<Record<string, readonly AnyRule[]>>;
+/** Per-call state only; on exhaustion validation sees the original input and enforces its own limits. */
+export declare function parseInput(input: unknown, shape: Shape, config: ValidatorOptions): unknown;
+export {};

package/dist/validation/parsing/Parse.js

@@ -0,0 +1,181 @@
+import { types } from "node:util";
+import { convert, scalarType } from "./Conversions.js";
+const plans = new WeakMap();
+function planFor(rules) {
+    let plan = plans.get(rules);
+    if (plan)
+        return plan;
+    const descriptors = rules.filter((rule) => typeof rule !== "function");
+    const scalars = new Set(descriptors.map(scalarType).filter((type) => type !== undefined));
+    const children = descriptors.filter((rule) => !["test", "optional", "nullable"].includes(rule.kind));
+    plan = {
+        scalar: scalars.size === 1 ? [...scalars][0] : undefined,
+        children,
+        ambiguous: scalars.size > 1 || (scalars.size > 0 && children.length > 0),
+    };
+    plans.set(rules, plan);
+    return plan;
+}
+function record(value) {
+    if (!value || typeof value !== "object" || types.isProxy(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === null || prototype === Object.prototype;
+}
+/** Per-call state only; on exhaustion validation sees the original input and enforces its own limits. */
+export function parseInput(input, shape, config) {
+    const maxDepth = config.maxDepth ?? 64;
+    const maxNodes = config.maxNodes ?? 10000;
+    let nodes = 0;
+    const exhausted = Symbol();
+    const active = new WeakSet();
+    function budget(depth) {
+        if (++nodes > maxNodes || depth > maxDepth)
+            throw exhausted;
+    }
+    function properties(value, select, depth) {
+        let copy;
+        for (const key of Object.keys(value)) {
+            const property = Object.getOwnPropertyDescriptor(value, key);
+            const rules = select(key);
+            if (!("value" in property) || !rules) {
+                budget(depth + 1);
+                continue;
+            }
+            const next = visit(property.value, rules, depth + 1);
+            if (Object.is(next, property.value))
+                continue;
+            if (!copy) {
+                // Preserve unknown fields, accessors and symbols without executing getters.
+                copy = Array.isArray(value)
+                    ? []
+                    : Object.create(Object.getPrototypeOf(value));
+                for (const ownKey of Reflect.ownKeys(value)) {
+                    const descriptor = Object.getOwnPropertyDescriptor(value, ownKey);
+                    Object.defineProperty(copy, ownKey, {
+                        ...descriptor,
+                        ...(ownKey === "length" && Array.isArray(value)
+                            ? { writable: true }
+                            : { configurable: true }),
+                    });
+                }
+            }
+            Object.defineProperty(copy, key, {
+                ...property,
+                value: next,
+                configurable: true,
+            });
+        }
+        return copy ?? value;
+    }
+    function object(value, fields, depth) {
+        return record(value)
+            ? properties(value, (key) => (Object.hasOwn(fields, key) ? fields[key] : undefined), depth)
+            : value;
+    }
+    function child(value, rule, depth) {
+        switch (rule.kind) {
+            case "object":
+                return object(value, rule.shape, depth);
+            case "array":
+            case "tuple":
+                return Array.isArray(value)
+                    ? properties(value, (key) => /^(0|[1-9]\d*)$/.test(key)
+                        ? rule.kind === "array"
+                            ? rule.items
+                            : rule.tuple[Number(key)]
+                        : undefined, depth)
+                    : value;
+            case "record":
+                return record(value)
+                    ? properties(value, () => rule.items, depth)
+                    : value;
+            case "lazy":
+            case "validator":
+                return visit(value, rule.resolve(), depth + 1, true);
+            case "union": {
+                // No branch guessing or user predicates during parsing.
+                if (!rule.discriminator || !record(value))
+                    return value;
+                const prop = Object.getOwnPropertyDescriptor(value, rule.discriminator);
+                const key = prop && "value" in prop ? prop.value : undefined;
+                if (!["string", "number", "boolean"].includes(typeof key))
+                    return value;
+                const rules = Object.hasOwn(rule.variants, String(key))
+                    ? rule.variants[String(key)]
+                    : undefined;
+                return rules ? visit(value, rules, depth + 1, true) : value;
+            }
+            // Intersections may specify incompatible conversions. Let validation decide.
+            case "intersection":
+                return value;
+            case "map": {
+                if (!(value instanceof Map))
+                    return value;
+                const entries = [];
+                const keys = new Set();
+                let changed = false;
+                for (const [key, item] of Map.prototype.entries.call(value)) {
+                    const nextKey = visit(key, rule.keys, depth + 1);
+                    const nextItem = visit(item, rule.items, depth + 1);
+                    if (keys.has(nextKey))
+                        return value;
+                    keys.add(nextKey);
+                    changed ||= !Object.is(key, nextKey) || !Object.is(item, nextItem);
+                    entries.push([nextKey, nextItem]);
+                }
+                return changed ? new Map(entries) : value;
+            }
+            case "set": {
+                if (!(value instanceof Set))
+                    return value;
+                const items = new Set();
+                let changed = false;
+                for (const item of Set.prototype.values.call(value)) {
+                    const next = visit(item, rule.items, depth + 1);
+                    if (items.has(next))
+                        return value;
+                    items.add(next);
+                    changed ||= !Object.is(item, next);
+                }
+                return changed ? items : value;
+            }
+            default:
+                return value;
+        }
+    }
+    function visit(value, rules, depth, sameNode = false) {
+        budget(depth);
+        if (value === null || value === undefined || types.isProxy(value))
+            return value;
+        const plan = planFor(rules);
+        if (plan.ambiguous)
+            return value;
+        if (plan.scalar)
+            return convert(value, plan.scalar);
+        const tracked = typeof value === "object";
+        if (tracked && !sameNode && active.has(value))
+            return value;
+        if (tracked && !sameNode)
+            active.add(value);
+        try {
+            let result = value;
+            for (const rule of plan.children)
+                result = child(result, rule, depth);
+            return result;
+        }
+        finally {
+            if (tracked && !sameNode)
+                active.delete(value);
+        }
+    }
+    try {
+        budget(0);
+        return object(input, shape, 0);
+    }
+    catch (error) {
+        if (error === exhausted)
+            return input;
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-net/node-kit",
-  "version": "0.1.2",
+  "version": "0.2.2",
   "description": "Framework-independent Node.js toolkit for the Azure-net ecosystem",
   "type": "module",
   "license": "MIT",