@amritk/generate-parsers 0.21.0 → 0.22.0

package/README.md

@@ -254,6 +254,73 @@ emitting a parser that quietly accepts what the schema forbids. Coercing
 (non-strict) parsers are documented to repair rather than reject, so they ignore
 the rejecting keywords by design.
 
+### How a coercing parser repairs a boolean
+
+`type: 'boolean'` is repaired from a table of spellings, not from JavaScript
+truthiness. `Boolean("false")` is `true` — as is `Boolean("no")`, `Boolean("0")`
+and `Boolean(2)` — so a truthiness test read every conventional way of writing
+*off* as *on*, which is precisely the input a coercing parser gets from
+environment variables, query strings and hand-written config.
+
+The accepted spellings are matched with surrounding whitespace trimmed and case
+folded, so `FALSE` and ` No ` land with `false` and `no`:
+
+| Input | Result |
+| --- | --- |
+| `true`, `yes`, `y`, `on`, `1`, the number `1` | `true` |
+| `false`, `no`, `n`, `off`, `0`, `""`, the number `0` | `false` |
+| anything else (`2`, `"maybe"`, an object, `null`) | the schema's `default`, else `false` |
+
+The last row is the same rule the other scalars follow: a value that does not
+denote a boolean is not repaired into a guess, it falls back to the default. This
+is wider than Ajv's `coerceTypes`, which takes `"true"` / `"false"`, the numbers
+`1` / `0`, and `null` (as `false`), and rejects the rest — including `"0"`,
+`"1"` and `""`. A coercing parser has no "reject", so its choice is between a
+default and a wrong answer. `null` is the one value both answer for and answer
+differently: Ajv says `false`, a coercing parser says whatever the schema's
+`default` is.
+
+### How a coercing parser repairs a union
+
+A coercing parser's contract is that whatever it returns is a valid instance of
+the schema that produced it, and
+`src/generators/coerced-output-validity.differential.test.ts` fuzzes exactly that
+property against Ajv.
+
+A union is the hard case, because "repair this value" first has to answer "toward
+which branch?". The generated parser answers it in two steps:
+
+1. **Recognition.** Every branch's shape predicate runs first. A value already in
+   a branch's shape takes that branch's parser and comes back unchanged, so valid
+   input costs one predicate call and is never rebuilt.
+2. **Scoring.** A value matching no branch is scored against each branch and
+   repaired toward the best fit. A `const` tag is near-decisive — a matching tag
+   names the branch, a present-but-wrong one rules it out. Below that, a present
+   required property is strong evidence and a present, well-typed declared
+   property is weak evidence. Ties keep the earliest branch, which is `anyOf`'s
+   own order.
+
+Scoring is why `{ name, folder }` is repaired toward the branch that declares
+`folder`, rather than toward whichever branch happens to be written first —
+which would invent a `sidebar` and discard the `folder` the author wrote. Every
+term is decided at build time, so the emitted code is a handful of property
+reads and no schema walking, and none of it runs for input that already matches.
+
+Every union position is dispatched: a definition, a `$ref`, an array's `items`
+(including a recursive one, where a branch's parser calls back into the
+dispatcher), and a union written directly as a property value. Measured over
+4000 mutated documents of the published Scalar configuration schema, **every
+coerced output is a valid instance of its own schema**, and each of the 2514
+documents Ajv rejects is repaired into one Ajv accepts.
+
+Two limits are worth stating. A union carrying its *own* keywords alongside its
+branches (`{ anyOf: […], required: […] }`) keeps the general coercion path,
+because the dispatcher expresses the branches and not the siblings. And a union
+of bare scalars in property position is left to that same path, since scoring
+reads keys: with no object branch there is nothing to discriminate on, every
+branch ties, and the first one wins — which is what the general path already
+does.
+
 ### Conformance, measured
 
 The coverage above is not a claim — it is checked against the corpus every

package/dist/generators/generate-default-from-pattern.d.ts

@@ -1,5 +1,26 @@
 /**
- * Generates a best-guess default value from a regex pattern.
- * Recognizes common patterns and returns appropriate defaults.
+ * Builds a default string for a `pattern`-constrained schema — a value a
+ * coercing parser can fall back to when the input cannot be repaired.
+ *
+ * The one invariant: **a returned default always matches the pattern it was
+ * built from** (and any length bounds handed in alongside it). Every candidate,
+ * synthesized or recognized, is tested against the real `RegExp` before it is
+ * returned, and anything that fails is discarded. That check is the whole point.
+ * Without it this returned a value the schema rejects — `'^\\+?\\d{3}\\d{4}$'`
+ * was answered with `"+1234567890"`, which has three digits too many — so a
+ * coercing parser "repaired" input into a document still invalid against its own
+ * schema, and the array or object built around it was invalid for the same
+ * reason.
+ *
+ * Two sources of candidates, in order:
+ *
+ *  1. {@link synthesize}, which reads the pattern and constructs a matching
+ *     string from it. This covers the ordinary shapes real schemas use — slugs,
+ *     identifiers, fixed-width codes — that no fixed list can anticipate.
+ *  2. A short list of well-known shapes (email, UUID, URL, semver, ISO date),
+ *     which read better than a synthesized `"aaa"` when they happen to fit.
+ *
+ * Returns `null` when nothing verifies, which callers already treat as "no
+ * usable default" — the safe answer, and far better than a confident wrong one.
  */
-export declare const generateDefaultFromPattern: (pattern: string) => string | null;
+export declare const generateDefaultFromPattern: (pattern: string, minLength?: number, maxLength?: number) => string | null;

package/dist/generators/generate-default-from-pattern.js

@@ -1,23 +1,220 @@
-const generateDefaultFromPattern = (pattern) => {
-  if (pattern.includes("@") || pattern.includes("[a-zA-Z0-9]") && pattern.includes("\\.")) {
-    return '"user@example.com"';
+const RECOGNIZED_DEFAULTS = [
+  "user@example.com",
+  "00000000-0000-0000-0000-000000000000",
+  "https://example.com",
+  "1.0.0",
+  "2000-01-01",
+  "+1234567890"
+];
+const UNSUPPORTED = /\(\?[=!<]|\\[1-9]|\\b|\\B/;
+const PREFERRED = "abcdefghijklmnopqrstuvwxyz0123456789";
+const escapedChar = (sequence) => {
+  switch (sequence) {
+    case "d":
+      return "0";
+    case "w":
+      return "a";
+    case "s":
+      return " ";
+    case "D":
+    case "S":
+      return "a";
+    case "W":
+      return "-";
+    case "n":
+      return "\n";
+    case "t":
+      return "	";
+    case "r":
+      return "\r";
+    default:
+      return null;
   }
-  if (pattern.includes("[0-9a-f]") && pattern.includes("{8}") || pattern.includes("\\-")) {
-    if (pattern.match(/[0-9a-f].*\{8\}/i) || pattern.match(/[0-9a-fA-F]{8}/)) {
-      return '"00000000-0000-0000-0000-000000000000"';
+};
+const ONCE = { min: 1, max: 1 };
+const pickFromClass = (body) => {
+  const negated = body.startsWith("^");
+  const source = negated ? body.slice(1) : body;
+  const members = [];
+  for (let i = 0; i < source.length; i++) {
+    const char = source[i];
+    if (char === "\\") {
+      const next = source[++i];
+      if (next === void 0)
+        return null;
+      members.push(escapedChar(next) ?? next);
+      continue;
+    }
+    if (source[i + 1] === "-" && i + 2 < source.length && source[i + 2] !== "]") {
+      const low = char;
+      const high = source[i + 2];
+      const preferred = [...PREFERRED].find((candidate) => candidate >= low && candidate <= high);
+      members.push(preferred ?? low);
+      i += 2;
+      continue;
     }
+    members.push(char);
   }
-  if (pattern.includes("https?") || pattern.includes("http")) {
-    return '"https://example.com"';
+  if (!negated) {
+    return [...PREFERRED].find((candidate) => members.includes(candidate)) ?? members[0] ?? null;
   }
-  if (pattern.match(/\d.*\\\.\.*\d/)) {
-    return '"1.0.0"';
+  return [...PREFERRED].find((candidate) => !members.includes(candidate)) ?? null;
+};
+const readQuantifier = (pattern, start) => {
+  const char = pattern[start];
+  let quantifier = ONCE;
+  let next = start;
+  if (char === "*") {
+    quantifier = { min: 0, max: Number.POSITIVE_INFINITY };
+    next = start + 1;
+  } else if (char === "+") {
+    quantifier = { min: 1, max: Number.POSITIVE_INFINITY };
+    next = start + 1;
+  } else if (char === "?") {
+    quantifier = { min: 0, max: 1 };
+    next = start + 1;
+  } else if (char === "{") {
+    const close = pattern.indexOf("}", start);
+    const body = close === -1 ? null : pattern.slice(start + 1, close);
+    const match = body === null ? null : /^(\d+)(,(\d*)?)?$/.exec(body);
+    if (match && close !== -1) {
+      const min = Number(match[1]);
+      const max = match[2] === void 0 ? min : match[3] ? Number(match[3]) : Number.POSITIVE_INFINITY;
+      quantifier = { min, max };
+      next = close + 1;
+    }
   }
-  if (pattern.includes("\\d{4}") && pattern.includes("\\d{2}")) {
-    return '"2000-01-01"';
+  if (quantifier !== ONCE && (pattern[next] === "?" || pattern[next] === "+"))
+    next += 1;
+  return { quantifier, next };
+};
+const parseAlternatives = (pattern, start, stop) => {
+  const alternatives = [];
+  let current = [];
+  let i = start;
+  while (i < stop) {
+    const char = pattern[i];
+    if (char === ")")
+      break;
+    if (char === "|") {
+      alternatives.push(current);
+      current = [];
+      i += 1;
+      continue;
+    }
+    let node = null;
+    if (char === "(") {
+      let bodyStart = i + 1;
+      if (pattern.startsWith("(?:", i))
+        bodyStart = i + 3;
+      else if (pattern.startsWith("(?<", i)) {
+        const close = pattern.indexOf(">", i);
+        if (close === -1)
+          return { alternatives: [], next: stop };
+        bodyStart = close + 1;
+      }
+      const inner = parseAlternatives(pattern, bodyStart, stop);
+      if (pattern[inner.next] !== ")")
+        return { alternatives: [], next: stop };
+      const { quantifier, next } = readQuantifier(pattern, inner.next + 1);
+      node = { kind: "group", alternatives: inner.alternatives, quantifier };
+      i = next;
+    } else if (char === "[") {
+      let end = i + 1;
+      if (pattern[end] === "^")
+        end += 1;
+      if (pattern[end] === "]")
+        end += 1;
+      while (end < stop && pattern[end] !== "]")
+        end += pattern[end] === "\\" ? 2 : 1;
+      if (end >= stop)
+        return { alternatives: [], next: stop };
+      const picked = pickFromClass(pattern.slice(i + 1, end));
+      if (picked === null)
+        return { alternatives: [], next: stop };
+      const { quantifier, next } = readQuantifier(pattern, end + 1);
+      node = { kind: "class", value: picked, quantifier };
+      i = next;
+    } else if (char === "\\") {
+      const sequence = pattern[i + 1];
+      if (sequence === void 0)
+        return { alternatives: [], next: stop };
+      const { quantifier, next } = readQuantifier(pattern, i + 2);
+      node = { kind: "literal", value: escapedChar(sequence) ?? sequence, quantifier };
+      i = next;
+    } else if (char === ".") {
+      const { quantifier, next } = readQuantifier(pattern, i + 1);
+      node = { kind: "class", value: "a", quantifier };
+      i = next;
+    } else if (char === "^" || char === "$") {
+      i += 1;
+      continue;
+    } else {
+      const { quantifier, next } = readQuantifier(pattern, i + 1);
+      node = { kind: "literal", value: char, quantifier };
+      i = next;
+    }
+    current.push(node);
+  }
+  alternatives.push(current);
+  return { alternatives, next: i };
+};
+const render = (nodes, budget) => {
+  let out = "";
+  for (const node of nodes) {
+    const { min, max } = node.quantifier;
+    const count = Math.min(min + (max > min ? budget : 0), max);
+    const unit = node.kind === "group" ? render(node.alternatives[0] ?? [], budget) : node.value;
+    out += unit.repeat(count);
+  }
+  return out;
+};
+const synthesize = (pattern) => {
+  if (UNSUPPORTED.test(pattern))
+    return [];
+  const { alternatives } = parseAlternatives(pattern, 0, pattern.length);
+  const candidates = [];
+  for (const alternative of alternatives) {
+    for (let budget = 0; budget <= 64; budget++) {
+      const rendered = render(alternative, budget);
+      candidates.push(rendered);
+      if (rendered.length > 512)
+        break;
+    }
+  }
+  return candidates;
+};
+const compile = (pattern) => {
+  try {
+    return new RegExp(pattern, "u");
+  } catch {
+    try {
+      return new RegExp(pattern);
+    } catch {
+      return null;
+    }
+  }
+};
+const generateDefaultFromPattern = (pattern, minLength, maxLength) => {
+  if (pattern === "")
+    return null;
+  const regex = compile(pattern);
+  if (regex === null)
+    return null;
+  const low = typeof minLength === "number" && minLength > 0 ? minLength : 0;
+  const high = typeof maxLength === "number" && maxLength >= 0 ? maxLength : Number.POSITIVE_INFINITY;
+  const fits = (candidate) => {
+    if (candidate.length < low || candidate.length > high)
+      return false;
+    return regex.test(candidate);
+  };
+  for (const candidate of RECOGNIZED_DEFAULTS) {
+    if (fits(candidate))
+      return JSON.stringify(candidate);
   }
-  if (pattern.includes("\\d{3}") && (pattern.includes("\\d{4}") || pattern.includes("\\d{7}"))) {
-    return '"+1234567890"';
+  for (const candidate of synthesize(pattern)) {
+    if (fits(candidate))
+      return JSON.stringify(candidate);
   }
   return null;
 };

package/dist/generators/generate-parser-function.js

@@ -1,8 +1,9 @@
 import { regexLiteral } from "@amritk/helpers/escape-regex-pattern";
+import { generateTypeDefinition } from "@amritk/helpers/generate-type-definition";
 import { quoteJsString } from "@amritk/helpers/quote-js-string";
 import { refToName } from "@amritk/helpers/ref-to-name";
 import { resolveRef } from "@amritk/helpers/resolve-ref";
-import { missingCheck, safeAccessor, safeKey } from "@amritk/helpers/safe-accessor";
+import { hasOwnCheck, missingCheck, safeAccessor, safeKey } from "@amritk/helpers/safe-accessor";
 import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasEnum, hasItems, hasMaxItems, hasMaxProperties, hasMinItems, hasMinProperties, hasOneOf, hasProperties, hasRef, hasRequired, hasType, hasUniqueItems, isObjectSchema, isSchemaObject } from "@amritk/helpers/schema-guards";
 import { unknownKeyCheck } from "@amritk/helpers/unknown-key-check";
 import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
@@ -12,7 +13,7 @@ import { getDiscriminatorValue } from "../helpers/get-discriminator-value.js";
 import { assertNoUnsupportedKeywords } from "./assert-supported-keywords.js";
 import { generateEnumCaseInsensitiveCoercion } from "./generate-enum-check.js";
 import { generateBackstopAssertion, generateCompositionChecks, generateContainsCheck, generateKeyedValueChecks, generateObjectKeywordChecks, generateObjectSizeChecks, generateObjectStrictAssertion, generateScalarStrictAssertion, inlineAllOfMembers } from "./generate-strict-assertion.js";
-import { canEnforceUnion, generatePropertyTypeCheck, generateUnionCheck, getUnionBranches, hasFastPathBlockingKeyword, isExclusiveUnion, isInlineObjectArrayProperty, isInlineObjectProperty, shapeValidatorName } from "./generate-type-checks.js";
+import { canEnforceUnion, generatePropertyTypeCheck, generateUnionCheck, getUnionBranches, hasFastPathBlockingKeyword, isExclusiveUnion, isInlineObjectArrayProperty, isInlineObjectProperty, isInlineUnionProperty, isUnionArrayProperty, shapeValidatorName } from "./generate-type-checks.js";
 import { generateUniqueItemsCheck } from "./generate-unique-items-check.js";
 import { generatePrefixItemsMap, generateValidationExpression, getPrefixItems, isCoercibleItemSchema, prefixItemsCapsLength } from "./generate-validation-expression.js";
 const generateParserName = (typeName) => {
@@ -209,6 +210,24 @@ const generateFallbackObject = (schema, useRefImports, typeName, suffix, subType
   result += "\n      }";
   return declaresPrototypeMemberProperty(schema) ? `${result} as unknown as ${typeName}` : result;
 };
+const SCALAR_ROOT_CONSTRAINTS = [
+  "pattern",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf"
+];
+const isConstrainedScalarRoot = (schema) => {
+  if (!isSchemaObject(schema) || !hasType(schema))
+    return false;
+  if (schema.type !== "string" && schema.type !== "number" && schema.type !== "integer")
+    return false;
+  const record = schema;
+  return SCALAR_ROOT_CONSTRAINTS.some((keyword) => keyword in record);
+};
 const scalarDefaultLiteral = (schema) => {
   const value = getDefaultValue(schema);
   return value === "undefined" ? "{}" : value;
@@ -252,6 +271,149 @@ ${prelude}  const _disc = ${discExpr};
   return ${expr};
 };`;
 };
+const SCORE_TAG_MATCH = 100;
+const SCORE_TAG_MISMATCH = -100;
+const SCORE_REQUIRED_PRESENT = 4;
+const SCORE_REQUIRED_MISSING = -4;
+const SCORE_DECLARED_PRESENT = 1;
+const SCORE_DECLARED_WELL_TYPED = 2;
+const resolveForScoring = (schema, rootSchema) => {
+  if (!isSchemaObject(schema) || !hasRef(schema) || rootSchema === void 0)
+    return schema;
+  const target = resolveRef(schema.$ref, rootSchema);
+  return target !== void 0 && isSchemaObject(target) ? target : schema;
+};
+const tagValueOf = (schema) => {
+  if (!isSchemaObject(schema))
+    return void 0;
+  if (hasConst(schema))
+    return schema.const;
+  if (hasEnum(schema) && schema.enum.length === 1)
+    return schema.enum[0];
+  return void 0;
+};
+const branchScoreExpression = (branch, ctx) => {
+  const resolved = resolveForScoring(branch, ctx.rootSchema);
+  if (!isSchemaObject(resolved) || !hasProperties(resolved))
+    return "0";
+  const properties = resolved.properties;
+  const required = new Set(hasRequired(resolved) ? resolved.required : []);
+  const terms = [];
+  for (const key of Object.keys(properties)) {
+    const propertySchema = resolveForScoring(properties[key], ctx.rootSchema);
+    const accessor = safeAccessor("input", key);
+    const present = hasOwnCheck("input", key);
+    const tag = tagValueOf(propertySchema);
+    if (tag !== void 0) {
+      terms.push(`(${accessor} === ${JSON.stringify(tag)} ? ${SCORE_TAG_MATCH} : ${present} ? ${SCORE_TAG_MISMATCH} : 0)`);
+      continue;
+    }
+    if (required.has(key)) {
+      terms.push(`(${present} ? ${SCORE_REQUIRED_PRESENT} : ${SCORE_REQUIRED_MISSING})`);
+    } else {
+      terms.push(`(${present} ? ${SCORE_DECLARED_PRESENT} : 0)`);
+    }
+    const typeCheck = generatePropertyTypeCheck(accessor, properties[key], ctx.useRefImports, ctx.suffix);
+    if (typeCheck !== null)
+      terms.push(`(${typeCheck} ? ${SCORE_DECLARED_WELL_TYPED} : 0)`);
+  }
+  return terms.length === 0 ? "0" : terms.join(" + ");
+};
+const generateScoredUnionParser = (functionName, typeName, branches, ctx, exported = true) => {
+  if (branches.length < 2)
+    return null;
+  const preamble = [];
+  const dispatch = [];
+  const reserved = new Set(ctx.reservedNames ?? []);
+  const needsUnnarrowedAlias = branches.some((branch) => isSchemaObject(branch) && !(hasRef(branch) && ctx.useRefImports) && !(isObjectSchema(branch) && hasProperties(branch)));
+  const valueRef = needsUnnarrowedAlias ? "_u" : "input";
+  for (const [index, branch] of branches.entries()) {
+    if (!isSchemaObject(branch))
+      return null;
+    if (hasRef(branch) && ctx.useRefImports) {
+      const refName = refToName(branch.$ref, ctx.suffix);
+      if (refName === typeName)
+        return null;
+      dispatch.push({
+        predicate: `${shapeValidatorName(refName)}(input)`,
+        result: `${generateParserName(refName)}(${valueRef}) as ${typeName}`
+      });
+      continue;
+    }
+    if (hasRef(branch))
+      return null;
+    if (hasOneOf(branch) || hasAnyOf(branch) || hasAllOf(branch) || "not" in branch)
+      return null;
+    if ("if" in branch || "then" in branch || "else" in branch || "patternProperties" in branch)
+      return null;
+    if (!isObjectSchema(branch) || !hasProperties(branch)) {
+      const predicate = generatePropertyTypeCheck("input", branch, ctx.useRefImports, ctx.suffix);
+      if (predicate === null)
+        return null;
+      const coerced = generateValidationExpression("", branch, scalarDefaultLiteral(branch), true, ctx.rootSchema, void 0, valueRef, false, ctx.caseInsensitive);
+      dispatch.push({ predicate, result: `(${coerced}) as ${typeName}` });
+      continue;
+    }
+    let subName = `${typeName}_B${index}`;
+    while (reserved.has(subName))
+      subName = `${subName}_`;
+    reserved.add(subName);
+    const shapeValidator = generateShapeValidator(branch, subName, ctx.useRefImports, ctx.suffix, false, ctx.stripUnknown ?? false, reserved, ctx.unknownKeys ?? DEFAULT_UNKNOWN_KEYS);
+    if (shapeValidator.includes("(_input: unknown): boolean => false"))
+      return null;
+    preamble.push(generateTypeDefinition(branch, subName, {
+      ...ctx.suffix ? { typeSuffix: ctx.suffix } : {},
+      ...ctx.rootSchema ? { rootSchema: ctx.rootSchema } : {}
+    }).replace(/^export /, ""));
+    preamble.push(shapeValidator);
+    preamble.push(generateObjectParser(
+      branch,
+      subName,
+      ctx.useRefImports,
+      ctx.suffix,
+      ctx.logWarnings,
+      // Always the coercing parser: this whole path exists to repair.
+      false,
+      false,
+      ctx.stripUnknown ?? false,
+      ctx.rootSchema,
+      reserved,
+      ctx.caseInsensitive ?? false,
+      shapeValidator,
+      ctx.unknownKeys ?? DEFAULT_UNKNOWN_KEYS
+    ));
+    dispatch.push({
+      predicate: `${shapeValidatorName(subName)}(input)`,
+      result: `${generateParserName(subName)}(${valueRef}) as ${typeName}`
+    });
+  }
+  const first = dispatch[0];
+  if (first === void 0)
+    return null;
+  const lines = [];
+  if (needsUnnarrowedAlias)
+    lines.push("  const _u: unknown = input;");
+  for (const { predicate, result } of dispatch) {
+    lines.push(`  if (${predicate}) return ${result};`);
+  }
+  lines.push(`  if (!isObject(input)) return ${first.result};`);
+  const scores = branches.map((branch, index) => `  const _s${index} = ${branchScoreExpression(branch, ctx)};`);
+  lines.push(...scores);
+  const last = dispatch[dispatch.length - 1];
+  let best = `${last?.result}`;
+  for (let index = dispatch.length - 2; index >= 0; index--) {
+    const atLeastAsGood = dispatch.slice(index + 1).map((_, offset) => `_s${index} >= _s${index + 1 + offset}`).join(" && ");
+    best = `${atLeastAsGood} ? ${dispatch[index]?.result} : ${best}`;
+  }
+  lines.push(`  return ${best};`);
+  const head = preamble.length > 0 ? `${preamble.join("\n\n")}
+
+` : "";
+  const exportPrefix = exported ? "export " : "";
+  return `${head}${exportPrefix}const ${functionName} = (input: unknown): ${typeName} => {
+${lines.join("\n")}
+};`;
+};
 const strictContext = (ctx) => ({
   useRefImports: ctx?.useRefImports ?? false,
   suffix: ctx?.suffix ?? "",
@@ -314,6 +476,9 @@ ${assertions}
     }
     if (hasOneOf(schema) || hasAnyOf(schema)) {
       const branches = hasOneOf(schema) ? schema.oneOf : hasAnyOf(schema) ? schema.anyOf : [];
+      const scored = unionCtx ? generateScoredUnionParser(functionName, typeName, branches, unionCtx) : null;
+      if (scored !== null)
+        return scored;
       const hasRefBranch = branches.some((b) => isSchemaObject(b) && hasRef(b));
       if (branches.length > 0 && !hasRefBranch) {
         const fallback = scalarDefaultLiteral(branches[0]);
@@ -415,6 +580,10 @@ ${assertion}
   return ${returnExpr};
 };`;
   }
+  if (isConstrainedScalarRoot(schema)) {
+    const expr = generateValidationExpression("", schema, getDefaultValue(schema), true, unionCtx?.rootSchema, void 0, "input", true, unionCtx?.caseInsensitive);
+    return `export const ${functionName} = (input: unknown): ${typeName} => (${expr}) as ${typeName};`;
+  }
   switch (schema.type) {
     case "string":
       return `export const ${functionName} = (input: unknown): ${typeName} => typeof input === "string" ? input as ${typeName} : "" as ${typeName};`;
@@ -519,7 +688,7 @@ const collectInlineSubTypes = (schema, typeName, reservedNames = NO_RESERVED_NAM
     if (isInlineObjectProperty(propSchema)) {
       objects ??= /* @__PURE__ */ new Map();
       objects.set(key, claim(`${typeName}_${pascalCaseKey(key) || "Value"}`));
-    } else if (isInlineObjectArrayProperty(propSchema)) {
+    } else if (isInlineObjectArrayProperty(propSchema) || isUnionArrayProperty(propSchema)) {
       arrayItems ??= /* @__PURE__ */ new Map();
       arrayItems.set(key, claim(`${typeName}_${pascalCaseKey(key) || "Value"}Item`));
     }
@@ -691,7 +860,51 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
   for (let i = 0; i < arr.length; i++) if (!${shapeValidatorName(subName)}(arr[i])) return false;
   return true;
 };`);
-    preamble.push(generateObjectParser(itemSchema, subName, useRefImports, suffix, logWarnings, strict, false, stripUnknown, rootSchema, reservedNames, caseInsensitive, itemShapeValidator, unknownKeys));
+    const unionBranches = strict ? null : getUnionBranches(itemSchema);
+    const scoredItemParser = unionBranches === null ? null : generateScoredUnionParser(generateParserName(subName), subName, unionBranches, {
+      useRefImports,
+      suffix,
+      ...rootSchema !== void 0 ? { rootSchema } : {},
+      ...logWarnings !== void 0 ? { logWarnings } : {},
+      reservedNames,
+      stripUnknown,
+      unknownKeys,
+      caseInsensitive
+    }, false);
+    preamble.push(scoredItemParser ?? generateObjectParser(itemSchema, subName, useRefImports, suffix, logWarnings, strict, false, stripUnknown, rootSchema, reservedNames, caseInsensitive, itemShapeValidator, unknownKeys));
+  }
+  const unionSubNames = /* @__PURE__ */ new Map();
+  if (!strict) {
+    const claimedUnionNames = /* @__PURE__ */ new Set([...reservedNames, ...subTypeNames.values(), ...subItemNames.values()]);
+    for (const key of Object.keys(schemaProps)) {
+      if (subTypeNames.has(key) || subItemNames.has(key))
+        continue;
+      const propSchema = schemaProps[key];
+      if (!isInlineUnionProperty(propSchema))
+        continue;
+      const branches = getUnionBranches(propSchema);
+      if (branches === null)
+        continue;
+      let unionSubName = `${typeName}_${pascalCaseKey(key) || "Value"}Union`;
+      while (claimedUnionNames.has(unionSubName))
+        unionSubName = `${unionSubName}_`;
+      claimedUnionNames.add(unionSubName);
+      const unionParser = generateScoredUnionParser(generateParserName(unionSubName), unionSubName, branches, {
+        useRefImports,
+        suffix,
+        ...rootSchema !== void 0 ? { rootSchema } : {},
+        ...logWarnings !== void 0 ? { logWarnings } : {},
+        reservedNames: claimedUnionNames,
+        stripUnknown,
+        unknownKeys,
+        caseInsensitive
+      }, false);
+      if (unionParser === null)
+        continue;
+      preamble.push(`type ${unionSubName} = NonNullable<${typeName}>[${JSON.stringify(key)}];`);
+      preamble.push(unionParser);
+      unionSubNames.set(key, unionSubName);
+    }
   }
   const strictKeys = hasStrictKeys(schema);
   const stripKeys = strictKeys || stripUnknown;
@@ -860,6 +1073,16 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
     for (const { key, varName, isRequired, propSchema } of propInfo) {
       const shouldCache = shouldCacheVariable(propSchema);
       const accessor = shouldCache ? varName : safeAccessor("input", key);
+      const unionSubName = unionSubNames.get(key);
+      if (unionSubName) {
+        const unionParserName = generateParserName(unionSubName);
+        if (isRequired) {
+          entries.push({ kind: "field", key, value: `${unionParserName}(${accessor})` });
+        } else {
+          entries.push({ kind: "optional", key, read: accessor, value: `${unionParserName}(${accessor})` });
+        }
+        continue;
+      }
       const subName = subTypeNames.get(key);
       if (subName) {
         const subParserName = generateParserName(subName);
@@ -1621,6 +1844,11 @@ const generateShapeValidator = (schema, typeName, useRefImports, suffix = "", ex
       if (check !== null) {
         return `${exportPrefix}const ${fnName} = (input: unknown): boolean => ${check};`;
       }
+      return stub;
+    }
+    const direct = generatePropertyTypeCheck("input", schema, useRefImports, suffix);
+    if (direct !== null) {
+      return `${exportPrefix}const ${fnName} = (input: unknown): boolean => ${direct};`;
     }
     return stub;
   }

package/dist/generators/generate-strict-assertion.js

@@ -221,9 +221,15 @@ const generateItemCheck = (schema, context) => {
   if (hasRef(items) && context.useRefImports === true || shapeIsDelegated(items, context))
     return null;
   const match = subschemaMatchExpr("_it", items, matchContext(context));
-  if (match === null || match === "true")
+  if (match !== null)
+    return match === "true" ? null : { check: match, message: "items do not match the item schema" };
+  const branches = getUnionBranches(items);
+  if (branches === null || context.stripUnknown === true)
+    return null;
+  if (!canEnforceUnion(branches, context.rootSchema))
     return null;
-  return { check: match, message: "items do not match the item schema" };
+  const union = generateUnionCheck("_it", branches, context.useRefImports ?? false, context.suffix ?? "", isExclusiveUnion(items));
+  return union === null ? null : { check: union, message: "items do not match the item schema" };
 };
 const nullableObjectShapeChecks = (acc, schema, type, label, optional, context) => {
   if (type !== "object")

package/dist/generators/generate-type-checks.d.ts

@@ -35,6 +35,27 @@ export declare const isInlineObjectProperty: (propSchema: JSONSchema) => propSch
  * `Array.isArray` check.
  */
 export declare const isInlineObjectArrayProperty: (propSchema: JSONSchema) => boolean;
+/**
+ * Matches an array property whose `items` is a *union* of object branches — the
+ * shape a coercing parser needs a private item sub-parser for, so an element can
+ * be dispatched to (and repaired toward) a branch rather than passed through.
+ * {@link isInlineObjectArrayProperty} deliberately does not cover this: a union
+ * is not one inline object, and the trust walk reads that predicate to decide
+ * what a shape validator proves.
+ */
+export declare const isUnionArrayProperty: (propSchema: JSONSchema) => boolean;
+/**
+ * Matches a union written directly as a property value — `logo: { anyOf: [...] }`
+ * rather than a `$ref`, a definition, or an array's `items`. This is the one
+ * union position the coercing dispatcher did not reach, so a value matching no
+ * branch was passed through unrepaired.
+ *
+ * The union's *own* keywords are the reason for the exclusions: 2020-12 applies
+ * them alongside the branches, and a dispatcher expresses none of them, so a
+ * constrained union keeps the general path rather than getting a parser that
+ * quietly drops the constraint.
+ */
+export declare const isInlineUnionProperty: (propSchema: JSONSchema) => boolean;
 /**
  * Extracts the branch list of a `oneOf`/`anyOf` union, or `null` when the
  * schema is not a union (or mixes in other composition keywords we cannot

package/dist/generators/generate-type-checks.js

@@ -36,6 +36,37 @@ const isInlineObjectArrayProperty = (propSchema) => {
     return false;
   return isInlineObjectProperty(propSchema.items);
 };
+const isUnionArrayProperty = (propSchema) => {
+  if (!isSchemaObject(propSchema))
+    return false;
+  if (!("type" in propSchema) || propSchema.type !== "array")
+    return false;
+  if (!hasItems(propSchema) || Array.isArray(propSchema.items))
+    return false;
+  const items = propSchema.items;
+  if (!isSchemaObject(items))
+    return false;
+  const branches = getUnionBranches(items);
+  if (branches === null || branches.length < 2)
+    return false;
+  return branches.every((branch) => isSchemaObject(branch) && (hasRef(branch) || isInlineObjectProperty(branch)));
+};
+const isInlineUnionProperty = (propSchema) => {
+  if (!isSchemaObject(propSchema))
+    return false;
+  if (hasRef(propSchema) || hasAllOf(propSchema) || "not" in propSchema)
+    return false;
+  if ("if" in propSchema || "then" in propSchema || "else" in propSchema)
+    return false;
+  if ("patternProperties" in propSchema)
+    return false;
+  const branches = getUnionBranches(propSchema);
+  if (branches === null || branches.length < 2)
+    return false;
+  if (hasBranchSiblingConstraint(propSchema))
+    return false;
+  return branches.every((branch) => isSchemaObject(branch) && (hasRef(branch) || isInlineObjectProperty(branch)));
+};
 const getUnionBranches = (schema) => {
   if (!isSchemaObject(schema))
     return null;
@@ -385,8 +416,11 @@ const canTrustReferencedValidator = (ref, rootSchema, visiting) => {
     }
     if (!hasProperties(resolved)) {
       const branches = getUnionBranches(resolved);
-      if (!branches)
-        return false;
+      if (!branches) {
+        if ("patternProperties" in resolved || "if" in resolved)
+          return false;
+        return canTrustPropertyCheck(resolved, rootSchema, visiting);
+      }
       if ("patternProperties" in resolved || "if" in resolved)
         return false;
       return branches.every((branch) => {
@@ -413,6 +447,8 @@ export {
   isExclusiveUnion,
   isInlineObjectArrayProperty,
   isInlineObjectProperty,
+  isInlineUnionProperty,
+  isUnionArrayProperty,
   multiTypeCheck,
   shapeValidatorName
 };

package/dist/generators/generate-validation-expression.js

@@ -141,6 +141,15 @@ const numberBoundChecks = (valueExpr, schema) => {
     checks.push(multipleOfPassExpr(valueExpr, schema.multipleOf));
   return checks;
 };
+const BOOLEAN_TRUE_TOKENS = ["true", "yes", "y", "on", "1"];
+const BOOLEAN_FALSE_TOKENS = ["false", "no", "n", "off", "0", ""];
+const getBooleanCoercion = (accessor, defaultValue) => {
+  const side = (tokens, literals) => [...tokens.map((token) => `"${token}"`), ...literals].map((term) => `_b === ${term}`).join(" || ");
+  const normalized = `typeof ${accessor} === "string" ? ${accessor}.trim().toLowerCase() : ${accessor}`;
+  const truthy = side(BOOLEAN_TRUE_TOKENS, ["1", "true"]);
+  const falsy = side(BOOLEAN_FALSE_TOKENS, ["0", "false"]);
+  return `((_b) => ${truthy} ? true : ${falsy} ? false : ${defaultValue})(${normalized})`;
+};
 const getTypeCoercion = (accessor, schema, defaultValue) => {
   if (!hasType(schema)) {
     return null;
@@ -163,7 +172,7 @@ const getTypeCoercion = (accessor, schema, defaultValue) => {
       return `((_n) => ${[`${wellFormed}(_n)`, ...bounds].join(" && ")} ? _n : ${defaultValue})(${n})`;
     }
     case "boolean":
-      return `Boolean(${accessor})`;
+      return getBooleanCoercion(accessor, defaultValue);
     case "array":
       return defaultValue;
     case "object":

package/dist/helpers/get-default-value.js

@@ -46,8 +46,9 @@ const arrayFallback = (schema) => {
 };
 const MAX_FALLBACK_LENGTH = 256;
 const stringFallback = (schema) => {
+  const bounds = schema;
   if (hasPattern(schema)) {
-    const patternDefault = generateDefaultFromPattern(schema.pattern);
+    const patternDefault = generateDefaultFromPattern(schema.pattern, typeof bounds["minLength"] === "number" ? bounds["minLength"] : void 0, typeof bounds["maxLength"] === "number" ? bounds["maxLength"] : void 0);
     if (patternDefault)
       return patternDefault;
     return '""';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-parsers",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -60,7 +60,7 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "^0.19.0"
+    "@amritk/helpers": "^0.20.0"
   },
   "devDependencies": {
     "@amritk/generate-markdown": "^0.6.0",