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

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.35.2"
+    }
+  ]
+}

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export * from './packlets/context';
+export * from './packlets/converters';
+export * from './packlets/editor';
+export * from './packlets/json';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}

package/lib/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/*
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./packlets/context"), exports);
+__exportStar(require("./packlets/converters"), exports);
+__exportStar(require("./packlets/editor"), exports);
+__exportStar(require("./packlets/json"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;AAEH,qDAAmC;AACnC,wDAAsC;AACtC,oDAAkC;AAClC,kDAAgC","sourcesContent":["/*\n * Copyright (c) 2023 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\nexport * from './packlets/context';\nexport * from './packlets/converters';\nexport * from './packlets/editor';\nexport * from './packlets/json';\n"]}

package/lib/packlets/context/compositeJsonMap.d.ts

@@ -0,0 +1,60 @@
+import { DetailedResult, Result } from '@fgv/ts-utils';
+import { JsonObject, JsonValue } from '../json';
+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 declare 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[]);
+    /**
+     * Creates a new {@link CompositeJsonMap | CompositeJsonMap} from supplied
+     * {@link IJsonReferenceMap | maps}.
+     * @param maps - one or more {@link IJsonReferenceMap | object maps} to be composed.
+     */
+    static create(maps: IJsonReferenceMap[]): Result<CompositeJsonMap>;
+    /**
+     * 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.
+     */
+    keyIsInRange(key: string): boolean;
+    /**
+     * 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.
+     */
+    has(key: string): boolean;
+    /**
+     * Gets a {@link JsonObject | 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.
+     */
+    getJsonObject(key: string, context?: IJsonContext): DetailedResult<JsonObject, JsonReferenceMapFailureReason>;
+    /**
+     * Gets a {@link JsonValue | 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.
+     */
+    getJsonValue(key: string, context?: IJsonContext): DetailedResult<JsonValue, JsonReferenceMapFailureReason>;
+}
+//# sourceMappingURL=compositeJsonMap.d.ts.map

package/lib/packlets/context/compositeJsonMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compositeJsonMap.d.ts","sourceRoot":"","sources":["../../../src/packlets/context/compositeJsonMap.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,cAAc,EAAE,MAAM,EAAoD,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,UAAU,EAAE,SAAS,EAAgB,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAE/F;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAErC;;;;;OAKG;IACH,SAAS,aAAa,IAAI,EAAE,iBAAiB,EAAE;IAI/C;;;;OAIG;WACW,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAAC,gBAAgB,CAAC;IAIzE;;;;;OAKG;IACI,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzC;;;;OAIG;IACI,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;;;;OAOG;IACI,aAAa,CAClB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,GACrB,cAAc,CAAC,UAAU,EAAE,6BAA6B,CAAC;IAS5D;;;;;;;OAOG;IAEI,YAAY,CACjB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,YAAY,GACrB,cAAc,CAAC,SAAS,EAAE,6BAA6B,CAAC;CAW5D"}

package/lib/packlets/context/compositeJsonMap.js

@@ -0,0 +1,105 @@
+"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.CompositeJsonMap = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const json_1 = require("../json");
+/**
+ * A {@link CompositeJsonMap | CompositeJsonMap} presents a composed view of one or more other
+ * {@link IJsonReferenceMap | JSON reference maps}.
+ * @public
+ */
+class CompositeJsonMap {
+    /**
+     * 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
+     */
+    constructor(maps) {
+        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.
+     */
+    static create(maps) {
+        return (0, ts_utils_1.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.
+     */
+    keyIsInRange(key) {
+        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.
+     */
+    has(key) {
+        return this._maps.find((map) => map.has(key)) !== undefined;
+    }
+    /**
+     * Gets a {@link JsonObject | 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.
+     */
+    getJsonObject(key, context) {
+        return this.getJsonValue(key, context).onSuccess((jv) => {
+            if (!(0, json_1.isJsonObject)(jv)) {
+                return (0, ts_utils_1.failWithDetail)(`${key}: not an object`, 'error');
+            }
+            return (0, ts_utils_1.succeedWithDetail)(jv);
+        });
+    }
+    /**
+     * Gets a {@link JsonValue | 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
+    getJsonValue(key, context) {
+        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 (0, ts_utils_1.failWithDetail)(`${key}: value not found`, 'unknown');
+    }
+}
+exports.CompositeJsonMap = CompositeJsonMap;
+//# sourceMappingURL=compositeJsonMap.js.map

package/lib/packlets/context/compositeJsonMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compositeJsonMap.js","sourceRoot":"","sources":["../../../src/packlets/context/compositeJsonMap.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAAyG;AACzG,kCAA8D;AAG9D;;;;GAIG;AACH,MAAa,gBAAgB;IAO3B;;;;;OAKG;IACH,YAAsB,IAAyB;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,MAAM,CAAC,IAAyB;QAC5C,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;IACzD,CAAC;IAED;;;;;OAKG;IACI,YAAY,CAAC,GAAW;QAC7B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC;IACvE,CAAC;IAED;;;;OAIG;IACI,GAAG,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC;IAC9D,CAAC;IAED;;;;;;;OAOG;IACI,aAAa,CAClB,GAAW,EACX,OAAsB;QAEtB,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE;YACtD,IAAI,CAAC,IAAA,mBAAY,EAAC,EAAE,CAAC,EAAE;gBACrB,OAAO,IAAA,yBAAc,EAAC,GAAG,GAAG,iBAAiB,EAAE,OAAO,CAAC,CAAC;aACzD;YACD,OAAO,IAAA,4BAAiB,EAAC,EAAE,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,gDAAgD;IACzC,YAAY,CACjB,GAAW,EACX,OAAsB;QAEtB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,EAAE;YAC5B,IAAI,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE;gBACzB,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;gBAC9C,IAAI,MAAM,CAAC,SAAS,EAAE,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,EAAE;oBACnD,OAAO,MAAM,CAAC;iBACf;aACF;SACF;QACD,OAAO,IAAA,yBAAc,EAAC,GAAG,GAAG,mBAAmB,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC;CACF;AAxFD,4CAwFC","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, Result, captureResult, failWithDetail, succeedWithDetail } from '@fgv/ts-utils';\nimport { JsonObject, JsonValue, isJsonObject } from '../json';\nimport { IJsonContext, IJsonReferenceMap, JsonReferenceMapFailureReason } from './jsonContext';\n\n/**\n * A {@link CompositeJsonMap | CompositeJsonMap} presents a composed view of one or more other\n * {@link IJsonReferenceMap | JSON reference maps}.\n * @public\n */\nexport class CompositeJsonMap implements IJsonReferenceMap {\n  /**\n   * The {@link IJsonReferenceMap | reference maps} from which this map is composed.\n   * @internal\n   */\n  protected _maps: IJsonReferenceMap[];\n\n  /**\n   * The {@link IJsonReferenceMap | reference maps} from which this map is to be composed.\n   * @param maps - An array o {@link IJsonReferenceMap | IJsonReferenceMap} containing the maps\n   * from which this map is to be composed.\n   * @internal\n   */\n  protected constructor(maps: IJsonReferenceMap[]) {\n    this._maps = maps;\n  }\n\n  /**\n   * Creates a new {@link CompositeJsonMap | CompositeJsonMap} from supplied\n   * {@link IJsonReferenceMap | maps}.\n   * @param maps - one or more {@link IJsonReferenceMap | object maps} to be composed.\n   */\n  public static create(maps: IJsonReferenceMap[]): Result<CompositeJsonMap> {\n    return captureResult(() => new CompositeJsonMap(maps));\n  }\n\n  /**\n   * Determine if a key might be valid for this map but does not determine\n   * if key actually exists. Allows key range to be constrained.\n   * @param key - The key to be tested.\n   * @returns `true` if the key is in the valid range, `false` otherwise.\n   */\n  public keyIsInRange(key: string): boolean {\n    return this._maps.find((map) => map.keyIsInRange(key)) !== undefined;\n  }\n\n  /**\n   * Determines if an object with the specified key actually exists in the map.\n   * @param key - The key to be tested.\n   * @returns `true` if an object with the specified key exists, `false` otherwise.\n   */\n  public has(key: string): boolean {\n    return this._maps.find((map) => map.has(key)) !== undefined;\n  }\n\n  /**\n   * Gets a {@link JsonObject | JSON object} specified by key.\n   * @param key - The key of the object to be retrieved.\n   * @param context - An optional {@link IJsonContext | JSON Context} used to format the object.\n   * @returns `Success` with the formatted object if successful. `Failure` with detail `'unknown'`\n   * if no such object exists, or `Failure` with detail `'error'` if the object was found but\n   * could not be formatted.\n   */\n  public getJsonObject(\n    key: string,\n    context?: IJsonContext\n  ): DetailedResult<JsonObject, JsonReferenceMapFailureReason> {\n    return this.getJsonValue(key, context).onSuccess((jv) => {\n      if (!isJsonObject(jv)) {\n        return failWithDetail(`${key}: not an object`, 'error');\n      }\n      return succeedWithDetail(jv);\n    });\n  }\n\n  /**\n   * Gets a {@link JsonValue | JSON value} specified by key.\n   * @param key - The key of the object to be retrieved.\n   * @param context - An optional {@link IJsonContext | JSON Context} used to format the value.\n   * @returns `Success` with the formatted object if successful. `Failure` with detail `'unknown'`\n   * if no such object exists, or failure with detail `'error'` if the object was found but\n   * could not be formatted.\n   */\n  // eslint-disable-next-line no-use-before-define\n  public getJsonValue(\n    key: string,\n    context?: IJsonContext\n  ): DetailedResult<JsonValue, JsonReferenceMapFailureReason> {\n    for (const map of this._maps) {\n      if (map.keyIsInRange(key)) {\n        const result = map.getJsonValue(key, context);\n        if (result.isSuccess() || result.detail === 'error') {\n          return result;\n        }\n      }\n    }\n    return failWithDetail(`${key}: value not found`, 'unknown');\n  }\n}\n"]}

package/lib/packlets/context/contextHelpers.d.ts

@@ -0,0 +1,116 @@
+import { Result } from '@fgv/ts-utils';
+import { IJsonContext, IJsonReferenceMap, TemplateVars, VariableValue } from './jsonContext';
+/**
+ * Helper class for working with {@link IJsonContext | IJsonContext} objects.
+ * @public
+ */
+export declare class JsonContextHelper {
+    /**
+     * The base {@link IJsonContext | context} on which we are operating.
+     * @internal
+     */
+    protected _context?: IJsonContext;
+    /**
+     * Constructs a new {@link JsonContextHelper | JsonContextHelper}.
+     * @param context - The base {@link IJsonContext | IJsonContext} on
+     * which to operate.
+     */
+    constructor(context?: IJsonContext);
+    /**
+     * Creates a new {@link IJsonContext | context}.
+     * @param context - The base {@link IJsonContext | IJsonContext} on
+     * which to operate.
+     * @returns `Success` with the new {@link IJsonContext | IJsonContext},
+     * or `Failure` with more information if an error occurs.
+     */
+    static create(context?: IJsonContext): Result<JsonContextHelper>;
+    /**
+     * Static helper to extend context variables for a supplied {@link IJsonContext | IJsonContext}.
+     * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`
+     * to start from an empty context.
+     * @param vars - Optional {@link VariableValue | variable values} to be added to the
+     * {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link TemplateVars | TemplateVars} containing the variables
+     * from the base context, merged with and overridden by any that were passed in, or `Failure`
+     * with a message if an error occurs.
+     */
+    static extendContextVars(baseContext: IJsonContext | undefined, vars?: VariableValue[]): Result<TemplateVars | undefined>;
+    /**
+     * Static helper to extend context references for a supplied {@link IJsonContext | IJsonContext}.
+     * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`
+     * to start from an empty context.
+     * @param refs - Optional {@link IJsonReferenceMap | reference maps} to be added to the
+     * {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link IJsonReferenceMap | reference map} which projects
+     * the references from the base context, merged with and overridden by any that were passed in,
+     * or `Failure` with a message if an error occurs.
+     */
+    static extendContextRefs(baseContext: IJsonContext | undefined, refs?: IJsonReferenceMap[]): Result<IJsonReferenceMap | undefined>;
+    /**
+     * Static helper to extend context variables and references for a supplied {@link IJsonContext | IJsonContext}.
+     * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`
+     * to start from an empty context.
+     * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+     * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+     * references from the base context, merged with and overridden by any that were passed in, or
+     * `Failure` with a message if an error occurs.
+     */
+    static extendContext(baseContext?: IJsonContext | undefined, add?: {
+        vars?: VariableValue[];
+        refs?: IJsonReferenceMap[];
+    }): Result<IJsonContext | undefined>;
+    /**
+     * Static helper to merge context variables and references for a supplied {@link IJsonContext | IJsonContext}.
+     * @param baseContext - The {@link IJsonContext | IJsonContext} into which variables and references
+     * are to be merged, or `undefined` to start from an empty context.
+     * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+     * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+     * references from the base context, merged with and overridden by any that were passed in, or
+     * `Failure` with a message if an error occurs.
+     */
+    static mergeContext(baseContext: IJsonContext | undefined, add: IJsonContext | undefined): Result<IJsonContext | undefined>;
+    /**
+     * Applies {@link JsonContextHelper.extendContextVars | extendContextVars} to the
+     * {@link IJsonContext | IJsonContext} associated with this helper.
+     * @param vars - Optional {@link VariableValue | variable values} to be added to the
+     * @returns `Success` with a new {@link TemplateVars | TemplateVars} containing the variables
+     * from the base context, merged with and overridden by any that were passed in, or `Failure`
+     * with a message if an error occurs.
+     */
+    extendVars(vars?: VariableValue[]): Result<TemplateVars | undefined>;
+    /**
+     * Applies {@link JsonContextHelper.extendContextRefs | extendContextRefs} to the
+     * {@link IJsonContext | IJsonContext} associated with this helper.
+     * @param refs - Optional {@link IJsonReferenceMap | reference maps} to be added to the
+     * @returns `Success` with a new {@link IJsonReferenceMap | reference map} which projects
+     * the references from the base context, merged with and overridden by any that were passed in,
+     * or `Failure` with a message if an error occurs.
+     */
+    extendRefs(refs?: IJsonReferenceMap[]): Result<IJsonReferenceMap | undefined>;
+    /**
+     * Applies {@link JsonContextHelper.(extendContext:static) | extendContext} to the
+     * {@link IJsonContext | IJsonContext} associated with this helper.
+     * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+     * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+     * references from the base context, merged with and overridden by any that were passed in, or
+     * `Failure` with a message if an error occurs.
+     */
+    extendContext(add?: {
+        vars?: VariableValue[];
+        refs?: IJsonReferenceMap[];
+    }): Result<IJsonContext | undefined>;
+    /**
+     * Applies {@link JsonContextHelper.(mergeContext:static) | mergeContext} to the
+     * {@link IJsonContext | IJsonContext} associated with this helper.
+     * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+     * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+     * references from the base context, merged with and overridden by any that were passed in, or
+     * `Failure` with a message if an error occurs.
+     */
+    mergeContext(merge?: IJsonContext): Result<IJsonContext | undefined>;
+}
+//# sourceMappingURL=contextHelpers.d.ts.map

package/lib/packlets/context/contextHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextHelpers.d.ts","sourceRoot":"","sources":["../../../src/packlets/context/contextHelpers.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,MAAM,EAA0B,MAAM,eAAe,CAAC;AAE/D,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,aAAa,EAEd,MAAM,eAAe,CAAC;AAEvB;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IAElC;;;;OAIG;gBACgB,OAAO,CAAC,EAAE,YAAY;IAIzC;;;;;;OAMG;WACW,MAAM,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAIvE;;;;;;;;;OASG;WACW,iBAAiB,CAC7B,WAAW,EAAE,YAAY,GAAG,SAAS,EACrC,IAAI,CAAC,EAAE,aAAa,EAAE,GACrB,MAAM,CAAC,YAAY,GAAG,SAAS,CAAC;IAQnC;;;;;;;;;OASG;WACW,iBAAiB,CAC7B,WAAW,EAAE,YAAY,GAAG,SAAS,EACrC,IAAI,CAAC,EAAE,iBAAiB,EAAE,GACzB,MAAM,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAWxC;;;;;;;;;OASG;WACW,aAAa,CACzB,WAAW,CAAC,EAAE,YAAY,GAAG,SAAS,EACtC,GAAG,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,aAAa,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,iBAAiB,EAAE,CAAA;KAAE,GAC3D,MAAM,CAAC,YAAY,GAAG,SAAS,CAAC;IAenC;;;;;;;;;OASG;WACW,YAAY,CACxB,WAAW,EAAE,YAAY,GAAG,SAAS,EACrC,GAAG,EAAE,YAAY,GAAG,SAAS,GAC5B,MAAM,CAAC,YAAY,GAAG,SAAS,CAAC;IAmBnC;;;;;;;OAOG;IACI,UAAU,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,GAAG,MAAM,CAAC,YAAY,GAAG,SAAS,CAAC;IAI3E;;;;;;;OAOG;IACI,UAAU,CAAC,IAAI,CAAC,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAIpF;;;;;;;;OAQG;IACI,aAAa,CAAC,GAAG,CAAC,EAAE;QACzB,IAAI,CAAC,EAAE,aAAa,EAAE,CAAC;QACvB,IAAI,CAAC,EAAE,iBAAiB,EAAE,CAAC;KAC5B,GAAG,MAAM,CAAC,YAAY,GAAG,SAAS,CAAC;IAIpC;;;;;;;;OAQG;IACI,YAAY,CAAC,KAAK,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,YAAY,GAAG,SAAS,CAAC;CAG5E"}

package/lib/packlets/context/contextHelpers.js

@@ -0,0 +1,191 @@
+"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.JsonContextHelper = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const compositeJsonMap_1 = require("./compositeJsonMap");
+const jsonContext_1 = require("./jsonContext");
+/**
+ * Helper class for working with {@link IJsonContext | IJsonContext} objects.
+ * @public
+ */
+class JsonContextHelper {
+    /**
+     * Constructs a new {@link JsonContextHelper | JsonContextHelper}.
+     * @param context - The base {@link IJsonContext | IJsonContext} on
+     * which to operate.
+     */
+    constructor(context) {
+        this._context = context;
+    }
+    /**
+     * Creates a new {@link IJsonContext | context}.
+     * @param context - The base {@link IJsonContext | IJsonContext} on
+     * which to operate.
+     * @returns `Success` with the new {@link IJsonContext | IJsonContext},
+     * or `Failure` with more information if an error occurs.
+     */
+    static create(context) {
+        return (0, ts_utils_1.captureResult)(() => new JsonContextHelper(context));
+    }
+    /**
+     * Static helper to extend context variables for a supplied {@link IJsonContext | IJsonContext}.
+     * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`
+     * to start from an empty context.
+     * @param vars - Optional {@link VariableValue | variable values} to be added to the
+     * {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link TemplateVars | TemplateVars} containing the variables
+     * from the base context, merged with and overridden by any that were passed in, or `Failure`
+     * with a message if an error occurs.
+     */
+    static extendContextVars(baseContext, vars) {
+        var _a, _b;
+        if (vars && vars.length > 0) {
+            const extend = (_a = baseContext === null || baseContext === void 0 ? void 0 : baseContext.extendVars) !== null && _a !== void 0 ? _a : jsonContext_1.defaultExtendVars;
+            return extend((_b = baseContext === null || baseContext === void 0 ? void 0 : baseContext.vars) !== null && _b !== void 0 ? _b : {}, vars);
+        }
+        return (0, ts_utils_1.succeed)(baseContext === null || baseContext === void 0 ? void 0 : baseContext.vars);
+    }
+    /**
+     * Static helper to extend context references for a supplied {@link IJsonContext | IJsonContext}.
+     * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`
+     * to start from an empty context.
+     * @param refs - Optional {@link IJsonReferenceMap | reference maps} to be added to the
+     * {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link IJsonReferenceMap | reference map} which projects
+     * the references from the base context, merged with and overridden by any that were passed in,
+     * or `Failure` with a message if an error occurs.
+     */
+    static extendContextRefs(baseContext, refs) {
+        if (refs && refs.length > 0) {
+            const full = (baseContext === null || baseContext === void 0 ? void 0 : baseContext.refs) ? [...refs, baseContext.refs] : refs;
+            if (full.length > 1) {
+                return compositeJsonMap_1.CompositeJsonMap.create(full);
+            }
+            return (0, ts_utils_1.succeed)(full[0]);
+        }
+        return (0, ts_utils_1.succeed)(baseContext === null || baseContext === void 0 ? void 0 : baseContext.refs);
+    }
+    /**
+     * Static helper to extend context variables and references for a supplied {@link IJsonContext | IJsonContext}.
+     * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`
+     * to start from an empty context.
+     * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+     * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+     * references from the base context, merged with and overridden by any that were passed in, or
+     * `Failure` with a message if an error occurs.
+     */
+    static extendContext(baseContext, add) {
+        return JsonContextHelper.extendContextVars(baseContext, (add === null || add === void 0 ? void 0 : add.vars) || []).onSuccess((vars) => {
+            return JsonContextHelper.extendContextRefs(baseContext, (add === null || add === void 0 ? void 0 : add.refs) || []).onSuccess((refs) => {
+                if (!vars && !refs && !(baseContext === null || baseContext === void 0 ? void 0 : baseContext.extendVars)) {
+                    return (0, ts_utils_1.succeed)(undefined);
+                }
+                const rtrn = { vars, refs };
+                if (baseContext === null || baseContext === void 0 ? void 0 : baseContext.extendVars) {
+                    rtrn.extendVars = baseContext.extendVars;
+                }
+                return (0, ts_utils_1.succeed)(rtrn);
+            });
+        });
+    }
+    /**
+     * Static helper to merge context variables and references for a supplied {@link IJsonContext | IJsonContext}.
+     * @param baseContext - The {@link IJsonContext | IJsonContext} into which variables and references
+     * are to be merged, or `undefined` to start from an empty context.
+     * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+     * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+     * references from the base context, merged with and overridden by any that were passed in, or
+     * `Failure` with a message if an error occurs.
+     */
+    static mergeContext(baseContext, add) {
+        var _a, _b;
+        if (baseContext) {
+            if (add) {
+                const rtrn = {
+                    vars: (_a = add.vars) !== null && _a !== void 0 ? _a : baseContext.vars,
+                    refs: (_b = add.refs) !== null && _b !== void 0 ? _b : baseContext.refs
+                };
+                if (add.hasOwnProperty('extendVars')) {
+                    rtrn.extendVars = add.extendVars;
+                }
+                else if (baseContext.hasOwnProperty('extendVars')) {
+                    rtrn.extendVars = baseContext.extendVars;
+                }
+                return (0, ts_utils_1.succeed)(rtrn);
+            }
+            return (0, ts_utils_1.succeed)(baseContext);
+        }
+        return (0, ts_utils_1.succeed)(add);
+    }
+    /**
+     * Applies {@link JsonContextHelper.extendContextVars | extendContextVars} to the
+     * {@link IJsonContext | IJsonContext} associated with this helper.
+     * @param vars - Optional {@link VariableValue | variable values} to be added to the
+     * @returns `Success` with a new {@link TemplateVars | TemplateVars} containing the variables
+     * from the base context, merged with and overridden by any that were passed in, or `Failure`
+     * with a message if an error occurs.
+     */
+    extendVars(vars) {
+        return JsonContextHelper.extendContextVars(this._context, vars);
+    }
+    /**
+     * Applies {@link JsonContextHelper.extendContextRefs | extendContextRefs} to the
+     * {@link IJsonContext | IJsonContext} associated with this helper.
+     * @param refs - Optional {@link IJsonReferenceMap | reference maps} to be added to the
+     * @returns `Success` with a new {@link IJsonReferenceMap | reference map} which projects
+     * the references from the base context, merged with and overridden by any that were passed in,
+     * or `Failure` with a message if an error occurs.
+     */
+    extendRefs(refs) {
+        return JsonContextHelper.extendContextRefs(this._context, refs);
+    }
+    /**
+     * Applies {@link JsonContextHelper.(extendContext:static) | extendContext} to the
+     * {@link IJsonContext | IJsonContext} associated with this helper.
+     * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+     * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+     * references from the base context, merged with and overridden by any that were passed in, or
+     * `Failure` with a message if an error occurs.
+     */
+    extendContext(add) {
+        return JsonContextHelper.extendContext(this._context, add);
+    }
+    /**
+     * Applies {@link JsonContextHelper.(mergeContext:static) | mergeContext} to the
+     * {@link IJsonContext | IJsonContext} associated with this helper.
+     * @param add - Optional initializer containing {@link VariableValue | variable values} and/or
+     * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.
+     * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and
+     * references from the base context, merged with and overridden by any that were passed in, or
+     * `Failure` with a message if an error occurs.
+     */
+    mergeContext(merge) {
+        return JsonContextHelper.mergeContext(this._context, merge);
+    }
+}
+exports.JsonContextHelper = JsonContextHelper;
+//# sourceMappingURL=contextHelpers.js.map

package/lib/packlets/context/contextHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextHelpers.js","sourceRoot":"","sources":["../../../src/packlets/context/contextHelpers.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 { Result, captureResult, succeed } from '@fgv/ts-utils';\nimport { CompositeJsonMap } from './compositeJsonMap';\nimport {\n  IJsonContext,\n  IJsonReferenceMap,\n  TemplateVars,\n  VariableValue,\n  defaultExtendVars\n} from './jsonContext';\n\n/**\n * Helper class for working with {@link IJsonContext | IJsonContext} objects.\n * @public\n */\nexport class JsonContextHelper {\n  /**\n   * The base {@link IJsonContext | context} on which we are operating.\n   * @internal\n   */\n  protected _context?: IJsonContext;\n\n  /**\n   * Constructs a new {@link JsonContextHelper | JsonContextHelper}.\n   * @param context - The base {@link IJsonContext | IJsonContext} on\n   * which to operate.\n   */\n  public constructor(context?: IJsonContext) {\n    this._context = context;\n  }\n\n  /**\n   * Creates a new {@link IJsonContext | context}.\n   * @param context - The base {@link IJsonContext | IJsonContext} on\n   * which to operate.\n   * @returns `Success` with the new {@link IJsonContext | IJsonContext},\n   * or `Failure` with more information if an error occurs.\n   */\n  public static create(context?: IJsonContext): Result<JsonContextHelper> {\n    return captureResult(() => new JsonContextHelper(context));\n  }\n\n  /**\n   * Static helper to extend context variables for a supplied {@link IJsonContext | IJsonContext}.\n   * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`\n   * to start from an empty context.\n   * @param vars - Optional {@link VariableValue | variable values} to be added to the\n   * {@link IJsonContext | context}.\n   * @returns `Success` with a new {@link TemplateVars | TemplateVars} containing the variables\n   * from the base context, merged with and overridden by any that were passed in, or `Failure`\n   * with a message if an error occurs.\n   */\n  public static extendContextVars(\n    baseContext: IJsonContext | undefined,\n    vars?: VariableValue[]\n  ): Result<TemplateVars | undefined> {\n    if (vars && vars.length > 0) {\n      const extend = baseContext?.extendVars ?? defaultExtendVars;\n      return extend(baseContext?.vars ?? {}, vars);\n    }\n    return succeed(baseContext?.vars);\n  }\n\n  /**\n   * Static helper to extend context references for a supplied {@link IJsonContext | IJsonContext}.\n   * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`\n   * to start from an empty context.\n   * @param refs - Optional {@link IJsonReferenceMap | reference maps} to be added to the\n   * {@link IJsonContext | context}.\n   * @returns `Success` with a new {@link IJsonReferenceMap | reference map} which projects\n   * the references from the base context, merged with and overridden by any that were passed in,\n   * or `Failure` with a message if an error occurs.\n   */\n  public static extendContextRefs(\n    baseContext: IJsonContext | undefined,\n    refs?: IJsonReferenceMap[]\n  ): Result<IJsonReferenceMap | undefined> {\n    if (refs && refs.length > 0) {\n      const full = baseContext?.refs ? [...refs, baseContext.refs] : refs;\n      if (full.length > 1) {\n        return CompositeJsonMap.create(full);\n      }\n      return succeed(full[0]);\n    }\n    return succeed(baseContext?.refs);\n  }\n\n  /**\n   * Static helper to extend context variables and references for a supplied {@link IJsonContext | IJsonContext}.\n   * @param baseContext - The {@link IJsonContext | IJsonContext} to be extended, or `undefined`\n   * to start from an empty context.\n   * @param add - Optional initializer containing {@link VariableValue | variable values} and/or\n   * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.\n   * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and\n   * references from the base context, merged with and overridden by any that were passed in, or\n   * `Failure` with a message if an error occurs.\n   */\n  public static extendContext(\n    baseContext?: IJsonContext | undefined,\n    add?: { vars?: VariableValue[]; refs?: IJsonReferenceMap[] }\n  ): Result<IJsonContext | undefined> {\n    return JsonContextHelper.extendContextVars(baseContext, add?.vars || []).onSuccess((vars) => {\n      return JsonContextHelper.extendContextRefs(baseContext, add?.refs || []).onSuccess((refs) => {\n        if (!vars && !refs && !baseContext?.extendVars) {\n          return succeed(undefined);\n        }\n        const rtrn: IJsonContext = { vars, refs };\n        if (baseContext?.extendVars) {\n          rtrn.extendVars = baseContext.extendVars;\n        }\n        return succeed(rtrn);\n      });\n    });\n  }\n\n  /**\n   * Static helper to merge context variables and references for a supplied {@link IJsonContext | IJsonContext}.\n   * @param baseContext - The {@link IJsonContext | IJsonContext} into which variables and references\n   * are to be merged, or `undefined` to start from an empty context.\n   * @param add - Optional initializer containing {@link VariableValue | variable values} and/or\n   * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.\n   * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and\n   * references from the base context, merged with and overridden by any that were passed in, or\n   * `Failure` with a message if an error occurs.\n   */\n  public static mergeContext(\n    baseContext: IJsonContext | undefined,\n    add: IJsonContext | undefined\n  ): Result<IJsonContext | undefined> {\n    if (baseContext) {\n      if (add) {\n        const rtrn: IJsonContext = {\n          vars: add.vars ?? baseContext.vars,\n          refs: add.refs ?? baseContext.refs\n        };\n        if (add.hasOwnProperty('extendVars')) {\n          rtrn.extendVars = add.extendVars;\n        } else if (baseContext.hasOwnProperty('extendVars')) {\n          rtrn.extendVars = baseContext.extendVars;\n        }\n        return succeed(rtrn);\n      }\n      return succeed(baseContext);\n    }\n    return succeed(add);\n  }\n\n  /**\n   * Applies {@link JsonContextHelper.extendContextVars | extendContextVars} to the\n   * {@link IJsonContext | IJsonContext} associated with this helper.\n   * @param vars - Optional {@link VariableValue | variable values} to be added to the\n   * @returns `Success` with a new {@link TemplateVars | TemplateVars} containing the variables\n   * from the base context, merged with and overridden by any that were passed in, or `Failure`\n   * with a message if an error occurs.\n   */\n  public extendVars(vars?: VariableValue[]): Result<TemplateVars | undefined> {\n    return JsonContextHelper.extendContextVars(this._context, vars);\n  }\n\n  /**\n   * Applies {@link JsonContextHelper.extendContextRefs | extendContextRefs} to the\n   * {@link IJsonContext | IJsonContext} associated with this helper.\n   * @param refs - Optional {@link IJsonReferenceMap | reference maps} to be added to the\n   * @returns `Success` with a new {@link IJsonReferenceMap | reference map} which projects\n   * the references from the base context, merged with and overridden by any that were passed in,\n   * or `Failure` with a message if an error occurs.\n   */\n  public extendRefs(refs?: IJsonReferenceMap[]): Result<IJsonReferenceMap | undefined> {\n    return JsonContextHelper.extendContextRefs(this._context, refs);\n  }\n\n  /**\n   * Applies {@link JsonContextHelper.(extendContext:static) | extendContext} to the\n   * {@link IJsonContext | IJsonContext} associated with this helper.\n   * @param add - Optional initializer containing {@link VariableValue | variable values} and/or\n   * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.\n   * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and\n   * references from the base context, merged with and overridden by any that were passed in, or\n   * `Failure` with a message if an error occurs.\n   */\n  public extendContext(add?: {\n    vars?: VariableValue[];\n    refs?: IJsonReferenceMap[];\n  }): Result<IJsonContext | undefined> {\n    return JsonContextHelper.extendContext(this._context, add);\n  }\n\n  /**\n   * Applies {@link JsonContextHelper.(mergeContext:static) | mergeContext} to the\n   * {@link IJsonContext | IJsonContext} associated with this helper.\n   * @param add - Optional initializer containing {@link VariableValue | variable values} and/or\n   * {@link IJsonReferenceMap | reference maps} to be added to the {@link IJsonContext | context}.\n   * @returns `Success` with a new {@link IJsonContext | IJsonContext} containing the variables and\n   * references from the base context, merged with and overridden by any that were passed in, or\n   * `Failure` with a message if an error occurs.\n   */\n  public mergeContext(merge?: IJsonContext): Result<IJsonContext | undefined> {\n    return JsonContextHelper.mergeContext(this._context, merge);\n  }\n}\n"]}

package/lib/packlets/context/index.d.ts

@@ -0,0 +1,4 @@
+export { CompositeJsonMap } from './compositeJsonMap';
+export { JsonContextHelper } from './contextHelpers';
+export { IJsonContext, IJsonReferenceMap, JsonReferenceMapFailureReason, TemplateVars, TemplateVarsExtendFunction, VariableValue, defaultExtendVars } from './jsonContext';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/context/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,6BAA6B,EAC7B,YAAY,EACZ,0BAA0B,EAC1B,aAAa,EACb,iBAAiB,EAClB,MAAM,eAAe,CAAC"}