json-schema-compatibility-checker 1.1.1 → 1.1.2

package/dist/cjs/types.d.ts

@@ -1,4 +1,9 @@
 import type { JSONSchema7, JSONSchema7Definition } from "json-schema";
+declare module "json-schema" {
+    interface JSONSchema7 {
+        constraints?: Constraints;
+    }
+}
 export interface SchemaError {
     /** Normalized path to the concerned property (e.g. "user.name", "users[].name", "accountId") */
     key: string;

package/dist/esm/types.d.ts

@@ -1,4 +1,9 @@
 import type { JSONSchema7, JSONSchema7Definition } from "json-schema";
+declare module "json-schema" {
+    interface JSONSchema7 {
+        constraints?: Constraints;
+    }
+}
 export interface SchemaError {
     /** Normalized path to the concerned property (e.g. "user.name", "users[].name", "accountId") */
     key: string;

package/dist/esm/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types.ts"],"sourcesContent":["import type { JSONSchema7, JSONSchema7Definition } from \"json-schema\";\n\n// ─── Public types ────────────────────────────────────────────────────────────\n\nexport interface SchemaError {\n\t/** Normalized path to the concerned property (e.g. \"user.name\", \"users[].name\", \"accountId\") */\n\tkey: string;\n\t/** Type or value expected by the target schema (sup) */\n\texpected: string;\n\t/** Type or value received from the source schema (sub) */\n\treceived: string;\n}\n\nexport interface SubsetResult {\n\t/** true if sub ⊆ sup (every value valid for sub is also valid for sup) */\n\tisSubset: boolean;\n\t/** The schema resulting from the intersection allOf(sub, sup), or null if incompatible */\n\tmerged: JSONSchema7Definition | null;\n\t/** Semantic errors describing incompatibilities between the two schemas */\n\terrors: SchemaError[];\n}\n\n/**\n * Options for runtime-aware subset checking.\n *\n * When `data` is provided, the checker:\n *   1. Resolves `if/then/else` conditions in both `sub` and `sup` using `data`\n *      (if `data` is `undefined`, conditions are resolved with `{}`)\n *   2. Narrows schemas using runtime values (e.g. enum materialization)\n *   3. Performs the static subset check on the resolved/narrowed schemas\n *\n * When `validate` is `true`, two additional runtime steps run **after** the\n * static check passes:\n *   4. `data` is validated against both resolved schemas via AJV\n *   5. Custom constraints are validated against `data`\n *\n * `data` can be a partial discriminant (e.g. `{ kind: \"text\" }`) used solely\n * for condition resolution and narrowing. It does **not** need to be a complete\n * instance of the schemas unless `validate: true` is set.\n */\nexport interface CheckRuntimeOptions {\n\t/** Runtime data used for condition resolution, narrowing, and optionally runtime validation */\n\tdata: unknown;\n\n\t/**\n\t * When `true`, enables runtime validation of `data` against both resolved\n\t * schemas via AJV, and custom constraint validation if a registry was\n\t * provided at construction time.\n\t *\n\t * When `false` or omitted (default), `data` is used only for condition\n\t * resolution (`if/then/else`) and schema narrowing — no AJV validation\n\t * or constraint validation is performed.\n\t *\n\t * @default false\n\t */\n\tvalidate?: boolean;\n}\n\n/**\n * Extended result from `check()` when runtime options are provided.\n * Includes resolution results for sub and sup in addition to the SubsetResult.\n */\nexport interface ResolvedSubsetResult extends SubsetResult {\n\tresolvedSub: ResolvedConditionResult;\n\tresolvedSup: ResolvedConditionResult;\n}\n\nexport interface ResolvedConditionResult {\n\t/** The schema with if/then/else resolved (flattened) */\n\tresolved: JSONSchema7;\n\t/** The branch that was applied (\"then\" | \"else\" | null if no condition) */\n\tbranch: \"then\" | \"else\" | null;\n\t/** The discriminant used for resolution */\n\tdiscriminant: Record<string, unknown>;\n}\n\nexport type Constraint =\n\t| string\n\t| {\n\t\t\tname: string;\n\t\t\tparams?: Record<string, unknown>;\n\t  };\n\nexport type Constraints = Constraint | Constraint[];\n\n// ─── Constraint Validator types ──────────────────────────────────────────────\n\n/**\n * Result of a constraint validation.\n */\nexport interface ConstraintValidationResult {\n\t/** Whether the value satisfies the constraint */\n\tvalid: boolean;\n\t/** Human-readable message when `valid` is `false` */\n\tmessage?: string;\n}\n\n/**\n * A constraint validator function.\n *\n * Receives the value to validate and optional params defined\n * in the schema's constraint definition.\n *\n * Must be synchronous — async validation is out of scope\n * for this library. Wrap async checks in your application layer.\n *\n * @param value - The runtime value to validate\n * @param params - The `params` object from the constraint definition, if any\n * @returns The validation result\n *\n * @example\n * ```ts\n * const isUuid: ConstraintValidator = (value) => ({\n *   valid: typeof value === \"string\" && /^[0-9a-f]{8}-/.test(value),\n *   message: \"Value must be a valid UUID\",\n * });\n *\n * const minAge: ConstraintValidator = (value, params) => ({\n *   valid: typeof value === \"number\" && value >= (params?.min ?? 0),\n *   message: `Value must be at least ${params?.min}`,\n * });\n * ```\n */\nexport type ConstraintValidator = (\n\tvalue: unknown,\n\tparams?: Record<string, unknown>,\n) => ConstraintValidationResult;\n\n/**\n * Registry mapping constraint names to their validator functions.\n *\n * Keys are constraint names as they appear in schema definitions\n * (e.g. `\"IsUuid\"`, `\"MinAge\"`).\n */\nexport type ConstraintValidatorRegistry = Record<string, ConstraintValidator>;\n\n/**\n * Options for the JsonSchemaCompatibilityChecker constructor.\n */\nexport interface CheckerOptions {\n\t/**\n\t * Registry of custom constraint validators.\n\t *\n\t * When provided, the checker can validate runtime data against\n\t * custom constraints defined in schemas via the `constraints` keyword.\n\t *\n\t * Constraint names must match those used in schema definitions.\n\t * Unknown constraints (present in a schema but absent from the registry)\n\t * will be reported as errors during runtime validation.\n\t */\n\tconstraints?: ConstraintValidatorRegistry;\n}\n"],"names":[],"mappings":"AA2IA,QAYC"}
+{"version":3,"sources":["../../src/types.ts"],"sourcesContent":["import type { JSONSchema7, JSONSchema7Definition } from \"json-schema\";\n\n// ─── Module augmentation ─────────────────────────────────────────────────────\n// Extends JSONSchema7 with the custom `constraints` keyword so that consumers\n// of this package see the property on every JSONSchema7 without needing a\n// separate ambient file or `/// <reference>` directive.\n\ndeclare module \"json-schema\" {\n\tinterface JSONSchema7 {\n\t\tconstraints?: Constraints;\n\t}\n}\n\n// ─── Public types ────────────────────────────────────────────────────────────\n\nexport interface SchemaError {\n\t/** Normalized path to the concerned property (e.g. \"user.name\", \"users[].name\", \"accountId\") */\n\tkey: string;\n\t/** Type or value expected by the target schema (sup) */\n\texpected: string;\n\t/** Type or value received from the source schema (sub) */\n\treceived: string;\n}\n\nexport interface SubsetResult {\n\t/** true if sub ⊆ sup (every value valid for sub is also valid for sup) */\n\tisSubset: boolean;\n\t/** The schema resulting from the intersection allOf(sub, sup), or null if incompatible */\n\tmerged: JSONSchema7Definition | null;\n\t/** Semantic errors describing incompatibilities between the two schemas */\n\terrors: SchemaError[];\n}\n\n/**\n * Options for runtime-aware subset checking.\n *\n * When `data` is provided, the checker:\n *   1. Resolves `if/then/else` conditions in both `sub` and `sup` using `data`\n *      (if `data` is `undefined`, conditions are resolved with `{}`)\n *   2. Narrows schemas using runtime values (e.g. enum materialization)\n *   3. Performs the static subset check on the resolved/narrowed schemas\n *\n * When `validate` is `true`, two additional runtime steps run **after** the\n * static check passes:\n *   4. `data` is validated against both resolved schemas via AJV\n *   5. Custom constraints are validated against `data`\n *\n * `data` can be a partial discriminant (e.g. `{ kind: \"text\" }`) used solely\n * for condition resolution and narrowing. It does **not** need to be a complete\n * instance of the schemas unless `validate: true` is set.\n */\nexport interface CheckRuntimeOptions {\n\t/** Runtime data used for condition resolution, narrowing, and optionally runtime validation */\n\tdata: unknown;\n\n\t/**\n\t * When `true`, enables runtime validation of `data` against both resolved\n\t * schemas via AJV, and custom constraint validation if a registry was\n\t * provided at construction time.\n\t *\n\t * When `false` or omitted (default), `data` is used only for condition\n\t * resolution (`if/then/else`) and schema narrowing — no AJV validation\n\t * or constraint validation is performed.\n\t *\n\t * @default false\n\t */\n\tvalidate?: boolean;\n}\n\n/**\n * Extended result from `check()` when runtime options are provided.\n * Includes resolution results for sub and sup in addition to the SubsetResult.\n */\nexport interface ResolvedSubsetResult extends SubsetResult {\n\tresolvedSub: ResolvedConditionResult;\n\tresolvedSup: ResolvedConditionResult;\n}\n\nexport interface ResolvedConditionResult {\n\t/** The schema with if/then/else resolved (flattened) */\n\tresolved: JSONSchema7;\n\t/** The branch that was applied (\"then\" | \"else\" | null if no condition) */\n\tbranch: \"then\" | \"else\" | null;\n\t/** The discriminant used for resolution */\n\tdiscriminant: Record<string, unknown>;\n}\n\nexport type Constraint =\n\t| string\n\t| {\n\t\t\tname: string;\n\t\t\tparams?: Record<string, unknown>;\n\t  };\n\nexport type Constraints = Constraint | Constraint[];\n\n// ─── Constraint Validator types ──────────────────────────────────────────────\n\n/**\n * Result of a constraint validation.\n */\nexport interface ConstraintValidationResult {\n\t/** Whether the value satisfies the constraint */\n\tvalid: boolean;\n\t/** Human-readable message when `valid` is `false` */\n\tmessage?: string;\n}\n\n/**\n * A constraint validator function.\n *\n * Receives the value to validate and optional params defined\n * in the schema's constraint definition.\n *\n * Must be synchronous — async validation is out of scope\n * for this library. Wrap async checks in your application layer.\n *\n * @param value - The runtime value to validate\n * @param params - The `params` object from the constraint definition, if any\n * @returns The validation result\n *\n * @example\n * ```ts\n * const isUuid: ConstraintValidator = (value) => ({\n *   valid: typeof value === \"string\" && /^[0-9a-f]{8}-/.test(value),\n *   message: \"Value must be a valid UUID\",\n * });\n *\n * const minAge: ConstraintValidator = (value, params) => ({\n *   valid: typeof value === \"number\" && value >= (params?.min ?? 0),\n *   message: `Value must be at least ${params?.min}`,\n * });\n * ```\n */\nexport type ConstraintValidator = (\n\tvalue: unknown,\n\tparams?: Record<string, unknown>,\n) => ConstraintValidationResult;\n\n/**\n * Registry mapping constraint names to their validator functions.\n *\n * Keys are constraint names as they appear in schema definitions\n * (e.g. `\"IsUuid\"`, `\"MinAge\"`).\n */\nexport type ConstraintValidatorRegistry = Record<string, ConstraintValidator>;\n\n/**\n * Options for the JsonSchemaCompatibilityChecker constructor.\n */\nexport interface CheckerOptions {\n\t/**\n\t * Registry of custom constraint validators.\n\t *\n\t * When provided, the checker can validate runtime data against\n\t * custom constraints defined in schemas via the `constraints` keyword.\n\t *\n\t * Constraint names must match those used in schema definitions.\n\t * Unknown constraints (present in a schema but absent from the registry)\n\t * will be reported as errors during runtime validation.\n\t */\n\tconstraints?: ConstraintValidatorRegistry;\n}\n"],"names":[],"mappings":"AAsJA,QAYC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "json-schema-compatibility-checker",
-	"version": "1.1.1",
+	"version": "1.1.2",
 	"license": "MIT",
 	"description": "A tool to check compatibility between two JSON Schemas.",
 	"author": {