@amritk/validation 0.2.0

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

@@ -0,0 +1,120 @@
+import { type UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling parser function generation behavior.
+ */
+type GenerateParserOptions = {
+    /**
+     * When true, properties with $ref will call the imported parser function
+     * instead of inlining the validation logic. This is used when generating
+     * files where each ref has its own separate file with a parser.
+     */
+    readonly useRefImports?: boolean;
+    /**
+     * When true, the generated parser emits a console.warn for every input key
+     * 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. When the schema sets `additionalProperties: false`,
+     * 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 `''`.
+     */
+    readonly typeSuffix?: string;
+    /**
+     * The root schema document. When present, a top-level `oneOf`/`anyOf` whose
+     * branches are `$ref`s can be resolved to find a shared discriminator and emit a
+     * dispatch to the branch parsers, instead of falling back to a passthrough cast.
+     */
+    readonly rootSchema?: Record<string, unknown>;
+    /**
+     * Type names the generated file imports for its `$ref`s. Synthesized private
+     * sub-type names (nested objects, array items, the root array's `{Type}Item`)
+     * dedup against this set so they can never shadow an imported identifier —
+     * which would both fail to compile (duplicate declaration) and silently
+     * validate against the wrong schema.
+     */
+    readonly reservedNames?: ReadonlySet<string>;
+    /**
+     * True when this schema is the root document (not a `$ref`-reached definition).
+     * The root type name is user-derived (schema `title`, filename, or `--root-type`),
+     * so the JSON Schema meta-schema special case — keyed on the literal name
+     * `Schema` — must not apply to it, or a common `schema.json` root would silently
+     * generate a validation-free pass-through parser.
+     */
+    readonly isRoot?: boolean;
+    /**
+     * When true, a mis-cased string that matches a declared `enum`/`const` member
+     * case-insensitively is normalized to that member's exact casing (e.g. `hElLo`
+     * → `hello`) instead of coercing to the default. Coerce mode only — strict
+     * parsers still reject a casing mismatch. The normalization lives on the
+     * failure branch of the coercion ternary, so a correctly-cased value keeps the
+     * exact `===` fast path and the hot path is unaffected.
+     */
+    readonly caseInsensitive?: boolean;
+    /**
+     * How the fast paths prove a closed object carries no undeclared key —
+     * `Object.getPrototypeOf(input) === Object.prototype && Object.keys(input).length`
+     * (the default) or a `for…in` count. See {@link UnknownKeysStrategy} for the
+     * trade-off, and {@link keyCountCheck} for what each form emits.
+     */
+    readonly unknownKeys?: UnknownKeysStrategy;
+    /**
+     * The exact source of the `validate{TypeName}Shape` predicate emitted into
+     * the same file as this parser (generate-files produces it for the root
+     * type). When the parser can prove — by rendering the predicate it would
+     * need and comparing byte-for-byte — that this emitted predicate tests
+     * exactly its own fast-path guard, it emits `validate{TypeName}Shape(input)`
+     * instead of a second inline copy of the whole check chain, which roughly
+     * halves the emitted checks per object type. Any mismatch (composition
+     * keywords, conditional flattening, alias/union predicates, stubs) keeps
+     * the inline guard, so a wrong substitution is impossible by construction.
+     */
+    readonly shapeValidatorSource?: string;
+};
+/**
+ * Generates a safe parser as an arrow function that never throws.
+ * The parser provides default values for all missing or invalid fields.
+ *
+ * When useRefImports is enabled, properties with $ref will call the imported
+ * parser function (e.g., parseContact(input?.contact)) instead of inlining
+ * the resolved schema's validation logic. Array properties whose items are a
+ * $ref will map each element through the imported parser.
+ */
+export declare const generateParserFunction: (schema: JSONSchema, typeName: string, rawOptions?: GenerateParserOptions) => string;
+/**
+ * Returns the predicate function name for a generated shape validator.
+ * @example shapeValidatorFunctionName('CustomerObject') // 'validateCustomerObjectShape'
+ */
+export declare const shapeValidatorFunctionName: (typeName: string) => string;
+/**
+ * Generates a `validate{TypeName}Shape(input)` predicate that returns true
+ * iff `input` already matches the shape produced by the parser's fast path —
+ * i.e. the parser would return `{ ...input } as TypeName` without coercion.
+ *
+ * Parents call this predicate to fast-path through nested ref properties
+ * (and arrays of refs) without recursing into their parser.
+ *
+ * Returns a stub that always returns `false` for schemas that cannot be
+ * predicated (composition, conditionals, pattern properties, complex refs
+ * 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, stripUnknown?: boolean, reservedNames?: ReadonlySet<string>, unknownKeys?: UnknownKeysStrategy) => string;
+export {};