@fgv/ts-json 5.0.0-2 → 5.0.0-21

package/lib/packlets/editor/jsonEditor.js

@@ -84,9 +84,15 @@ class JsonEditor {
         ]);
     }
     /**
+     * Creates a complete IJsonEditorOptions object from partial options, filling in
+     * default values for any missing properties. This ensures all editor instances
+     * have consistent, complete configuration including validation rules and merge behavior.
+     * @param options - Optional partial editor options to merge with defaults
+     * @returns Success with complete editor options, or Failure if validation fails
      * @internal
      */
     static _getDefaultOptions(options) {
+        var _a;
         const context = options === null || options === void 0 ? void 0 : options.context;
         let validation = options === null || options === void 0 ? void 0 : options.validation;
         if (validation === undefined) {
@@ -99,7 +105,14 @@ class JsonEditor {
         let merge = options === null || options === void 0 ? void 0 : options.merge;
         if (merge === undefined) {
             merge = {
-                arrayMergeBehavior: 'append'
+                arrayMergeBehavior: 'append',
+                nullAsDelete: false
+            };
+        }
+        else {
+            merge = {
+                arrayMergeBehavior: merge.arrayMergeBehavior,
+                nullAsDelete: (_a = merge.nullAsDelete) !== null && _a !== void 0 ? _a : false
             };
         }
         return (0, ts_utils_1.succeed)({ context, validation, merge });
@@ -171,7 +184,7 @@ class JsonEditor {
             return (0, ts_utils_1.succeedWithDetail)(value, 'edited');
         }
         else if ((0, ts_json_base_1.isJsonObject)(value)) {
-            return this.mergeObjectInPlace({}, value, state.context).withFailureDetail('error');
+            return this._cloneObjectWithoutNullAsDelete({}, value, state);
         }
         else if ((0, ts_json_base_1.isJsonArray)(value)) {
             return this._cloneArray(value, state.context);
@@ -182,16 +195,22 @@ class JsonEditor {
         return state.failValidation('invalidPropertyValue', `Cannot convert invalid JSON: "${JSON.stringify(value)}"`);
     }
     /**
-     *
-     * @param target -
-     * @param src -
-     * @param state -
-     * @returns
+     * Merges properties from a source object into a target object, applying editor rules and
+     * null-as-delete logic. This is the core merge implementation that handles property-by-property
+     * merging with rule processing and deferred property handling.
+     * @param target - The target object to merge properties into
+     * @param src - The source object containing properties to merge
+     * @param state - The editor state containing options and context
+     * @returns Success with the modified target object, or Failure with error details
      * @internal
      */
     _mergeObjectInPlace(target, src, state) {
         for (const key in src) {
             if (src.hasOwnProperty(key)) {
+                // Skip dangerous property names to prevent prototype pollution
+                if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+                    continue;
+                }
                 const propResult = this._editProperty(key, src[key], state);
                 if (propResult.isSuccess()) {
                     if (propResult.detail === 'deferred') {
@@ -223,10 +242,12 @@ class JsonEditor {
         return (0, ts_utils_1.succeed)(target);
     }
     /**
-     *
-     * @param src -
-     * @param context -
-     * @returns
+     * Creates a deep clone of a JSON array by recursively cloning each element.
+     * Each array element is cloned using the main clone method, preserving the
+     * editor's rules and validation settings.
+     * @param src - The source JSON array to clone
+     * @param context - Optional JSON context for cloning operations
+     * @returns Success with the cloned array, or Failure with error details
      * @internal
      */
     _cloneArray(src, context) {
@@ -240,17 +261,30 @@ class JsonEditor {
             .withFailureDetail('error');
     }
     /**
-     *
-     * @param target -
-     * @param key -
-     * @param newValue -
-     * @param state -
-     * @returns
+     * Merges a single cloned property value into a target object. This method handles
+     * the core merge logic including null-as-delete behavior, array merging, and
+     * recursive object merging. The null-as-delete check occurs before primitive
+     * handling to ensure null values can signal property deletion.
+     * @param target - The target object to merge the property into
+     * @param key - The property key being merged
+     * @param newValue - The cloned value to merge (from source object)
+     * @param state - The editor state containing merge options and context
+     * @returns Success with the merged value, or Failure with error details
      * @internal
      */
     _mergeClonedProperty(target, key, newValue, state) {
-        var _a, _b;
+        var _a, _b, _c;
+        // Skip dangerous property names to prevent prototype pollution
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+            return (0, ts_utils_1.succeedWithDetail)(newValue, 'edited');
+        }
         const existing = target[key];
+        // Handle null-as-delete behavior before primitive check
+        /* c8 ignore next 1 - ? is defense in depth */
+        if (newValue === null && ((_a = state.options.merge) === null || _a === void 0 ? void 0 : _a.nullAsDelete) === true) {
+            delete target[key];
+            return (0, ts_utils_1.succeedWithDetail)(null, 'edited');
+        }
         // merge is called right after clone so this should never happen
         // since clone itself will have failed
         if ((0, ts_json_base_1.isJsonPrimitive)(newValue)) {
@@ -268,7 +302,7 @@ class JsonEditor {
         if ((0, ts_json_base_1.isJsonArray)(newValue)) {
             if ((0, ts_json_base_1.isJsonArray)(existing)) {
                 /* c8 ignore next 1 - ?? is defense in depth */
-                const arrayMergeBehavior = (_b = (_a = state.options.merge) === null || _a === void 0 ? void 0 : _a.arrayMergeBehavior) !== null && _b !== void 0 ? _b : 'append';
+                const arrayMergeBehavior = (_c = (_b = state.options.merge) === null || _b === void 0 ? void 0 : _b.arrayMergeBehavior) !== null && _c !== void 0 ? _c : 'append';
                 switch (arrayMergeBehavior) {
                     case 'append':
                         target[key] = existing.concat(...newValue);
@@ -289,11 +323,13 @@ class JsonEditor {
         return (0, ts_utils_1.failWithDetail)(`Invalid JSON: ${JSON.stringify(newValue)}`, 'error');
     } /* c8 ignore stop */
     /**
-     *
-     * @param key -
-     * @param value -
-     * @param state -
-     * @returns
+     * Applies editor rules to a single property during merge operations. This method
+     * iterates through all configured editor rules to process the property, handling
+     * templates, conditionals, multi-value properties, and references.
+     * @param key - The property key to edit
+     * @param value - The property value to edit
+     * @param state - The editor state containing rules and context
+     * @returns Success with transformed property object, or Failure if rules cannot process
      * @internal
      */
     _editProperty(key, value, state) {
@@ -306,10 +342,12 @@ class JsonEditor {
         return (0, ts_utils_1.failWithDetail)('inapplicable', 'inapplicable');
     }
     /**
-     *
-     * @param value -
-     * @param state -
-     * @returns
+     * Applies editor rules to a single JSON value during clone operations. This method
+     * iterates through all configured editor rules to process the value, handling
+     * templates, conditionals, multi-value expressions, and references.
+     * @param value - The JSON value to edit and transform
+     * @param state - The editor state containing rules and context
+     * @returns Success with transformed value, or Failure if rules cannot process
      * @internal
      */
     _editValue(value, state) {
@@ -322,10 +360,41 @@ class JsonEditor {
         return (0, ts_utils_1.failWithDetail)('inapplicable', 'inapplicable');
     }
     /**
-     *
-     * @param target -
-     * @param state -
-     * @returns
+     * Clone an object without applying null-as-delete behavior.
+     * This preserves null values during cloning so they can be used for deletion signaling during merge.
+     * @param target - The target object to clone into
+     * @param src - The source object to clone
+     * @param state - The editor state
+     * @returns The cloned object
+     * @internal
+     */
+    _cloneObjectWithoutNullAsDelete(target, src, state) {
+        var _a, _b;
+        // Temporarily disable null-as-delete during cloning
+        const modifiedOptions = {
+            context: state.options.context,
+            validation: state.options.validation,
+            merge: {
+                /* c8 ignore next 1 - ? is defense in depth */
+                arrayMergeBehavior: (_b = (_a = state.options.merge) === null || _a === void 0 ? void 0 : _a.arrayMergeBehavior) !== null && _b !== void 0 ? _b : 'append',
+                nullAsDelete: false
+            }
+        };
+        const modifiedState = new jsonEditorState_1.JsonEditorState(state.editor, modifiedOptions, state.context);
+        return this._mergeObjectInPlace(target, src, modifiedState)
+            .onSuccess((merged) => {
+            return this._finalizeAndMerge(merged, modifiedState);
+        })
+            .withFailureDetail('error');
+    }
+    /**
+     * Finalizes the merge operation by processing any deferred properties and merging
+     * them into the target object. Deferred properties are those that require special
+     * processing after the initial merge phase, such as references that depend on
+     * other properties being resolved first.
+     * @param target - The target object that has been merged
+     * @param state - The editor state containing deferred properties and rules
+     * @returns Success with the finalized target object, or Failure with error details
      * @internal
      */
     _finalizeAndMerge(target, state) {

package/lib/test/legacy/jsonConverter.conditional.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=jsonConverter.conditional.test.d.ts.map

package/lib/test/legacy/jsonEditor/rules/conditional.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=conditional.test.d.ts.map

package/lib/test/legacy/jsonEditor/rules/multivalue.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=multivalue.test.d.ts.map

package/lib/test/legacy/jsonEditor/rules/references.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=references.test.d.ts.map

package/lib/test/legacy/jsonEditor/rules/templates.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=templates.test.d.ts.map

package/lib/test/unit/contextHelpers.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=contextHelpers.test.d.ts.map

package/lib/test/unit/converters.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=converters.test.d.ts.map

package/lib/test/unit/diff/jsonDiff.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=jsonDiff.test.d.ts.map

package/lib/test/unit/jsonConverter.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=jsonConverter.test.d.ts.map

package/lib/test/unit/jsonEditor/jsonEditor.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=jsonEditor.test.d.ts.map

package/lib/test/unit/jsonEditor/templateContext.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=templateContext.test.d.ts.map

package/lib/test/unit/jsonReferenceMap.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=jsonReferenceMap.test.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-json",
-  "version": "5.0.0-2",
+  "version": "5.0.0-21",
   "description": "Typescript utilities for working with JSON",
   "main": "lib/index.js",
   "types": "dist/ts-json.d.ts",
@@ -29,25 +29,25 @@
     "jest-extended": "^4.0.2",
     "mustache": "^4.2.0",
     "rimraf": "^5.0.7",
-    "ts-jest": "^29.4.0",
+    "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.7.3",
+    "typescript": "^5.8.3",
     "eslint-plugin-n": "^16.6.2",
-    "@rushstack/heft-node-rig": "~2.9.0",
-    "@rushstack/heft": "~0.74.0",
+    "@rushstack/heft-node-rig": "~2.9.3",
+    "@rushstack/heft": "~0.74.2",
     "heft-jest": "~1.0.2",
     "@types/heft-jest": "1.0.6",
-    "@microsoft/api-documenter": "^7.26.29",
+    "@microsoft/api-documenter": "^7.26.31",
     "@rushstack/eslint-config": "~4.4.0",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils": "5.0.0-2",
-    "@fgv/ts-utils-jest": "5.0.0-2",
-    "@fgv/ts-json-base": "5.0.0-2"
+    "@fgv/ts-utils": "5.0.0-21",
+    "@fgv/ts-utils-jest": "5.0.0-21",
+    "@fgv/ts-json-base": "5.0.0-21"
   },
   "peerDependencies": {
     "mustache": "^4.2.0",
-    "@fgv/ts-json-base": "5.0.0-2",
-    "@fgv/ts-utils": "5.0.0-2"
+    "@fgv/ts-utils": "5.0.0-21",
+    "@fgv/ts-json-base": "5.0.0-21"
   },
   "scripts": {
     "build": "heft build --clean",

package/src/index.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export * from './packlets/context';
+export * from './packlets/converters';
+export * from './packlets/editor';
+
+import * as Diff from './packlets/diff';
+
+export { Diff };

package/src/packlets/context/compositeJsonMap.ts

@@ -0,0 +1,120 @@
+/*
+ * Copyright (c) 2020 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { JsonObject, JsonValue, isJsonObject } from '@fgv/ts-json-base';
+import { DetailedResult, Result, captureResult, failWithDetail, succeedWithDetail } from '@fgv/ts-utils';
+import { IJsonContext, IJsonReferenceMap, JsonReferenceMapFailureReason } from './jsonContext';
+
+/**
+ * A {@link CompositeJsonMap | CompositeJsonMap} presents a composed view of one or more other
+ * {@link IJsonReferenceMap | JSON reference maps}.
+ * @public
+ */
+export class CompositeJsonMap implements IJsonReferenceMap {
+  /**
+   * The {@link IJsonReferenceMap | reference maps} from which this map is composed.
+   * @internal
+   */
+  protected _maps: IJsonReferenceMap[];
+
+  /**
+   * The {@link IJsonReferenceMap | reference maps} from which this map is to be composed.
+   * @param maps - An array o {@link IJsonReferenceMap | IJsonReferenceMap} containing the maps
+   * from which this map is to be composed.
+   * @internal
+   */
+  protected constructor(maps: IJsonReferenceMap[]) {
+    this._maps = maps;
+  }
+
+  /**
+   * Creates a new {@link CompositeJsonMap | CompositeJsonMap} from supplied
+   * {@link IJsonReferenceMap | maps}.
+   * @param maps - one or more {@link IJsonReferenceMap | object maps} to be composed.
+   */
+  public static create(maps: IJsonReferenceMap[]): Result<CompositeJsonMap> {
+    return captureResult(() => new CompositeJsonMap(maps));
+  }
+
+  /**
+   * Determine if a key might be valid for this map but does not determine
+   * if key actually exists. Allows key range to be constrained.
+   * @param key - The key to be tested.
+   * @returns `true` if the key is in the valid range, `false` otherwise.
+   */
+  public keyIsInRange(key: string): boolean {
+    return this._maps.find((map) => map.keyIsInRange(key)) !== undefined;
+  }
+
+  /**
+   * Determines if an object with the specified key actually exists in the map.
+   * @param key - The key to be tested.
+   * @returns `true` if an object with the specified key exists, `false` otherwise.
+   */
+  public has(key: string): boolean {
+    return this._maps.find((map) => map.has(key)) !== undefined;
+  }
+
+  /**
+   * Gets a JSON object specified by key.
+   * @param key - The key of the object to be retrieved.
+   * @param context - An optional {@link IJsonContext | JSON Context} used to format the object.
+   * @returns `Success` with the formatted object if successful. `Failure` with detail `'unknown'`
+   * if no such object exists, or `Failure` with detail `'error'` if the object was found but
+   * could not be formatted.
+   */
+  public getJsonObject(
+    key: string,
+    context?: IJsonContext
+  ): DetailedResult<JsonObject, JsonReferenceMapFailureReason> {
+    return this.getJsonValue(key, context).onSuccess((jv) => {
+      if (!isJsonObject(jv)) {
+        return failWithDetail(`${key}: not an object`, 'error');
+      }
+      return succeedWithDetail(jv);
+    });
+  }
+
+  /**
+   * Gets a JSON value specified by key.
+   * @param key - The key of the object to be retrieved.
+   * @param context - An optional {@link IJsonContext | JSON Context} used to format the value.
+   * @returns `Success` with the formatted object if successful. `Failure` with detail `'unknown'`
+   * if no such object exists, or failure with detail `'error'` if the object was found but
+   * could not be formatted.
+   */
+  // eslint-disable-next-line no-use-before-define
+  public getJsonValue(
+    key: string,
+    context?: IJsonContext
+  ): DetailedResult<JsonValue, JsonReferenceMapFailureReason> {
+    for (const map of this._maps) {
+      if (map.keyIsInRange(key)) {
+        const result = map.getJsonValue(key, context);
+        if (result.isSuccess() || result.detail === 'error') {
+          return result;
+        }
+      }
+    }
+    return failWithDetail(`${key}: value not found`, 'unknown');
+  }
+}