@amritk/generate-parsers 0.9.0 → 0.11.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,38 +549,32 @@ 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};`);
         }
         preamble.push(`const _hasOnlyKnownKeys${typeName} = (input: Record<string, unknown>): boolean => {\n  for (const _k in input) if (${strictKeyCheck.isUnknown('_k')}) return false;\n  return true;\n};`);
     }
     const fallbackObject = generateFallbackObject(schema, useRefImports, typeName, suffix, subTypeNames);
-    const lines = [];
-    lines.push(`${exportPrefix}const ${functionName} = (input: unknown): ${typeName} => {`);
-    if (strict) {
-        for (const assertionLine of generateObjectStrictAssertion(schema, typeName)) {
-            lines.push(assertionLine);
-        }
-        if (strictKeys) {
-            lines.push(`  for (const _k in input) {`);
-            lines.push(`    if (${strictKeyCheck.isUnknown('_k')}) throw new Error(\`[${typeName}] unknown property "\${_k}"\`);`);
-            lines.push(`  }`);
-        }
-    }
-    else {
-        lines.push(`  if (!isObject(input)) return ${fallbackObject};`);
-    }
-    // First pass: determine if we can generate a fast path
+    // First pass: gather per-property info and decide whether a fast path is
+    // possible. A fast path returns the input (or a direct strip-build) for
+    // already-valid input without re-running per-property validation, so it may
+    // only fire when every property can be cheaply proven in-shape.
     const propInfo = [];
     // Disable fast path when allOf $ref parsers need to be spread — the fast path
     // returns input as-is and would skip those coercions.
@@ -594,160 +588,259 @@ const generateObjectParser = (schema, typeName, useRefImports, suffix, logWarnin
         const isRequired = isPropertyRequired(key, schema);
         const varName = toVarName(key);
         propInfo.push({ key, varName, isRequired, propSchema });
-        // Check if this property can participate in fast path
-        if (canFastPath) {
-            // Records of refs require iterating every value to check shape — too
-            // expensive to inline into the parser's fast path. Disable.
-            if (shouldUseRecordRefImport(propSchema, useRefImports)) {
-                canFastPath = false;
+        if (!canFastPath)
+            continue;
+        // Records of refs require iterating every value to check shape — too
+        // expensive to inline into the parser's fast path. Disable.
+        if (shouldUseRecordRefImport(propSchema, useRefImports)) {
+            canFastPath = false;
+            continue;
+        }
+        const subName = subTypeNames.get(key);
+        // Inline nested objects fast-path through their private shape predicate, the
+        // same way $ref properties use the imported one.
+        const check = subName
+            ? `${shapeValidatorName(subName)}(${varName})`
+            : generatePropertyTypeCheck(varName, propSchema, useRefImports, suffix);
+        if (check === null) {
+            canFastPath = false;
+        }
+        else if (isRequired) {
+            fastPathChecks.push(check);
+        }
+        else {
+            fastPathChecks.push(`(${varName} === undefined || ${check})`);
+        }
+    }
+    // The `{ ...input }` fast path preserves extras, so when stripping it may only
+    // fire on inputs that carry no undeclared key. For strict + additionalProperties:
+    // false the cold path rejects extras instead; folding the known-keys term into
+    // the guard lets the guard run *before* that rejection, so a valid clean input
+    // never pays for the per-property assertions.
+    if (stripKeys) {
+        fastPathChecks.push(`_hasOnlyKnownKeys${typeName}(input)`);
+    }
+    // The deep guard proves the whole shape (so `{ ...input }` can be returned),
+    // using the nested shape predicates and the known-keys term above.
+    const deepGuard = canFastPath && fastPathChecks.length > 0 ? fastPathChecks.join(' && ') : null;
+    // The shallow guard powers the strict strip-build fast path (stripUnknown
+    // without additionalProperties: false): it proves every scalar is well-typed
+    // and every nested object is an object, but neither walks nested shapes deeply
+    // nor requires the absence of extras. That lets it fire on the common
+    // stripUnknown input — which carries extras the build removes, and nested
+    // extras each sub-parser removes — while the cold path's per-property
+    // assertions still produce the precise error on a genuine mismatch.
+    let canShallowGuard = strict && stripUnknown && !strictKeys;
+    const shallowChecks = [];
+    if (canShallowGuard) {
+        for (const { key, varName, isRequired, propSchema } of propInfo) {
+            const subName = subTypeNames.get(key);
+            let check;
+            if (subName) {
+                // Nested inline object: a shallow `isObject` is enough — the sub-parser
+                // validates and strips it.
+                check = `isObject(${varName})`;
+            }
+            else if (isSchemaObject(propSchema) &&
+                !hasEnum(propSchema) &&
+                !hasRef(propSchema) &&
+                !hasOneOf(propSchema) &&
+                !hasAnyOf(propSchema) &&
+                !hasAllOf(propSchema) &&
+                !('not' in propSchema) &&
+                !shouldUseRefImport(propSchema, useRefImports) &&
+                !shouldUseArrayRefImport(propSchema, useRefImports) &&
+                !shouldUseRecordRefImport(propSchema, useRefImports)) {
+                // Plain scalar / array / object: its own type check is already shallow
+                // (arrays are not walked, objects only `isObject`-checked).
+                check = generatePropertyTypeCheck(varName, propSchema, useRefImports, suffix);
             }
             else {
-                const subName = subTypeNames.get(key);
-                // Inline nested objects fast-path through their private shape
-                // predicate, the same way $ref properties use the imported one.
-                const check = subName
-                    ? `${shapeValidatorName(subName)}(${varName})`
-                    : generatePropertyTypeCheck(varName, propSchema, useRefImports, suffix);
-                if (check === null) {
-                    canFastPath = false;
-                }
-                else {
-                    if (isRequired) {
-                        fastPathChecks.push(check);
-                    }
-                    else {
-                        fastPathChecks.push(`(${varName} === undefined || ${check})`);
-                    }
-                }
+                check = null;
+            }
+            if (check === null) {
+                canShallowGuard = false;
+                break;
             }
+            shallowChecks.push(isRequired ? check : `(${varName} === undefined || ${check})`);
         }
     }
-    // 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) {
-        fastPathChecks.push(`_hasOnlyKnownKeys${typeName}(input)`);
-    }
-    // Second pass: generate variable declarations only for properties that need them
+    const shallowGuard = canShallowGuard && shallowChecks.length > 0 ? shallowChecks.join(' && ') : null;
+    // Variable declarations for properties that need them (the build and guards
+    // read each cached value once instead of re-accessing `input`).
+    const varDeclLines = [];
     for (const { key, varName, propSchema } of propInfo) {
         if (shouldCacheVariable(propSchema, canFastPath, useRefImports)) {
-            lines.push(`  const ${varName} = ${safeAccessor('input', key)};`);
+            varDeclLines.push(`  const ${varName} = ${safeAccessor('input', key)};`);
         }
     }
-    // Emit a warning for any input key not declared in the schema's properties
+    // Emit a warning for any input key not declared in the schema's properties.
+    const warnLines = [];
     if (logWarnings && propInfo.length > 0) {
         const warnKeyCheck = unknownKeyCheck(propInfo.map(({ key }) => key), '_knownKeys');
         for (const declaration of warnKeyCheck.declarations) {
-            lines.push(`  ${declaration};`);
+            warnLines.push(`  ${declaration};`);
         }
-        lines.push(`  for (const _k in input) {`);
-        lines.push(`    if (${warnKeyCheck.isUnknown('_k')}) {`);
-        lines.push(`      console.warn(\`[${typeName}] Unknown property "\${_k}"\`);`);
-        lines.push(`    }`);
-        lines.push(`  }`);
-    }
-    // Generate fast-path check if possible
-    if (canFastPath && fastPathChecks.length > 0) {
-        let fastPathExpr = fastPathChecks[0];
-        for (let i = 1; i < fastPathChecks.length; i++) {
-            fastPathExpr += ' && ' + fastPathChecks[i];
+        warnLines.push(`  for (const _k in input) {`);
+        warnLines.push(`    if (${warnKeyCheck.isUnknown('_k')}) {`);
+        warnLines.push(`      console.warn(\`[${typeName}] Unknown property "\${_k}"\`);`);
+        warnLines.push(`    }`);
+        warnLines.push(`  }`);
+    }
+    // Builds the result object literal. `directAssign` (strict mode) assigns each
+    // field straight from its cached read — the guard or the per-property
+    // assertions have already proven the type, so no coercion ternary is needed.
+    // Coerce mode keeps the type-checking-and-coercing expression. Refs, arrays of
+    // refs, records of refs and inline nested objects always delegate to their
+    // parser in both modes; the input spread is dropped whenever stripping.
+    const buildObjectLines = (directAssign) => {
+        const objectLines = [];
+        if (!stripKeys) {
+            objectLines.push('    ...input,');
         }
-        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.
-    const objectLines = [];
-    if (!strictKeys) {
-        objectLines.push('    ...input,');
-    }
-    // Spread allOf $ref parsers so their field coercions are applied before
-    // the explicit property validations below.
-    if (useRefImports && isSchemaObject(schema) && hasAllOf(schema)) {
-        for (const entry of schema.allOf) {
-            if (isSchemaObject(entry) && hasRef(entry)) {
-                const parserName = generateParserName(refToName(entry.$ref, suffix));
-                objectLines.push(`    ...(${parserName}(input) as Record<string, unknown>),`);
+        // Spread allOf $ref parsers so their field coercions are applied before
+        // the explicit property validations below.
+        if (useRefImports && isSchemaObject(schema) && hasAllOf(schema)) {
+            for (const entry of schema.allOf) {
+                if (isSchemaObject(entry) && hasRef(entry)) {
+                    const parserName = generateParserName(refToName(entry.$ref, suffix));
+                    objectLines.push(`    ...(${parserName}(input) as Record<string, unknown>),`);
+                }
             }
         }
-    }
-    for (const { key, varName, isRequired, propSchema } of propInfo) {
-        const shouldCache = shouldCacheVariable(propSchema, canFastPath, useRefImports);
-        const accessor = shouldCache ? varName : safeAccessor('input', key);
-        // Handle inline nested objects via their private sub-parser, mirroring
-        // how $ref properties delegate to the imported parser.
-        const subName = subTypeNames.get(key);
-        if (subName) {
-            const subParserName = generateParserName(subName);
-            if (isRequired) {
-                objectLines.push(`    ${safeKey(key)}: ${subParserName}(${accessor}),`);
+        for (const { key, varName, isRequired, propSchema } of propInfo) {
+            const shouldCache = shouldCacheVariable(propSchema, canFastPath, useRefImports);
+            const accessor = shouldCache ? varName : safeAccessor('input', key);
+            // Handle inline nested objects via their private sub-parser, mirroring
+            // how $ref properties delegate to the imported parser.
+            const subName = subTypeNames.get(key);
+            if (subName) {
+                const subParserName = generateParserName(subName);
+                if (isRequired) {
+                    objectLines.push(`    ${safeKey(key)}: ${subParserName}(${accessor}),`);
+                }
+                else {
+                    objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: ${subParserName}(${accessor}) }),`);
+                }
+                continue;
             }
-            else {
-                objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: ${subParserName}(${accessor}) }),`);
+            // Handle direct $ref properties via imported parsers
+            if (shouldUseRefImport(propSchema, useRefImports)) {
+                const ref = propSchema.$ref;
+                const parserName = generateParserName(refToName(ref, suffix));
+                if (isRequired) {
+                    objectLines.push(`    ${safeKey(key)}: ${parserName}(${accessor}),`);
+                }
+                else {
+                    objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: ${parserName}(${accessor}) }),`);
+                }
+                continue;
             }
-            continue;
-        }
-        // Handle direct $ref properties via imported parsers
-        if (shouldUseRefImport(propSchema, useRefImports)) {
-            const ref = propSchema.$ref;
-            const parserName = generateParserName(refToName(ref, suffix));
-            if (isRequired) {
-                objectLines.push(`    ${safeKey(key)}: ${parserName}(${accessor}),`);
+            // Handle array properties with $ref items
+            if (shouldUseArrayRefImport(propSchema, useRefImports)) {
+                const items = propSchema.items;
+                const ref = items.$ref;
+                const parserName = generateParserName(refToName(ref, suffix));
+                if (isRequired) {
+                    objectLines.push(`    ${safeKey(key)}: validateArray(${accessor}, ${parserName}),`);
+                }
+                else {
+                    objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: validateArray(${accessor}, ${parserName}) }),`);
+                }
+                continue;
             }
-            else {
-                objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: ${parserName}(${accessor}) }),`);
+            // Handle object properties with additionalProperties $ref
+            if (shouldUseRecordRefImport(propSchema, useRefImports)) {
+                const additionalProps = propSchema.additionalProperties;
+                const ref = additionalProps.$ref;
+                const parserName = generateParserName(refToName(ref, suffix));
+                if (isRequired) {
+                    objectLines.push(`    ${safeKey(key)}: validateRecord(${accessor}, ${parserName}),`);
+                }
+                else {
+                    objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: validateRecord(${accessor}, ${parserName}) }),`);
+                }
+                continue;
             }
-            continue;
-        }
-        // Handle array properties with $ref items
-        if (shouldUseArrayRefImport(propSchema, useRefImports)) {
-            const items = propSchema.items;
-            const ref = items.$ref;
-            const parserName = generateParserName(refToName(ref, suffix));
-            if (isRequired) {
-                objectLines.push(`    ${safeKey(key)}: validateArray(${accessor}, ${parserName}),`);
+            // Handle non-schema-object properties
+            if (!isSchemaObject(propSchema)) {
+                if (isRequired) {
+                    objectLines.push(`    ${safeKey(key)}: undefined,`);
+                }
+                continue;
+            }
+            // Strict mode has already proven the value's type (by guard or assertion),
+            // so the field is assigned straight from the cached read with no coercion.
+            let valueExpr;
+            if (directAssign) {
+                valueExpr = accessor;
             }
             else {
-                objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: validateArray(${accessor}, ${parserName}) }),`);
+                const defaultValue = getDefaultValue(propSchema);
+                // For optional properties we know the value is not undefined because
+                // we're inside the `...(accessor !== undefined && { ... })` check.
+                const knownNotUndefined = !isRequired;
+                valueExpr = generateValidationExpression(key, propSchema, defaultValue, true, undefined, undefined, shouldCache ? varName : undefined, knownNotUndefined);
             }
-            continue;
-        }
-        // Handle object properties with additionalProperties $ref
-        if (shouldUseRecordRefImport(propSchema, useRefImports)) {
-            const additionalProps = propSchema.additionalProperties;
-            const ref = additionalProps.$ref;
-            const parserName = generateParserName(refToName(ref, suffix));
             if (isRequired) {
-                objectLines.push(`    ${safeKey(key)}: validateRecord(${accessor}, ${parserName}),`);
+                objectLines.push(`    ${safeKey(key)}: ${valueExpr},`);
             }
             else {
-                objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: validateRecord(${accessor}, ${parserName}) }),`);
+                objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: ${valueExpr} }),`);
             }
-            continue;
         }
-        // Handle non-schema-object properties
-        if (!isSchemaObject(propSchema)) {
-            if (isRequired) {
-                objectLines.push(`    ${safeKey(key)}: undefined,`);
+        return objectLines;
+    };
+    const emitReturn = (lines, objectLines) => {
+        lines.push(`  return {`);
+        lines.push(objectLines.join('\n'));
+        lines.push(`  } as unknown as ${typeName};`);
+    };
+    const lines = [];
+    lines.push(`${exportPrefix}const ${functionName} = (input: unknown): ${typeName} => {`);
+    if (strict) {
+        // Guard first: a non-object throws straight away; a clean, well-typed input
+        // then short-circuits past the per-property assertions, which only run to
+        // pinpoint the failure when the guard rejects the input.
+        lines.push(`  if (!isObject(input)) throw new Error(\`[${typeName}] expected object, got \${input === null ? "null" : typeof input}\`);`);
+        lines.push(...varDeclLines);
+        lines.push(...warnLines);
+        // The first assertion line is the `isObject` check, already done above.
+        const assertionLines = generateObjectStrictAssertion(schema, typeName).slice(1);
+        if (shallowGuard) {
+            // stripUnknown: a well-typed input skips the assertions and goes straight
+            // to the strip build (which removes extras and recurses into sub-parsers).
+            lines.push(`  if (!(${shallowGuard})) {`);
+            for (const assertionLine of assertionLines) {
+                lines.push(`  ${assertionLine}`);
             }
-            continue;
-        }
-        // Generate validation expression
-        const defaultValue = getDefaultValue(propSchema);
-        // For optional properties in the slow path, we know the value is not undefined
-        // because we're inside the `...(accessor !== undefined && { ... })` check
-        const knownNotUndefined = !isRequired;
-        const valueExpr = generateValidationExpression(key, propSchema, defaultValue, true, undefined, undefined, shouldCache ? varName : undefined, knownNotUndefined);
-        if (isRequired) {
-            objectLines.push(`    ${safeKey(key)}: ${valueExpr},`);
+            lines.push(`  }`);
+            emitReturn(lines, buildObjectLines(true));
         }
         else {
-            objectLines.push(`    ...(${accessor} !== undefined && { ${safeKey(key)}: ${valueExpr} }),`);
+            if (deepGuard) {
+                lines.push(`  if (${deepGuard}) return { ...input } as ${typeName};`);
+            }
+            for (const assertionLine of assertionLines) {
+                lines.push(assertionLine);
+            }
+            if (strictKeys) {
+                lines.push(`  for (const _k in input) {`);
+                lines.push(`    if (${strictKeyCheck.isUnknown('_k')}) throw new Error(\`[${typeName}] unknown property "\${_k}"\`);`);
+                lines.push(`  }`);
+            }
+            emitReturn(lines, buildObjectLines(true));
+        }
+    }
+    else {
+        lines.push(`  if (!isObject(input)) return ${fallbackObject};`);
+        lines.push(...varDeclLines);
+        lines.push(...warnLines);
+        if (deepGuard) {
+            lines.push(`  if (${deepGuard}) return { ...input } as ${typeName};`);
         }
+        emitReturn(lines, buildObjectLines(false));
     }
-    lines.push(`  return {`);
-    lines.push(objectLines.join('\n'));
-    lines.push(`  } as unknown as ${typeName};`);
     lines.push(`}`);
     const fn = lines.join('\n');
     if (preamble.length === 0)
@@ -811,7 +904,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 +916,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 +930,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 +1109,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 +1124,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 +1138,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 +1233,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 +1250,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 +1324,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 +1347,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.11.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"
   }
 }