@fgv/ts-json 1.9.5 → 2.0.1-alpha.0

package/lib/packlets/editor/jsonEditor.js

@@ -0,0 +1,333 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonEditor = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const rules_1 = require("./rules");
+const json_1 = require("../json");
+const jsonEditorState_1 = require("./jsonEditorState");
+/**
+ * A {@link JsonEditor | JsonEditor} can be used to edit JSON objects in place or to
+ * clone any JSON value, applying a default context and optional set of editor rules that
+ * were supplied at initialization.
+ * @public
+ */
+class JsonEditor {
+    /**
+     * Protected constructor for {@link Editor.JsonEditor | JsonEditor} and derived classes.
+     * External consumers should instantiate via the {@link Editor.JsonEditor.create | create static method}.
+     * @param options - Optional partial {@link Editor.IJsonEditorOptions | editor options} for the
+     * constructed editor.
+     * @param rules - Any {@link Editor.IJsonEditorRule | editor rules} to be applied by the editor.
+     * @internal
+     */
+    constructor(options, rules) {
+        this.options = JsonEditor._getDefaultOptions(options).orThrow();
+        this._rules = rules || JsonEditor.getDefaultRules(this.options).orThrow();
+    }
+    /**
+     * Default singleton {@link Editor.JsonEditor | JsonEditor} for simple use. Applies all rules
+     * but with no default context.
+     */
+    static get default() {
+        if (!JsonEditor._default) {
+            const rules = this.getDefaultRules().orDefault();
+            JsonEditor._default = new JsonEditor(undefined, rules);
+        }
+        return JsonEditor._default;
+    }
+    /**
+     * Constructs a new {@link Editor.JsonEditor | JsonEditor}.
+     * @param options - Optional partial {@link Editor.IJsonEditorOptions | editor options} for the
+     * constructed editor.
+     * @param rules - Optional set of {@link Editor.IJsonEditorRule | editor rules} to be applied by the editor.
+     * @readonly A new {@link Editor.JsonEditor | JsonEditor}.
+     */
+    static create(options, rules) {
+        return (0, ts_utils_1.captureResult)(() => new JsonEditor(options, rules));
+    }
+    /**
+     * Gets the default set of rules to be applied for a given set of options.
+     * By default, all available rules (templates, conditionals, multi-value and references)
+     * are applied.
+     * @param options - Optional partial {@link Editor.IJsonEditorOptions | editor options} for
+     * all rules.
+     * @returns Default {@link Editor.IJsonEditorRule | editor rules} with any supplied options
+     * applied.
+     */
+    static getDefaultRules(options) {
+        return (0, ts_utils_1.mapResults)([
+            rules_1.TemplatedJsonEditorRule.create(options),
+            rules_1.ConditionalJsonEditorRule.create(options),
+            rules_1.MultiValueJsonEditorRule.create(options),
+            rules_1.ReferenceJsonEditorRule.create(options)
+        ]);
+    }
+    /**
+     * @internal
+     */
+    static _getDefaultOptions(options) {
+        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) {
+            validation = {
+                onInvalidPropertyName: 'error',
+                onInvalidPropertyValue: 'error',
+                onUndefinedPropertyValue: 'ignore'
+            };
+        }
+        return (0, ts_utils_1.succeed)({ context, validation });
+    }
+    /**
+     * Merges a supplied source object into a supplied target, updating the target object.
+     * @param target - The target {@link JsonObject | object} to be updated
+     * @param src - The source {@link JsonObject | object} to be merged
+     * @param runtimeContext - An optional {@link IJsonContext | IJsonContext} supplying variables
+     * and references.
+     * @returns `Success` with the original source {@link JsonObject | object} if merge was successful.
+     * Returns `Failure` with details if an error occurs.
+     */
+    mergeObjectInPlace(target, src, runtimeContext) {
+        const state = new jsonEditorState_1.JsonEditorState(this, this.options, runtimeContext);
+        return this._mergeObjectInPlace(target, src, state).onSuccess((merged) => {
+            return this._finalizeAndMerge(merged, state);
+        });
+    }
+    /**
+     * Merges multiple supplied source objects into a supplied target, updating the target
+     * object and using the default context supplied at creation time.
+     * @param target - The target {@link JsonObject | object} to be updated
+     * @param srcObjects - {@link JsonObject | Objects} to be merged into the target object, in the order
+     * supplied.
+     * @returns `Success` with the original source {@link JsonObject | object} if merge was successful.
+     * Returns `Failure` with details if an error occurs.
+     */
+    mergeObjectsInPlace(target, srcObjects) {
+        return this.mergeObjectsInPlaceWithContext(this.options.context, target, srcObjects);
+    }
+    /**
+     * Merges multiple supplied source objects into a supplied target, updating the target
+     * object and using an optional {@link IJsonContext | context} supplied in the call.
+     * @param context - An optional {@link IJsonContext | IJsonContext} supplying variables and
+     * references.
+     * @param base - The base {@link JsonObject | object} to be updated
+     * @param srcObjects - Objects to be merged into the target object, in the order supplied.
+     * @returns `Success` with the original source {@link JsonObject | object} if merge was successful.
+     * Returns `Failure` with details if an error occurs.
+     */
+    mergeObjectsInPlaceWithContext(context, base, srcObjects) {
+        for (const src of srcObjects) {
+            const mergeResult = this.mergeObjectInPlace(base, src, context);
+            if (mergeResult.isFailure()) {
+                return mergeResult.withFailureDetail('error');
+            }
+        }
+        return (0, ts_utils_1.succeedWithDetail)(base);
+    }
+    /**
+     * Deep clones a supplied {@link JsonValue | JSON value}, applying all editor rules and a default
+     * or optionally supplied context
+     * @param src - The {@link JsonValue | JsonValue} to be cloned.
+     * @param context - An optional {@link IJsonContext | JSON context} supplying variables and references.
+     */
+    clone(src, context) {
+        const state = new jsonEditorState_1.JsonEditorState(this, this.options, context);
+        let value = src;
+        let valueResult = this._editValue(src, state);
+        while (valueResult.isSuccess()) {
+            value = valueResult.value;
+            valueResult = this._editValue(value, state);
+        }
+        if (valueResult.detail === 'error' || valueResult.detail === 'ignore') {
+            return valueResult;
+        }
+        if ((0, json_1.isJsonPrimitive)(value) || value === null) {
+            return (0, ts_utils_1.succeedWithDetail)(value, 'edited');
+        }
+        else if ((0, json_1.isJsonObject)(value)) {
+            return this.mergeObjectInPlace({}, value, state.context).withFailureDetail('error');
+        }
+        else if ((0, json_1.isJsonArray)(value)) {
+            return this._cloneArray(value, state.context);
+        }
+        else if (value === undefined) {
+            return state.failValidation('undefinedPropertyValue');
+        }
+        return state.failValidation('invalidPropertyValue', `Cannot convert invalid JSON: "${JSON.stringify(value)}"`);
+    }
+    /**
+     *
+     * @param target -
+     * @param src -
+     * @param state -
+     * @returns
+     * @internal
+     */
+    _mergeObjectInPlace(target, src, state) {
+        for (const key in src) {
+            if (src.hasOwnProperty(key)) {
+                const propResult = this._editProperty(key, src[key], state);
+                if (propResult.isSuccess()) {
+                    if (propResult.detail === 'deferred') {
+                        state.defer(propResult.value);
+                    }
+                    else {
+                        const mergeResult = this._mergeObjectInPlace(target, propResult.value, state);
+                        if (mergeResult.isFailure()) {
+                            return mergeResult;
+                        }
+                    }
+                }
+                else if (propResult.detail === 'inapplicable') {
+                    const valueResult = this.clone(src[key], state.context).onSuccess((cloned) => {
+                        return this._mergeClonedProperty(target, key, cloned, state);
+                    });
+                    if (valueResult.isFailure() && valueResult.detail === 'error') {
+                        return (0, ts_utils_1.fail)(`${key}: ${valueResult.message}`);
+                    }
+                }
+                else if (propResult.detail !== 'ignore') {
+                    return (0, ts_utils_1.fail)(`${key}: ${propResult.message}`);
+                }
+            }
+            else {
+                return (0, ts_utils_1.fail)(`${key}: Cannot merge inherited properties`);
+            }
+        }
+        return (0, ts_utils_1.succeed)(target);
+    }
+    /**
+     *
+     * @param src -
+     * @param context -
+     * @returns
+     * @internal
+     */
+    _cloneArray(src, context) {
+        const results = src.map((v) => {
+            return this.clone(v, context);
+        });
+        return (0, ts_utils_1.mapDetailedResults)(results, ['ignore'])
+            .onSuccess((converted) => {
+            return (0, ts_utils_1.succeed)(converted);
+        })
+            .withFailureDetail('error');
+    }
+    /**
+     *
+     * @param target -
+     * @param key -
+     * @param newValue -
+     * @param state -
+     * @returns
+     * @internal
+     */
+    _mergeClonedProperty(target, key, newValue, state) {
+        const existing = target[key];
+        // merge is called right after clone so this should never happen
+        // since clone itself will have failed
+        // istanbul ignore else
+        if ((0, json_1.isJsonPrimitive)(newValue)) {
+            target[key] = newValue;
+            return (0, ts_utils_1.succeedWithDetail)(newValue, 'edited');
+        }
+        else if ((0, json_1.isJsonObject)(newValue)) {
+            if ((0, json_1.isJsonObject)(existing)) {
+                return this.mergeObjectInPlace(existing, newValue, state.context).withFailureDetail('error');
+            }
+            target[key] = newValue;
+            return (0, ts_utils_1.succeedWithDetail)(newValue, 'edited');
+        }
+        else if ((0, json_1.isJsonArray)(newValue)) {
+            if ((0, json_1.isJsonArray)(existing)) {
+                target[key] = existing.concat(...newValue);
+                return (0, ts_utils_1.succeedWithDetail)(target[key], 'edited');
+            }
+            target[key] = newValue;
+            return (0, ts_utils_1.succeedWithDetail)(newValue, 'edited');
+        }
+        else {
+            return (0, ts_utils_1.failWithDetail)(`Invalid JSON: ${JSON.stringify(newValue)}`, 'error');
+        }
+    }
+    /**
+     *
+     * @param key -
+     * @param value -
+     * @param state -
+     * @returns
+     * @internal
+     */
+    _editProperty(key, value, state) {
+        for (const rule of this._rules) {
+            const ruleResult = rule.editProperty(key, value, state);
+            if (ruleResult.isSuccess() || ruleResult.detail !== 'inapplicable') {
+                return ruleResult;
+            }
+        }
+        return (0, ts_utils_1.failWithDetail)('inapplicable', 'inapplicable');
+    }
+    /**
+     *
+     * @param value -
+     * @param state -
+     * @returns
+     * @internal
+     */
+    _editValue(value, state) {
+        for (const rule of this._rules) {
+            const ruleResult = rule.editValue(value, state);
+            if (ruleResult.isSuccess() || ruleResult.detail !== 'inapplicable') {
+                return ruleResult;
+            }
+        }
+        return (0, ts_utils_1.failWithDetail)('inapplicable', 'inapplicable');
+    }
+    /**
+     *
+     * @param target -
+     * @param state -
+     * @returns
+     * @internal
+     */
+    _finalizeAndMerge(target, state) {
+        const deferred = state.deferred;
+        if (deferred.length > 0) {
+            for (const rule of this._rules) {
+                const ruleResult = rule.finalizeProperties(deferred, state);
+                if (ruleResult.isSuccess()) {
+                    return this.mergeObjectsInPlaceWithContext(state.context, target, ruleResult.value).withFailureDetail('error');
+                }
+                else if (ruleResult.detail === 'ignore') {
+                    (0, ts_utils_1.succeedWithDetail)(target, 'edited');
+                }
+                else if (ruleResult.detail !== 'inapplicable') {
+                    return (0, ts_utils_1.failWithDetail)(ruleResult.message, ruleResult.detail);
+                }
+            }
+        }
+        return (0, ts_utils_1.succeedWithDetail)(target, 'edited');
+    }
+}
+exports.JsonEditor = JsonEditor;
+//# sourceMappingURL=jsonEditor.js.map

package/lib/packlets/editor/jsonEditor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonEditor.js","sourceRoot":"","sources":["../../../src/packlets/editor/jsonEditor.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport {\n  DetailedResult,\n  Result,\n  captureResult,\n  fail,\n  failWithDetail,\n  mapDetailedResults,\n  mapResults,\n  succeed,\n  succeedWithDetail\n} from '@fgv/ts-utils';\nimport {\n  ConditionalJsonEditorRule,\n  MultiValueJsonEditorRule,\n  ReferenceJsonEditorRule,\n  TemplatedJsonEditorRule\n} from './rules';\n\nimport { IJsonContext } from '../context';\nimport { JsonArray, JsonObject, JsonValue, isJsonArray, isJsonObject, isJsonPrimitive } from '../json';\nimport {\n  IJsonCloneEditor,\n  IJsonEditorOptions,\n  IJsonEditorValidationOptions,\n  JsonEditFailureReason,\n  JsonPropertyEditFailureReason\n} from './common';\n\nimport { IJsonEditorRule } from './jsonEditorRule';\nimport { JsonEditorState } from './jsonEditorState';\n\n/**\n * A {@link JsonEditor | JsonEditor} can be used to edit JSON objects in place or to\n * clone any JSON value, applying a default context and optional set of editor rules that\n * were supplied at initialization.\n * @public\n */\nexport class JsonEditor implements IJsonCloneEditor {\n  /**\n   * Default singleton {@link Editor.JsonEditor | JsonEditor}.\n   * @internal\n   */\n  protected static _default?: JsonEditor;\n\n  /**\n   * Full set of {@link Editor.IJsonEditorOptions | editor options} in effect for this editor.\n   */\n  public options: IJsonEditorOptions;\n\n  /**\n   * The set of {@link Editor.IJsonEditorRule | editor rules} applied by this editor.\n   * @internal\n   */\n  protected _rules: IJsonEditorRule[];\n\n  /**\n   * Protected constructor for {@link Editor.JsonEditor | JsonEditor} and derived classes.\n   * External consumers should instantiate via the {@link Editor.JsonEditor.create | create static method}.\n   * @param options - Optional partial {@link Editor.IJsonEditorOptions | editor options} for the\n   * constructed editor.\n   * @param rules - Any {@link Editor.IJsonEditorRule | editor rules} to be applied by the editor.\n   * @internal\n   */\n  protected constructor(options?: Partial<IJsonEditorOptions>, rules?: IJsonEditorRule[]) {\n    this.options = JsonEditor._getDefaultOptions(options).orThrow();\n    this._rules = rules || JsonEditor.getDefaultRules(this.options).orThrow();\n  }\n\n  /**\n   * Default singleton {@link Editor.JsonEditor | JsonEditor} for simple use. Applies all rules\n   * but with no default context.\n   */\n  public static get default(): JsonEditor {\n    if (!JsonEditor._default) {\n      const rules = this.getDefaultRules().orDefault();\n      JsonEditor._default = new JsonEditor(undefined, rules);\n    }\n    return JsonEditor._default;\n  }\n\n  /**\n   * Constructs a new {@link Editor.JsonEditor | JsonEditor}.\n   * @param options - Optional partial {@link Editor.IJsonEditorOptions | editor options} for the\n   * constructed editor.\n   * @param rules - Optional set of {@link Editor.IJsonEditorRule | editor rules} to be applied by the editor.\n   * @readonly A new {@link Editor.JsonEditor | JsonEditor}.\n   */\n  public static create(options?: Partial<IJsonEditorOptions>, rules?: IJsonEditorRule[]): Result<JsonEditor> {\n    return captureResult(() => new JsonEditor(options, rules));\n  }\n\n  /**\n   * Gets the default set of rules to be applied for a given set of options.\n   * By default, all available rules (templates, conditionals, multi-value and references)\n   * are applied.\n   * @param options - Optional partial {@link Editor.IJsonEditorOptions | editor options} for\n   * all rules.\n   * @returns Default {@link Editor.IJsonEditorRule | editor rules} with any supplied options\n   * applied.\n   */\n  public static getDefaultRules(options?: IJsonEditorOptions): Result<IJsonEditorRule[]> {\n    return mapResults<IJsonEditorRule>([\n      TemplatedJsonEditorRule.create(options),\n      ConditionalJsonEditorRule.create(options),\n      MultiValueJsonEditorRule.create(options),\n      ReferenceJsonEditorRule.create(options)\n    ]);\n  }\n\n  /**\n   * @internal\n   */\n  protected static _getDefaultOptions(options?: Partial<IJsonEditorOptions>): Result<IJsonEditorOptions> {\n    const context: IJsonContext | undefined = options?.context;\n    let validation: IJsonEditorValidationOptions | undefined = options?.validation;\n    if (validation === undefined) {\n      validation = {\n        onInvalidPropertyName: 'error',\n        onInvalidPropertyValue: 'error',\n        onUndefinedPropertyValue: 'ignore'\n      };\n    }\n    return succeed({ context, validation });\n  }\n\n  /**\n   * Merges a supplied source object into a supplied target, updating the target object.\n   * @param target - The target {@link JsonObject | object} to be updated\n   * @param src - The source {@link JsonObject | object} to be merged\n   * @param runtimeContext - An optional {@link IJsonContext | IJsonContext} supplying variables\n   * and references.\n   * @returns `Success` with the original source {@link JsonObject | object} if merge was successful.\n   * Returns `Failure` with details if an error occurs.\n   */\n  public mergeObjectInPlace(\n    target: JsonObject,\n    src: JsonObject,\n    runtimeContext?: IJsonContext\n  ): Result<JsonObject> {\n    const state = new JsonEditorState(this, this.options, runtimeContext);\n    return this._mergeObjectInPlace(target, src, state).onSuccess((merged) => {\n      return this._finalizeAndMerge(merged, state);\n    });\n  }\n\n  /**\n   * Merges multiple supplied source objects into a supplied target, updating the target\n   * object and using the default context supplied at creation time.\n   * @param target - The target {@link JsonObject | object} to be updated\n   * @param srcObjects - {@link JsonObject | Objects} to be merged into the target object, in the order\n   * supplied.\n   * @returns `Success` with the original source {@link JsonObject | object} if merge was successful.\n   * Returns `Failure` with details if an error occurs.\n   */\n  public mergeObjectsInPlace(target: JsonObject, srcObjects: JsonObject[]): Result<JsonObject> {\n    return this.mergeObjectsInPlaceWithContext(this.options.context, target, srcObjects);\n  }\n\n  /**\n   * Merges multiple supplied source objects into a supplied target, updating the target\n   * object and using an optional {@link IJsonContext | context} supplied in the call.\n   * @param context - An optional {@link IJsonContext | IJsonContext} supplying variables and\n   * references.\n   * @param base - The base {@link JsonObject | object} to be updated\n   * @param srcObjects - Objects to be merged into the target object, in the order supplied.\n   * @returns `Success` with the original source {@link JsonObject | object} if merge was successful.\n   * Returns `Failure` with details if an error occurs.\n   */\n  public mergeObjectsInPlaceWithContext(\n    context: IJsonContext | undefined,\n    base: JsonObject,\n    srcObjects: JsonObject[]\n  ): Result<JsonObject> {\n    for (const src of srcObjects) {\n      const mergeResult = this.mergeObjectInPlace(base, src, context);\n      if (mergeResult.isFailure()) {\n        return mergeResult.withFailureDetail('error');\n      }\n    }\n    return succeedWithDetail(base);\n  }\n\n  /**\n   * Deep clones a supplied {@link JsonValue | JSON value}, applying all editor rules and a default\n   * or optionally supplied context\n   * @param src - The {@link JsonValue | JsonValue} to be cloned.\n   * @param context - An optional {@link IJsonContext | JSON context} supplying variables and references.\n   */\n  public clone(src: JsonValue, context?: IJsonContext): DetailedResult<JsonValue, JsonEditFailureReason> {\n    const state = new JsonEditorState(this, this.options, context);\n    let value = src;\n    let valueResult = this._editValue(src, state);\n\n    while (valueResult.isSuccess()) {\n      value = valueResult.value;\n      valueResult = this._editValue(value, state);\n    }\n\n    if (valueResult.detail === 'error' || valueResult.detail === 'ignore') {\n      return valueResult;\n    }\n\n    if (isJsonPrimitive(value) || value === null) {\n      return succeedWithDetail(value, 'edited');\n    } else if (isJsonObject(value)) {\n      return this.mergeObjectInPlace({}, value, state.context).withFailureDetail('error');\n    } else if (isJsonArray(value)) {\n      return this._cloneArray(value, state.context);\n    } else if (value === undefined) {\n      return state.failValidation('undefinedPropertyValue');\n    }\n    return state.failValidation(\n      'invalidPropertyValue',\n      `Cannot convert invalid JSON: \"${JSON.stringify(value)}\"`\n    );\n  }\n\n  /**\n   *\n   * @param target -\n   * @param src -\n   * @param state -\n   * @returns\n   * @internal\n   */\n  protected _mergeObjectInPlace(\n    target: JsonObject,\n    src: JsonObject,\n    state: JsonEditorState\n  ): Result<JsonObject> {\n    for (const key in src) {\n      if (src.hasOwnProperty(key)) {\n        const propResult = this._editProperty(key, src[key], state);\n        if (propResult.isSuccess()) {\n          if (propResult.detail === 'deferred') {\n            state.defer(propResult.value);\n          } else {\n            const mergeResult = this._mergeObjectInPlace(target, propResult.value, state);\n            if (mergeResult.isFailure()) {\n              return mergeResult;\n            }\n          }\n        } else if (propResult.detail === 'inapplicable') {\n          const valueResult = this.clone(src[key], state.context).onSuccess((cloned) => {\n            return this._mergeClonedProperty(target, key, cloned, state);\n          });\n\n          if (valueResult.isFailure() && valueResult.detail === 'error') {\n            return fail(`${key}: ${valueResult.message}`);\n          }\n        } else if (propResult.detail !== 'ignore') {\n          return fail(`${key}: ${propResult.message}`);\n        }\n      } else {\n        return fail(`${key}: Cannot merge inherited properties`);\n      }\n    }\n    return succeed(target);\n  }\n\n  /**\n   *\n   * @param src -\n   * @param context -\n   * @returns\n   * @internal\n   */\n  protected _cloneArray(\n    src: JsonArray,\n    context?: IJsonContext\n  ): DetailedResult<JsonArray, JsonEditFailureReason> {\n    const results = src.map((v) => {\n      return this.clone(v, context);\n    });\n\n    return mapDetailedResults<JsonValue, JsonEditFailureReason>(results, ['ignore'])\n      .onSuccess((converted) => {\n        return succeed(converted);\n      })\n      .withFailureDetail('error');\n  }\n\n  /**\n   *\n   * @param target -\n   * @param key -\n   * @param newValue -\n   * @param state -\n   * @returns\n   * @internal\n   */\n  protected _mergeClonedProperty(\n    target: JsonObject,\n    key: string,\n    newValue: JsonValue,\n    state: JsonEditorState\n  ): DetailedResult<JsonValue, JsonEditFailureReason> {\n    const existing = target[key];\n\n    // merge is called right after clone so this should never happen\n    // since clone itself will have failed\n    // istanbul ignore else\n    if (isJsonPrimitive(newValue)) {\n      target[key] = newValue;\n      return succeedWithDetail(newValue, 'edited');\n    } else if (isJsonObject(newValue)) {\n      if (isJsonObject(existing)) {\n        return this.mergeObjectInPlace(existing, newValue, state.context).withFailureDetail('error');\n      }\n      target[key] = newValue;\n      return succeedWithDetail(newValue, 'edited');\n    } else if (isJsonArray(newValue)) {\n      if (isJsonArray(existing)) {\n        target[key] = existing.concat(...newValue);\n        return succeedWithDetail(target[key], 'edited');\n      }\n      target[key] = newValue;\n      return succeedWithDetail(newValue, 'edited');\n    } else {\n      return failWithDetail(`Invalid JSON: ${JSON.stringify(newValue)}`, 'error');\n    }\n  }\n\n  /**\n   *\n   * @param key -\n   * @param value -\n   * @param state -\n   * @returns\n   * @internal\n   */\n  protected _editProperty(\n    key: string,\n    value: JsonValue,\n    state: JsonEditorState\n  ): DetailedResult<JsonObject, JsonPropertyEditFailureReason> {\n    for (const rule of this._rules) {\n      const ruleResult = rule.editProperty(key, value, state);\n      if (ruleResult.isSuccess() || ruleResult.detail !== 'inapplicable') {\n        return ruleResult;\n      }\n    }\n    return failWithDetail('inapplicable', 'inapplicable');\n  }\n\n  /**\n   *\n   * @param value -\n   * @param state -\n   * @returns\n   * @internal\n   */\n  protected _editValue(\n    value: JsonValue,\n    state: JsonEditorState\n  ): DetailedResult<JsonValue, JsonEditFailureReason> {\n    for (const rule of this._rules) {\n      const ruleResult = rule.editValue(value, state);\n      if (ruleResult.isSuccess() || ruleResult.detail !== 'inapplicable') {\n        return ruleResult;\n      }\n    }\n    return failWithDetail('inapplicable', 'inapplicable');\n  }\n\n  /**\n   *\n   * @param target -\n   * @param state -\n   * @returns\n   * @internal\n   */\n  protected _finalizeAndMerge(\n    target: JsonObject,\n    state: JsonEditorState\n  ): DetailedResult<JsonObject, JsonEditFailureReason> {\n    const deferred = state.deferred;\n    if (deferred.length > 0) {\n      for (const rule of this._rules) {\n        const ruleResult = rule.finalizeProperties(deferred, state);\n        if (ruleResult.isSuccess()) {\n          return this.mergeObjectsInPlaceWithContext(\n            state.context,\n            target,\n            ruleResult.value\n          ).withFailureDetail('error');\n        } else if (ruleResult.detail === 'ignore') {\n          succeedWithDetail(target, 'edited');\n        } else if (ruleResult.detail !== 'inapplicable') {\n          return failWithDetail(ruleResult.message, ruleResult.detail);\n        }\n      }\n    }\n    return succeedWithDetail(target, 'edited');\n  }\n}\n"]}

package/lib/packlets/editor/jsonEditorRule.d.ts

@@ -0,0 +1,64 @@
+import { DetailedResult } from '@fgv/ts-utils';
+import { JsonObject, JsonValue } from '../json';
+import { JsonEditFailureReason, JsonPropertyEditFailureReason } from './common';
+import { JsonEditorState } from './jsonEditorState';
+/**
+ * An {@link Editor.IJsonEditorRule | IJsonEditorRule} represents a single configurable
+ * rule to be applied by a {@link Editor.JsonEditor | JsonEditor}.
+ * @public
+ */
+export interface IJsonEditorRule {
+    /**
+     * Called by a {@link Editor.JsonEditor | JsonEditor} to possibly edit one of the properties being
+     * merged into a target object.
+     * @param key - The key of the property to be edited.
+     * @param value - The {@link JsonValue | value} of the property to be edited.
+     * @param state - {@link Editor.JsonEditorState | Editor state} which applies to the edit.
+     * @returns If the property was edited, returns `Success` with a {@link JsonObject | JsonObject} containing
+     * the edited results and with detail `'edited'`. If this property should be deferred for later consideration
+     * or merge, `Success` with detail `'deferred'` and a {@link JsonObject | JsonObject} to be finalized.  If
+     * the rule does not affect this property, returns `Failure` with detail `'inapplicable'`. If an error occurred
+     * while processing the error, returns `Failure` with detail `'error'`.
+     */
+    editProperty(key: string, value: JsonValue, state: JsonEditorState): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;
+    /**
+     * Called by a {@link Editor.JsonEditor | JsonEditor} to possibly edit a property value or array element.
+     * @param value - The {@link JsonValue | value} of the property to be edited.
+     * @param state - {@link Editor.JsonEditorState | Editor state} which applies to the edit.
+     * @returns Returns `Success` with the {@link JsonValue | JsonValue} to be inserted, with detail `'edited'` if
+     * the value was edited.  Returns `Failure` with `'inapplicable'` if the rule does not affect this value.
+     * Fails with detail `'ignore'` if the value is to be ignored, or with `'error'` if an error occurs.
+     */
+    editValue(value: JsonValue, state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
+    /**
+     * Called for each rule after all properties have been merged.  Any properties that were deferred
+     * during the initial edit pass are supplied as input.
+     * @param deferred - Any {@link JsonObject | objects} that were deferred during the first edit pass.
+     * @param state - {@link Editor.JsonEditorState | Editor state} which applies to the edit.
+     * @returns On `Success` return, any returned objects are merged in order and finalization
+     * is stopped. Finalization is also stopped on `Failure` with detail `'ignore'`. On `Failure`
+     * with detail `'inapplicable'`, finalization continues with the next rule. Fails with an
+     * error detail `'error'` and an informative message if an error occurs.
+     */
+    finalizeProperties(deferred: JsonObject[], state: JsonEditorState): DetailedResult<JsonObject[], JsonEditFailureReason>;
+}
+/**
+ * Default base implementation of {@link Editor.IJsonEditorRule | IJsonEditorRule} returns inapplicable for all operations so that
+ * derived classes need only implement the operations they actually support.
+ * @public
+ */
+export declare class JsonEditorRuleBase implements IJsonEditorRule {
+    /**
+     * {@inheritdoc Editor.IJsonEditorRule.editProperty}
+     */
+    editProperty(__key: string, __value: JsonValue, __state: JsonEditorState): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;
+    /**
+     * {@inheritdoc Editor.IJsonEditorRule.editValue}
+     */
+    editValue(__value: JsonValue, __state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
+    /**
+     * {@inheritdoc Editor.IJsonEditorRule.finalizeProperties}
+     */
+    finalizeProperties(__deferred: JsonObject[], __state: JsonEditorState): DetailedResult<JsonObject[], JsonEditFailureReason>;
+}
+//# sourceMappingURL=jsonEditorRule.d.ts.map

package/lib/packlets/editor/jsonEditorRule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonEditorRule.d.ts","sourceRoot":"","sources":["../../../src/packlets/editor/jsonEditorRule.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,cAAc,EAAkB,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,MAAM,UAAU,CAAC;AAEhF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;OAWG;IACH,YAAY,CACV,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,eAAe,GACrB,cAAc,CAAC,UAAU,EAAE,6BAA6B,CAAC,CAAC;IAE7D;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,eAAe,GAAG,cAAc,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAC;IAEtG;;;;;;;;;OASG;IACH,kBAAkB,CAChB,QAAQ,EAAE,UAAU,EAAE,EACtB,KAAK,EAAE,eAAe,GACrB,cAAc,CAAC,UAAU,EAAE,EAAE,qBAAqB,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IACxD;;OAEG;IAEI,YAAY,CACjB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,eAAe,GACvB,cAAc,CAAC,UAAU,EAAE,6BAA6B,CAAC;IAK5D;;OAEG;IACI,SAAS,CACd,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,eAAe,GACvB,cAAc,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAInD;;OAEG;IACI,kBAAkB,CACvB,UAAU,EAAE,UAAU,EAAE,EACxB,OAAO,EAAE,eAAe,GACvB,cAAc,CAAC,UAAU,EAAE,EAAE,qBAAqB,CAAC;CAGvD"}

package/lib/packlets/editor/jsonEditorRule.js

@@ -0,0 +1,54 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonEditorRuleBase = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Default base implementation of {@link Editor.IJsonEditorRule | IJsonEditorRule} returns inapplicable for all operations so that
+ * derived classes need only implement the operations they actually support.
+ * @public
+ */
+class JsonEditorRuleBase {
+    /**
+     * {@inheritdoc Editor.IJsonEditorRule.editProperty}
+     */
+    // istanbul ignore next
+    editProperty(__key, __value, __state) {
+        // istanbul ignore next
+        return (0, ts_utils_1.failWithDetail)('inapplicable', 'inapplicable');
+    }
+    /**
+     * {@inheritdoc Editor.IJsonEditorRule.editValue}
+     */
+    editValue(__value, __state) {
+        return (0, ts_utils_1.failWithDetail)('inapplicable', 'inapplicable');
+    }
+    /**
+     * {@inheritdoc Editor.IJsonEditorRule.finalizeProperties}
+     */
+    finalizeProperties(__deferred, __state) {
+        return (0, ts_utils_1.failWithDetail)('inapplicable', 'inapplicable');
+    }
+}
+exports.JsonEditorRuleBase = JsonEditorRuleBase;
+//# sourceMappingURL=jsonEditorRule.js.map

package/lib/packlets/editor/jsonEditorRule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonEditorRule.js","sourceRoot":"","sources":["../../../src/packlets/editor/jsonEditorRule.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAA+D;AAwD/D;;;;GAIG;AACH,MAAa,kBAAkB;IAC7B;;OAEG;IACH,uBAAuB;IAChB,YAAY,CACjB,KAAa,EACb,OAAkB,EAClB,OAAwB;QAExB,uBAAuB;QACvB,OAAO,IAAA,yBAAc,EAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACI,SAAS,CACd,OAAkB,EAClB,OAAwB;QAExB,OAAO,IAAA,yBAAc,EAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACI,kBAAkB,CACvB,UAAwB,EACxB,OAAwB;QAExB,OAAO,IAAA,yBAAc,EAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IACxD,CAAC;CACF;AAjCD,gDAiCC","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { DetailedResult, failWithDetail } from '@fgv/ts-utils';\nimport { JsonObject, JsonValue } from '../json';\nimport { JsonEditFailureReason, JsonPropertyEditFailureReason } from './common';\n\nimport { JsonEditorState } from './jsonEditorState';\n\n/**\n * An {@link Editor.IJsonEditorRule | IJsonEditorRule} represents a single configurable\n * rule to be applied by a {@link Editor.JsonEditor | JsonEditor}.\n * @public\n */\nexport interface IJsonEditorRule {\n  /**\n   * Called by a {@link Editor.JsonEditor | JsonEditor} to possibly edit one of the properties being\n   * merged into a target object.\n   * @param key - The key of the property to be edited.\n   * @param value - The {@link JsonValue | value} of the property to be edited.\n   * @param state - {@link Editor.JsonEditorState | Editor state} which applies to the edit.\n   * @returns If the property was edited, returns `Success` with a {@link JsonObject | JsonObject} containing\n   * the edited results and with detail `'edited'`. If this property should be deferred for later consideration\n   * or merge, `Success` with detail `'deferred'` and a {@link JsonObject | JsonObject} to be finalized.  If\n   * the rule does not affect this property, returns `Failure` with detail `'inapplicable'`. If an error occurred\n   * while processing the error, returns `Failure` with detail `'error'`.\n   */\n  editProperty(\n    key: string,\n    value: JsonValue,\n    state: JsonEditorState\n  ): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;\n\n  /**\n   * Called by a {@link Editor.JsonEditor | JsonEditor} to possibly edit a property value or array element.\n   * @param value - The {@link JsonValue | value} of the property to be edited.\n   * @param state - {@link Editor.JsonEditorState | Editor state} which applies to the edit.\n   * @returns Returns `Success` with the {@link JsonValue | JsonValue} to be inserted, with detail `'edited'` if\n   * the value was edited.  Returns `Failure` with `'inapplicable'` if the rule does not affect this value.\n   * Fails with detail `'ignore'` if the value is to be ignored, or with `'error'` if an error occurs.\n   */\n  editValue(value: JsonValue, state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;\n\n  /**\n   * Called for each rule after all properties have been merged.  Any properties that were deferred\n   * during the initial edit pass are supplied as input.\n   * @param deferred - Any {@link JsonObject | objects} that were deferred during the first edit pass.\n   * @param state - {@link Editor.JsonEditorState | Editor state} which applies to the edit.\n   * @returns On `Success` return, any returned objects are merged in order and finalization\n   * is stopped. Finalization is also stopped on `Failure` with detail `'ignore'`. On `Failure`\n   * with detail `'inapplicable'`, finalization continues with the next rule. Fails with an\n   * error detail `'error'` and an informative message if an error occurs.\n   */\n  finalizeProperties(\n    deferred: JsonObject[],\n    state: JsonEditorState\n  ): DetailedResult<JsonObject[], JsonEditFailureReason>;\n}\n\n/**\n * Default base implementation of {@link Editor.IJsonEditorRule | IJsonEditorRule} returns inapplicable for all operations so that\n * derived classes need only implement the operations they actually support.\n * @public\n */\nexport class JsonEditorRuleBase implements IJsonEditorRule {\n  /**\n   * {@inheritdoc Editor.IJsonEditorRule.editProperty}\n   */\n  // istanbul ignore next\n  public editProperty(\n    __key: string,\n    __value: JsonValue,\n    __state: JsonEditorState\n  ): DetailedResult<JsonObject, JsonPropertyEditFailureReason> {\n    // istanbul ignore next\n    return failWithDetail('inapplicable', 'inapplicable');\n  }\n\n  /**\n   * {@inheritdoc Editor.IJsonEditorRule.editValue}\n   */\n  public editValue(\n    __value: JsonValue,\n    __state: JsonEditorState\n  ): DetailedResult<JsonValue, JsonEditFailureReason> {\n    return failWithDetail('inapplicable', 'inapplicable');\n  }\n\n  /**\n   * {@inheritdoc Editor.IJsonEditorRule.finalizeProperties}\n   */\n  public finalizeProperties(\n    __deferred: JsonObject[],\n    __state: JsonEditorState\n  ): DetailedResult<JsonObject[], JsonEditFailureReason> {\n    return failWithDetail('inapplicable', 'inapplicable');\n  }\n}\n"]}

package/lib/packlets/editor/jsonEditorState.d.ts

@@ -0,0 +1,125 @@
+import { DetailedFailure, Result } from '@fgv/ts-utils';
+import { IJsonContext, IJsonReferenceMap, TemplateVars, VariableValue } from '../context';
+import { JsonObject } from '../json';
+import { IJsonCloneEditor, IJsonEditorOptions, IJsonEditorValidationOptions, JsonEditFailureReason, JsonEditorValidationRules } from './common';
+/**
+ * Represents the internal state of a {@link Editor.JsonEditor | JsonEditor}.
+ * @public
+ */
+export declare class JsonEditorState {
+    /**
+     * Static global counter used to assign each {@link Editor.JsonEditorState | JsonEditorState}
+     * a unique identifier.
+     * @internal
+     */
+    protected static _nextId: number;
+    /**
+     * The {@link Editor.IJsonCloneEditor | editor} for which this state applies.
+     */
+    readonly editor: IJsonCloneEditor;
+    /**
+     * Fully resolved {@link Editor.IJsonEditorOptions | editor options} that apply
+     * to the operation for which this state applies.
+     */
+    readonly options: IJsonEditorOptions;
+    /**
+     * Any deferred {@link JsonObject | objects} to be merged during finalization.
+     * @internal
+     */
+    protected readonly _deferred: JsonObject[];
+    /**
+     * Unique global identifier for this {@link Editor.JsonEditorState | state object}.
+     * @internal
+     */
+    protected readonly _id: number;
+    /**
+     * Constructs a new {@link Editor.JsonEditorState | JsonEditorState}.
+     * @param editor - The {@link Editor.IJsonCloneEditor | editor} to which this state
+     * applies.
+     * @param baseOptions - The {@link Editor.IJsonEditorOptions | editor options} that
+     * apply to this rule.
+     * @param runtimeContext - An optional {@link IJsonContext | JSON context} to be used
+     * for json value conversion.
+     */
+    constructor(editor: IJsonCloneEditor, baseOptions: IJsonEditorOptions, runtimeContext?: IJsonContext);
+    /**
+     * The optional {@link IJsonContext | JSON context} for this state.
+     */
+    get context(): IJsonContext | undefined;
+    /**
+     * An array of {@link JsonObject | objects} that are deferred for merge during
+     * finalization.
+     */
+    get deferred(): JsonObject[];
+    /**
+     * Merges an optional {@link IJsonContext | JSON context} into a supplied set
+     * of {@link Editor.IJsonEditorOptions | JSON editor options}.
+     * @param options - The {@link Editor.IJsonEditorOptions | IJsonEditorOptions} into
+     * which the the new context is to be merged.
+     * @param context - The {@link IJsonContext | JSON context} to be merged into the
+     * editor options.
+     * @returns `Success` with the supplied {@link Editor.IJsonEditorOptions | options} if
+     * there was nothing to merge, or aa new {@link Editor.IJsonEditorOptions | IJsonEditorOptions}
+     * constructed from the base options merged with the supplied context.  Returns `Failure`
+     * with more information if an error occurs.
+     * @internal
+     */
+    protected static _getEffectiveOptions(options: IJsonEditorOptions, context?: IJsonContext): Result<IJsonEditorOptions>;
+    /**
+     * Adds a supplied {@link JsonObject | object} to the deferred list.
+     * @param obj - The {@link JsonObject | object} to be deferred.
+     */
+    defer(obj: JsonObject): void;
+    /**
+     * Gets a {@link TemplateVars | TemplateVars} from the context of this {@link Editor.JsonEditorState | JsonEditorState},
+     * or from an optional supplied {@link IJsonContext | IJsonContext} if the current state has no default
+     * context.
+     * @param defaultContext - An optional default {@link IJsonContext | IJsonContext} to use as `TemplateVars`
+     * if the current state does not have context.
+     * @returns A {@link TemplateVars | TemplateVars} reflecting the appropriate {@link IJsonContext | JSON context}, or
+     * `undefined` if no vars are found.
+     */
+    getVars(defaultContext?: IJsonContext): TemplateVars | undefined;
+    /**
+     * Gets an {@link IJsonReferenceMap | reference map} containing any other values
+     * referenced during the operation.
+     * @param defaultContext - An optional default {@link IJsonContext | IJsonContext} to use as
+     * {@link TemplateVars | TemplateVars} if the current state does not have context.
+     * @returns An {@link IJsonReferenceMap | IJsonReferenceMap} containing any values referenced
+     * during this operation.
+     */
+    getRefs(defaultContext?: IJsonContext): IJsonReferenceMap | undefined;
+    /**
+     * Gets the context of this {@link Editor.JsonEditorState | JsonEditorState} or an optionally
+     * supplied default context if this state has no context.
+     * @param defaultContext - The default {@link IJsonContext | JSON context} to use as default
+     * if this state has no context.
+     * @returns The appropriate {@link IJsonContext | IJsonContext} or `undefined` if no context
+     * is available.
+     */
+    getContext(defaultContext?: IJsonContext): IJsonContext | undefined;
+    /**
+     * Constructs a new {@link IJsonContext | IJsonContext} by merging supplied variables
+     * and references into a supplied existing context.
+     * @param baseContext - The {@link IJsonContext | IJsonContext} into which variables
+     * and references are to be merged, or `undefined` to start with a default empty context.
+     * @param add - The {@link VariableValue | variable values} and/or
+     * {@link IJsonReferenceMap | JSON entity references} to be merged into the base context.
+     * @returns A new {@link IJsonContext | IJsonContext} created by merging the supplied values.
+     */
+    extendContext(baseContext: IJsonContext | undefined, add: {
+        vars?: VariableValue[];
+        refs?: IJsonReferenceMap[];
+    }): Result<IJsonContext | undefined>;
+    /**
+     * Helper method to constructs  `DetailedFailure` with appropriate details and messaging
+     * for various validation failures.
+     * @param rule - The {@link Editor.JsonEditorValidationRules | validation rule} that failed.
+     * @param message -  A string message describing the failed validation.
+     * @param validation - The {@link Editor.IJsonEditorValidationOptions | validation options}
+     * in effect.
+     * @returns A `DetailedFailure` with appropriate detail and message.
+     */
+    failValidation<T = JsonObject>(rule: JsonEditorValidationRules, message?: string, validation?: IJsonEditorValidationOptions): DetailedFailure<T, JsonEditFailureReason>;
+}
+//# sourceMappingURL=jsonEditorState.d.ts.map

package/lib/packlets/editor/jsonEditorState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonEditorState.d.ts","sourceRoot":"","sources":["../../../src/packlets/editor/jsonEditorState.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,eAAe,EAAE,MAAM,EAA2B,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAqB,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC7G,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,4BAA4B,EAC5B,qBAAqB,EACrB,yBAAyB,EAE1B,MAAM,UAAU,CAAC;AAElB;;;GAGG;AACH,qBAAa,eAAe;IAC1B;;;;OAIG;IACH,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAK;IAErC;;OAEG;IACH,SAAgB,MAAM,EAAE,gBAAgB,CAAC;IAEzC;;;OAGG;IACH,SAAgB,OAAO,EAAE,kBAAkB,CAAC;IAE5C;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,UAAU,EAAE,CAAM;IAEhD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAE/B;;;;;;;;OAQG;gBAED,MAAM,EAAE,gBAAgB,EACxB,WAAW,EAAE,kBAAkB,EAC/B,cAAc,CAAC,EAAE,YAAY;IAO/B;;OAEG;IACH,IAAW,OAAO,IAAI,YAAY,GAAG,SAAS,CAE7C;IAED;;;OAGG;IACH,IAAW,QAAQ,IAAI,UAAU,EAAE,CAElC;IAED;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,MAAM,CAAC,oBAAoB,CACnC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,YAAY,GACrB,MAAM,CAAC,kBAAkB,CAAC;IAS7B;;;OAGG;IACI,KAAK,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAInC;;;;;;;;OAQG;IACI,OAAO,CAAC,cAAc,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,SAAS;IAIvE;;;;;;;OAOG;IACI,OAAO,CAAC,cAAc,CAAC,EAAE,YAAY,GAAG,iBAAiB,GAAG,SAAS;IAI5E;;;;;;;OAOG;IACI,UAAU,CAAC,cAAc,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,SAAS;IAI1E;;;;;;;;OAQG;IACI,aAAa,CAClB,WAAW,EAAE,YAAY,GAAG,SAAS,EACrC,GAAG,EAAE;QAAE,IAAI,CAAC,EAAE,aAAa,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,iBAAiB,EAAE,CAAA;KAAE,GAC1D,MAAM,CAAC,YAAY,GAAG,SAAS,CAAC;IAKnC;;;;;;;;OAQG;IACI,cAAc,CAAC,CAAC,GAAG,UAAU,EAClC,IAAI,EAAE,yBAAyB,EAC/B,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,4BAA4B,GACxC,eAAe,CAAC,CAAC,EAAE,qBAAqB,CAAC;CAmB7C"}