@amritk/generate-parsers 0.17.1 → 0.18.0

package/README.md

@@ -5,7 +5,7 @@
 **Programmatic API for generating TypeScript parsers and type definitions from JSON Schemas.**
 
 ![status](https://img.shields.io/badge/status-pre--alpha-ef4444?style=flat-square) 
-![version](https://img.shields.io/badge/version-v0.1.0-6366f1?style=flat-square&logo=npm&logoColor=white) 
+![version](https://img.shields.io/npm/v/@amritk/generate-parsers?style=flat-square&logo=npm&logoColor=white&label=version&color=6366f1) 
 ![license](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square) 
 ![JSON Schema](https://img.shields.io/badge/JSON%20Schema-2020--12-f97316?style=flat-square) 
 ![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white) 
@@ -75,19 +75,33 @@ Write them to disk however you like.
 
 ## API
 
-### `buildSchema(rootSchema, rootTypeName, extensions?, typesOnly?, logWarnings?, strict?)`
-
-| Parameter | Type | Description |
-|:---|:---|:---|
-| `rootSchema` | `JSONSchema` | The root schema to traverse. `$ref` and `$dynamicRef` are resolved recursively. |
-| `rootTypeName` | `string` | Name used for the root type (e.g. `"Document"`). |
-| `extensions` | `SchemaExtensions` _(optional)_ | Map of definition name → extra optional properties to merge in before generation. |
-| `typesOnly` | `boolean` _(optional)_ | When `true`, only emit `.ts` type definitions — skip parser functions and runtime helpers. |
-| `logWarnings` | `boolean` _(optional)_ | When `true`, generated parsers emit a `console.warn` for every input key not declared in the schema's properties. |
-| `strict` | `boolean` _(optional)_ | When `true`, generated parsers throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. |
+### `buildSchema(rootSchema, rootTypeName, …options)`
+
+Every option after the first two is **positional** — pass them in this order:
+
+| # | Parameter | Type | Default | Description |
+|--:|:---|:---|:---|:---|
+| 1 | `rootSchema` | `JSONSchema` | — | The root schema to traverse. `$ref` and `$dynamicRef` are resolved recursively. |
+| 2 | `rootTypeName` | `string` | — | Name used for the root type (e.g. `"Document"`). |
+| 3 | `extensions` | `SchemaExtensions` | — | Map of definition name → extra optional properties to merge in before generation. |
+| 4 | `typesOnly` | `boolean` | — | Only emit `.ts` type definitions — skip parser functions and runtime helpers. |
+| 5 | `logWarnings` | `boolean` | — | Generated parsers emit a `console.warn` for every input key not declared in the schema's properties. |
+| 6 | `strict` | `boolean` | — | Generated parsers throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. |
+| 7 | `helpersMode` | `'package' \| 'embedded'` | `'package'` | `'package'` imports runtime helpers from `@amritk/helpers`; `'embedded'` emits them alongside the output so it is self-contained. |
+| 8 | `helpersImportPrefix` | `string` | `'./'` | Prefix the generated files use when importing embedded helpers. |
+| 9 | `readonly` | `boolean` | `false` | Emit every property, array, and record in the type definitions as `readonly`. |
+| 10 | `stripUnknown` | `boolean` | `false` | Build each result from the declared properties only, dropping undeclared input keys at every level (zod's `.strip()`). |
+| 11 | `typeSuffix` | `string` | `''` | Suffix appended to every `$ref`-derived type name (`'Object'` turns `Contact` into `ContactObject`). The root type name is unaffected. |
+| 12 | `importExt` | `'js' \| 'ts'` | `'js'` | Extension emitted on relative import specifiers. `'js'` is the NodeNext form for output you compile; `'ts'` emits the literal on-disk paths so the sources run unbuilt. |
+| 13 | `caseInsensitive` | `boolean` | `false` | Normalize a mis-cased string to the exact casing of an enum/const member it matches case-insensitively. Coerce mode only. |
 
 Returns: `Promise<GeneratedFile[]>`.
 
+> [!NOTE]
+> `importExt` defaults to `'js'` here, whereas the [`mjst` CLI](../cli) defaults it to
+> `'ts'`. The example above therefore emits `./info.js` specifiers; pass `'ts'` for
+> output meant to run without a build step.
+
 ---
 
 ## Options
@@ -151,7 +165,9 @@ The generator handles:
 - `$ref` and `$dynamicRef` resolution, including JSON Schema 2020-12 `$dynamicAnchor`
 - Discriminated and non-discriminated unions (`oneOf` / `anyOf`)
 - Enums and `const` values
-- Nested objects, arrays, records, and tuples
+- Nested objects, arrays, records, and tuples (`prefixItems`, and the draft-07 array form of `items`)
+- Multi-type schemas (`type: ["string", "null"]`) and the OpenAPI 3.0 `nullable: true` spelling
+- Composition alongside a declared shape — `allOf` members and sibling unions are intersected into the type, not dropped
 - Pattern-based default values
 
 ---

package/dist/generators/build-schema.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, resolve as resolvePath } from "node:path";
+import { foldNullable } from "@amritk/helpers/fold-nullable";
 import { generateIndexBarrel } from "@amritk/helpers/generate-index-barrel";
 import { walkRefGraph } from "@amritk/helpers/walk-ref-graph";
 import { applySchemaExtensions } from "../helpers/apply-schema-extensions.js";
@@ -22,11 +23,13 @@ const readHelperSource = async (helper, importExt) => {
 const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = "package", helpersImportPrefix = "./", readonly = false, stripUnknown = false, typeSuffix = "", importExt = "js", caseInsensitive = false) => {
   const files = [];
   const usedHelpers = /* @__PURE__ */ new Set();
-  walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
+  const foldedSchema = foldNullable(rootSchema);
+  walkRefGraph(foldedSchema, rootTypeName, { typeSuffix }, (node) => {
     if (node.filename === "index")
       return;
     const extended = extensions ? applySchemaExtensions(node.schema, node.filename, extensions) : node.schema;
     const result = generateFile(extended, node.typeName, {
+      selfFilename: node.filename,
       typesOnly: typesOnly ?? false,
       rootSchema: node.rootSchema,
       helpersMode,

package/dist/generators/generate-discriminated-union-validation.js

@@ -1,8 +1,7 @@
-import { safeAccessor } from "@amritk/helpers/safe-accessor";
 import { getDiscriminatorValue } from "../helpers/get-discriminator-value.js";
 import { generateSchemaChecks } from "./generate-schema-checks.js";
 const generateDiscriminatedUnionValidation = (accessor, schemas, discriminatorKey, defaultValue, isRequired) => {
-  const discAccessor = safeAccessor(`${accessor}?`, discriminatorKey);
+  const discAccessor = `(${accessor} as Record<string, unknown> | null | undefined)?.[${JSON.stringify(discriminatorKey)}]`;
   const branches = [];
   for (const schema of schemas) {
     const discriminatorValue = getDiscriminatorValue(schema, discriminatorKey);

package/dist/generators/generate-files.d.ts

@@ -16,6 +16,13 @@ type GenerateFileOptions = {
      * the import list, preventing a file from importing itself.
      */
     readonly selfRef?: string;
+    /**
+     * The filename this file is written as, without extension. Used for
+     * self-import detection when the schema has no `$ref` of its own — the root
+     * document — so a `$defs` entry that collides with the root type name cannot
+     * make the root file import itself.
+     */
+    readonly selfFilename?: string;
     /**
      * The root schema document. When provided, URI refs that cannot be resolved
      * within the root schema's $defs are excluded from the import list.

package/dist/generators/generate-files.js

@@ -9,9 +9,20 @@ const generateFile = (schema, typeName, options) => {
   const helpersMode = options?.helpersMode ?? "package";
   const typeSuffix = options?.typeSuffix ?? "";
   const importExt = options?.importExt ?? "js";
-  const typeDefinition = generateTypeDefinition(schema, typeName, { readonly: options?.readonly ?? false, typeSuffix });
+  const typeDefinition = generateTypeDefinition(schema, typeName, {
+    readonly: options?.readonly ?? false,
+    typeSuffix,
+    ...rootSchema !== void 0 ? { rootSchema } : {}
+  });
   if (typesOnly) {
-    const imports2 = collectImports(schema, { typesOnly: true, selfRef, rootSchema, typeSuffix, importExt });
+    const imports2 = collectImports(schema, {
+      typesOnly: true,
+      selfRef,
+      selfFilename: options?.selfFilename,
+      rootSchema,
+      typeSuffix,
+      importExt
+    });
     let result2 = "";
     if (imports2.length > 0) {
       result2 += imports2[0];
@@ -23,7 +34,12 @@ const generateFile = (schema, typeName, options) => {
     return { content: result2 + typeDefinition, usedHelpers: /* @__PURE__ */ new Set() };
   }
   const stripUnknown = options?.stripUnknown ?? false;
-  const reservedNames = collectImportTypeNames(schema, { selfRef, rootSchema, typeSuffix });
+  const reservedNames = collectImportTypeNames(schema, {
+    selfRef,
+    selfFilename: options?.selfFilename,
+    rootSchema,
+    typeSuffix
+  });
   const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix, true, stripUnknown, reservedNames);
   const parserFunction = generateParserFunction(schema, typeName, {
     useRefImports: true,
@@ -41,7 +57,10 @@ const generateFile = (schema, typeName, options) => {
 
 ${parserFunction}`;
   const helpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix, importExt);
-  const imports = [...collectImports(schema, { selfRef, rootSchema, typeSuffix, importExt }), ...helpers.imports];
+  const imports = [
+    ...collectImports(schema, { selfRef, selfFilename: options?.selfFilename, rootSchema, typeSuffix, importExt }),
+    ...helpers.imports
+  ];
   let result = "";
   if (imports.length > 0) {
     result += imports[0];

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

@@ -10,7 +10,7 @@ import { getDefaultValue } from "../helpers/get-default-value.js";
 import { getDiscriminatorValue } from "../helpers/get-discriminator-value.js";
 import { assertNoUnsupportedKeywords } from "./assert-supported-keywords.js";
 import { generateEnumCaseInsensitiveCoercion } from "./generate-enum-check.js";
-import { generateContainsCheck, generateObjectKeywordChecks, generateObjectStrictAssertion, generateScalarStrictAssertion } from "./generate-strict-assertion.js";
+import { generateContainsCheck, generateObjectKeywordChecks, generateObjectStrictAssertion, generateScalarStrictAssertion, inlineAllOfMembers } from "./generate-strict-assertion.js";
 import { canEnforceUnion, generatePropertyTypeCheck, generateUnionCheck, getUnionBranches, hasFastPathBlockingKeyword, isInlineObjectArrayProperty, isInlineObjectProperty, shapeValidatorName } from "./generate-type-checks.js";
 import { generatePrefixItemsMap, generateValidationExpression, getPrefixItems, isCoercibleItemSchema, prefixItemsCapsLength } from "./generate-validation-expression.js";
 const generateParserName = (typeName) => {
@@ -165,7 +165,8 @@ const generateFallbackObject = (schema, useRefImports, typeName, suffix, subType
       if (fallbackValue === "undefined") {
         return `{} as ${typeName}`;
       }
-      requiredProps.push(`        ${safeLiteralKey(key)}: ${fallbackValue},`);
+      const partialFallback = fallbackValue === "{}" || isSchemaObject(propSchema) && (hasAllOf(propSchema) || hasOneOf(propSchema) || hasAnyOf(propSchema));
+      requiredProps.push(`        ${safeLiteralKey(key)}: ${partialFallback ? `${fallbackValue} as NonNullable<${typeName}>[${JSON.stringify(key)}]` : fallbackValue},`);
     }
   }
   if (requiredProps.length === 0) {
@@ -330,7 +331,7 @@ ${delegatedBody(itemParserName)}
       const stripUnknown = unionCtx?.stripUnknown ?? false;
       const itemShapeValidator = generateShapeValidator(items, itemName, useRefImports, suffix, false, stripUnknown, reserved);
       const preamble = [
-        `type ${itemName} = ${typeName}[number];`,
+        `type ${itemName} = NonNullable<${typeName}>[number];`,
         itemShapeValidator,
         generateObjectParser(items, itemName, useRefImports, suffix, unionCtx?.logWarnings ?? false, strict, false, stripUnknown, unionCtx?.rootSchema, reserved, unionCtx?.caseInsensitive ?? false, itemShapeValidator)
       ].join("\n\n");
@@ -339,7 +340,8 @@ ${delegatedBody(itemParserName)}
 ${delegated(generateParserName(itemName))}`;
     }
   }
-  if (!isSchemaObject(schema) || !hasType(schema)) {
+  const isMultiType = isSchemaObject(schema) && Array.isArray(schema.type);
+  if (!isSchemaObject(schema) || !hasType(schema) && !isMultiType) {
     return `export const ${functionName} = (input: unknown): ${typeName} => input as ${typeName};`;
   }
   if (!strict && schema.type === "null") {
@@ -350,7 +352,8 @@ ${delegated(generateParserName(itemName))}`;
     if (assertion === null) {
       return `export const ${functionName} = (input: unknown): ${typeName} => input as ${typeName};`;
     }
-    const returnExpr = schema.type === "array" ? `[...(input as readonly unknown[])] as ${typeName}` : `input as ${typeName}`;
+    const arrayCast = getPrefixItems(schema) ? `[...(input as readonly unknown[])] as unknown as ${typeName}` : `[...(input as readonly unknown[])] as ${typeName}`;
+    const returnExpr = !isMultiType && schema.type === "array" ? arrayCast : `input as ${typeName}`;
     return `export const ${functionName} = (input: unknown): ${typeName} => {
 ${assertion}
   return ${returnExpr};
@@ -369,7 +372,7 @@ ${assertion}
       const prefixItems = getPrefixItems(schema);
       if (prefixItems) {
         const mapped = generatePrefixItemsMap("input", prefixItems, prefixItemsCapsLength(schema), unionCtx?.rootSchema, void 0, unionCtx?.caseInsensitive);
-        return `export const ${functionName} = (input: unknown): ${typeName} => Array.isArray(input) ? ${mapped} as ${typeName} : [] as ${typeName};`;
+        return `export const ${functionName} = (input: unknown): ${typeName} => Array.isArray(input) ? ${mapped} as unknown as ${typeName} : [] as unknown as ${typeName};`;
       }
       if (hasItems(schema) && !Array.isArray(schema.items) && isCoercibleItemSchema(schema.items)) {
         const item = schema.items;
@@ -485,7 +488,7 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
   const preamble = [];
   for (const [key, subName] of subTypeNames) {
     const propSchema = schemaProps[key];
-    preamble.push(`type ${subName} = ${typeName}[${JSON.stringify(key)}];`);
+    preamble.push(`type ${subName} = NonNullable<${typeName}>[${JSON.stringify(key)}];`);
     const subShapeValidator = generateShapeValidator(propSchema, subName, useRefImports, suffix, false, stripUnknown, reservedNames);
     preamble.push(subShapeValidator);
     preamble.push(generateObjectParser(propSchema, subName, useRefImports, suffix, logWarnings, strict, false, stripUnknown, rootSchema, reservedNames, caseInsensitive, subShapeValidator));
@@ -493,7 +496,7 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
   for (const [key, subName] of subItemNames) {
     const propSchema = schemaProps[key];
     const itemSchema = propSchema.items;
-    preamble.push(`type ${subName} = NonNullable<${typeName}[${JSON.stringify(key)}]>[number];`);
+    preamble.push(`type ${subName} = NonNullable<NonNullable<${typeName}>[${JSON.stringify(key)}]>[number];`);
     const itemShapeValidator = generateShapeValidator(itemSchema, subName, useRefImports, suffix, false, stripUnknown, reservedNames);
     preamble.push(itemShapeValidator);
     preamble.push(`const _every${subName} = (arr: readonly unknown[]): boolean => {
@@ -522,7 +525,7 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
   const fallbackObject = generateFallbackObject(schema, useRefImports, typeName, suffix, subTypeNames);
   const propInfo = [];
   const hasAllOfRefParsers = useRefImports && isSchemaObject(schema) && hasAllOf(schema) && schema.allOf.some((entry) => isSchemaObject(entry) && hasRef(entry));
-  let canFastPath = !hasAllOfRefParsers && !hasFastPathBlockingKeyword(schema);
+  let canFastPath = !hasAllOfRefParsers && !hasFastPathBlockingKeyword(schema) && !(strict && inlineAllOfMembers(schema).length > 0);
   const fastPathChecks = [];
   const fastPathAccessorChecks = [];
   const usedVarNames = /* @__PURE__ */ new Set();

package/dist/generators/generate-strict-assertion.d.ts

@@ -46,6 +46,13 @@ export declare const generateObjectKeywordChecks: (obj: string, schema: JSONSche
  * Properties with a `$ref` are validated by the nested parser's own strict
  * check when that parser is invoked downstream.
  */
+/**
+ * The `allOf` members this assertion must enforce itself: plain object schemas
+ * written inline. A `$ref` member is enforced by the parser generated for its
+ * target, and a member that composes further (nested `allOf`/`oneOf`/`if`) is
+ * left alone rather than half-checked.
+ */
+export declare const inlineAllOfMembers: (schema: JSONSchema) => JSONSchema[];
 export declare const generateObjectStrictAssertion: (schema: JSONSchema, typeName: string, context?: StrictAssertionContext) => string[];
 /**
  * Generates a single strict-mode assertion line for a non-object scalar parser.

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

@@ -6,7 +6,7 @@ import { resolveRef } from "@amritk/helpers/resolve-ref";
 import { safeAccessor } from "@amritk/helpers/safe-accessor";
 import { hasConst, hasDependentRequired, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMultipleOf, hasPattern, hasProperties, hasPropertyNames, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject } from "@amritk/helpers/schema-guards";
 import { generateEnumCheck } from "./generate-enum-check.js";
-import { canEnforceUnion, generateUnionCheck, getUnionBranches, isInlineObjectProperty } from "./generate-type-checks.js";
+import { canEnforceUnion, generateUnionCheck, getUnionBranches, isInlineObjectProperty, multiTypeCheck } from "./generate-type-checks.js";
 import { getPrefixItems, prefixItemsCapsLength, scalarItemTypeCheck } from "./generate-validation-expression.js";
 import { subschemaMatchExpr } from "./subschema-match.js";
 const wrongTypeCondition = (accessor, type) => {
@@ -262,6 +262,19 @@ const generatePropertyAssertion = (key, propSchema, isRequired, typeName, contex
     }
     return lines;
   }
+  const multiType = multiTypeCheck(acc, propSchema, { ignoreConstraints: true });
+  if (multiType !== void 0) {
+    const types = propSchema.type;
+    if (multiType !== null) {
+      const expected = throwError(`${field} expected ${types.map(typeLabel).join(" | ")}, got `, `typeof ${acc}`);
+      lines.push(isRequired ? `  if (!${multiType}) ${expected};` : `  if (${acc} !== undefined && !${multiType}) ${expected};`);
+    }
+    const nonNull = types.filter((type) => type !== "null");
+    if (nonNull.length === 1) {
+      lines.push(...generateConstraintChecks(acc, { ...propSchema, type: nonNull[0] }, field, context));
+    }
+    return lines;
+  }
   if (hasType(propSchema)) {
     const t = propSchema.type;
     const wrongType = wrongTypeCondition(acc, t);
@@ -285,17 +298,39 @@ const generatePropertyAssertion = (key, propSchema, isRequired, typeName, contex
   }
   return lines;
 };
+const inlineAllOfMembers = (schema) => {
+  if (!isSchemaObject(schema) || !Array.isArray(schema.allOf))
+    return [];
+  return schema.allOf.filter((member) => {
+    if (!isSchemaObject(member) || hasRef(member))
+      return false;
+    const record = member;
+    if ("allOf" in record || "oneOf" in record || "anyOf" in record || "not" in record)
+      return false;
+    if ("if" in record || "then" in record || "else" in record)
+      return false;
+    return hasProperties(member) || hasRequired(member);
+  });
+};
 const generateObjectStrictAssertion = (schema, typeName, context = {}) => {
   const lines = [];
   lines.push(`  if (!isObject(input)) ${throwError(`[${typeName}] expected object, got `, 'input === null ? "null" : typeof input')};`);
   if (!isSchemaObject(schema))
     return lines;
+  const required = new Set(hasRequired(schema) ? schema.required : []);
   if (hasProperties(schema)) {
-    const required = new Set(hasRequired(schema) ? schema.required : []);
     const props = schema.properties;
     for (const key in props) {
       lines.push(...generatePropertyAssertion(key, props[key], required.has(key), typeName, context));
     }
+    for (const key in props)
+      required.delete(key);
+  }
+  for (const key of required) {
+    lines.push(`  if (!(${JSON.stringify(key)} in input)) ${throwError(`[${typeName}] missing required property '${key}'`)};`);
+  }
+  for (const member of inlineAllOfMembers(schema)) {
+    lines.push(...generateObjectStrictAssertion(member, typeName, context).slice(1));
   }
   const sr = schema;
   if ("dependentRequired" in sr || "dependentSchemas" in sr || "propertyNames" in sr) {
@@ -325,6 +360,18 @@ const generateScalarStrictAssertion = (schema, typeName, rootSchema) => {
     const enumLabel = schema.enum.map((v) => JSON.stringify(v)).join(", ");
     lines.push(`  if (!(${allowed} as readonly unknown[]).includes(input)) ${throwError(`${label} must be one of: ${enumLabel}`)};`);
   }
+  const rootMultiType = multiTypeCheck("input", schema, { ignoreConstraints: true });
+  if (rootMultiType !== void 0) {
+    const types = schema.type;
+    if (rootMultiType !== null) {
+      lines.push(`  if (!${rootMultiType}) ${throwError(`${label} expected ${types.map(typeLabel).join(" | ")}, got `, got)};`);
+    }
+    const nonNull = types.filter((type) => type !== "null");
+    if (nonNull.length === 1) {
+      lines.push(...generateConstraintChecks("input", { ...schema, type: nonNull[0] }, label, rootSchema ? { rootSchema } : {}));
+    }
+    return lines.length > 0 ? lines.join("\n") : null;
+  }
   if (hasType(schema)) {
     const t = schema.type;
     const wrongType = wrongTypeCondition("input", t);
@@ -332,12 +379,7 @@ const generateScalarStrictAssertion = (schema, typeName, rootSchema) => {
       lines.push(`  if (${wrongType}) ${throwError(`${label} expected ${typeLabel(t)}, got `, got)};`);
     }
     if (t === "array") {
-      const itemCheck = generateItemCheck(schema);
-      if (itemCheck) {
-        lines.push(`  if (!(input as readonly unknown[]).every((_it) => ${itemCheck.check})) ${throwError(`${label} ${itemCheck.message}`)};`);
-      }
       lines.push(...generateContainsCheck("input", schema, label));
-      lines.push(...generatePrefixItemsAssertion("input", label, schema, rootSchema));
     }
     lines.push(...generateConstraintChecks("input", schema, label, rootSchema ? { rootSchema } : {}));
   }
@@ -347,5 +389,6 @@ export {
   generateContainsCheck,
   generateObjectKeywordChecks,
   generateObjectStrictAssertion,
-  generateScalarStrictAssertion
+  generateScalarStrictAssertion,
+  inlineAllOfMembers
 };

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

@@ -50,6 +50,21 @@ export declare const getUnionBranches: (schema: JSONSchema) => readonly JSONSche
  * both must bail when this is true — the slow path then runs the real checks.
  */
 export declare const hasFastPathBlockingKeyword: (schema: JSONSchema) => boolean;
+/**
+ * The membership check for an array-form `type` (the multi-type / nullable
+ * idiom, e.g. `["string","null"]`): the disjunction of the per-type checks.
+ * Returns `undefined` when the schema has no array `type`, and `null` when it
+ * has one that cannot be checked soundly — a type name we do not model, or a
+ * constraint keyword a bare `typeof` would skip.
+ *
+ * Without this every nullable property fell through to `hasType`, which is false
+ * for an array `type`, and produced no check at all: no fast path (so the shape
+ * validator degraded to the `=> false` stub) and, in strict mode, nothing to
+ * throw on.
+ */
+export declare const multiTypeCheck: (varName: string, schema: JSONSchema, options?: {
+    readonly ignoreConstraints?: boolean;
+}) => string | null | undefined;
 /**
  * Generates a fast-path type check expression for a property.
  * Returns null if the schema is too complex for a simple type check.

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

@@ -5,13 +5,15 @@ import { resolveRef } from "@amritk/helpers/resolve-ref";
 import { safeAccessor } from "@amritk/helpers/safe-accessor";
 import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasRef, hasType, hasUniqueItems, isObjectSchema, isSchemaObject } from "@amritk/helpers/schema-guards";
 import { generateEnumCheck } from "./generate-enum-check.js";
-import { getPrefixItems, prefixItemsCapsLength, scalarItemTypeCheck } from "./generate-validation-expression.js";
+import { getPrefixItems, prefixItemsCapsLength, scalarItemTypeCheck, singleTypeCheck } from "./generate-validation-expression.js";
 const shapeValidatorName = (typeName) => `validate${typeName}Shape`;
 const isInlineObjectProperty = (propSchema) => {
   if (!isSchemaObject(propSchema))
     return false;
   if (hasRef(propSchema) || hasEnum(propSchema) || hasConst(propSchema))
     return false;
+  if (Array.isArray(propSchema.type))
+    return false;
   if (hasOneOf(propSchema) || hasAnyOf(propSchema) || hasAllOf(propSchema))
     return false;
   if ("patternProperties" in propSchema || "not" in propSchema)
@@ -48,6 +50,44 @@ const hasFastPathBlockingKeyword = (schema) => {
   const record = schema;
   return "contains" in record || "dependentSchemas" in record || "propertyNames" in record || "dependentRequired" in record;
 };
+const CONSTRAINT_KEYWORDS = [
+  "pattern",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "items",
+  "prefixItems",
+  "properties",
+  "required",
+  "additionalProperties",
+  "patternProperties",
+  "minProperties",
+  "maxProperties"
+];
+const multiTypeCheck = (varName, schema, options = {}) => {
+  if (!isSchemaObject(schema) || !Array.isArray(schema.type))
+    return void 0;
+  const record = schema;
+  if (!options.ignoreConstraints && CONSTRAINT_KEYWORDS.some((keyword) => keyword in record))
+    return null;
+  const checks = [];
+  for (const type of schema.type) {
+    const check = singleTypeCheck(varName, type);
+    if (check === null)
+      return null;
+    checks.push(`(${check})`);
+  }
+  if (checks.length === 0)
+    return null;
+  return checks.length === 1 ? checks[0] : `(${checks.join(" || ")})`;
+};
 const generatePropertyTypeCheck = (varName, schema, useRefImports, suffix) => {
   if (!isSchemaObject(schema))
     return null;
@@ -75,6 +115,9 @@ const generatePropertyTypeCheck = (varName, schema, useRefImports, suffix) => {
     const c = schema.const;
     return c === null || typeof c !== "object" ? `${varName} === ${JSON.stringify(c)}` : null;
   }
+  const multiType = multiTypeCheck(varName, schema);
+  if (multiType !== void 0)
+    return multiType;
   if (!hasType(schema))
     return null;
   if (useRefImports && schema.type === "array" && hasItems(schema) && isSchemaObject(schema.items) && hasRef(schema.items)) {
@@ -225,6 +268,9 @@ const canTrustPropertyCheck = (schema, rootSchema, visiting) => {
     return false;
   if (hasConst(schema))
     return schema.const === null || typeof schema.const !== "object";
+  const multiType = multiTypeCheck("_x", schema);
+  if (multiType !== void 0)
+    return multiType !== null;
   if (!hasType(schema))
     return false;
   if (schema.type === "array" && hasItems(schema) && isSchemaObject(schema.items) && hasRef(schema.items)) {
@@ -309,5 +355,6 @@ export {
   hasFastPathBlockingKeyword,
   isInlineObjectArrayProperty,
   isInlineObjectProperty,
+  multiTypeCheck,
   shapeValidatorName
 };

package/dist/generators/generate-validation-expression.d.ts

@@ -14,10 +14,11 @@ export declare const scalarItemTypeCheck: (itemSchema: JSONSchema, accessor: str
  */
 export declare const isCoercibleItemSchema: (itemSchema: JSONSchema) => boolean;
 /**
- * The tuple `prefixItems` array when the schema declares one, else `null`.
- * `prefixItems` (JSON Schema 2020-12) positions each element against its own
- * subschema; the draft array-form `items` is handled by the existing item
- * paths, not here.
+ * The tuple positions a schema declares, else `null`. `prefixItems` (JSON
+ * Schema 2020-12) positions each element against its own subschema; draft-07
+ * spelled the same construct as an array-valued `items`, which every other item
+ * path skips (they all read `items` as a single schema), so it is normalized
+ * here rather than left unchecked.
  */
 export declare const getPrefixItems: (schema: JSONSchema) => readonly JSONSchema[] | null;
 /**
@@ -26,6 +27,14 @@ export declare const getPrefixItems: (schema: JSONSchema) => readonly JSONSchema
  * disallowed, so the coercer drops it and strict mode rejects it.
  */
 export declare const prefixItemsCapsLength: (schema: JSONSchema) => boolean;
+/**
+ * A boolean type check for a single JSON Schema primitive type name. Unlike
+ * {@link scalarItemTypeCheck} this also covers `array`/`object` (as inline shape
+ * checks, so no `isObject` import is assumed) and enforces `integer` with
+ * `Number.isInteger` — a bare `typeof === "number"` accepts `1.5`. Used to build
+ * the disjunction for an array-form `type` (e.g. `["string","null"]`).
+ */
+export declare const singleTypeCheck: (accessor: string, type: string) => string | null;
 /**
  * Generates a validation expression that checks if a value matches the expected type.
  * Returns the value if valid, coerces to the correct type if invalid, or uses default if required and missing.

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

@@ -42,7 +42,9 @@ const getPrefixItems = (schema) => {
   if (!isSchemaObject(schema))
     return null;
   const prefix = schema["prefixItems"];
-  return Array.isArray(prefix) ? prefix : null;
+  if (Array.isArray(prefix))
+    return prefix;
+  return Array.isArray(schema.items) ? schema.items : null;
 };
 const prefixItemsCapsLength = (schema) => {
   if (!isSchemaObject(schema))
@@ -328,5 +330,6 @@ export {
   getPrefixItems,
   isCoercibleItemSchema,
   prefixItemsCapsLength,
-  scalarItemTypeCheck
+  scalarItemTypeCheck,
+  singleTypeCheck
 };

package/dist/helpers/collect-imports.d.ts

@@ -16,6 +16,14 @@ type CollectImportsOptions = {
      * the import list, preventing a file from importing itself.
      */
     readonly selfRef?: string | undefined;
+    /**
+     * The filename this file is being written as, without extension. Takes
+     * precedence over `selfRef` for self-import detection, and covers the case
+     * `selfRef` cannot: the root document has no ref of its own, so a definition
+     * whose name collides with the root type name (root `Contact` + `$defs.contact`)
+     * used to make the root file import its own type from itself.
+     */
+    readonly selfFilename?: string | undefined;
     /**
      * The root schema document. When provided, URI refs that cannot be resolved
      * within the root schema's $defs are excluded from the import list, preventing

package/dist/helpers/collect-imports.js

@@ -21,7 +21,7 @@ const collectImportTypeNames = (schema, options) => {
   return names;
 };
 const collectImportTargets = (schema, options) => {
-  const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : void 0;
+  const selfFilename = options?.selfFilename ?? (options?.selfRef ? refToFilename(options.selfRef) : void 0);
   const rootSchema = options?.rootSchema;
   const typeSuffix = options?.typeSuffix;
   const refs = /* @__PURE__ */ new Set();

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

@@ -1,11 +1,33 @@
 import { getMjstPrimitive } from "@amritk/helpers/mjst-extension";
 import { hasAllOf, hasAnyOf, hasConst, hasDefault, hasEnum, hasExamples, hasOneOf, hasPattern, hasProperties, hasRequired, hasType, isSchemaObject } from "@amritk/helpers/schema-guards";
 import { generateDefaultFromPattern } from "../generators/generate-default-from-pattern.js";
+const defaultMatchesType = (value, schema) => {
+  if (!hasType(schema))
+    return true;
+  switch (schema.type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number";
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "null":
+      return value === null;
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    default:
+      return true;
+  }
+};
 const getDefaultValue = (schema) => {
   if (!isSchemaObject(schema)) {
     return "undefined";
   }
-  if (hasDefault(schema)) {
+  if (hasDefault(schema) && defaultMatchesType(schema.default, schema)) {
     return JSON.stringify(schema.default);
   }
   if (hasConst(schema)) {

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@amritk/generate-parsers",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
   "license": "MIT",
   "author": "amritk",
   "keywords": [
@@ -49,8 +53,8 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.13.4",
-    "@amritk/generate-markdown": "0.4.4"
+    "@amritk/helpers": "0.14.0",
+    "@amritk/generate-markdown": "0.4.5"
   },
   "devDependencies": {
     "@sinclair/typebox": "^0.34.49",