@schema-ts/core 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -88,7 +88,42 @@ declare function detectSchemaType(value: unknown): string;
 declare function parseJsonPointer(jsonPointer: string): string[];
 declare function getJsonPointer(obj: unknown, jsonPointer: string): unknown;
 declare function removeJsonPointer(obj: unknown, jsonPointer: string): boolean;
+/**
+ * Sets a value at the specified JSON Pointer path within an object.
+ *
+ * This function modifies the object in place by setting a value at the location
+ * specified by the JSON Pointer. If intermediate paths don't exist, they will be
+ * automatically created as objects or arrays based on the next path segment
+ * (numeric segments create arrays, non-numeric create objects).
+ *
+ * @param obj - The object to modify. Must be a non-null object or array.
+ * @param jsonPointer - A JSON Pointer string (RFC 6901) indicating where to set the value.
+ *                      Examples: "/foo", "/foo/0", "/foo/bar/baz"
+ * @param value - The value to set at the specified location.
+ * @returns `true` if the value was successfully set, `false` otherwise.
+ *
+ * @remarks
+ * - Returns `false` if `jsonPointer` is an empty string (cannot replace root object).
+ *   To replace the entire object, handle this case in the calling code.
+ * - Returns `false` if `obj` is null or undefined.
+ * - For array paths, automatically extends the array if the index is beyond current length.
+ * - Automatically initializes missing intermediate containers as arrays or objects.
+ *
+ * @example
+ * ```typescript
+ * const obj = { foo: { bar: 1 } };
+ * setJsonPointer(obj, "/foo/bar", 2); // true, obj.foo.bar is now 2
+ * setJsonPointer(obj, "/foo/baz", 3); // true, obj.foo.baz is now 3
+ * setJsonPointer(obj, "/new/path", 4); // true, obj.new.path is now 4
+ * setJsonPointer(obj, "", 5); // false, cannot replace root object
+ *
+ * const arr = [1, 2, 3];
+ * setJsonPointer(arr, "/0", 10); // true, arr[0] is now 10
+ * setJsonPointer(arr, "/5", 20); // true, arr is now [10, 2, 3, undefined, undefined, 20]
+ * ```
+ */
 declare function setJsonPointer(obj: unknown, jsonPointer: string, value: unknown): boolean;
+declare function getJsonPointerParent(path: string): string;
 declare function get(obj: unknown, path: string[]): unknown;
 /**
  * Deep equality comparison for two values.
@@ -175,6 +210,103 @@ declare class Validator {
  */
 declare function validateSchema(schema: Schema | unknown, value: unknown, instancePath?: string, schemaPath?: string, fastFail?: boolean): Output;
 
+/**
+ * JSON Schema draft version definitions and detection utilities.
+ */
+/**
+ * Supported JSON Schema draft versions.
+ */
+type SchemaDraft = "draft-04" | "draft-07" | "draft-2019-09" | "draft-2020-12";
+/**
+ * Standard $schema URI patterns for each draft version.
+ */
+declare const DRAFT_URIS: Record<SchemaDraft, string[]>;
+/**
+ * Detect the JSON Schema draft version from a schema.
+ * Detection is based on:
+ * 1. The $schema URI if present
+ * 2. Heuristics based on keywords used
+ *
+ * @param schema - The schema to detect the version of (can be object, boolean, or unknown)
+ * @returns The detected draft version, defaults to "draft-2020-12" if unknown
+ */
+declare function detectSchemaDraft(schema: unknown): SchemaDraft;
+
+/**
+ * Schema normalizer that transforms older JSON Schema drafts to draft-2020-12.
+ *
+ * This allows the validator to only implement draft-2020-12 semantics
+ * while still supporting schemas written for older drafts.
+ */
+
+/**
+ * Schema normalizer interface for transforming various JSON Schema formats into a unified version.
+ */
+interface Normalizer {
+    /**
+     * Normalizes the given schema.
+     * @param schema The raw schema input
+     * @returns A schema object following the latest draft specification
+     */
+    normalize(schema: unknown): Schema;
+}
+/**
+ * Base draft normalizer responsible for converting older JSON Schema keywords to newer versions (e.g., Draft-04 to Draft-2020-12).
+ */
+declare class DraftNormalizer implements Normalizer {
+    normalize(schema: unknown): Schema;
+}
+interface DraftNormalizerOptions {
+    /**
+     * Source draft version. If not specified, will be auto-detected.
+     */
+    sourceDraft?: SchemaDraft;
+}
+/**
+ * Normalize a JSON Schema from any supported draft to draft-2020-12 format.
+ *
+ * Transformations performed:
+ * - `id` → `$id` (draft-04)
+ * - Boolean `exclusiveMaximum`/`exclusiveMinimum` → numeric values (draft-04)
+ * - Array `items` + `additionalItems` → `prefixItems` + `items` (draft-04/07/2019-09)
+ * - `dependencies` → `dependentRequired`/`dependentSchemas` (draft-04/07)
+ * - `$recursiveRef`/`$recursiveAnchor` → `$dynamicRef`/`$dynamicAnchor` (draft-2019-09)
+ *
+ * @param schema - The schema to normalize (can be object, boolean, or unknown)
+ * @param options - Optional configuration
+ * @returns A new schema object in draft-2020-12 format (always returns an object)
+ */
+declare function normalizeSchema(schema: unknown, options?: DraftNormalizerOptions): Schema;
+/**
+ * Enhanced normalizer that adds type inference, automatic required field identification,
+ * and support for OpenAPI/Kubernetes extension properties on top of base draft transformations.
+ */
+declare class BetterNormalizer implements Normalizer {
+    /**
+     * Performs the normalization process:
+     * 1. Base draft normalization (DraftNormalizer)
+     * 2. Enhanced default value completion (Better logic)
+     */
+    normalize(schema: unknown): Schema;
+    /**
+     * Recursively processes all sub-nodes of the schema, applying default rules.
+     */
+    private default;
+    /**
+     * Batch processes Record-type sub-schemas.
+     */
+    private defaultSchemaMap;
+    /**
+     * Applies inference and heuristic rules to a single schema object.
+     * Includes:
+     * - `type` inference based on properties (object/array)
+     * - Automatically setting properties with `const`/`default`/`enum` as `required`
+     * - Handling `required` fields from OpenAPI `discriminator`
+     * - Handling `x-required` and `x-kubernetes-patch-merge-key`
+     */
+    private defaultSchema;
+}
+
 /**
  * Represents a node in the schema tree.
  * Each node corresponds to a location in both the schema and the instance data.
@@ -187,10 +319,13 @@ interface FieldNode {
     children?: FieldNode[];
     instanceLocation: string;
     keywordLocation: string;
+    originKeywordLocation?: string;
     version: number;
     dependencies?: Set<string>;
     canRemove: boolean;
     canAdd: boolean;
+    required: boolean;
+    activated: boolean;
 }
 type SchemaChangeEvent = {
     type: "schema" | "value" | "error";
@@ -200,14 +335,26 @@ interface SchemaRuntimeOptions {
     /**
      * Control how default values are applied when schema changes.
      * - 'always': Fill all type-based defaults (e.g., [] for array, "" for string)
-     * - 'explicit': Only fill explicitly declared defaults (schema.default)
-     * - 'never': Never auto-fill defaults
-     * @default 'explicit'
+     * - 'auto': Fill defaults by defaulting rules (required fields, const, default keyword etc.)
+     * @default 'auto'
+     */
+    fillDefaults?: "auto" | "never";
+    /**
+     * Control behavior when removing the last element from an array or object.
+     * - 'never': Always keep empty containers ([] or {})
+     * - 'auto': Remove empty container only following rules.
+     * @default 'auto'
+     */
+    removeEmptyContainers?: "never" | "auto";
+    /**
+     * Custom schema normalizer.
+     * If specified, will use this normalizer instead of the default one.
      */
-    autoFillDefaults?: "always" | "explicit" | "never";
+    schemaNormalizer?: Normalizer;
 }
 declare class SchemaRuntime {
     private validator;
+    private normalizer;
     private watchers;
     private globalWatchers;
     private dependentsMap;
@@ -231,6 +378,12 @@ declare class SchemaRuntime {
      * const runtime = new SchemaRuntime(validator, schema, { name: "Alice" });
      */
     constructor(validator: Validator, schema: Schema | unknown, value: unknown, options?: SchemaRuntimeOptions);
+    private resolveSchema;
+    /**
+     * Update the entire schema.
+     * This triggers a full rebuild of the node tree while preserving the current value.
+     */
+    setSchema(schema: Schema | unknown): void;
     /**
      * Register a node as dependent on a path
      */
@@ -293,11 +446,6 @@ declare class SchemaRuntime {
      * @param event - The change event containing type and path
      */
     notify(event: SchemaChangeEvent): void;
-    /**
-     * Update the entire schema.
-     * This triggers a full rebuild of the node tree while preserving the current value.
-     */
-    setSchema(schema: Schema | unknown): void;
     /**
      * Get the value at a specific path.
      *
@@ -313,18 +461,42 @@ declare class SchemaRuntime {
      * Internal helper to set a value at a normalized path.
      * Handles both root and non-root paths.
      *
-     * @param normalizedPath - The normalized JSON Pointer path
+     * @param path - The JSON Pointer path
      * @param value - The value to set
      * @returns true if successful, false if the path cannot be set
      */
-    private setValueAtPath;
+    private setJsonPointer;
+    /**
+     * Internal method to remove a value at a path.
+     * Shared logic for removeValue and setValue(undefined).
+     * @param path - The normalized path to remove
+     * @param canRemove - Whether the removal is allowed (pre-checked by caller)
+     * @returns true if successful, false if removal failed
+     */
+    private removeValueInternal;
     /**
      * Remove a node at the specified path.
      * This deletes the value from the data structure (array splice or object delete).
+     * After removal, may also remove empty parent containers based on removeEmptyContainers option.
      * @param path - The path to remove
      * @returns true if successful, false if the path cannot be removed
      */
     removeValue(path: string): boolean;
+    /**
+     * Clean up empty parent containers after element removal.
+     * Recursively removes empty arrays/objects based on removeEmptyContainers option.
+     * @param path - The path to check for empty container
+     * @returns The topmost parent path changed
+     */
+    private cleanupEmptyContainers;
+    /**
+     * Get default value for a schema, respecting autoFillDefaults option.
+     * Falls back to 'always' strategy if configured strategy returns undefined.
+     * If still undefined (e.g., schema has no type), falls back to null as a valid JSON value.
+     */
+    private newDefaultValue;
+    private addObjectProperty;
+    private addArrayItem;
     /**
      * Add a new child to an array or object at the specified parent path.
      * For arrays, appends a new item with default value based on items schema.
@@ -334,34 +506,39 @@ declare class SchemaRuntime {
      * @param initialValue - Optional initial value to set. If not provided, uses default from schema.
      * @returns true if successful, false if cannot add
      */
-    addValue(parentPath: string, key?: string, initialValue?: unknown): boolean;
+    addChild(parentPath: string, key?: string, initialValue?: unknown): boolean;
     /**
      * Set the value at a specific path.
      * Creates intermediate containers (objects/arrays) as needed.
      * Triggers reconciliation and notifies subscribers.
      *
+     * When value is undefined and the field is not required, the field will be
+     * removed from the parent container (similar to removeValue behavior).
+     *
      * @param path - The JSON Pointer path (e.g., "/user/name", "" for root)
-     * @param value - The new value to set
+     * @param value - The new value to set. If undefined and field is optional, removes the field.
      * @returns true if successful, false if the path cannot be set
      *
      * @example
      * runtime.setValue("/name", "Bob"); // set name to "Bob"
      * runtime.setValue("", { name: "Alice" }); // replace entire root value
+     * runtime.setValue("/optional", undefined); // remove optional field
      */
     setValue(path: string, value: unknown): boolean;
     /**
-     * Find the FieldNode at a specific path.
+     * Get the FieldNode at a specific path.
      * Returns the node tree representation that includes schema, type, error, and children.
      *
      * @param path - The JSON Pointer path (e.g., "/user/name", "" for root)
      * @returns The FieldNode at the path, or undefined if not found
      *
      * @example
-     * const node = runtime.findNode("/name");
+     * const node = runtime.getNode("/name");
      * console.log(node?.schema, node?.type, node?.error);
      */
-    findNode(path: string): FieldNode | undefined;
+    getNode(path: string): FieldNode | undefined;
     private findNearestExistingNode;
+    validate(path: string): void;
     /**
      * Update node dependencies when schema changes.
      * Unregisters old dependencies and registers new ones.
@@ -372,11 +549,22 @@ declare class SchemaRuntime {
      * This handles cases like if-then-else where new properties with defaults
      * may appear when conditions change.
      *
+     * Container initialization rules:
+     * - Required containers will be initialized if it has defaults or required properties
+     * - Nested containers are initialized only if they are in parent's required array
+     *
      * @param instanceLocation - The path to the node
      * @param newSchema - The new effective schema
      * @param type - The schema type
+     * @param required - Whether this node is required by its parent
      */
     private applySchemaDefaults;
+    /**
+     * Sort property entries by x-order.
+     * Properties with lower x-order values come first.
+     * Properties without x-order are placed at the end.
+     */
+    private sortPropertiesByOrder;
     /**
      * Build children for object and array nodes.
      * Reuses existing child nodes where possible.
@@ -386,61 +574,11 @@ declare class SchemaRuntime {
      * Build/update a FieldNode in place.
      * Updates the node's schema, type, error, and children based on the current value.
      * @param schema - Optional. If provided, updates node.originalSchema. Otherwise uses existing.
+     * @param isRequired - Whether this node is required by its parent schema.
      */
     private buildNode;
 }
 
-/**
- * JSON Schema draft version definitions and detection utilities.
- */
-/**
- * Supported JSON Schema draft versions.
- */
-type SchemaDraft = "draft-04" | "draft-07" | "draft-2019-09" | "draft-2020-12";
-/**
- * Standard $schema URI patterns for each draft version.
- */
-declare const DRAFT_URIS: Record<SchemaDraft, string[]>;
-/**
- * Detect the JSON Schema draft version from a schema.
- * Detection is based on:
- * 1. The $schema URI if present
- * 2. Heuristics based on keywords used
- *
- * @param schema - The schema to detect the version of (can be object, boolean, or unknown)
- * @returns The detected draft version, defaults to "draft-2020-12" if unknown
- */
-declare function detectSchemaDraft(schema: unknown): SchemaDraft;
-
-/**
- * Schema normalizer that transforms older JSON Schema drafts to draft-2020-12.
- *
- * This allows the validator to only implement draft-2020-12 semantics
- * while still supporting schemas written for older drafts.
- */
-
-interface NormalizerOptions {
-    /**
-     * Source draft version. If not specified, will be auto-detected.
-     */
-    sourceDraft?: SchemaDraft;
-}
-/**
- * Normalize a JSON Schema from any supported draft to draft-2020-12 format.
- *
- * Transformations performed:
- * - `id` → `$id` (draft-04)
- * - Boolean `exclusiveMaximum`/`exclusiveMinimum` → numeric values (draft-04)
- * - Array `items` + `additionalItems` → `prefixItems` + `items` (draft-04/07/2019-09)
- * - `dependencies` → `dependentRequired`/`dependentSchemas` (draft-04/07)
- * - `$recursiveRef`/`$recursiveAnchor` → `$dynamicRef`/`$dynamicAnchor` (draft-2019-09)
- *
- * @param schema - The schema to normalize (can be object, boolean, or unknown)
- * @param options - Optional configuration
- * @returns A new schema object in draft-2020-12 format (always returns an object)
- */
-declare function normalizeSchema(schema: unknown, options?: NormalizerOptions): Schema;
-
 /**
  * Collect all dependencies for a node's schema.
  *
@@ -460,6 +598,17 @@ declare function collectDependencies(schema: Schema, instanceLocation: string):
  */
 declare function extractReferencedPaths(conditionSchema: Schema, basePath?: string, depth?: number): string[];
 
+interface GetDefaultValueOptions {
+    /** Optional existing value to fill defaults into */
+    value?: unknown;
+    /**
+     * Controls type-based default behavior:
+     *   - 'always': Returns type-based defaults (e.g., "" for string, [] for array)
+     *   - 'explicit' (default): Only returns explicitly declared schema.const or schema.default
+     */
+    strategy?: "always" | "explicit";
+}
+declare function typeNullable(schema: Schema): [string | undefined, boolean];
 /**
  * Generate a default value for a schema based on its type and constraints.
  *
@@ -474,24 +623,10 @@ declare function extractReferencedPaths(conditionSchema: Schema, basePath?: stri
  * If a value is provided, it will be used as the base and missing defaults will be filled in.
  *
  * @param schema - The JSON Schema to generate a default value for
- * @param value - Optional existing value to fill defaults into
- * @param strategy - Controls type-based default behavior:
- *   - 'always' (default): Returns type-based defaults (e.g., "" for string, [] for array)
- *   - 'explicit': Only returns explicitly declared schema.const or schema.default
+ * @param strategy - Controls type-based default behavior
  * @returns The generated default value, or undefined if type cannot be determined
- *
- * @example
- * getDefaultValue({ type: "string" }) // returns ""
- * getDefaultValue({ type: "string" }, undefined, 'explicit') // returns undefined
- * getDefaultValue({ type: "number", default: 42 }) // returns 42
- * getDefaultValue({ const: "fixed" }) // returns "fixed"
- * getDefaultValue({
- *   type: "object",
- *   properties: { name: { type: "string" } },
- *   required: ["name"]
- * }) // returns { name: "" }
- * getDefaultValue({ type: "object", properties: { a: { default: 1 } } }, {}) // returns { a: 1 }
  */
-declare function getDefaultValue(schema: Schema, value?: unknown, strategy?: "always" | "explicit"): unknown;
+declare function getDefaultValue(schema: Schema, required?: boolean): unknown;
+declare function applyDefaults(type: string, value: unknown, schema: Schema, required?: boolean): [unknown, boolean];
 
-export { DRAFT_URIS, type ErrorFormatter, type ErrorMessage, type FieldNode, MESSAGES, type NormalizerOptions, type Output, type Schema, type SchemaChangeEvent, type SchemaDraft, SchemaRuntime, type SchemaRuntimeOptions, type SchemaType, StringFormatValidator, type StringFormatValidatorInterface, Validator, type ValidatorConfig, type ValidatorOptions, collectDependencies, deepEqual, defaultErrorFormatter, detectSchemaDraft, detectSchemaType, extractReferencedPaths, get, getDefaultValue, getJsonPointer, jsonPointerEscape, jsonPointerJoin, jsonPointerUnescape, matchSchemaType, normalizeSchema, parseJsonPointer, removeJsonPointer, resolveAbsolutePath, safeRegexTest, setJsonPointer, stringFormatValidator, validateSchema };
+export { BetterNormalizer, DRAFT_URIS, DraftNormalizer, type DraftNormalizerOptions, type ErrorFormatter, type ErrorMessage, type FieldNode, type GetDefaultValueOptions, MESSAGES, type Normalizer, type Output, type Schema, type SchemaChangeEvent, type SchemaDraft, SchemaRuntime, type SchemaRuntimeOptions, type SchemaType, StringFormatValidator, type StringFormatValidatorInterface, Validator, type ValidatorConfig, type ValidatorOptions, applyDefaults, collectDependencies, deepEqual, defaultErrorFormatter, detectSchemaDraft, detectSchemaType, extractReferencedPaths, get, getDefaultValue, getJsonPointer, getJsonPointerParent, jsonPointerEscape, jsonPointerJoin, jsonPointerUnescape, matchSchemaType, normalizeSchema, parseJsonPointer, removeJsonPointer, resolveAbsolutePath, safeRegexTest, setJsonPointer, stringFormatValidator, typeNullable, validateSchema };