@amritk/generate-parsers 0.1.0 → 0.3.0

package/README.md

@@ -75,7 +75,7 @@ Write them to disk however you like.
 
 ## API
 
-### `buildSchema(rootSchema, rootTypeName, extensions?, typesOnly?, logWarnings?)`
+### `buildSchema(rootSchema, rootTypeName, extensions?, typesOnly?, logWarnings?, strict?)`
 
 | Parameter | Type | Description |
 |:---|:---|:---|
@@ -84,6 +84,7 @@ Write them to disk however you like.
 | `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. |
 
 Returns: `Promise<GeneratedFile[]>`.
 
@@ -96,6 +97,7 @@ Returns: `Promise<GeneratedFile[]>`.
 |:---:|:---|:---|:---:|:---:|:---:|:---|
 | 🏷️ | `typesOnly` | — | `boolean` | — | `false` | Generate only TypeScript type definitions without parser functions. Runtime helper files (validators, isObject) are also omitted since they are only needed for parsers. |
 | ⚠️ | `logWarnings` | — | `boolean` | — | `false` | Emit a console.warn in the generated parsers for every input key that is not declared in the schema's properties. Useful for detecting schema drift or unexpected data shapes at runtime. |
+| 🚫 | `strict` | — | `boolean` | — | `false` | 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. Unknown extra keys are still allowed. |
 <!-- config-table-end -->
 
 The generator handles:

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

@@ -1,4 +1,5 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import type { HelpersMode } from '#helpers/collect-helpers';
 import type { SchemaExtensions } from '#types/schema-extensions';
 /**
  * Represents a generated file with its filename and content.
@@ -27,6 +28,12 @@ export type GeneratedFile = {
  * @param typesOnly - When true, only generate TypeScript type definitions without parser functions.
  * @param logWarnings - When true, the generated parsers emit a console.warn for every input key
  *   that is not declared in the schema's properties.
+ * @param strict - When true, the 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.
+ * @param helpersMode - `'package'` (default) emits `import ... from '@amritk/helpers/...'`.
+ *   `'embedded'` emits `import ... from './_helpers/...'` and appends the helper sources
+ *   as additional `GeneratedFile` entries so the output directory is self-contained.
  * @returns An array of generated TypeScript files
  *
  * @example
@@ -59,4 +66,4 @@ export type GeneratedFile = {
  * });
  * ```
  */
-export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean) => Promise<GeneratedFile[]>;
+export declare const buildSchema: (rootSchema: JSONSchema, rootTypeName: string, extensions?: SchemaExtensions, typesOnly?: boolean, logWarnings?: boolean, strict?: boolean, helpersMode?: HelpersMode) => Promise<GeneratedFile[]>;

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

@@ -1,4 +1,5 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import { type HelpersMode, type RuntimeHelperName } from '#helpers/collect-helpers';
 /**
  * Options for controlling what gets generated in a file.
  */
@@ -24,6 +25,23 @@ type GenerateFileOptions = {
      * that is not declared in the schema's properties.
      */
     readonly logWarnings?: boolean;
+    /**
+     * When true, the generated parser throws on type/shape mismatches instead
+     * of coercing invalid input to default values.
+     */
+    readonly strict?: boolean;
+    /**
+     * Controls how runtime helpers are referenced.
+     * - `'package'` (default): emit imports from `@amritk/helpers/...`.
+     * - `'embedded'`: emit imports from `./_helpers/...` so the helper sources can
+     *   be shipped alongside the generated files.
+     */
+    readonly helpersMode?: HelpersMode;
+};
+/** Result of generating a single parser file. */
+export type GeneratedFileContent = {
+    readonly content: string;
+    readonly usedHelpers: ReadonlySet<RuntimeHelperName>;
 };
 /**
  * Generates a complete TypeScript file from a JSON Schema.
@@ -34,7 +52,7 @@ type GenerateFileOptions = {
  * @param schema - The JSON Schema to generate code from
  * @param typeName - The name to use for the generated TypeScript type
  * @param options - Optional settings to control what gets generated
- * @returns The complete TypeScript code
+ * @returns The generated file content and the set of runtime helpers it references
  *
  * @example
  * ```typescript
@@ -54,5 +72,5 @@ type GenerateFileOptions = {
  * // typesOnly contains only type-only imports and type User (no parser)
  * ```
  */
-export declare const generateFile: (schema: JSONSchema, typeName: string, options?: GenerateFileOptions) => string;
+export declare const generateFile: (schema: JSONSchema, typeName: string, options?: GenerateFileOptions) => GeneratedFileContent;
 export {};

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

@@ -14,6 +14,12 @@ type GenerateParserOptions = {
      * that is not declared in the schema's properties.
      */
     readonly logWarnings?: boolean;
+    /**
+     * When true, the generated parser throws on type/shape mismatches instead
+     * of coercing invalid input to default values. Throws on the first violation
+     * with a path-aware Error. Unknown extra keys are still allowed.
+     */
+    readonly strict?: boolean;
 };
 /**
  * Generates a safe parser as an arrow function that never throws.

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

@@ -0,0 +1,18 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Generates strict-mode assertions for the body of an object parser.
+ * Throws on:
+ *   - non-object input
+ *   - missing required property
+ *   - property of the wrong primitive type
+ *   - enum / pattern / length / min / max / multipleOf violations
+ *
+ * Properties with a `$ref` are validated by the nested parser's own strict
+ * check when that parser is invoked downstream.
+ */
+export declare const generateObjectStrictAssertion: (schema: JSONSchema, typeName: string) => string[];
+/**
+ * Generates a single strict-mode assertion line for a non-object scalar parser.
+ * Returns null when the schema has no type information to assert on.
+ */
+export declare const generateScalarStrictAssertion: (schema: JSONSchema, typeName: string) => string | null;

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

@@ -1,2 +1,16 @@
-/** A more foolproof way to generate imports from the parserFunction */
-export declare const collectHelpers: (parserFunction: string) => string[];
+/** Names (without `.ts`) of runtime helpers that can be embedded into generated output. */
+export type RuntimeHelperName = 'is-object' | 'validate-array' | 'validate-record' | 'has-ref';
+/** Controls how generated parsers reference their runtime helpers. */
+export type HelpersMode = 'package' | 'embedded';
+export type CollectedHelpers = {
+    /** Import lines to splice into the generated file. */
+    readonly imports: string[];
+    /**
+     * Helper names that need to ship alongside the generated file in embedded mode.
+     * Includes transitive deps (e.g. `validate-record` pulls in `is-object`) so the
+     * orchestrator can emit a complete `_helpers/` directory.
+     */
+    readonly used: Set<RuntimeHelperName>;
+};
+/** Detects which runtime helpers a generated parser body references. */
+export declare const collectHelpers: (parserFunction: string, mode: HelpersMode) => CollectedHelpers;