@amritk/generate-parsers 0.9.0 → 0.10.0

package/README.md

@@ -134,6 +134,16 @@ Returns: `Promise<GeneratedFile[]>`.
 <tr>
 <td colspan="5">Generate parsers that throw on type/shape mismatches (wrong type, missing required property, enum/pattern/min/max violations) instead of coercing invalid input to default values. When a schema sets additionalProperties: false, undeclared keys throw too; otherwise they are still allowed.</td>
 </tr>
+<tr>
+<td>🧹 <code>stripUnknown</code></td>
+<td>—</td>
+<td><code>boolean</code></td>
+<td align="center">—</td>
+<td align="center"><code>false</code></td>
+</tr>
+<tr>
+<td colspan="5">Build each parser's result from the schema's declared properties only, silently dropping undeclared input keys at every nesting level (zod's .strip()). Extras are never a validation error, so this composes with strict (which still throws on wrong types and missing required properties) and yields to additionalProperties: false, which rejects rather than strips in strict mode.</td>
+</tr>
 </tbody>
 </table>
 <!-- config-table-end -->

package/dist/generators/build-schema.d.ts

@@ -38,6 +38,10 @@ export type GeneratedFile = {
  *   directory while the helper sources are emitted once at the output root.
  * @param readonly - When true, every property, array, and record in the generated type
  *   definitions is emitted as `readonly`.
+ * @param stripUnknown - When true, the generated parsers build their result from declared
+ *   properties only, silently dropping undeclared input keys at every nesting level (zod's
+ *   `.strip()`) without treating extras as a validation error. Composes with `strict` and
+ *   yields to `additionalProperties: false` (which rejects rather than strips in strict mode).
  * @param typeSuffix - Suffix appended to every type/parser name derived from a `$ref`
  *   (e.g. `'Object'` → `ContactObject`). Defaults to `''` (no suffix). The root type name
  *   is used verbatim and is not affected by this suffix.
@@ -73,4 +77,4 @@ export type GeneratedFile = {
  * });
  * ```
  */
-export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean, typeSuffix?: string) => Promise<GeneratedFile[]>;
+export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode, helpersImportPrefix?: string, readonly?: boolean, stripUnknown?: boolean, typeSuffix?: string) => Promise<GeneratedFile[]>;

package/dist/generators/build-schema.js

@@ -43,6 +43,10 @@ const readHelperSource = async (helper) => {
  *   directory while the helper sources are emitted once at the output root.
  * @param readonly - When true, every property, array, and record in the generated type
  *   definitions is emitted as `readonly`.
+ * @param stripUnknown - When true, the generated parsers build their result from declared
+ *   properties only, silently dropping undeclared input keys at every nesting level (zod's
+ *   `.strip()`) without treating extras as a validation error. Composes with `strict` and
+ *   yields to `additionalProperties: false` (which rejects rather than strips in strict mode).
  * @param typeSuffix - Suffix appended to every type/parser name derived from a `$ref`
  *   (e.g. `'Object'` → `ContactObject`). Defaults to `''` (no suffix). The root type name
  *   is used verbatim and is not affected by this suffix.
@@ -78,7 +82,7 @@ const readHelperSource = async (helper) => {
  * });
  * ```
  */
-export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = 'package', helpersImportPrefix = './', readonly = false, typeSuffix = '') => {
+export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnly, logWarnings, strict, helpersMode = 'package', helpersImportPrefix = './', readonly = false, stripUnknown = false, typeSuffix = '') => {
     const files = [];
     const usedHelpers = new Set();
     walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
@@ -99,6 +103,7 @@ export const buildSchema = async (rootSchema, rootTypeName, extensions, typesOnl
             ...(node.ref !== undefined ? { selfRef: node.ref } : {}),
             ...(logWarnings !== undefined ? { logWarnings } : {}),
             ...(strict !== undefined ? { strict } : {}),
+            ...(stripUnknown ? { stripUnknown } : {}),
         });
         files.push({ filename: `${node.filename}.ts`, content: result.content });
         for (const helper of result.usedHelpers)

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

@@ -30,6 +30,15 @@ type GenerateFileOptions = {
      * of coercing invalid input to default values.
      */
     readonly strict?: boolean;
+    /**
+     * When true, the generated parser builds its result from declared properties
+     * only, silently dropping undeclared input keys at every nesting level (zod's
+     * `.strip()`), without treating extras as a validation error. Composes with
+     * `strict` (still throws on wrong types / missing required properties) and
+     * yields to `additionalProperties: false` (which rejects rather than strips in
+     * strict mode).
+     */
+    readonly stripUnknown?: boolean;
     /**
      * Controls how runtime helpers are referenced.
      * - `'package'` (default): emit imports from `@amritk/helpers/...`.

package/dist/generators/generate-files.js

@@ -51,13 +51,15 @@ export const generateFile = (schema, typeName, options) => {
         }
         return { content: result + typeDefinition, usedHelpers: new Set() };
     }
+    const stripUnknown = options?.stripUnknown ?? false;
     const parserFunction = generateParserFunction(schema, typeName, {
         useRefImports: true,
         typeSuffix,
         ...(options?.logWarnings !== undefined ? { logWarnings: options.logWarnings } : {}),
         ...(options?.strict !== undefined ? { strict: options.strict } : {}),
+        ...(options?.stripUnknown !== undefined ? { stripUnknown: options.stripUnknown } : {}),
     });
-    const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix);
+    const shapeValidator = generateShapeValidator(schema, typeName, true, typeSuffix, true, stripUnknown);
     const combinedFunctions = `${shapeValidator}\n\n${parserFunction}`;
     const helpers = collectHelpers(combinedFunctions, helpersMode, options?.helpersImportPrefix);
     const imports = [...collectImports(schema, { selfRef, rootSchema, typeSuffix }), ...helpers.imports];

package/dist/generators/generate-parser-function.d.ts

@@ -21,6 +21,16 @@ type GenerateParserOptions = {
      * undeclared keys throw too; otherwise they are still allowed.
      */
     readonly strict?: boolean;
+    /**
+     * When true, the generated parser builds its result from the schema's declared
+     * properties only, silently dropping any undeclared input key at every nesting
+     * level (zod's `.strip()`). Unlike `additionalProperties: false`, extras are
+     * never a validation error — this composes with `strict`: `strict + stripUnknown`
+     * still throws on wrong types and missing required properties but strips extras
+     * instead of throwing on them. When the schema *also* sets
+     * `additionalProperties: false`, rejecting wins over stripping in strict mode.
+     */
+    readonly stripUnknown?: boolean;
     /**
      * Suffix appended to every type/parser name derived from a `$ref`. Must match
      * the suffix used when generating the referenced files. Defaults to `''`.
@@ -55,5 +65,5 @@ export declare const shapeValidatorFunctionName: (typeName: string) => string;
  * in additionalProperties). The stub is safe: parents calling it will fall
  * through to the slow path, matching the pre-deep-fast-path behavior.
  */
-export declare const generateShapeValidator: (schema: JSONSchema, typeName: string, useRefImports: boolean, suffix?: string, exported?: boolean) => string;
+export declare const generateShapeValidator: (schema: JSONSchema, typeName: string, useRefImports: boolean, suffix?: string, exported?: boolean, stripUnknown?: boolean) => string;
 export {};

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

@@ -530,7 +530,7 @@ const shouldCacheVariable = (propSchema, _canFastPath, _useRefImports) => {
  * - Fast path that returns input directly when all properties are already valid
  * - Slow path with optimized expressions
  */
-const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnings, strict, exported = true) => {
+const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnings, strict, exported = true, stripUnknown = false) => {
     const functionName = generateParserName(typeName);
     const exportPrefix = exported ? 'export ' : '';
     if (!hasProperties(schema)) {
@@ -549,16 +549,22 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
     for (const [key, subName] of subTypeNames) {
         const propSchema = schema.properties[key];
         preamble.push(`type ${subName} = ${typeName}[${JSON.stringify(key)}];`);
-        preamble.push(generateShapeValidator(propSchema, subName, useRefImports, suffix, false));
-        preamble.push(generateObjectParser(propSchema, subName, useRefImports, suffix, logWarnings, strict, false));
+        preamble.push(generateShapeValidator(propSchema, subName, useRefImports, suffix, false, stripUnknown));
+        preamble.push(generateObjectParser(propSchema, subName, useRefImports, suffix, logWarnings, strict, false, stripUnknown));
     }
     // additionalProperties: false — the per-key "is this undeclared" test inlines
     // `!==` comparisons for a short key list and hoists a Set only for a long one
     // (see unknownKeyCheck). The predicate form is shared by the fast path and the
     // shape validator; strict mode throws with the offending key.
+    // `additionalProperties: false` strips *and rejects* extras; `stripUnknown`
+    // only strips them. Both build the result from declared properties alone, so
+    // they share the same machinery (`stripKeys`): drop the `...input` spread and
+    // gate the `{ ...input }` fast path on the known-keys predicate. Only the real
+    // `strictKeys` makes an extra a hard error (the throw block further down).
     const strictKeys = hasStrictKeys(schema);
+    const stripKeys = strictKeys || stripUnknown;
     const strictKeyCheck = unknownKeyCheck(properties.map(([key]) => key), `_knownKeys${typeName}`);
-    if (strictKeys) {
+    if (stripKeys) {
         for (const declaration of strictKeyCheck.declarations) {
             preamble.push(`${declaration};`);
         }
@@ -622,10 +628,11 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
             }
         }
     }
-    // The fast path returns `{ ...input }`, so with additionalProperties: false
-    // it must only fire when no undeclared keys are present. Strict mode already
-    // threw on them above.
-    if (strictKeys && !strict) {
+    // The fast path returns `{ ...input }`, which preserves extras — so when we're
+    // stripping it must only fire when no undeclared key is present. The exception
+    // is strict + additionalProperties: false, where the throw block above already
+    // rejected any extra, so the fast path is safe to take unconditionally.
+    if (stripKeys && !(strict && strictKeys)) {
         fastPathChecks.push(`_hasOnlyKnownKeys${typeName}(input)`);
     }
     // Second pass: generate variable declarations only for properties that need them
@@ -655,10 +662,11 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
         lines.push(`  if (${fastPathExpr}) return { ...input } as ${typeName};`);
     }
     // Generate slow-path object construction. The input spread preserves
-    // undeclared keys, so it is dropped when additionalProperties: false —
-    // building from the declared properties alone strips them from the result.
+    // undeclared keys, so it is dropped whenever we're stripping (either
+    // additionalProperties: false or stripUnknown) — building from the declared
+    // properties alone strips the extras from the result.
     const objectLines = [];
-    if (!strictKeys) {
+    if (!stripKeys) {
         objectLines.push('    ...input,');
     }
     // Spread allOf $ref parsers so their field coercions are applied before
@@ -811,7 +819,7 @@ ${loopLines.join('\n')}
  * Generates a parser for schemas that have both properties AND patternProperties.
  * Parses the known properties first, then iterates remaining keys to match patterns.
  */
-const generateCombinedObjectParser = (schema, typeName, useRefImports, suffix, logWarnings, strict) => {
+const generateCombinedObjectParser = (schema, typeName, useRefImports, suffix, logWarnings, strict, stripUnknown = false) => {
     const functionName = generateParserName(typeName);
     const entries = generatePropertyEntries(schema, useRefImports, suffix);
     // Build the known property lines for the initial object
@@ -823,7 +831,7 @@ const generateCombinedObjectParser = (schema, typeName, useRefImports, suffix, l
     });
     // Find the first pattern with a $ref for parser delegation
     if (!isSchemaObject(schema) || !('patternProperties' in schema)) {
-        return generateObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict);
+        return generateObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict, true, stripUnknown);
     }
     const patternProps = schema.patternProperties;
     const patterns = Object.entries(patternProps);
@@ -837,7 +845,7 @@ const generateCombinedObjectParser = (schema, typeName, useRefImports, suffix, l
         return generateStrictCombinedParser(schema, typeName, functionName, propertyLines, patterns, useRefImports, suffix, strict);
     }
     if (!refPattern || !useRefImports) {
-        return generateObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict);
+        return generateObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict, true, stripUnknown);
     }
     const [pattern, patternSchema] = refPattern;
     const ref = patternSchema.$ref;
@@ -1016,7 +1024,7 @@ ${notObjectBranch}
  * This always generates parser calls regardless of useRefImports setting,
  * because conditional logic requires delegating to the appropriate parser.
  */
-const generateConditionalParser = (schema, typeName, suffix) => {
+const generateConditionalParser = (schema, typeName, suffix, stripUnknown = false) => {
     const functionName = generateParserName(typeName);
     // Extract the condition and branches
     const ifSchema = schema.if;
@@ -1031,7 +1039,7 @@ const generateConditionalParser = (schema, typeName, suffix) => {
         // regular object parser from the merged property set.
         const mergedSchema = getConditionalObjectSchema(schema);
         if (mergedSchema) {
-            return generateObjectParser(mergedSchema, typeName, false, suffix);
+            return generateObjectParser(mergedSchema, typeName, false, suffix, false, false, true, stripUnknown);
         }
         return generateEmptyObjectParser(typeName);
     }
@@ -1045,7 +1053,7 @@ const generateConditionalParser = (schema, typeName, suffix) => {
         // Condition is not a $ref check — flatten into an object parser
         const mergedSchema = getConditionalObjectSchema(schema);
         if (mergedSchema) {
-            return generateObjectParser(mergedSchema, typeName, false, suffix);
+            return generateObjectParser(mergedSchema, typeName, false, suffix, false, false, true, stripUnknown);
         }
         return generateEmptyObjectParser(typeName);
     }
@@ -1140,6 +1148,7 @@ const selectParserStrategy = (schema, typeName, options) => {
     const useRefImports = options?.useRefImports ?? false;
     const logWarnings = options?.logWarnings ?? false;
     const strict = options?.strict ?? false;
+    const stripUnknown = options?.stripUnknown ?? false;
     const suffix = options?.typeSuffix ?? '';
     // Special case for the self-referential JSON Schema meta-schema type (e.g.
     // `Schema` / `SchemaObject`) - it can be any JSON Schema.
@@ -1156,24 +1165,24 @@ const selectParserStrategy = (schema, typeName, options) => {
     // This generates a parser that handles known properties and also iterates
     // pattern-matched keys (e.g. responses with "default" + "200", "4XX").
     if (hasProperties(schema) && isSchemaObject(schema) && 'patternProperties' in schema) {
-        return generateCombinedObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict);
+        return generateCombinedObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict, stripUnknown);
     }
     // Handle schemas that have explicit properties — generate a full object parser.
     // This intentionally runs before if/then checks so that schemas with both
     // properties AND conditional keywords use all declared properties rather than
     // only the if/then fragment.
     if (hasProperties(schema)) {
-        return generateObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict);
+        return generateObjectParser(schema, typeName, useRefImports, suffix, logWarnings, strict, true, stripUnknown);
     }
     // Handle conditional schemas (if/then/else) for schemas without explicit properties.
     if (isSchemaObject(schema) && 'if' in schema && 'then' in schema && 'else' in schema) {
-        return generateConditionalParser(schema, typeName, suffix);
+        return generateConditionalParser(schema, typeName, suffix, stripUnknown);
     }
     // Handle conditional schemas that only define if/then object fragments.
     // We flatten the fragments into a regular object parser.
     const conditionalObjectSchema = getConditionalObjectSchema(schema);
     if (conditionalObjectSchema) {
-        return generateObjectParser(conditionalObjectSchema, typeName, useRefImports, suffix, logWarnings, strict);
+        return generateObjectParser(conditionalObjectSchema, typeName, useRefImports, suffix, logWarnings, strict, true, stripUnknown);
     }
     // Handle non-object schemas with type-appropriate validation (no properties, no conditionals)
     if (!isObjectLikeSchema) {
@@ -1230,7 +1239,7 @@ export const shapeValidatorFunctionName = (typeName) => shapeValidatorName(typeN
  * in additionalProperties). The stub is safe: parents calling it will fall
  * through to the slow path, matching the pre-deep-fast-path behavior.
  */
-export const generateShapeValidator = (schema, typeName, useRefImports, suffix = '', exported = true) => {
+export const generateShapeValidator = (schema, typeName, useRefImports, suffix = '', exported = true, stripUnknown = false) => {
     const fnName = shapeValidatorName(typeName);
     const exportPrefix = exported ? 'export ' : '';
     const stub = `${exportPrefix}const ${fnName} = (_input: unknown): boolean => false;`;
@@ -1253,9 +1262,12 @@ export const generateShapeValidator = (schema, typeName, useRefImports, suffix =
     // Same deterministic naming as the parser's sub-parser generation, so the
     // referenced private shape predicates exist in the same file.
     const subTypeNames = collectInlineObjectProperties(schema, typeName);
-    // With additionalProperties: false the shape only matches when every key is
-    // declared, so the parser's fast path will not smuggle extras through.
-    const strictKeysGuard = hasStrictKeys(schema) ? `\n  if (!_hasOnlyKnownKeys${typeName}(input)) return false;` : '';
+    // When the parser strips extras (additionalProperties: false or stripUnknown),
+    // an input carrying an undeclared key is *not* fast-path eligible — the parser
+    // would strip it rather than return `{ ...input }` — so the shape only matches
+    // when every key is declared. (The `_hasOnlyKnownKeys` predicate this calls is
+    // emitted by the parser under the same `stripKeys` condition.)
+    const strictKeysGuard = hasStrictKeys(schema) || stripUnknown ? `\n  if (!_hasOnlyKnownKeys${typeName}(input)) return false;` : '';
     const checks = [];
     for (const [key, propSchema] of properties) {
         // Records of refs require iterating every value — too expensive for the fast path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-parsers",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Generate TypeScript parsers and type definitions from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -32,7 +32,8 @@
     "build": "tsgo -p tsconfig.build.json && tsc-alias -p tsconfig.build.json -f",
     "types:check": "tsgo -p . --noEmit",
     "test": "NODE_ENV=production vitest run --root ../.. generate-parsers",
-    "generate-readme": "bun run ./scripts/generate-readme.ts"
+    "generate-readme": "bun run ./scripts/generate-readme.ts",
+    "bench": "bun --conditions development ./bench/run.ts"
   },
   "imports": {
     "#generators/*": "./src/generators/*.ts",
@@ -49,5 +50,9 @@
     "json-schema-typed": "^8.0.1",
     "@amritk/helpers": "0.10.0",
     "@amritk/generate-markdown": "0.2.4"
+  },
+  "devDependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "zod": "^4.4.3"
   }
 }