@schema-ts/core 0.1.2 → 0.1.4

package/dist/index.cjs

@@ -1334,7 +1334,7 @@ function validateSchema(schema, value, instancePath = "", schemaPath = "#", fast
 }
 
 // src/effective.ts
-function resolveEffectiveSchema(validator, schema, value, keywordLocation, instanceLocation) {
+function resolveEffectiveSchema(validator, schema, value, keywordLocation, instanceLocation, isRequired = true) {
   let effective = schema;
   if (effective.if) {
     const output = validator.validate(
@@ -1400,7 +1400,6 @@ function resolveEffectiveSchema(validator, schema, value, keywordLocation, insta
           instanceLocation
         );
         effective = mergeSchema(effective, res.effectiveSchema);
-        break;
       }
     }
     const { anyOf: _, ...rest } = effective;
@@ -1439,6 +1438,13 @@ function resolveEffectiveSchema(validator, schema, value, keywordLocation, insta
   } else {
     type = detectSchemaType(value);
   }
+  if (!isRequired && value === void 0) {
+    return {
+      effectiveSchema: effective,
+      type,
+      error: void 0
+    };
+  }
   const validationOutput = validator.validate(
     effective,
     value,
@@ -1472,6 +1478,19 @@ function mergeSchemaArrays(a, b) {
   if (b === void 0) return a;
   return [...a, ...b];
 }
+function mergeSchemaMap(base, override) {
+  if (base === void 0) return override;
+  if (override === void 0) return base;
+  const merged = { ...base };
+  for (const [key, schema] of Object.entries(override)) {
+    if (merged[key]) {
+      merged[key] = mergeSchema(merged[key], schema);
+    } else {
+      merged[key] = schema;
+    }
+  }
+  return merged;
+}
 function mergeSchema(base, override) {
   if (!override) return base;
   const merged = {
@@ -1498,17 +1517,16 @@ function mergeSchema(base, override) {
       ...override.dependentRequired
     };
   }
-  if (base.properties || override.properties) {
-    merged.properties = {
-      ...base.properties,
-      ...override.properties
-    };
+  const mergedProperties = mergeSchemaMap(base.properties, override.properties);
+  if (mergedProperties !== void 0) {
+    merged.properties = mergedProperties;
   }
-  if (base.patternProperties || override.patternProperties) {
-    merged.patternProperties = {
-      ...base.patternProperties,
-      ...override.patternProperties
-    };
+  const mergedPatternProperties = mergeSchemaMap(
+    base.patternProperties,
+    override.patternProperties
+  );
+  if (mergedPatternProperties !== void 0) {
+    merged.patternProperties = mergedPatternProperties;
   }
   if (base.items && override.items) {
     merged.items = mergeSchema(base.items, override.items);
@@ -1543,11 +1561,12 @@ function mergeSchema(base, override) {
       merged[keyword] = mergedArray;
     }
   }
-  if (base.dependentSchemas || override.dependentSchemas) {
-    merged.dependentSchemas = {
-      ...base.dependentSchemas,
-      ...override.dependentSchemas
-    };
+  const mergedDependentSchemas = mergeSchemaMap(
+    base.dependentSchemas,
+    override.dependentSchemas
+  );
+  if (mergedDependentSchemas !== void 0) {
+    merged.dependentSchemas = mergedDependentSchemas;
   }
   return merged;
 }
@@ -1768,7 +1787,8 @@ function getSubSchema(schema, key) {
 }
 
 // src/default.ts
-function getDefaultValue(schema, value) {
+function getDefaultValue(schema, options = {}) {
+  const { value, strategy = "explicit" } = options;
   if (value === void 0) {
     if (schema.const !== void 0) return schema.const;
     if (schema.default !== void 0) return schema.default;
@@ -1777,6 +1797,7 @@ function getDefaultValue(schema, value) {
   if (type === "object" || !type && schema.properties) {
     let obj;
     if (value === void 0) {
+      if (strategy === "explicit") return void 0;
       obj = {};
     } else if (typeof value === "object" && value !== null) {
       obj = value;
@@ -1786,9 +1807,9 @@ function getDefaultValue(schema, value) {
     if (schema.properties) {
       for (const [key, subschema] of Object.entries(schema.properties)) {
         if (obj[key] !== void 0) {
-          obj[key] = getDefaultValue(subschema, obj[key]);
+          obj[key] = getDefaultValue(subschema, { value: obj[key], strategy });
         } else if (schema.required?.includes(key)) {
-          obj[key] = getDefaultValue(subschema);
+          obj[key] = getDefaultValue(subschema, { strategy });
         }
       }
     }
@@ -1797,6 +1818,7 @@ function getDefaultValue(schema, value) {
   if (type === "array") {
     let arr;
     if (value === void 0) {
+      if (strategy === "explicit") return void 0;
       arr = [];
     } else if (Array.isArray(value)) {
       arr = value;
@@ -1806,16 +1828,19 @@ function getDefaultValue(schema, value) {
     if (schema.prefixItems) {
       schema.prefixItems.forEach((subschema, index) => {
         if (index < arr.length) {
-          arr[index] = getDefaultValue(subschema, arr[index]);
+          arr[index] = getDefaultValue(subschema, {
+            value: arr[index],
+            strategy
+          });
         } else if (value === void 0) {
-          arr.push(getDefaultValue(subschema));
+          arr.push(getDefaultValue(subschema, { strategy }));
         }
       });
     }
     if (value !== void 0 && schema.items) {
       const startIndex = schema.prefixItems ? schema.prefixItems.length : 0;
       for (let i = startIndex; i < arr.length; i++) {
-        arr[i] = getDefaultValue(schema.items, arr[i]);
+        arr[i] = getDefaultValue(schema.items, { value: arr[i], strategy });
       }
     }
     return arr;
@@ -1823,6 +1848,9 @@ function getDefaultValue(schema, value) {
   if (value !== void 0) {
     return value;
   }
+  if (strategy === "explicit") {
+    return void 0;
+  }
   switch (type) {
     case "string":
       return "";
@@ -2029,21 +2057,28 @@ var SchemaRuntime = class {
   value;
   version = 0;
   rootSchema = {};
+  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, schema, value) {
+  constructor(validator, schema, value, options = {}) {
     this.validator = validator;
     this.value = value;
+    this.options = {
+      autoFillDefaults: "explicit",
+      removeEmptyContainers: "auto",
+      ...options
+    };
     const normalized = normalizeSchema(schema);
     this.rootSchema = dereferenceSchemaDeep(normalized, normalized);
     this.root = this.createEmptyNode("", "#");
@@ -2097,12 +2132,15 @@ var SchemaRuntime = class {
     return {
       type: "null",
       schema: {},
+      // Placeholder, will be set in buildNode
       version: -1,
+      // -1 indicates initial construction (not yet built)
       instanceLocation,
       keywordLocation,
       originalSchema: {},
       canRemove: false,
       canAdd: false,
+      isRequired: false,
       children: []
     };
   }
@@ -2225,9 +2263,44 @@ var SchemaRuntime = class {
     if (normalizedPath === ROOT_PATH) return this.value;
     return getJsonPointer(this.value, normalizedPath);
   }
+  /**
+   * 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
+   */
+  setValueAtPath(normalizedPath, value) {
+    if (normalizedPath === ROOT_PATH) {
+      this.value = value;
+      return true;
+    }
+    return setJsonPointer(this.value, normalizedPath, value);
+  }
+  /**
+   * 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
+   */
+  removeValueInternal(path) {
+    const success = removeJsonPointer(this.value, path);
+    if (!success) {
+      return false;
+    }
+    const lastSlash = path.lastIndexOf("/");
+    const parentPath = lastSlash <= 0 ? ROOT_PATH : path.substring(0, lastSlash);
+    const reconcilePath = this.cleanupEmptyContainers(parentPath);
+    this.reconcile(reconcilePath);
+    this.notify({ type: "value", path: reconcilePath });
+    return true;
+  }
   /**
    * 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
    */
@@ -2240,15 +2313,54 @@ var SchemaRuntime = class {
     if (!node || !node.canRemove) {
       return false;
     }
-    const success = removeJsonPointer(this.value, normalizedPath);
+    return this.removeValueInternal(normalizedPath);
+  }
+  /**
+   * 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
+   */
+  cleanupEmptyContainers(path) {
+    const strategy = this.options.removeEmptyContainers;
+    if (strategy === "never" || path === ROOT_PATH) {
+      return path;
+    }
+    const node = this.findNode(path);
+    if (!node) {
+      return path;
+    }
+    const value = this.getValue(path);
+    const isEmpty = Array.isArray(value) && value.length === 0 || value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0;
+    if (!isEmpty) {
+      return path;
+    }
+    const shouldRemove = strategy === "always" || strategy === "auto" && !node.isRequired;
+    if (!shouldRemove) {
+      return path;
+    }
+    const success = removeJsonPointer(this.value, path);
     if (!success) {
-      return false;
+      return path;
     }
-    const lastSlash = normalizedPath.lastIndexOf("/");
-    const parentPath = lastSlash <= 0 ? ROOT_PATH : normalizedPath.substring(0, lastSlash);
-    this.reconcile(parentPath);
-    this.notify({ type: "value", path: parentPath });
-    return true;
+    const lastSlash = path.lastIndexOf("/");
+    const parentPath = lastSlash <= 0 ? ROOT_PATH : path.substring(0, lastSlash);
+    return this.cleanupEmptyContainers(parentPath);
+  }
+  /**
+   * Get default value for a schema, respecting autoFillDefaults option.
+   * Falls back to 'always' strategy if configured strategy returns undefined.
+   */
+  getDefaultValueForAdd(schema) {
+    const strategy = this.options.autoFillDefaults;
+    let defaultValue;
+    if (strategy && strategy !== "never") {
+      defaultValue = getDefaultValue(schema, { strategy });
+    }
+    if (defaultValue === void 0) {
+      defaultValue = getDefaultValue(schema, { strategy: "always" });
+    }
+    return defaultValue;
   }
   /**
    * Add a new child to an array or object at the specified parent path.
@@ -2265,8 +2377,23 @@ var SchemaRuntime = class {
     if (!parentNode || !parentNode.canAdd) {
       return false;
     }
-    const parentValue = this.getValue(normalizedPath);
+    let parentValue = this.getValue(normalizedPath);
     const parentSchema = parentNode.schema;
+    if (parentNode.type === "array") {
+      if (Array.isArray(parentValue)) ; else if (parentValue === void 0 || parentValue === null) {
+        parentValue = [];
+        this.setValueAtPath(normalizedPath, parentValue);
+      } else {
+        return false;
+      }
+    } else if (parentNode.type === "object") {
+      if (parentValue && typeof parentValue === "object") ; else if (parentValue === void 0 || parentValue === null) {
+        parentValue = {};
+        this.setValueAtPath(normalizedPath, parentValue);
+      } else {
+        return false;
+      }
+    }
     if (parentNode.type === "array" && Array.isArray(parentValue)) {
       const newIndex = parentValue.length;
       const { schema: subschema, keywordLocationToken } = getSubSchema(
@@ -2276,14 +2403,14 @@ var SchemaRuntime = class {
       if (!keywordLocationToken) {
         return false;
       }
-      const defaultValue = initialValue !== void 0 ? initialValue : getDefaultValue(subschema);
+      const defaultValue = initialValue !== void 0 ? initialValue : this.getDefaultValueForAdd(subschema);
       const itemPath = jsonPointerJoin(normalizedPath, String(newIndex));
       const success = setJsonPointer(this.value, itemPath, defaultValue);
       if (!success) return false;
       this.reconcile(normalizedPath);
       this.notify({ type: "value", path: normalizedPath });
       return true;
-    } else if (parentNode.type === "object" && parentValue && typeof parentValue === "object") {
+    } else if (parentNode.type === "object" && typeof parentValue === "object") {
       if (!key) {
         return false;
       }
@@ -2294,7 +2421,7 @@ var SchemaRuntime = class {
       if (!keywordLocationToken) {
         return false;
       }
-      const defaultValue = initialValue !== void 0 ? initialValue : getDefaultValue(subschema);
+      const defaultValue = initialValue !== void 0 ? initialValue : this.getDefaultValueForAdd(subschema);
       const propertyPath = jsonPointerJoin(normalizedPath, key);
       const success = setJsonPointer(this.value, propertyPath, defaultValue);
       if (!success) return false;
@@ -2309,22 +2436,28 @@ var SchemaRuntime = class {
    * 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, value) {
     const normalizedPath = normalizeRootPath(path);
-    if (normalizedPath === ROOT_PATH) {
-      this.value = value;
-    } else {
-      const success = setJsonPointer(this.value, normalizedPath, value);
-      if (!success) return false;
+    if (value === void 0 && normalizedPath !== ROOT_PATH) {
+      const node = this.findNode(normalizedPath);
+      if (node && !node.isRequired) {
+        return this.removeValueInternal(normalizedPath);
+      }
     }
+    const success = this.setValueAtPath(normalizedPath, value);
+    if (!success) return false;
     this.reconcile(normalizedPath);
     this.notify({ type: "value", path: normalizedPath });
     return true;
@@ -2388,22 +2521,56 @@ var SchemaRuntime = class {
    * 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
    */
-  applySchemaDefaults(instanceLocation, newSchema, type) {
-    const value = this.getValue(instanceLocation);
+  applySchemaDefaults(instanceLocation, newSchema, type, isRequired = true) {
+    const strategy = this.options.autoFillDefaults;
+    if (strategy === "never") {
+      return;
+    }
+    let value = this.getValue(instanceLocation);
+    const isRoot = instanceLocation === ROOT_PATH;
     if (type === "object" && newSchema.properties) {
+      const requiredSet = new Set(newSchema.required || []);
+      const hasAnyDefaults = Object.entries(newSchema.properties).some(
+        ([key, subschema]) => {
+          const defaultValue = getDefaultValue(subschema, { strategy });
+          if (defaultValue !== void 0) return true;
+          const isChildRequired = requiredSet.has(key);
+          if (isChildRequired && (subschema.type === "object" || subschema.type === "array")) {
+            return true;
+          }
+          return false;
+        }
+      );
+      const shouldInitialize = (value === void 0 || value === null) && hasAnyDefaults && (isRoot || isRequired);
+      if (shouldInitialize) {
+        value = {};
+        this.setValueAtPath(normalizeRootPath(instanceLocation), value);
+      }
       const obj = value && typeof value === "object" ? value : null;
       if (!obj) return;
       for (const [key, subschema] of Object.entries(newSchema.properties)) {
         const hasValue = obj[key] !== void 0;
+        const isChildRequired = requiredSet.has(key);
         if (!hasValue) {
-          const defaultValue = getDefaultValue(subschema);
+          const defaultValue = getDefaultValue(subschema, { strategy });
           if (defaultValue !== void 0) {
             const propertyPath = jsonPointerJoin(instanceLocation, key);
             setJsonPointer(this.value, propertyPath, defaultValue);
+          } else if (isChildRequired && subschema.type === "object") {
+            const propertyPath = jsonPointerJoin(instanceLocation, key);
+            setJsonPointer(this.value, propertyPath, {});
+          } else if (isChildRequired && subschema.type === "array") {
+            const propertyPath = jsonPointerJoin(instanceLocation, key);
+            setJsonPointer(this.value, propertyPath, []);
           }
         }
       }
@@ -2414,7 +2581,8 @@ var SchemaRuntime = class {
       if (!arr) return;
       for (let i = 0; i < newSchema.prefixItems.length; i++) {
         if (arr[i] === void 0) {
-          const defaultValue = getDefaultValue(newSchema.prefixItems[i]);
+          const itemSchema = newSchema.prefixItems[i];
+          const defaultValue = getDefaultValue(itemSchema, { strategy });
           if (defaultValue !== void 0) {
             const itemPath = jsonPointerJoin(instanceLocation, String(i));
             setJsonPointer(this.value, itemPath, defaultValue);
@@ -2438,7 +2606,7 @@ var SchemaRuntime = class {
       }
     }
     const newChildren = [];
-    const processChild = (childKey, childSchema, childkeywordLocation, canRemove = false) => {
+    const processChild = (childKey, childSchema, childkeywordLocation, canRemove = false, isRequired = false) => {
       const childinstanceLocation = jsonPointerJoin(instanceLocation, childKey);
       let childNode = oldChildrenMap.get(childinstanceLocation);
       if (childNode) {
@@ -2451,7 +2619,8 @@ var SchemaRuntime = class {
         );
       }
       childNode.canRemove = canRemove;
-      this.buildNode(childNode, childSchema, options);
+      childNode.isRequired = isRequired;
+      this.buildNode(childNode, childSchema, { ...options, isRequired });
       newChildren.push(childNode);
     };
     switch (type) {
@@ -2464,11 +2633,13 @@ var SchemaRuntime = class {
             effectiveSchema.properties
           )) {
             processedKeys.add(key);
+            const isChildRequired = effectiveSchema.required?.includes(key) ?? false;
             processChild(
               key,
               subschema,
               `${keywordLocation}/properties/${key}`,
-              false
+              false,
+              isChildRequired
             );
           }
         }
@@ -2483,7 +2654,9 @@ var SchemaRuntime = class {
                   key,
                   subschema,
                   `${keywordLocation}/patternProperties/${jsonPointerEscape(pattern)}`,
-                  true
+                  true,
+                  false
+                  // patternProperties are never required
                 );
               }
             }
@@ -2497,7 +2670,9 @@ var SchemaRuntime = class {
                 key,
                 subschema,
                 `${keywordLocation}/additionalProperties`,
-                true
+                true,
+                false
+                // additionalProperties are never required
               );
             }
           }
@@ -2515,7 +2690,9 @@ var SchemaRuntime = class {
                 String(i),
                 effectiveSchema.prefixItems[i],
                 `${keywordLocation}/prefixItems/${i}`,
-                false
+                false,
+                true
+                // array items are always considered required
               );
             }
           }
@@ -2525,7 +2702,9 @@ var SchemaRuntime = class {
                 String(i),
                 effectiveSchema.items,
                 `${keywordLocation}/items`,
+                true,
                 true
+                // array items are always considered required
               );
             }
           }
@@ -2542,6 +2721,7 @@ var SchemaRuntime = class {
    * 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.
    */
   buildNode(node, schema, options = {}) {
     const { keywordLocation, instanceLocation } = node;
@@ -2559,17 +2739,25 @@ var SchemaRuntime = class {
       if (schemaChanged) {
         this.updateNodeDependencies(node, schema);
       }
+      const isRequired = options.isRequired ?? true;
       const { type, effectiveSchema, error } = resolveEffectiveSchema(
         this.validator,
         node.originalSchema,
         value,
         keywordLocation,
-        instanceLocation
+        instanceLocation,
+        isRequired
       );
-      const effectiveSchemaChanged = !deepEqual(effectiveSchema, node.schema) || type !== node.type;
-      const errorChanged = !deepEqual(error, node.error);
+      const isInitialBuild = node.version === -1;
+      const effectiveSchemaChanged = isInitialBuild || !deepEqual(effectiveSchema, node.schema) || type !== node.type;
+      const errorChanged = isInitialBuild || !deepEqual(error, node.error);
       if (effectiveSchemaChanged) {
-        this.applySchemaDefaults(instanceLocation, effectiveSchema, type);
+        this.applySchemaDefaults(
+          instanceLocation,
+          effectiveSchema,
+          type,
+          isRequired
+        );
       }
       node.schema = effectiveSchema;
       node.type = type;