@azure-net/node-kit 0.0.0-stage → 0.1.0

package/dist/validation/Engine.js

@@ -0,0 +1,406 @@
+import { ValidationResult } from "./Result.js";
+import { validationMessagesEn, validationMessagesI18n, } from "./messages/index.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");
+    plan = {
+        optional: descriptors.some((rule) => rule.kind === "optional"),
+        nullable: descriptors.some((rule) => rule.kind === "nullable" ||
+            (rule.kind === "optional" && rule.params.nullable === true)),
+        structural: descriptors.some((rule) => rule.structural && rule.kind !== "optional" && rule.kind !== "nullable"),
+        guards: descriptors.filter((rule) => rule.kind === "test" && rule.structural),
+        children: descriptors.filter((rule) => rule.kind !== "test" &&
+            rule.kind !== "optional" &&
+            rule.kind !== "nullable"),
+        checks: [
+            ...descriptors.filter((rule) => rule.kind === "test" && !rule.structural),
+            ...rules.filter((rule) => typeof rule === "function"),
+        ],
+    };
+    plans.set(rules, plan);
+    return plan;
+}
+function record(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        !(value instanceof Date) &&
+        !(value instanceof Map) &&
+        !(value instanceof Set) &&
+        !(value instanceof RegExp) &&
+        !ArrayBuffer.isView(value) &&
+        !(value instanceof ArrayBuffer));
+}
+function thenable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
+function issue(state, path, code, params = {}, options = {}) {
+    const { runtime, issues } = state;
+    if (issues.length >= runtime.maxIssues)
+        return;
+    const key = options.messageKey ?? code;
+    const config = runtime.config;
+    const own = (object, key) => object && Object.hasOwn(object, key) ? object[key] : undefined;
+    const messageContext = {
+        code: options.code ?? code,
+        messageKey: key,
+        params,
+        path,
+        locale: runtime.locale,
+        label: options.label ?? String(path.at(-1) ?? "value"),
+    };
+    const catalog = own(config.locales ?? validationMessagesI18n, runtime.locale);
+    const fallback = own(config.locales ?? validationMessagesI18n, config.fallbackLocale ?? "en");
+    const template = options.message ??
+        own(config.messages, key) ??
+        own(catalog, key) ??
+        own(own(validationMessagesI18n, runtime.locale), key) ??
+        own(fallback, key) ??
+        own(validationMessagesEn, key) ??
+        "Invalid value";
+    const raw = typeof template === "function" ? template(messageContext) : template;
+    const message = raw.replace(/\{([\w]+)\}/g, (match, name) => {
+        if (name === "label")
+            return messageContext.label;
+        return Object.hasOwn(params, name) ? String(params[name]) : match;
+    });
+    issues.push({ path: [...path], code: messageContext.code, message, params });
+}
+function consume(state, result, context, rule) {
+    if (result === true)
+        return true;
+    if (result === false) {
+        issue(state, context.path, rule?.code ?? "custom.invalid", rule?.params, rule?.options);
+        return false;
+    }
+    const failures = Array.isArray(result) ? result : [result];
+    for (const failure of failures) {
+        if (!failure || typeof failure !== "object" || thenable(failure)) {
+            throw new TypeError("Validation rules must return true, false, a failure object or an array of failures.");
+        }
+        issue(state, [...context.path, ...(failure.path ?? [])], failure.code ?? rule?.code ?? "custom.invalid", { ...rule?.params, ...failure.params }, { ...rule?.options, ...failure });
+    }
+    return failures.length === 0;
+}
+function failStructure(state, context, code, params, options) {
+    state.structuralValid = false;
+    issue(state, context.path, code, params, options);
+}
+function fork(state) {
+    return {
+        runtime: state.runtime,
+        issues: [],
+        jobs: [],
+        structuralValid: true,
+    };
+}
+function prepare(state, value, data, path, rules, depth) {
+    const runtime = state.runtime;
+    runtime.signal?.throwIfAborted();
+    const context = {
+        value,
+        data,
+        root: runtime.root,
+        context: runtime.context,
+        path,
+        signal: runtime.signal,
+    };
+    if (runtime.budget.exhausted) {
+        state.structuralValid = false;
+        return;
+    }
+    if (++runtime.budget.nodes > runtime.maxNodes) {
+        runtime.budget.exhausted = true;
+        failStructure(state, context, "validation.nodes", {
+            max: runtime.maxNodes,
+        });
+        return;
+    }
+    if (depth > runtime.maxDepth) {
+        failStructure(state, context, "validation.depth", {
+            max: runtime.maxDepth,
+        });
+        return;
+    }
+    const { optional, nullable, guards, children, checks, structural } = planFor(rules);
+    if ((value === undefined && optional) || (value === null && nullable))
+        return;
+    if (!structural) {
+        throw new TypeError(`Missing structural rule at ${JSON.stringify(path)}. Add string(), number(), object(), unknown(), etc.`);
+    }
+    if (value === null || value === undefined) {
+        for (const rule of checks) {
+            if (typeof rule !== "function" &&
+                ["required", "notNull", "notEmpty"].includes(rule.code) &&
+                !consume(state, rule.test(value, context), context, rule)) {
+                state.structuralValid = false;
+                return;
+            }
+        }
+    }
+    const initial = state.issues.length;
+    // Type guards always precede constraints, regardless of their position in the array.
+    for (const rule of guards) {
+        if (!consume(state, rule.test(value, context), context, rule)) {
+            state.structuralValid = false;
+            return;
+        }
+    }
+    const ownJob = { kind: "node", context, checks };
+    for (const rule of children) {
+        if (rule.kind === "intersection") {
+            for (const branch of rule.alternatives)
+                prepare(state, value, data, path, branch, depth + 1);
+            continue;
+        }
+        if (rule.kind === "lazy" || rule.kind === "validator") {
+            if (rule.kind === "validator") {
+                const child = {
+                    ...state,
+                    runtime: {
+                        ...runtime,
+                        root: value,
+                        config: { ...runtime.config, unknownKeys: rule.unknownKeys },
+                    },
+                };
+                prepare(child, value, data, path, rule.resolve(), depth + 1);
+                if (!child.structuralValid)
+                    state.structuralValid = false;
+            }
+            else
+                prepare(state, value, data, path, rule.resolve(), depth + 1);
+            continue;
+        }
+        if (rule.kind === "union") {
+            let alternatives = rule.alternatives;
+            if (rule.discriminator !== undefined) {
+                const property = record(value)
+                    ? Object.getOwnPropertyDescriptor(value, rule.discriminator)
+                    : undefined;
+                const key = property && Object.hasOwn(property, "value")
+                    ? property.value
+                    : undefined;
+                const variant = (typeof key === "string" ||
+                    typeof key === "number" ||
+                    typeof key === "boolean") &&
+                    Object.hasOwn(rule.variants, String(key))
+                    ? rule.variants[String(key)]
+                    : undefined;
+                if (variant)
+                    prepare(state, value, data, path, variant, depth + 1);
+                else
+                    failStructure(state, context, rule.code, rule.params, rule.options);
+                continue;
+            }
+            const candidates = alternatives.map((alternative) => {
+                const candidate = fork(state);
+                prepare(candidate, value, data, path, alternative, depth + 1);
+                return candidate;
+            });
+            const valid = candidates.filter((candidate) => candidate.structuralValid);
+            if (!valid.length || runtime.budget.exhausted) {
+                failStructure(state, context, rule.code, rule.params, rule.options);
+            }
+            else
+                state.jobs.push({ kind: "union", context, rule, candidates: valid });
+            continue;
+        }
+        const isObject = rule.kind === "object" || rule.kind === "record";
+        const isArray = rule.kind === "array" || rule.kind === "tuple";
+        if ((isObject && !record(value)) ||
+            (isArray && !Array.isArray(value)) ||
+            (rule.kind === "map" && !(value instanceof Map)) ||
+            (rule.kind === "set" && !(value instanceof Set))) {
+            failStructure(state, context, rule.code, rule.params, rule.options);
+            break;
+        }
+        const container = value;
+        if (runtime.active.has(container)) {
+            failStructure(state, context, "validation.cycle");
+            break;
+        }
+        runtime.active.add(container);
+        try {
+            if (isObject) {
+                const object = value;
+                const shape = rule.shape;
+                const keys = shape ? Object.keys(shape) : Object.keys(object);
+                for (const key of keys) {
+                    if (runtime.budget.exhausted ||
+                        state.issues.length >= runtime.maxIssues)
+                        break;
+                    const property = Object.getOwnPropertyDescriptor(object, key);
+                    if (property && !Object.hasOwn(property, "value")) {
+                        if (++runtime.budget.nodes > runtime.maxNodes) {
+                            runtime.budget.exhausted = true;
+                            failStructure(state, { ...context, path: [...path, key] }, "validation.nodes", { max: runtime.maxNodes });
+                            break;
+                        }
+                        failStructure(state, { ...context, path: [...path, key] }, "object.accessor");
+                        continue;
+                    }
+                    prepare(state, property?.value, object, [...path, key], shape?.[key] ?? rule.items, depth + 1);
+                    if (rule.keys)
+                        prepare(state, key, object, [...path, key], rule.keys, depth + 1);
+                }
+                if (shape &&
+                    (rule.unknownKeys ?? runtime.config.unknownKeys ?? "reject") ===
+                        "reject") {
+                    for (const key of Object.keys(object)) {
+                        if (!Object.hasOwn(shape, key))
+                            failStructure(state, { ...context, path: [...path, key] }, "object.unknownKeys");
+                        if (state.issues.length >= runtime.maxIssues)
+                            break;
+                    }
+                }
+            }
+            else if (isArray) {
+                const array = value;
+                if (rule.kind === "tuple" && array.length !== rule.tuple.length) {
+                    failStructure(state, context, "array.length", { length: rule.tuple.length }, rule.options);
+                }
+                else {
+                    for (let index = 0; index < array.length; index++) {
+                        if (runtime.budget.exhausted ||
+                            state.issues.length >= runtime.maxIssues)
+                            break;
+                        const property = Object.getOwnPropertyDescriptor(array, String(index));
+                        if (property && !Object.hasOwn(property, "value")) {
+                            if (++runtime.budget.nodes > runtime.maxNodes) {
+                                runtime.budget.exhausted = true;
+                                failStructure(state, { ...context, path: [...path, index] }, "validation.nodes", { max: runtime.maxNodes });
+                                break;
+                            }
+                            failStructure(state, { ...context, path: [...path, index] }, "object.accessor");
+                            continue;
+                        }
+                        prepare(state, property?.value, array, [...path, index], rule.items ?? rule.tuple[index], depth + 1);
+                    }
+                }
+            }
+            else if (rule.kind === "set") {
+                let index = 0;
+                for (const item of value) {
+                    if (runtime.budget.exhausted ||
+                        state.issues.length >= runtime.maxIssues)
+                        break;
+                    prepare(state, item, value, [...path, index++], rule.items, depth + 1);
+                }
+            }
+            else if (rule.kind === "map") {
+                let index = 0;
+                for (const [key, item] of value) {
+                    if (runtime.budget.exhausted ||
+                        state.issues.length >= runtime.maxIssues)
+                        break;
+                    prepare(state, key, value, [...path, index, "key"], rule.keys, depth + 1);
+                    prepare(state, item, value, [...path, index++, "value"], rule.items, depth + 1);
+                }
+            }
+        }
+        finally {
+            runtime.active.delete(container);
+        }
+    }
+    if (state.issues.length === initial && checks.length)
+        state.jobs.push(ownJob);
+}
+function* execute(state, allowCustom) {
+    for (const job of state.jobs) {
+        state.runtime.signal?.throwIfAborted();
+        if (state.issues.length >= state.runtime.maxIssues ||
+            state.runtime.budget.exhausted)
+            break;
+        if (job.kind === "union") {
+            let success = false;
+            for (const candidate of job.candidates) {
+                yield* execute(candidate, allowCustom);
+                if (!candidate.issues.length) {
+                    success = true;
+                    break;
+                }
+            }
+            if (!success)
+                issue(state, job.context.path, job.rule.code, job.rule.params, job.rule.options);
+            continue;
+        }
+        let failed = false;
+        // Built-in constraints precede user callbacks, avoiding I/O for invalid fields.
+        for (const rule of job.checks) {
+            if (typeof rule === "function" &&
+                (!allowCustom ||
+                    failed ||
+                    state.issues.some((issue) => issue.path.length >= job.context.path.length &&
+                        job.context.path.every((part, index) => issue.path[index] === part))))
+                continue;
+            let result = typeof rule === "function"
+                ? rule(job.context)
+                : rule.test(job.context.value, job.context);
+            if (thenable(result))
+                result = yield result;
+            state.runtime.signal?.throwIfAborted();
+            if (!consume(state, result, job.context, typeof rule === "function" ? undefined : rule)) {
+                failed = true;
+                if ((state.runtime.config.cascade ?? "stop") === "stop")
+                    break;
+            }
+        }
+    }
+}
+function initialize(input, shape, config, options) {
+    options.signal?.throwIfAborted();
+    const runtime = {
+        config,
+        locale: options.locale ?? config.getLocale?.() ?? config.defaultLocale ?? "en",
+        root: input,
+        context: options.context,
+        signal: options.signal,
+        maxDepth: config.maxDepth ?? 64,
+        maxNodes: config.maxNodes ?? 10000,
+        maxIssues: config.maxIssues ?? 100,
+        budget: { nodes: 0, exhausted: false },
+        active: new WeakSet(),
+    };
+    const state = { runtime, issues: [], jobs: [], structuralValid: true };
+    prepare(state, input, input, [], [
+        {
+            kind: "object",
+            code: "type.object",
+            structural: true,
+            options: {},
+            params: {},
+            shape,
+        },
+    ], 0);
+    return state;
+}
+export function validateSync(input, shape, config, options) {
+    const state = initialize(input, shape, config, options);
+    const iterator = execute(state, state.structuralValid);
+    const step = iterator.next();
+    if (!step.done) {
+        // Observe rejection even on API misuse; the user's already-started I/O cannot be undone.
+        void Promise.resolve(step.value).catch(() => { });
+        iterator.return();
+        throw new TypeError("Async rule encountered during validate(). Use validateAsync().");
+    }
+    return new ValidationResult(input, state.issues);
+}
+export async function validateAsync(input, shape, config, options) {
+    const state = initialize(input, shape, config, options);
+    const iterator = execute(state, state.structuralValid);
+    let step = iterator.next();
+    try {
+        while (!step.done)
+            step = iterator.next(await step.value);
+    }
+    finally {
+        iterator.return();
+    }
+    return new ValidationResult(input, state.issues);
+}

package/dist/validation/Result.d.ts

@@ -0,0 +1,31 @@
+import type { ValidationErrors, ValidationIssue } from "./Types.js";
+/** A snapshot of validation diagnostics. Failed results never retain `data`. */
+export declare class ValidationResult<T> {
+    #private;
+    readonly isValid: boolean;
+    readonly issues: readonly ValidationIssue[];
+    readonly data: T | undefined;
+    /** No issues means success (including when data is undefined); otherwise data is discarded. */
+    constructor(data: T | undefined, issues: readonly ValidationIssue[]);
+    get errors(): ValidationErrors<T>;
+    get formErrors(): readonly string[];
+    /**
+     * Flat RFC 6901 JSON Pointer keys: ~ becomes ~0, / becomes ~1.
+     * Root issues are excluded (see formErrors). String "0" and numeric 0
+     * share a pointer; the typed tree preserves their separate namespaces.
+     */
+    toFieldErrors(): Readonly<Record<string, readonly string[]>>;
+}
+/** An Error wrapper whose JSON representation excludes validated input and stack. */
+export declare class ValidationError<T = unknown> extends Error {
+    readonly result: ValidationResult<T>;
+    constructor(result: ValidationResult<T>, message?: string);
+    get issues(): readonly ValidationIssue[];
+    get errors(): ValidationErrors<T>;
+    toJSON(): {
+        name: string;
+        message: string;
+        issues: readonly ValidationIssue[];
+        errors: ValidationErrors<T>;
+    };
+}