@amritk/validation 0.3.1 → 0.4.0

package/dist/validators/generators/generate-coerce-function.js

@@ -2,7 +2,19 @@ import { regexFlagsFor } from "@amritk/helpers/escape-regex-pattern";
 import { declaresKey, readKey } from "@amritk/helpers/read-key";
 import { refToName } from "@amritk/helpers/ref-to-name";
 import { isSchemaObject } from "@amritk/helpers/schema-guards";
+import { NO_FORMATS } from "./enforced-keywords.js";
+import { createSubschemaMatcher } from "./generate-validator-function.js";
 const COERCIBLE_TYPES = /* @__PURE__ */ new Set(["string", "number", "integer", "boolean", "null"]);
+const ANNOTATION_KEYWORDS = /* @__PURE__ */ new Set([
+  "title",
+  "description",
+  "$comment",
+  "examples",
+  "default",
+  "deprecated",
+  "readOnly",
+  "writeOnly"
+]);
 const coercerNameFor = (ref, typeSuffix) => `coerce${refToName(ref, typeSuffix)}Value`;
 const declaresObjectKeys = (schema) => declaresKey(schema, "properties") || declaresKey(schema, "patternProperties") || declaresKey(schema, "additionalProperties");
 const declaresArrayItems = (schema) => declaresKey(schema, "items") || declaresKey(schema, "prefixItems");
@@ -14,34 +26,121 @@ const soleScalarType = (schema) => {
   const type = readKey(schema, "type");
   return typeof type === "string" && COERCIBLE_TYPES.has(type) ? type : null;
 };
-const unionScalarTypes = (schema) => {
+const typeArrayScalars = (schema) => {
   const declared = readKey(schema, "type");
-  if (Array.isArray(declared)) {
-    const types2 = declared.filter((entry) => typeof entry === "string");
-    return types2.length > 0 && types2.every((type) => COERCIBLE_TYPES.has(type)) ? types2 : null;
-  }
-  if (declared !== void 0)
+  if (!Array.isArray(declared))
     return null;
-  const branches = readKey(schema, "anyOf") ?? readKey(schema, "oneOf");
+  const types = declared.filter((entry) => typeof entry === "string");
+  return types.length > 0 && types.every((type) => COERCIBLE_TYPES.has(type)) ? types : null;
+};
+const bareScalarBranches = (branches) => {
   if (!Array.isArray(branches) || branches.length === 0)
     return null;
   const types = [];
   for (const branch of branches) {
     if (!isSchemaObject(branch))
       return null;
-    const type = soleScalarType(branch);
-    if (type !== null)
-      types.push(type);
-    else if (declaresObjectKeys(branch) || declaresArrayItems(branch))
-      continue;
-    else if (readKey(branch, "type") === "object")
-      continue;
-    else if (readKey(branch, "type") === "array")
-      continue;
-    else
+    const node = branch;
+    const type = soleScalarType(node);
+    if (type === null)
+      return null;
+    if (Object.keys(node).some((key) => key !== "type" && !ANNOTATION_KEYWORDS.has(key)))
       return null;
+    types.push(type);
+  }
+  return types;
+};
+const emitMatcher = (body, ctx) => {
+  const name = `_matches${ctx.next()}`;
+  const parameter = /\binput\b/.test(body) ? "input" : "_input";
+  const path = /\b_path\b/.test(body) ? [`  const _path = ''`] : [];
+  ctx.helpers.push([`const ${name} = (${parameter}: unknown): boolean => {`, ...path, body, `}`].join("\n"));
+  return name;
+};
+const branchTest = (branch, ctx) => {
+  const named = ctx.matcher.named(branch);
+  if (named !== null)
+    return named;
+  const body = ctx.matcher.test(branch);
+  return typeof body === "string" ? emitMatcher(body, ctx) : body;
+};
+const emitBranchCoercer = (schema, keyword, ctx) => {
+  const branches = readKey(schema, keyword);
+  if (!Array.isArray(branches) || branches.length === 0)
+    return null;
+  const tests = [];
+  for (const branch of branches) {
+    const test = branchTest(branch, ctx);
+    if (test === true)
+      return null;
+    tests.push(test);
+  }
+  const live = branches.map((branch, index) => ({ name: tests[index], coerce: coercerFor(branch, ctx) })).filter((entry) => typeof entry.name === "string");
+  if (live.every(({ coerce }) => coerce === null))
+    return null;
+  const names = [];
+  const attempts = [];
+  for (const { name: name2, coerce } of live) {
+    names.push(name2);
+    if (coerce !== null)
+      attempts.push({ coerce, test: name2 });
+  }
+  const id = ctx.next();
+  const name = `_coerceBranches${id}`;
+  const lines = [
+    `const ${name} = (input: unknown): unknown => {`,
+    `  if (${names.map((name2) => `${name2}(input)`).join(" || ")}) return input`
+  ];
+  if (attempts.length === 1) {
+    const [only] = attempts;
+    lines.push(`  const next = ${only.coerce("input")}`, `  return next !== input && ${only.test}(next) ? next : input`);
+  } else {
+    lines.push(`  let out: unknown = input`);
+    attempts.forEach(({ coerce, test }, index) => {
+      const local = `_next${index}`;
+      lines.push(`  const ${local} = ${coerce("input")}`, `  if (${local} !== input && ${test}(${local})) {`, `    if (out === input) out = ${local}`, `    else if (!valuesEqual(out, ${local})) return input`, `  }`);
+    });
+    lines.push(`  return out`);
   }
-  return types.length > 0 ? types : null;
+  lines.push(`}`);
+  ctx.helpers.push(lines.join("\n"));
+  return (valueExpr) => `${name}(${valueExpr})`;
+};
+const emitUnionCoercer = (schema, keyword, ctx) => {
+  const scalars = bareScalarBranches(readKey(schema, keyword));
+  if (scalars !== null)
+    return (valueExpr) => `coerceUnion(${valueExpr}, ${JSON.stringify(scalars)})`;
+  return emitBranchCoercer(schema, keyword, ctx);
+};
+const emitAllOfCoercer = (schema, ctx) => {
+  const subschemas = readKey(schema, "allOf");
+  if (!Array.isArray(subschemas))
+    return null;
+  return compose(subschemas.map((sub) => coercerFor(sub, ctx)));
+};
+const emitConditionalCoercer = (schema, ctx) => {
+  if (!declaresKey(schema, "if"))
+    return null;
+  const thenCoercer = declaresKey(schema, "then") ? coercerFor(readKey(schema, "then"), ctx) : null;
+  const elseCoercer = declaresKey(schema, "else") ? coercerFor(readKey(schema, "else"), ctx) : null;
+  if (thenCoercer === null && elseCoercer === null)
+    return null;
+  const test = branchTest(readKey(schema, "if"), ctx);
+  if (test === true)
+    return thenCoercer;
+  if (test === false)
+    return elseCoercer;
+  const name = `_coerceIf${ctx.next()}`;
+  const whenThen = thenCoercer === null ? "input" : thenCoercer("input");
+  const whenElse = elseCoercer === null ? "input" : elseCoercer("input");
+  ctx.helpers.push(`const ${name} = (input: unknown): unknown => (${test}(input) ? ${whenThen} : ${whenElse})`);
+  return (valueExpr) => `${name}(${valueExpr})`;
+};
+const compose = (stages) => {
+  const present = stages.filter((stage) => stage !== null);
+  if (present.length === 0)
+    return null;
+  return (valueExpr) => present.reduce((expr, stage) => stage(expr), valueExpr);
 };
 const emitObjectCoercer = (schema, ctx) => {
   const properties = schemaMap(schema, "properties") ?? {};
@@ -74,17 +173,20 @@ const emitObjectCoercer = (schema, ctx) => {
     const quoted = JSON.stringify(key);
     const local = `_value${id}_${index}`;
     lines.push(
-      // Own properties only. A plain `obj[key]` walks the prototype chain, and
-      // this pass *writes*: with `Object.prototype.flag` set by any dependency, an
-      // empty object was read as carrying `flag`, coerced, and handed back with
-      // `flag` as its own — inventing data the caller never sent, and satisfying
-      // a `required` the input actually violates. An absent key is not a value to
-      // coerce, and `{ a: undefined }` counts as absent everywhere else in this
-      // package, so it counts as absent here too.
-      `  const ${local} = Object.hasOwn(obj, ${quoted}) ? obj[${quoted}] : undefined`,
+      // Own properties only, where it matters: at the write. A plain `obj[key]`
+      // walks the prototype chain, and this pass *writes* — with
+      // `Object.prototype.flag` set by any dependency, an empty object was read as
+      // carrying `flag`, coerced, and handed back with `flag` as its own,
+      // inventing data the caller never sent and satisfying a `required` the input
+      // actually violates. Coercing an inherited value is harmless (every walk is
+      // pure) as long as the result is never written, so the `Object.hasOwn` is
+      // asked only of a value that moved: on V8 it is the dearest thing in the
+      // walk, and most keys do not move. `{ a: undefined }` counts as absent
+      // everywhere else in this package, so it counts as absent here too.
+      `  const ${local} = obj[${quoted}]`,
       `  if (${local} !== undefined) {`,
       `    const next = ${coerce(local)}`,
-      `    if (next !== ${local}) (out ??= { ...obj })[${quoted}] = next`,
+      `    if (next !== ${local} && Object.hasOwn(obj, ${quoted})) (out ??= { ...obj })[${quoted}] = next`,
       `  }`
     );
   });
@@ -143,17 +245,18 @@ const emitArrayCoercer = (schema, ctx) => {
       return;
     const read = `input[${index}]`;
     lines.push(
-      // `Object.hasOwn` rather than a length test, for the same reason the
-      // properties above use it: a hole reads through `Array.prototype`, and
-      // coercing what it finds there would turn a hole into an own element.
-      `  if (Object.hasOwn(input, ${index})) {`,
+      // `Object.hasOwn` rather than a length test, for the same reason the object
+      // walk uses it, and at the write for the same reason: a hole reads through
+      // `Array.prototype`, and writing what that coerces to would turn a hole into
+      // an own element.
+      `  {`,
       `    const next = ${coerce(read)}`,
-      `    if (next !== ${read}) (out ??= [...input])[${index}] = next`,
+      `    if (next !== ${read} && Object.hasOwn(input, ${index})) (out ??= [...input])[${index}] = next`,
       `  }`
     );
   });
   if (restCoercer !== null) {
-    lines.push(`  for (let i = ${tuple.length}; i < input.length; i++) {`, `    if (!Object.hasOwn(input, i)) continue`, `    const value = input[i]`, `    const next = ${restCoercer("value")}`, `    if (next !== value) (out ??= [...input])[i] = next`, `  }`);
+    lines.push(`  for (let i = ${tuple.length}; i < input.length; i++) {`, `    const value = input[i]`, `    const next = ${restCoercer("value")}`, `    if (next !== value && Object.hasOwn(input, i)) (out ??= [...input])[i] = next`, `  }`);
   }
   lines.push(`  return out ?? input`, `}`);
   ctx.helpers.push(lines.join("\n"));
@@ -164,37 +267,61 @@ const coercerFor = (schema, ctx) => {
     return null;
   const node = schema;
   const ref = readKey(node, "$ref");
-  if (typeof ref === "string") {
-    const name = coercerNameFor(ref, ctx.typeSuffix);
-    return (valueExpr) => `${name}(${valueExpr})`;
-  }
   const scalar = soleScalarType(node);
-  if (scalar !== null)
-    return (valueExpr) => `coerceScalar(${valueExpr}, ${JSON.stringify(scalar)})`;
-  const union = unionScalarTypes(node);
-  if (union !== null)
-    return (valueExpr) => `coerceUnion(${valueExpr}, ${JSON.stringify(union)})`;
+  const typeArray = typeArrayScalars(node);
   const type = readKey(node, "type");
-  if (type === "object" || type === void 0 && declaresObjectKeys(node))
-    return emitObjectCoercer(node, ctx);
-  if (type === "array" || type === void 0 && declaresArrayItems(node))
-    return emitArrayCoercer(node, ctx);
-  return null;
+  return compose([
+    // Whether the target coerces anything is a question about another file, and
+    // following it here would have to chase cycles. The call is cheap and
+    // returns its argument when there is nothing to do.
+    typeof ref === "string" ? (valueExpr) => `${ctx.refCoercer(ref)}(${valueExpr})` : null,
+    scalar !== null ? (valueExpr) => `coerceScalar(${valueExpr}, ${JSON.stringify(scalar)})` : typeArray !== null ? (valueExpr) => `coerceUnion(${valueExpr}, ${JSON.stringify(typeArray)})` : type === "object" || type === void 0 && declaresObjectKeys(node) ? emitObjectCoercer(node, ctx) : type === "array" || type === void 0 && declaresArrayItems(node) ? emitArrayCoercer(node, ctx) : null,
+    emitAllOfCoercer(node, ctx),
+    emitUnionCoercer(node, "anyOf", ctx),
+    emitUnionCoercer(node, "oneOf", ctx),
+    emitConditionalCoercer(node, ctx)
+  ]);
 };
-const generateCoerceFunction = (schema, typeName, typeSuffix = "") => {
+const generateCoerceWalk = (schema, options) => {
   const helpers = [];
   const hoisted = [];
   let counter = 0;
-  const ctx = { typeSuffix, helpers, hoisted, next: () => counter++ };
+  const matcher = createSubschemaMatcher(options.typeSuffix, options.rootSchema ?? (isSchemaObject(schema) ? schema : void 0), options.formats ?? NO_FORMATS, options.hoistNamespace, ...options.refGuard !== void 0 ? [options.refGuard] : []);
+  const ctx = {
+    typeSuffix: options.typeSuffix,
+    helpers,
+    hoisted,
+    next: () => counter++,
+    matcher,
+    refCoercer: options.refCoercer
+  };
   const coerce = coercerFor(schema, ctx);
+  const rootMatch = options.withRootMatch === true ? matcher.test(schema) : null;
+  const reads = helpers.join("\n") + (typeof rootMatch === "string" ? `
+${rootMatch}` : "");
+  return {
+    declarations: [...hoisted, ...matcher.declarations(reads), ...helpers],
+    expression: coerce === null ? null : coerce("input"),
+    rootMatch
+  };
+};
+const generateCoerceFunction = (schema, typeName, typeSuffix = "", options = {}) => {
+  const { declarations, expression } = generateCoerceWalk(schema, {
+    typeSuffix,
+    ...options.rootSchema !== void 0 ? { rootSchema: options.rootSchema } : {},
+    ...options.formats !== void 0 ? { formats: options.formats } : {},
+    refCoercer: (ref) => coercerNameFor(ref, typeSuffix),
+    hoistNamespace: "_coerce"
+  });
   const valueName = `coerce${typeName}Value`;
-  const body = coerce === null ? "input" : coerce("input");
-  const parts = [...hoisted, ...helpers];
+  const body = expression ?? "input";
+  const passes = expression !== null && options.standaloneGuard === true ? `is${typeName}` : null;
   const walk = [
-    ...parts.length > 0 ? [parts.join("\n\n"), ""] : [],
+    ...declarations.length > 0 ? [declarations.join("\n\n"), ""] : [],
     `export const ${valueName} = (input: unknown): unknown => ${body}`,
     "",
     `export const coerce${typeName} = (input: unknown, _path = ''): CoercionResult<${typeName}> => {`,
+    ...passes === null ? [] : [`  if (${passes}(input)) return { valid: true, value: input as ${typeName} }`],
     `  const value = ${valueName}(input)`,
     `  const result = validate${typeName}(value, _path)`,
     `  return result === true ? { valid: true, value: value as ${typeName} } : { valid: false, errors: result.errors }`,
@@ -204,5 +331,6 @@ const generateCoerceFunction = (schema, typeName, typeSuffix = "") => {
 };
 export {
   coercerNameFor,
-  generateCoerceFunction
+  generateCoerceFunction,
+  generateCoerceWalk
 };

package/dist/validators/generators/generate-files.js

@@ -6,7 +6,7 @@ import { formatCheckName } from "./emit-format-checks.js";
 import { NO_FORMATS } from "./enforced-keywords.js";
 import { generateCoerceFunction } from "./generate-coerce-function.js";
 import { generateRepairFunction } from "./generate-repair-function.js";
-import { generateBooleanGuard, generateCheckFunction, generateValidatorFunction } from "./generate-validator-function.js";
+import { generateBooleanGuardSource, generateCheckFunction, generateValidatorFunction } from "./generate-validator-function.js";
 const generateValidatorFile = (schema, typeName, options) => {
   const typeSuffix = options?.typeSuffix ?? "";
   const typeDefinition = generateTypeDefinition(schema, typeName, {
@@ -17,10 +17,14 @@ const generateValidatorFile = (schema, typeName, options) => {
   const importExt = options?.importExt ?? "js";
   const formats = options?.formats ?? NO_FORMATS;
   const validatorFunction = generateValidatorFunction(schema, typeName, typeSuffix, options?.rootSchema, unknownKeys, formats, options?.branchErrors === true);
-  const booleanGuard = generateBooleanGuard(schema, typeName, typeSuffix, unknownKeys, formats);
+  const { code: booleanGuard, standalone: standaloneGuard } = generateBooleanGuardSource(schema, typeName, unknownKeys, formats);
   const checker = options?.check === true ? generateCheckFunction(schema, typeName, typeSuffix, options?.rootSchema, unknownKeys, formats) : "";
   const wantsCoerce = options?.coerce === true || options?.repair === true;
-  const coercer = wantsCoerce ? generateCoerceFunction(schema, typeName, typeSuffix).code : "";
+  const coercer = wantsCoerce ? generateCoerceFunction(schema, typeName, typeSuffix, {
+    ...options?.rootSchema !== void 0 ? { rootSchema: options.rootSchema } : {},
+    formats,
+    standaloneGuard
+  }).code : "";
   const repairer = options?.repair === true ? generateRepairFunction(schema, typeName, typeSuffix).code : "";
   const appended = [checker, coercer, repairer].filter((part) => part !== "");
   const body = validatorFunction + booleanGuard + (appended.length === 0 ? "" : "\n\n" + appended.join("\n\n"));
@@ -30,9 +34,10 @@ const generateValidatorFile = (schema, typeName, options) => {
     rootSchema: options?.rootSchema,
     typeSuffix,
     importExt,
-    reads: ({ typeName: name, validatorName, checkerName, coercerName, repairerName }) => ({
+    reads: ({ typeName: name, validatorName, guardName, checkerName, coercerName, repairerName }) => ({
       type: mentions(name),
       validator: mentions(validatorName),
+      guard: mentions(guardName),
       checker: mentions(checkerName),
       coercer: mentions(coercerName),
       repairer: mentions(repairerName)

package/dist/validators/generators/generate-validator-function.d.ts

@@ -17,6 +17,19 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * {@link UnknownKeysStrategy}.
  */
 export declare const generateBooleanGuard: (schema: JSONSchema, typeName: string, _suffix?: string, unknownKeys?: UnknownKeysStrategy, formats?: ReadonlySet<string>) => string;
+/**
+ * {@link generateBooleanGuard}, together with whether the guard it emitted stands
+ * on its own or falls back to calling `validateX`.
+ *
+ * The coercing half asks: it answers an already-valid document with one guard
+ * call, which is only a saving when the guard is a real fail-fast check. A
+ * fallback runs the whole validator and builds every error on the way to `false`,
+ * so there the coercer walks first instead.
+ */
+export declare const generateBooleanGuardSource: (schema: JSONSchema, typeName: string, unknownKeys?: UnknownKeysStrategy, formats?: ReadonlySet<string>) => {
+    code: string;
+    standalone: boolean;
+};
 /**
  * Generates a TypeScript validator function from a JSON Schema.
  *
@@ -56,3 +69,38 @@ export declare const generateValidatorFunction: (schema: JSONSchema, typeName: s
  * way; only the short circuit is lost.
  */
 export declare const generateCheckFunction: (schema: JSONSchema, typeName: string, suffix?: string, rootSchema?: Record<string, unknown>, unknownKeys?: UnknownKeysStrategy, formats?: ReadonlySet<string>) => string;
+/**
+ * A yes/no matcher for subschemas, for generated code that has to ask "does this
+ * value satisfy that branch?" outside any validator body.
+ *
+ * The coercing half is the caller: a union only knows which branch a value was
+ * meant for by asking each branch, and the answer has to be the one `validateX`
+ * gives, or coercion would steer a value toward a branch the validator then
+ * rejects. So this hands out the very match expression the `anyOf` / `oneOf`
+ * emitters use, rather than a second opinion.
+ *
+ * Every expression built from one matcher shares one hoisted list, so the names
+ * it mints are unique across all of them; `hoistNamespace` keeps those names
+ * apart from the validator's own in the same module. `declarations` returns the
+ * hoisted lines a finished text actually reads, pruned the way
+ * {@link withHoisted} prunes a validator's.
+ */
+export declare const createSubschemaMatcher: (suffix: string, rootSchema: Record<string, unknown> | undefined, formats: ReadonlySet<string>, hoistNamespace: string, refGuard?: (typeName: string) => string) => {
+    /**
+     * The test for `sub` as the body of a function whose parameter is `input` —
+     * statements that `return false` at the first failure and `true` at the end —
+     * or a constant when the answer never depends on the value.
+     *
+     * A body rather than an expression because an expression here is an IIFE, and
+     * JavaScriptCore allocates the closure on every call: roughly 50 ns per branch
+     * tested, which on a union-heavy document was most of what coercing it cost.
+     */
+    test: (sub: JSONSchema) => boolean | string;
+    /**
+     * The same test as a named function, hoisted with the rest and shared with
+     * every other test of the same subschema in this file — or a constant, or
+     * `null` for a body only the buffered form of {@link test} can express.
+     */
+    named: (sub: JSONSchema) => boolean | string | null;
+    declarations: (text: string) => string[];
+};