@amritk/generate-parsers 0.11.1 → 0.12.1

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

@@ -1,11 +1,11 @@
 import { escapeRegexPattern } from '@amritk/helpers/escape-regex-pattern';
 import { refToName } from '@amritk/helpers/ref-to-name';
 import { safeAccessor, safeKey } from '@amritk/helpers/safe-accessor';
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasDefault, hasEnum, hasExamples, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasRef, hasType, hasUniqueItems, isObjectSchema, isSchemaObject, } from '@amritk/helpers/schema-guards';
+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 { unknownKeyCheck } from '@amritk/helpers/unknown-key-check';
 import { getDefaultValue } from '../helpers/get-default-value.js';
 import { generateObjectStrictAssertion, generateScalarStrictAssertion } from './generate-strict-assertion.js';
-import { generateValidationExpression } from './generate-validation-expression.js';
+import { generateValidationExpression, scalarItemTypeCheck } from './generate-validation-expression.js';
 /**
  * Generates the parser function name from a type name.
  * Converts "UserObject" to "parseUserObject".
@@ -213,41 +213,10 @@ const generateFallbackValue = (_, propSchema, useRefImports, suffix) => {
             return '{}';
         }
     }
-    // For non-schema objects, return undefined
-    if (!isSchemaObject(propSchema)) {
-        return 'undefined';
-    }
-    // Use explicit default if provided
-    if (hasDefault(propSchema)) {
-        return JSON.stringify(propSchema.default);
-    }
-    // Use first enum value if available
-    if (hasEnum(propSchema) && propSchema.enum.length > 0) {
-        return JSON.stringify(propSchema.enum[0]);
-    }
-    // Use first example if available
-    if (hasExamples(propSchema) && propSchema.examples.length > 0) {
-        return JSON.stringify(propSchema.examples[0]);
-    }
-    // Return simple type-based defaults without pattern inference
-    if (!hasType(propSchema)) {
-        return 'undefined';
-    }
-    switch (propSchema.type) {
-        case 'string':
-            return '""';
-        case 'number':
-        case 'integer':
-            return '0';
-        case 'boolean':
-            return 'false';
-        case 'array':
-            return '[]';
-        case 'object':
-            return '{}';
-        default:
-            return 'undefined';
-    }
+    // Everything else (default/const/enum/examples/union, the null type, and a
+    // recursively-defaulted object) shares one source of truth so the fallback
+    // object is itself a valid instance — `getDefaultValue` handles them all.
+    return getDefaultValue(propSchema);
 };
 /**
  * Generates a fallback object with required properties filled with default values.
@@ -296,12 +265,85 @@ const generateFallbackObject = (schema, useRefImports, typeName, suffix, subType
  * Generates a parser for non-object schemas (string, number, boolean, array, etc.)
  * that validates the input matches the expected primitive type before casting.
  */
+/**
+ * A default value literal (as source text) for `schema`, used as the fallback a
+ * top-level union coerces an unmatched value to. Prefers a `const`/`enum` member,
+ * then a per-type empty value.
+ */
+const scalarDefaultLiteral = (schema) => {
+    if (!isSchemaObject(schema))
+        return '{}';
+    if (hasConst(schema))
+        return JSON.stringify(schema.const);
+    if (hasEnum(schema) && schema.enum.length > 0)
+        return JSON.stringify(schema.enum[0]);
+    if (hasType(schema)) {
+        switch (schema.type) {
+            case 'string':
+                return '""';
+            case 'number':
+            case 'integer':
+                return '0';
+            case 'boolean':
+                return 'false';
+            case 'null':
+                return 'null';
+            case 'array':
+                return '[]';
+            case 'object':
+                return '{}';
+        }
+    }
+    return '{}';
+};
 const generateNonObjectParser = (typeName, schema, strict) => {
     const functionName = generateParserName(typeName);
+    // `const`/`enum` define the value space directly (the generated type is a
+    // literal / literal-union), so a non-member must coerce to a valid member —
+    // otherwise the returned value would not be of the declared type. This runs
+    // before the `type` switch so e.g. `{ type: 'string', enum: [...] }` is covered,
+    // and before the no-`type` bail so a bare `const`/`enum` schema is covered too.
+    if (!strict && isSchemaObject(schema)) {
+        if (hasConst(schema)) {
+            const literal = JSON.stringify(schema.const);
+            // The const is the only valid value, so the parser always yields it. For a
+            // primitive we can keep the caller's value when it already equals the const
+            // (`===` is a correct comparison); for an object/array, `===` would be a
+            // (always-false) reference comparison, so just return the const literal.
+            const isPrimitive = schema.const === null || typeof schema.const !== 'object';
+            return isPrimitive
+                ? `export const ${functionName} = (input: unknown): ${typeName} => input === ${literal} ? input as ${typeName} : ${literal} as ${typeName};`
+                : `export const ${functionName} = (input: unknown): ${typeName} => ${literal} as ${typeName};`;
+        }
+        if (hasEnum(schema) && schema.enum.length > 0) {
+            const values = JSON.stringify(schema.enum);
+            const fallback = JSON.stringify(schema.enum[0]);
+            return `export const ${functionName} = (input: unknown): ${typeName} => ${values}.includes(input as never) ? input as ${typeName} : ${fallback} as ${typeName};`;
+        }
+        // A top-level union must validate membership: an unmatched value is not of
+        // the declared union type, so coerce it to a member-shaped default. Reuse the
+        // same union validation the property path uses. A `$ref` branch can't be
+        // validated inline here (the membership test would silently drop it and
+        // wrongly coerce a valid ref-shaped value), so fall through to a passthrough
+        // cast rather than discarding valid input.
+        if (hasOneOf(schema) || hasAnyOf(schema)) {
+            const branches = hasOneOf(schema) ? schema.oneOf : hasAnyOf(schema) ? schema.anyOf : [];
+            const hasRefBranch = branches.some((b) => isSchemaObject(b) && hasRef(b));
+            if (branches.length > 0 && !hasRefBranch) {
+                const fallback = scalarDefaultLiteral(branches[0]);
+                const expr = generateValidationExpression('', schema, fallback, true, undefined, undefined, 'input', true);
+                return `export const ${functionName} = (input: unknown): ${typeName} => (${expr}) as ${typeName};`;
+            }
+            return `export const ${functionName} = (input: unknown): ${typeName} => input as ${typeName};`;
+        }
+    }
     if (!isSchemaObject(schema) || !hasType(schema)) {
         // Schema without type information cannot be validated beyond a cast
         return `export const ${functionName} = (input: unknown): ${typeName} => input as ${typeName};`;
     }
+    if (!strict && schema.type === 'null') {
+        return `export const ${functionName} = (input: unknown): ${typeName} => null as ${typeName};`;
+    }
     if (strict) {
         const assertion = generateScalarStrictAssertion(schema, typeName);
         if (assertion === null) {
@@ -318,8 +360,15 @@ const generateNonObjectParser = (typeName, schema, strict) => {
             return `export const ${functionName} = (input: unknown): ${typeName} => typeof input === "number" ? input as ${typeName} : 0 as ${typeName};`;
         case 'boolean':
             return `export const ${functionName} = (input: unknown): ${typeName} => typeof input === "boolean" ? input as ${typeName} : false as ${typeName};`;
-        case 'array':
+        case 'array': {
+            // Coerce each element when the item schema is a single scalar type.
+            if (hasItems(schema) && !Array.isArray(schema.items) && scalarItemTypeCheck(schema.items, '_it') !== null) {
+                const item = schema.items;
+                const itemExpr = generateValidationExpression('', item, getDefaultValue(item), true, undefined, undefined, '_it', true);
+                return `export const ${functionName} = (input: unknown): ${typeName} => Array.isArray(input) ? (input as unknown[]).map((_it) => ${itemExpr}) as ${typeName} : [] as ${typeName};`;
+            }
             return `export const ${functionName} = (input: unknown): ${typeName} => Array.isArray(input) ? [...input] as ${typeName} : [] as ${typeName};`;
+        }
         default:
             return `export const ${functionName} = (input: unknown): ${typeName} => input as ${typeName};`;
     }
@@ -493,6 +542,14 @@ const generatePropertyTypeCheck = (varName, schema, useRefImports, suffix) => {
             if (hasUniqueItems(schema) && schema.uniqueItems === true) {
                 checks.push(`new Set(${varName}).size === ${varName}.length`);
             }
+            // For a scalar item type, every element must already be well-typed to take
+            // the fast path; a mistyped element routes the array to the slow path where
+            // each element is coerced.
+            if (hasItems(schema) && !Array.isArray(schema.items)) {
+                const itemCheck = scalarItemTypeCheck(schema.items, '_it');
+                if (itemCheck)
+                    checks.push(`${varName}.every((_it) => ${itemCheck})`);
+            }
             break;
         }
         case 'object':

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

@@ -1,4 +1,11 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * A boolean type check for an array element whose schema is a single scalar type
+ * (the cases the element coercion below can handle). `integer` is treated as
+ * `number` because the generated TS element type is `number`. Returns `null` for
+ * objects, arrays, unions, `$ref`s, and anything richer.
+ */
+export declare const scalarItemTypeCheck: (itemSchema: JSONSchema, accessor: 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

@@ -2,8 +2,9 @@ import { escapeRegexPattern } from '@amritk/helpers/escape-regex-pattern';
 import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extension';
 import { resolveRef } from '@amritk/helpers/resolve-ref';
 import { safeAccessor } from '@amritk/helpers/safe-accessor';
-import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasMaxItems, hasMaximum, hasMaxLength, hasMaxProperties, hasMinItems, hasMinimum, hasMinLength, hasMinProperties, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject, } from '@amritk/helpers/schema-guards';
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasConst, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMaxProperties, hasMinItems, hasMinimum, hasMinLength, hasMinProperties, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject, } from '@amritk/helpers/schema-guards';
 import { findDiscriminator } from '../helpers/find-discriminator.js';
+import { getDefaultValue } from '../helpers/get-default-value.js';
 import { generateDiscriminatedUnionValidation } from './generate-discriminated-union-validation.js';
 import { generateEnumCheck } from './generate-enum-check.js';
 import { generateNonDiscriminatedUnionValidation } from './generate-non-discriminated-union-validation.js';
@@ -19,6 +20,29 @@ const getInstanceCoercion = (accessor, instanceOf) => {
         return `new Date(${accessor} as string | number | Date)`;
     return null;
 };
+/**
+ * A boolean type check for an array element whose schema is a single scalar type
+ * (the cases the element coercion below can handle). `integer` is treated as
+ * `number` because the generated TS element type is `number`. Returns `null` for
+ * objects, arrays, unions, `$ref`s, and anything richer.
+ */
+export const scalarItemTypeCheck = (itemSchema, accessor) => {
+    if (!isSchemaObject(itemSchema) || !hasType(itemSchema) || hasEnum(itemSchema))
+        return null;
+    switch (itemSchema.type) {
+        case 'string':
+            return `typeof ${accessor} === "string"`;
+        case 'number':
+        case 'integer':
+            return `typeof ${accessor} === "number"`;
+        case 'boolean':
+            return `typeof ${accessor} === "boolean"`;
+        case 'null':
+            return `${accessor} === null`;
+        default:
+            return null;
+    }
+};
 /**
  * Generates a type coercion expression for converting a value to the expected type.
  */
@@ -41,7 +65,9 @@ const getTypeCoercion = (accessor, schema, defaultValue) => {
         case 'array':
             return `[]`;
         case 'object':
-            return `typeof ${accessor} === "object" && ${accessor} !== null ? ${accessor} : {}`;
+            // Fall back to the schema's default (which fills required properties)
+            // rather than a bare `{}`, so a coerced object is a valid instance.
+            return `typeof ${accessor} === "object" && ${accessor} !== null ? ${accessor} : ${defaultValue}`;
         default:
             return null;
     }
@@ -148,6 +174,20 @@ export const generateValidationExpression = (key, schema, defaultValue, isRequir
     if (!hasType(schema) && !hasEnum(schema)) {
         return `${accessor} ?? ${defaultValue}`;
     }
+    // An array of scalar items: coerce each element so e.g. `number[]` actually
+    // contains numbers. The fast path only takes a well-typed array, so a mistyped
+    // element reaches here. ($ref items use the caller's validateArray path;
+    // object/union items still pass through.)
+    if (hasType(schema) &&
+        schema.type === 'array' &&
+        hasItems(schema) &&
+        !Array.isArray(schema.items) &&
+        scalarItemTypeCheck(schema.items, '_it') !== null) {
+        const itemSchema = schema.items;
+        const itemExpr = generateValidationExpression('', itemSchema, getDefaultValue(itemSchema), true, rootSchema, visitedRefs, '_it', true);
+        const mapped = `(Array.isArray(${accessor}) ? (${accessor} as unknown[]).map((_it) => ${itemExpr}) : ${defaultValue})`;
+        return isRequired ? mapped : `(${accessor} !== undefined ? ${mapped} : undefined)`;
+    }
     // Build type-specific checks
     if (hasType(schema)) {
         switch (schema.type) {
@@ -187,6 +227,9 @@ export const generateValidationExpression = (key, schema, defaultValue, isRequir
             case 'boolean':
                 checks.push(`typeof ${accessor} === "boolean"`);
                 break;
+            case 'null':
+                checks.push(`${accessor} === null`);
+                break;
             case 'array': {
                 checks.push(`Array.isArray(${accessor})`);
                 if (hasMinItems(schema)) {
@@ -241,7 +284,12 @@ export const generateValidationExpression = (key, schema, defaultValue, isRequir
     // Generate the fallback value
     // If the value exists but fails validation, try to coerce it
     // If the value is missing and required, use the default
-    const typeCoercion = getTypeCoercion(accessor, schema, defaultValue);
+    //
+    // `enum` constrains the value to a fixed set, so type coercion (e.g.
+    // `String(x)`) can't rescue a non-member — `String("z")` is still not in the
+    // enum. Fall back to the default (the first enum value) so the result is always
+    // a valid member of the declared literal-union type.
+    const typeCoercion = hasEnum(schema) ? null : getTypeCoercion(accessor, schema, defaultValue);
     if (isRequired) {
         // For required fields: valid ? use_value : (exists ? coerce : default)
         if (typeCoercion) {

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

@@ -1,5 +1,5 @@
 import { getMjstPrimitive } from '@amritk/helpers/mjst-extension';
-import { hasAllOf, hasAnyOf, hasDefault, hasEnum, hasExamples, hasOneOf, hasPattern, hasType, isSchemaObject, } from '@amritk/helpers/schema-guards';
+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';
 /**
  * Returns the default value for a JSON Schema property.
@@ -14,6 +14,10 @@ export const getDefaultValue = (schema) => {
     if (hasDefault(schema)) {
         return JSON.stringify(schema.default);
     }
+    // A `const` value is the only valid value, so it is also the default.
+    if (hasConst(schema)) {
+        return JSON.stringify(schema.const);
+    }
     // Use first enum value if available
     if (hasEnum(schema) && schema.enum.length > 0) {
         return JSON.stringify(schema.enum[0]);
@@ -64,10 +68,28 @@ export const getDefaultValue = (schema) => {
             return '0';
         case 'boolean':
             return 'false';
+        case 'null':
+            return 'null';
         case 'array':
             return '[]';
-        case 'object':
+        case 'object': {
+            // A bare `{}` omits required properties, leaving the default invalid against
+            // its own type. Populate each required property with its own default so the
+            // fallback object is itself a valid instance.
+            if (hasProperties(schema) && hasRequired(schema)) {
+                const props = schema.properties;
+                const required = schema.required.filter((key) => Object.hasOwn(props, key));
+                const defaults = required.map((key) => getDefaultValue(props[key]));
+                // A required property whose schema has no concrete default (a `$ref` we
+                // can't resolve here, or a type-less schema) would otherwise emit
+                // `"key": undefined` — i.e. a *missing* required key. Don't build a
+                // partial object with holes; fall back to a bare `{}` for the whole node.
+                if (defaults.length > 0 && !defaults.includes('undefined')) {
+                    return `{ ${required.map((key, i) => `${JSON.stringify(key)}: ${defaults[i]}`).join(', ')} }`;
+                }
+            }
             return '{}';
+        }
         default:
             return 'undefined';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-parsers",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -48,11 +48,12 @@
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.10.0",
-    "@amritk/generate-markdown": "0.2.4"
+    "@amritk/helpers": "0.10.1",
+    "@amritk/generate-markdown": "0.3.0"
   },
   "devDependencies": {
     "@sinclair/typebox": "^0.34.49",
+    "ajv": "^8.17.1",
     "zod": "^4.4.3"
   }
 }