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

package/lib/packlets/editor/jsonEditorState.js

@@ -0,0 +1,177 @@
+"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.JsonEditorState = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const context_1 = require("../context");
+/**
+ * Represents the internal state of a {@link Editor.JsonEditor | JsonEditor}.
+ * @public
+ */
+class JsonEditorState {
+    /**
+     * 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, baseOptions, runtimeContext) {
+        /**
+         * Any deferred {@link JsonObject | objects} to be merged during finalization.
+         * @internal
+         */
+        this._deferred = [];
+        this.editor = editor;
+        this.options = JsonEditorState._getEffectiveOptions(baseOptions, runtimeContext).orThrow();
+        this._id = JsonEditorState._nextId++;
+    }
+    /**
+     * The optional {@link IJsonContext | JSON context} for this state.
+     */
+    get context() {
+        return this.options.context;
+    }
+    /**
+     * An array of {@link JsonObject | objects} that are deferred for merge during
+     * finalization.
+     */
+    get deferred() {
+        return this._deferred;
+    }
+    /**
+     * 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
+     */
+    static _getEffectiveOptions(options, context) {
+        if (!context) {
+            return (0, ts_utils_1.succeed)(options);
+        }
+        return context_1.JsonContextHelper.mergeContext(options.context, context).onSuccess((merged) => {
+            return (0, ts_utils_1.succeed)({ context: merged, validation: options.validation });
+        });
+    }
+    /**
+     * Adds a supplied {@link JsonObject | object} to the deferred list.
+     * @param obj - The {@link JsonObject | object} to be deferred.
+     */
+    defer(obj) {
+        this._deferred.push(obj);
+    }
+    /**
+     * 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) {
+        var _a, _b;
+        return (_b = (_a = this.options.context) === null || _a === void 0 ? void 0 : _a.vars) !== null && _b !== void 0 ? _b : defaultContext === null || defaultContext === void 0 ? void 0 : defaultContext.vars;
+    }
+    /**
+     * 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) {
+        var _a, _b;
+        return (_b = (_a = this.options.context) === null || _a === void 0 ? void 0 : _a.refs) !== null && _b !== void 0 ? _b : defaultContext === null || defaultContext === void 0 ? void 0 : defaultContext.refs;
+    }
+    /**
+     * 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) {
+        return context_1.JsonContextHelper.mergeContext(defaultContext, this.options.context).orDefault();
+    }
+    /**
+     * 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, add) {
+        const context = this.getContext(baseContext);
+        return context_1.JsonContextHelper.extendContext(context, add);
+    }
+    /**
+     * 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(rule, message, validation) {
+        let detail = 'error';
+        const effective = validation !== null && validation !== void 0 ? validation : this.options.validation;
+        switch (rule) {
+            case 'invalidPropertyName':
+                detail = effective.onInvalidPropertyName !== 'ignore' ? 'error' : 'inapplicable';
+                break;
+            case 'invalidPropertyValue':
+                detail = effective.onInvalidPropertyValue !== 'ignore' ? 'error' : 'ignore';
+                break;
+            case 'undefinedPropertyValue':
+                detail = effective.onUndefinedPropertyValue !== 'error' ? 'ignore' : 'error';
+                // istanbul ignore next
+                message = message !== null && message !== void 0 ? message : 'Cannot convert undefined to JSON';
+                break;
+        }
+        // istanbul ignore next
+        return (0, ts_utils_1.failWithDetail)(message !== null && message !== void 0 ? message : rule, detail);
+    }
+}
+/**
+ * Static global counter used to assign each {@link Editor.JsonEditorState | JsonEditorState}
+ * a unique identifier.
+ * @internal
+ */
+JsonEditorState._nextId = 0;
+exports.JsonEditorState = JsonEditorState;
+//# sourceMappingURL=jsonEditorState.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonEditorState.js","sourceRoot":"","sources":["../../../src/packlets/editor/jsonEditorState.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 { DetailedFailure, Result, failWithDetail, succeed } from '@fgv/ts-utils';\nimport { IJsonContext, IJsonReferenceMap, JsonContextHelper, TemplateVars, VariableValue } from '../context';\nimport { JsonObject } from '../json';\nimport {\n  IJsonCloneEditor,\n  IJsonEditorOptions,\n  IJsonEditorValidationOptions,\n  JsonEditFailureReason,\n  JsonEditorValidationRules,\n  JsonPropertyEditFailureReason\n} from './common';\n\n/**\n * Represents the internal state of a {@link Editor.JsonEditor | JsonEditor}.\n * @public\n */\nexport class JsonEditorState {\n  /**\n   * Static global counter used to assign each {@link Editor.JsonEditorState | JsonEditorState}\n   * a unique identifier.\n   * @internal\n   */\n  protected static _nextId: number = 0;\n\n  /**\n   * The {@link Editor.IJsonCloneEditor | editor} for which this state applies.\n   */\n  public readonly editor: IJsonCloneEditor;\n\n  /**\n   * Fully resolved {@link Editor.IJsonEditorOptions | editor options} that apply\n   * to the operation for which this state applies.\n   */\n  public readonly options: IJsonEditorOptions;\n\n  /**\n   * Any deferred {@link JsonObject | objects} to be merged during finalization.\n   * @internal\n   */\n  protected readonly _deferred: JsonObject[] = [];\n\n  /**\n   * Unique global identifier for this {@link Editor.JsonEditorState | state object}.\n   * @internal\n   */\n  protected readonly _id: number;\n\n  /**\n   * Constructs a new {@link Editor.JsonEditorState | JsonEditorState}.\n   * @param editor - The {@link Editor.IJsonCloneEditor | editor} to which this state\n   * applies.\n   * @param baseOptions - The {@link Editor.IJsonEditorOptions | editor options} that\n   * apply to this rule.\n   * @param runtimeContext - An optional {@link IJsonContext | JSON context} to be used\n   * for json value conversion.\n   */\n  public constructor(\n    editor: IJsonCloneEditor,\n    baseOptions: IJsonEditorOptions,\n    runtimeContext?: IJsonContext\n  ) {\n    this.editor = editor;\n    this.options = JsonEditorState._getEffectiveOptions(baseOptions, runtimeContext).orThrow();\n    this._id = JsonEditorState._nextId++;\n  }\n\n  /**\n   * The optional {@link IJsonContext | JSON context} for this state.\n   */\n  public get context(): IJsonContext | undefined {\n    return this.options.context;\n  }\n\n  /**\n   * An array of {@link JsonObject | objects} that are deferred for merge during\n   * finalization.\n   */\n  public get deferred(): JsonObject[] {\n    return this._deferred;\n  }\n\n  /**\n   * Merges an optional {@link IJsonContext | JSON context} into a supplied set\n   * of {@link Editor.IJsonEditorOptions | JSON editor options}.\n   * @param options - The {@link Editor.IJsonEditorOptions | IJsonEditorOptions} into\n   * which the the new context is to be merged.\n   * @param context - The {@link IJsonContext | JSON context} to be merged into the\n   * editor options.\n   * @returns `Success` with the supplied {@link Editor.IJsonEditorOptions | options} if\n   * there was nothing to merge, or aa new {@link Editor.IJsonEditorOptions | IJsonEditorOptions}\n   * constructed from the base options merged with the supplied context.  Returns `Failure`\n   * with more information if an error occurs.\n   * @internal\n   */\n  protected static _getEffectiveOptions(\n    options: IJsonEditorOptions,\n    context?: IJsonContext\n  ): Result<IJsonEditorOptions> {\n    if (!context) {\n      return succeed(options);\n    }\n    return JsonContextHelper.mergeContext(options.context, context).onSuccess((merged) => {\n      return succeed({ context: merged, validation: options.validation });\n    });\n  }\n\n  /**\n   * Adds a supplied {@link JsonObject | object} to the deferred list.\n   * @param obj - The {@link JsonObject | object} to be deferred.\n   */\n  public defer(obj: JsonObject): void {\n    this._deferred.push(obj);\n  }\n\n  /**\n   * Gets a {@link TemplateVars | TemplateVars} from the context of this {@link Editor.JsonEditorState | JsonEditorState},\n   * or from an optional supplied {@link IJsonContext | IJsonContext} if the current state has no default\n   * context.\n   * @param defaultContext - An optional default {@link IJsonContext | IJsonContext} to use as `TemplateVars`\n   * if the current state does not have context.\n   * @returns A {@link TemplateVars | TemplateVars} reflecting the appropriate {@link IJsonContext | JSON context}, or\n   * `undefined` if no vars are found.\n   */\n  public getVars(defaultContext?: IJsonContext): TemplateVars | undefined {\n    return this.options.context?.vars ?? defaultContext?.vars;\n  }\n\n  /**\n   * Gets an {@link IJsonReferenceMap | reference map} containing any other values\n   * referenced during the operation.\n   * @param defaultContext - An optional default {@link IJsonContext | IJsonContext} to use as\n   * {@link TemplateVars | TemplateVars} if the current state does not have context.\n   * @returns An {@link IJsonReferenceMap | IJsonReferenceMap} containing any values referenced\n   * during this operation.\n   */\n  public getRefs(defaultContext?: IJsonContext): IJsonReferenceMap | undefined {\n    return this.options.context?.refs ?? defaultContext?.refs;\n  }\n\n  /**\n   * Gets the context of this {@link Editor.JsonEditorState | JsonEditorState} or an optionally\n   * supplied default context if this state has no context.\n   * @param defaultContext - The default {@link IJsonContext | JSON context} to use as default\n   * if this state has no context.\n   * @returns The appropriate {@link IJsonContext | IJsonContext} or `undefined` if no context\n   * is available.\n   */\n  public getContext(defaultContext?: IJsonContext): IJsonContext | undefined {\n    return JsonContextHelper.mergeContext(defaultContext, this.options.context).orDefault();\n  }\n\n  /**\n   * Constructs a new {@link IJsonContext | IJsonContext} by merging supplied variables\n   * and references into a supplied existing context.\n   * @param baseContext - The {@link IJsonContext | IJsonContext} into which variables\n   * and references are to be merged, or `undefined` to start with a default empty context.\n   * @param add - The {@link VariableValue | variable values} and/or\n   * {@link IJsonReferenceMap | JSON entity references} to be merged into the base context.\n   * @returns A new {@link IJsonContext | IJsonContext} created by merging the supplied values.\n   */\n  public extendContext(\n    baseContext: IJsonContext | undefined,\n    add: { vars?: VariableValue[]; refs?: IJsonReferenceMap[] }\n  ): Result<IJsonContext | undefined> {\n    const context = this.getContext(baseContext);\n    return JsonContextHelper.extendContext(context, add);\n  }\n\n  /**\n   * Helper method to constructs  `DetailedFailure` with appropriate details and messaging\n   * for various validation failures.\n   * @param rule - The {@link Editor.JsonEditorValidationRules | validation rule} that failed.\n   * @param message -  A string message describing the failed validation.\n   * @param validation - The {@link Editor.IJsonEditorValidationOptions | validation options}\n   * in effect.\n   * @returns A `DetailedFailure` with appropriate detail and message.\n   */\n  public failValidation<T = JsonObject>(\n    rule: JsonEditorValidationRules,\n    message?: string,\n    validation?: IJsonEditorValidationOptions\n  ): DetailedFailure<T, JsonEditFailureReason> {\n    let detail: JsonPropertyEditFailureReason = 'error';\n    const effective = validation ?? this.options.validation;\n    switch (rule) {\n      case 'invalidPropertyName':\n        detail = effective.onInvalidPropertyName !== 'ignore' ? 'error' : 'inapplicable';\n        break;\n      case 'invalidPropertyValue':\n        detail = effective.onInvalidPropertyValue !== 'ignore' ? 'error' : 'ignore';\n        break;\n      case 'undefinedPropertyValue':\n        detail = effective.onUndefinedPropertyValue !== 'error' ? 'ignore' : 'error';\n        // istanbul ignore next\n        message = message ?? 'Cannot convert undefined to JSON';\n        break;\n    }\n    // istanbul ignore next\n    return failWithDetail(message ?? rule, detail);\n  }\n}\n"]}

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

@@ -0,0 +1,303 @@
+import { DetailedResult, Result } from '@fgv/ts-utils';
+import { IJsonContext, IJsonReferenceMap, JsonReferenceMapFailureReason } from '../context';
+import { JsonObject, JsonValue } from '../json';
+import { JsonEditor } from './jsonEditor';
+/**
+ * Options for creating a {@link ReferenceMapKeyPolicy | ReferenceMapKeyPolicy} object.
+ * @public
+ */
+export interface IReferenceMapKeyPolicyValidateOptions {
+    /**
+     * If `true`, the validator coerces keys to some valid value.
+     * If `false`, invalid keys cause an error.
+     */
+    makeValid?: boolean;
+}
+/**
+ * Policy object responsible for validating or correcting
+ * keys in a {@link IJsonReferenceMap | reference map}.
+ * @public
+ */
+export declare class ReferenceMapKeyPolicy<T> {
+    /**
+     * @internal
+     */
+    protected readonly _defaultOptions?: IReferenceMapKeyPolicyValidateOptions;
+    /**
+     * @internal
+     */
+    protected readonly _isValid: (key: string, item?: T) => boolean;
+    /**
+     * Constructs a new {@link ReferenceMapKeyPolicy | ReferenceMapKeyPolicy}.
+     * @param options - Optional {@link IReferenceMapKeyPolicyValidateOptions | options}
+     * used to construct the {@link ReferenceMapKeyPolicy}.
+     * @param isValid - An optional predicate to test a supplied key for validity.
+     */
+    constructor(options?: IReferenceMapKeyPolicyValidateOptions, isValid?: (key: string, item?: T) => boolean);
+    /**
+     * The static default key name validation predicate rejects keys that contain
+     * mustache templates or which start with the default conditional prefix
+     * `'?'`.
+     * @param key - The key to test.
+     * @returns `true` if the key is valid, `false` otherwise.
+     */
+    static defaultKeyPredicate(key: string): boolean;
+    /**
+     * Determines if a supplied key and item are valid according to the current policy.
+     * @param key - The key to be tested.
+     * @param item - The item to be tested.
+     * @returns `true` if the key and value are valid, `false` otherwise.
+     */
+    isValid(key: string, item?: T): boolean;
+    /**
+     * Determines if a supplied key and item are valid according to the current policy.
+     * @param key - The key to be tested.
+     * @param item - The item to be tested.
+     * @returns `Success` with the key if valid, `Failure` with an error message if invalid.
+     */
+    validate(key: string, item?: T, __options?: IReferenceMapKeyPolicyValidateOptions): Result<string>;
+    /**
+     * Validates an array of entries using the validation rules for this policy.
+     * @param items - The array of entries to be validated.
+     * @param options - Optional {@link IReferenceMapKeyPolicyValidateOptions | options} to control
+     * validation.
+     * @returns `Success` with an array of validated entries, or `Failure` with an error message
+     * if validation fails.
+     */
+    validateItems(items: [string, T][], options?: IReferenceMapKeyPolicyValidateOptions): Result<[string, T][]>;
+    /**
+     * Validates a `Map\<string, T\>` using the validation rules for this policy.
+     * @param items - The `Map\<string, T\>` to be validated.
+     * @param options - Optional {@link IReferenceMapKeyPolicyValidateOptions | options} to control
+     * validation.
+     * @returns `Success` with a new `Map\<string, T\>`, or `Failure` with an error message
+     * if validation fails.
+     */
+    validateMap(map: Map<string, T>, options?: IReferenceMapKeyPolicyValidateOptions): Result<Map<string, T>>;
+}
+/**
+ * A {@link PrefixKeyPolicy | PrefixKeyPolicy} enforces that all keys start with a supplied
+ * prefix, optionally adding the prefix as necessary.
+ * @public
+ */
+export declare class PrefixKeyPolicy<T> extends ReferenceMapKeyPolicy<T> {
+    /**
+     * The string prefix to be enforced by this policy.
+     */
+    readonly prefix: string;
+    /**
+     * Constructs a new {@link PrefixKeyPolicy | PrefixKeyPolicy}.
+     * @param prefix - The string prefix to be enforced or applied.
+     * @param options - Optional {@link IReferenceMapKeyPolicyValidateOptions | options} to
+     * configure the policy.
+     */
+    constructor(prefix: string, options?: IReferenceMapKeyPolicyValidateOptions);
+    /**
+     * Determines if a key is valid according to policy.
+     * @param key - The key to be tested.
+     * @param __item - The item to be tested.
+     * @returns `true` if the key starts with the expected prefix, `false` otherwise.
+     */
+    isValid(key: string, __item?: T): boolean;
+    /**
+     * Determines if a key is valid according to policy, optionally coercing to a valid value by
+     * adding the required prefix.
+     * @param key - The key to be tested.
+     * @param item - The item which corresponds to the key.
+     * @param options - Optional {@link IReferenceMapKeyPolicyValidateOptions | options} to guide
+     * validation.
+     * @returns `Success` with a valid key name if the supplied key is valid or if `makeValid` is set
+     * in the policy options. Returns `Failure` with an error message if an error occurs.
+     */
+    validate(key: string, item?: T, options?: IReferenceMapKeyPolicyValidateOptions): Result<string>;
+}
+/**
+ * Type representing either a `Map\<string, T\>` or a `Record\<string, T\>`.
+ * @public
+ */
+export type MapOrRecord<T> = Map<string, T> | Record<string, T>;
+/**
+ * Abstract base class with common functionality for simple
+ * {@link IJsonReferenceMap | reference map} implementations.
+ * {@link JsonValue | json values}.
+ * @public
+ */
+export declare abstract class SimpleJsonMapBase<T> implements IJsonReferenceMap {
+    /**
+     * The {@link ReferenceMapKeyPolicy | key policy} in effect for this map.
+     * @internal
+     */
+    protected readonly _keyPolicy: ReferenceMapKeyPolicy<T>;
+    /**
+     * A map containing keys and values already present in this map.
+     * @internal
+     */
+    protected readonly _values: Map<string, T>;
+    /**
+     * An optional {@link IJsonContext | IJsonContext} used for any conversions
+     * involving items in this map.
+     * @internal
+     */
+    protected readonly _context?: IJsonContext;
+    /**
+     * Constructs a new {@link SimpleJsonMap | SimpleJsonMap}.
+     * @param values - Initial values for the map.
+     * @param context - An optional {@link IJsonContext | IJsonContext} used for any conversions
+     * involving items in this map.
+     * @param keyPolicy - The {@link ReferenceMapKeyPolicy | key policy} to use for this map.
+     * @internal
+     */
+    protected constructor(values?: MapOrRecord<T>, context?: IJsonContext, keyPolicy?: ReferenceMapKeyPolicy<T>);
+    /**
+     * Returns a `Map\<string, T\>` derived from a supplied {@link MapOrRecord | MapOrRecord}
+     * @param values - The {@link MapOrRecord | MapOrRecord} to be returned as a map.
+     * @returns `Success` with the corresponding `Map\<string, T\>` or `Failure` with a
+     * message if an error occurs.
+     * @internal
+     */
+    protected static _toMap<T>(values?: MapOrRecord<T>): Result<Map<string, T>>;
+    /**
+     * 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 - key to be tested
+     * @returns `true` if the key is in the valid range, `false` otherwise.
+     */
+    keyIsInRange(key: string): boolean;
+    /**
+     * Determines if an entry with the specified key actually exists in the map.
+     * @param key - key to be tested
+     * @returns `true` if an object with the specified key exists, `false` otherwise.
+     */
+    has(key: string): boolean;
+    /**
+     * Gets a {@link JsonObject | JSON object} specified by key.
+     * @param key - key of the object to be retrieved
+     * @param context - optional {@link IJsonContext | JSON context} used to format the
+     * returned object.
+     * @returns {@link ts-utils#Success | `Success`} with the formatted object if successful.
+     * {@link ts-utils#Failure | `Failure`} with detail 'unknown' if no such object exists,
+     * or {@link ts-utils#Failure | `Failure`} with detail 'error' if the object was found
+     * but could not be formatted.
+     */
+    getJsonObject(key: string, context?: IJsonContext): DetailedResult<JsonObject, JsonReferenceMapFailureReason>;
+    /**
+     * Gets a {@link JsonValue | JSON value} specified by key.
+     * @param key - key of the value to be retrieved
+     * @param context - 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.
+     */
+    abstract getJsonValue(key: string, context?: IJsonContext): DetailedResult<JsonValue, JsonReferenceMapFailureReason>;
+}
+/**
+ * Initialization options for a {@link SimpleJsonMap | SimpleJsonMap}.
+ * @public
+ */
+export interface ISimpleJsonMapOptions {
+    keyPolicy?: ReferenceMapKeyPolicy<JsonValue>;
+    editor?: JsonEditor;
+}
+/**
+ * A {@link SimpleJsonMap | SimpleJsonMap } presents a view of a simple map
+ * of {@link JsonValue | JSON values}.
+ * @public
+ */
+export declare class SimpleJsonMap extends SimpleJsonMapBase<JsonValue> {
+    /**
+     * @internal
+     */
+    protected _editor?: JsonEditor;
+    /**
+     * Constructs a new {@link SimpleJsonMap | SimpleJsonMap} from the supplied objects
+     * @param values - A string-keyed `Map` or `Record` of the {@link JsonValue | JSON values}
+     * to be returned.
+     * @param context - Optional {@link IJsonContext | IJsonContext} used to format returned values.
+     * @param options - Optional {@link ISimpleJsonMapOptions | ISimpleJsonMapOptions} for initialization.
+     * @public
+     */
+    protected constructor(values?: MapOrRecord<JsonValue>, context?: IJsonContext, options?: ISimpleJsonMapOptions);
+    /**
+     * Creates a new {@link SimpleJsonMap | SimpleJsonMap} from the supplied objects
+     * @param values - A string-keyed `Map` or `Record` of the {@link JsonValue | JSON values}
+     * to be returned.
+     * @param context - Optional {@link IJsonContext | IJsonContext} used to format returned values.
+     * @param options - Optional {@link ISimpleJsonMapOptions | ISimpleJsonMapOptions} for initialization.
+     * @returns `Success` with a {@link SimpleJsonMap | SimpleJsonMap} or `Failure` with a message if
+     * an error occurs.
+     */
+    static createSimple(values?: MapOrRecord<JsonValue>, context?: IJsonContext, options?: ISimpleJsonMapOptions): Result<SimpleJsonMap>;
+    /**
+     * Gets a {@link JsonValue | JSON value} specified by key.
+     * @param key - key of the value to be retrieved
+     * @param context - 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.
+     */
+    getJsonValue(key: string, context?: IJsonContext): DetailedResult<JsonValue, JsonReferenceMapFailureReason>;
+    /**
+     * @internal
+     */
+    protected _clone(value: JsonValue, context?: IJsonContext): DetailedResult<JsonValue, JsonReferenceMapFailureReason>;
+}
+/**
+ * Initialization options for a {@link PrefixedJsonMap | PrefixedJsonMap}
+ * @public
+ */
+export interface IKeyPrefixOptions {
+    /**
+     * Indicates whether the prefix should be added automatically as needed (default true)
+     */
+    addPrefix?: boolean;
+    /**
+     * The prefix to be enforced
+     */
+    prefix: string;
+}
+/**
+ * A {@link PrefixedJsonMap | PrefixedJsonMap} enforces a supplied prefix for all contained values,
+ * optionally adding the prefix as necessary (default `true`).
+ * @public
+ */
+export declare class PrefixedJsonMap extends SimpleJsonMap {
+    /**
+     * Constructs a new {@link PrefixedJsonMap | PrefixedJsonMap} from the supplied values
+     * @param prefix - A string prefix to be enforced for and added to key names as necessary
+     * @param values - A string-keyed Map or Record of the {@link JsonValue | JsonValue} to be returned
+     * @param context - Optional {@link IJsonContext | JSON Context} used to format returned values
+     * @param editor - Optional {@link Editor.JsonEditor | JsonEditor} used to format returned values
+     * @public
+     */
+    protected constructor(values?: MapOrRecord<JsonValue>, context?: IJsonContext, options?: ISimpleJsonMapOptions);
+    /**
+     * Creates a new {@link PrefixedJsonMap | PrefixedJsonMap} from the supplied values
+     * @param prefix - A string prefix to be enforced for and added to key names as necessary
+     * @param values - A string-keyed Map or Record of the {@link JsonValue | JsonValue} to be returned
+     * @param context - Optional {@link IJsonContext | JSON Context} used to format returned values
+     * @param editor - Optional {@link Editor.JsonEditor | JsonEditor} used to format returned values
+     * @returns `Success` with a {@link PrefixedJsonMap | PrefixedJsonMap} or `Failure` with a message
+     * if an error occurs.
+     */
+    static createPrefixed(prefix: string, values?: MapOrRecord<JsonValue>, context?: IJsonContext, editor?: JsonEditor): Result<PrefixedJsonMap>;
+    /**
+     * Creates a new {@link PrefixedJsonMap | PrefixedJsonMap} from the supplied values
+     * @param prefixOptions - A KeyPrefixOptions indicating the prefix to enforce and whether that prefix should
+     * be added automatically if necessary (default true)
+     * @param values - A string-keyed Map or record of the {@link JsonValue | JsonValue} to be returned
+     * @param context - Optional {@link IJsonContext | JSON Context} used to format returned values
+     * @param editor - Optional {@link Editor.JsonEditor | JsonEditor} used to format returned values
+     */
+    static createPrefixed(prefixOptions: IKeyPrefixOptions, values?: MapOrRecord<JsonValue>, context?: IJsonContext, editor?: JsonEditor): Result<PrefixedJsonMap>;
+    /**
+     * Constructs a new {@link PrefixKeyPolicy | PrefixKeyPolicy} from a supplied prefix
+     * or set of {@link IKeyPrefixOptions | prefix options}.
+     * @param prefixOptions - The prefix or {@link IKeyPrefixOptions | prefix options} or options
+     * for the new policy.
+     * @returns A new {@link ReferenceMapKeyPolicy | ReferenceMapKeyPolicy} which enforces the
+     * supplied prefix or options.
+     * @internal
+     */
+    protected static _toPolicy(prefixOptions: string | IKeyPrefixOptions): ReferenceMapKeyPolicy<JsonValue>;
+}
+//# sourceMappingURL=jsonReferenceMap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsonReferenceMap.d.ts","sourceRoot":"","sources":["../../../src/packlets/editor/jsonReferenceMap.ts"],"names":[],"mappings":"AAsBA,OAAO,EACL,cAAc,EACd,MAAM,EAQP,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,SAAS,EAAgB,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,qCAAqC;IACpD;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,qBAAqB,CAAC,CAAC;IAClC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,qCAAqC,CAAC;IAE3E;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEhE;;;;;OAKG;gBAED,OAAO,CAAC,EAAE,qCAAqC,EAC/C,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,KAAK,OAAO;IAM9C;;;;;;OAMG;WACW,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIvD;;;;;OAKG;IACI,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,GAAG,OAAO;IAI9C;;;;;OAKG;IACI,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,EAAE,qCAAqC,GAAG,MAAM,CAAC,MAAM,CAAC;IAIzG;;;;;;;OAOG;IACI,aAAa,CAClB,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EACpB,OAAO,CAAC,EAAE,qCAAqC,GAC9C,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC;IAUxB;;;;;;;OAOG;IACI,WAAW,CAChB,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,EACnB,OAAO,CAAC,EAAE,qCAAqC,GAC9C,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;CAK1B;AAED;;;;GAIG;AACH,qBAAa,eAAe,CAAC,CAAC,CAAE,SAAQ,qBAAqB,CAAC,CAAC,CAAC;IAC9D;;OAEG;IACH,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B;;;;;OAKG;gBACgB,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qCAAqC;IAKlF;;;;;OAKG;IACI,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,OAAO;IAMhD;;;;;;;;;OASG;IACI,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,qCAAqC,GAAG,MAAM,CAAC,MAAM,CAAC;CAUxG;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,8BAAsB,iBAAiB,CAAC,CAAC,CAAE,YAAW,iBAAiB;IACrE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;IAExD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAE3C;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IAE3C;;;;;;;OAOG;IACH,SAAS,aACP,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,EACvB,OAAO,CAAC,EAAE,YAAY,EACtB,SAAS,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAQtC;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAS3E;;;;;OAKG;IACI,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzC;;;;OAIG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;;;;;;OASG;IACI,aAAa,CAClB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,GACrB,cAAc,CAAC,UAAU,EAAE,6BAA6B,CAAC;IAS5D;;;;;;;OAOG;aAEa,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,GACrB,cAAc,CAAC,SAAS,EAAE,6BAA6B,CAAC;CAC5D;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,iBAAiB,CAAC,SAAS,CAAC;IAC7D;;OAEG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAE/B;;;;;;;OAOG;IACH,SAAS,aACP,MAAM,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,EAC/B,OAAO,CAAC,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,qBAAqB;IAMjC;;;;;;;;OAQG;WACW,YAAY,CACxB,MAAM,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,EAC/B,OAAO,CAAC,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,MAAM,CAAC,aAAa,CAAC;IAIxB;;;;;;;OAOG;IACI,YAAY,CACjB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,GACrB,cAAc,CAAC,SAAS,EAAE,6BAA6B,CAAC;IAS3D;;OAEG;IACH,SAAS,CAAC,MAAM,CACd,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,YAAY,GACrB,cAAc,CAAC,SAAS,EAAE,6BAA6B,CAAC;CAW5D;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,aAAa;IAChD;;;;;;;OAOG;IACH,SAAS,aACP,MAAM,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,EAC/B,OAAO,CAAC,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,qBAAqB;IAKjC;;;;;;;;OAQG;WACW,cAAc,CAC1B,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,EAC/B,OAAO,CAAC,EAAE,YAAY,EACtB,MAAM,CAAC,EAAE,UAAU,GAClB,MAAM,CAAC,eAAe,CAAC;IAE1B;;;;;;;OAOG;WACW,cAAc,CAC1B,aAAa,EAAE,iBAAiB,EAChC,MAAM,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,EAC/B,OAAO,CAAC,EAAE,YAAY,EACtB,MAAM,CAAC,EAAE,UAAU,GAClB,MAAM,CAAC,eAAe,CAAC;IAY1B;;;;;;;;OAQG;IACH,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,iBAAiB,GAAG,qBAAqB,CAAC,SAAS,CAAC;CAMxG"}