@schema-ts/core 0.1.2 → 0.1.4

package/dist/index.d.cts

@@ -191,11 +191,30 @@ interface FieldNode {
     dependencies?: Set<string>;
     canRemove: boolean;
     canAdd: boolean;
+    isRequired: boolean;
 }
 type SchemaChangeEvent = {
     type: "schema" | "value" | "error";
     path: string;
 };
+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'
+     */
+    autoFillDefaults?: "always" | "explicit" | "never";
+    /**
+     * Control behavior when removing the last element from an array or object.
+     * - 'never': Always keep empty containers ([] or {})
+     * - 'auto': Remove empty container only if the field is optional (not in parent's required array)
+     * - 'always': Always remove empty containers (may cause validation errors for required fields)
+     * @default 'auto'
+     */
+    removeEmptyContainers?: "never" | "auto" | "always";
+}
 declare class SchemaRuntime {
     private validator;
     private watchers;
@@ -206,19 +225,21 @@ declare class SchemaRuntime {
     private value;
     private version;
     private rootSchema;
+    private options;
     /**
      * Create a new SchemaRuntime instance.
      *
      * @param validator - The validator instance for schema validation
      * @param schema - The JSON Schema definition (will be normalized and dereferenced)
      * @param value - The initial data value to manage
+     * @param options - Runtime configuration options
      *
      * @example
      * const validator = new Validator();
      * const schema = { type: "object", properties: { name: { type: "string" } } };
      * const runtime = new SchemaRuntime(validator, schema, { name: "Alice" });
      */
-    constructor(validator: Validator, schema: Schema | unknown, value: unknown);
+    constructor(validator: Validator, schema: Schema | unknown, value: unknown, options?: SchemaRuntimeOptions);
     /**
      * Register a node as dependent on a path
      */
@@ -297,13 +318,43 @@ declare class SchemaRuntime {
      * runtime.getValue("/name"); // returns value at /name
      */
     getValue(path: string): unknown;
+    /**
+     * 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 value - The value to set
+     * @returns true if successful, false if the path cannot be set
+     */
+    private setValueAtPath;
+    /**
+     * 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 for reconciliation
+     */
+    private cleanupEmptyContainers;
+    /**
+     * Get default value for a schema, respecting autoFillDefaults option.
+     * Falls back to 'always' strategy if configured strategy returns undefined.
+     */
+    private getDefaultValueForAdd;
     /**
      * 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.
@@ -319,13 +370,17 @@ declare class SchemaRuntime {
      * 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;
     /**
@@ -351,9 +406,14 @@ declare class SchemaRuntime {
      * This handles cases like if-then-else where new properties with defaults
      * may appear when conditions change.
      *
+     * Container initialization rules:
+     * - Root node is always considered required and 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 isRequired - Whether this node is required by its parent
      */
     private applySchemaDefaults;
     /**
@@ -365,6 +425,7 @@ 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;
 }
@@ -439,19 +500,23 @@ 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";
+}
 /**
  * Generate a default value for a schema based on its type and constraints.
  *
  * Priority order for determining the default value:
  *   1. const - if defined, returns the const value
  *   2. default - if defined, returns the default value
- *   3. Type-based defaults:
- *      - string: ""
- *      - number/integer: 0
- *      - boolean: false
- *      - null: null
- *      - object: {} with required properties recursively initialized
- *      - array: []
+ *   3. Type-based defaults (controlled by strategy):
  *
  * For objects, only required properties are initialized with their default values.
  * If no type is specified but properties exist, the schema is treated as an object.
@@ -459,20 +524,21 @@ 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 options - Optional configuration for default value generation
  * @returns The generated default value, or undefined if type cannot be determined
  *
  * @example
- * getDefaultValue({ type: "string" }) // returns ""
+ * getDefaultValue({ type: "string" }) // returns undefined (explicit mode)
+ * getDefaultValue({ type: "string" }, { strategy: 'always' }) // returns ""
  * 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 }
+ * }, { strategy: 'always' }) // returns { name: "" }
+ * getDefaultValue({ type: "object", properties: { a: { default: 1 } } }, { value: {} }) // returns { a: 1 }
  */
-declare function getDefaultValue(schema: Schema, value?: unknown): unknown;
+declare function getDefaultValue(schema: Schema, options?: GetDefaultValueOptions): unknown;
 
-export { DRAFT_URIS, type ErrorFormatter, type ErrorMessage, type FieldNode, MESSAGES, type NormalizerOptions, type Output, type Schema, type SchemaChangeEvent, type SchemaDraft, SchemaRuntime, 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 { DRAFT_URIS, type ErrorFormatter, type ErrorMessage, type FieldNode, type GetDefaultValueOptions, 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 };

package/dist/index.d.ts

@@ -191,11 +191,30 @@ interface FieldNode {
     dependencies?: Set<string>;
     canRemove: boolean;
     canAdd: boolean;
+    isRequired: boolean;
 }
 type SchemaChangeEvent = {
     type: "schema" | "value" | "error";
     path: string;
 };
+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'
+     */
+    autoFillDefaults?: "always" | "explicit" | "never";
+    /**
+     * Control behavior when removing the last element from an array or object.
+     * - 'never': Always keep empty containers ([] or {})
+     * - 'auto': Remove empty container only if the field is optional (not in parent's required array)
+     * - 'always': Always remove empty containers (may cause validation errors for required fields)
+     * @default 'auto'
+     */
+    removeEmptyContainers?: "never" | "auto" | "always";
+}
 declare class SchemaRuntime {
     private validator;
     private watchers;
@@ -206,19 +225,21 @@ declare class SchemaRuntime {
     private value;
     private version;
     private rootSchema;
+    private options;
     /**
      * Create a new SchemaRuntime instance.
      *
      * @param validator - The validator instance for schema validation
      * @param schema - The JSON Schema definition (will be normalized and dereferenced)
      * @param value - The initial data value to manage
+     * @param options - Runtime configuration options
      *
      * @example
      * const validator = new Validator();
      * const schema = { type: "object", properties: { name: { type: "string" } } };
      * const runtime = new SchemaRuntime(validator, schema, { name: "Alice" });
      */
-    constructor(validator: Validator, schema: Schema | unknown, value: unknown);
+    constructor(validator: Validator, schema: Schema | unknown, value: unknown, options?: SchemaRuntimeOptions);
     /**
      * Register a node as dependent on a path
      */
@@ -297,13 +318,43 @@ declare class SchemaRuntime {
      * runtime.getValue("/name"); // returns value at /name
      */
     getValue(path: string): unknown;
+    /**
+     * 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 value - The value to set
+     * @returns true if successful, false if the path cannot be set
+     */
+    private setValueAtPath;
+    /**
+     * 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 for reconciliation
+     */
+    private cleanupEmptyContainers;
+    /**
+     * Get default value for a schema, respecting autoFillDefaults option.
+     * Falls back to 'always' strategy if configured strategy returns undefined.
+     */
+    private getDefaultValueForAdd;
     /**
      * 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.
@@ -319,13 +370,17 @@ declare class SchemaRuntime {
      * 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;
     /**
@@ -351,9 +406,14 @@ declare class SchemaRuntime {
      * This handles cases like if-then-else where new properties with defaults
      * may appear when conditions change.
      *
+     * Container initialization rules:
+     * - Root node is always considered required and 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 isRequired - Whether this node is required by its parent
      */
     private applySchemaDefaults;
     /**
@@ -365,6 +425,7 @@ 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;
 }
@@ -439,19 +500,23 @@ 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";
+}
 /**
  * Generate a default value for a schema based on its type and constraints.
  *
  * Priority order for determining the default value:
  *   1. const - if defined, returns the const value
  *   2. default - if defined, returns the default value
- *   3. Type-based defaults:
- *      - string: ""
- *      - number/integer: 0
- *      - boolean: false
- *      - null: null
- *      - object: {} with required properties recursively initialized
- *      - array: []
+ *   3. Type-based defaults (controlled by strategy):
  *
  * For objects, only required properties are initialized with their default values.
  * If no type is specified but properties exist, the schema is treated as an object.
@@ -459,20 +524,21 @@ 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 options - Optional configuration for default value generation
  * @returns The generated default value, or undefined if type cannot be determined
  *
  * @example
- * getDefaultValue({ type: "string" }) // returns ""
+ * getDefaultValue({ type: "string" }) // returns undefined (explicit mode)
+ * getDefaultValue({ type: "string" }, { strategy: 'always' }) // returns ""
  * 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 }
+ * }, { strategy: 'always' }) // returns { name: "" }
+ * getDefaultValue({ type: "object", properties: { a: { default: 1 } } }, { value: {} }) // returns { a: 1 }
  */
-declare function getDefaultValue(schema: Schema, value?: unknown): unknown;
+declare function getDefaultValue(schema: Schema, options?: GetDefaultValueOptions): unknown;
 
-export { DRAFT_URIS, type ErrorFormatter, type ErrorMessage, type FieldNode, MESSAGES, type NormalizerOptions, type Output, type Schema, type SchemaChangeEvent, type SchemaDraft, SchemaRuntime, 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 { DRAFT_URIS, type ErrorFormatter, type ErrorMessage, type FieldNode, type GetDefaultValueOptions, 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 };