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

package/dist/ts-json.d.ts

@@ -0,0 +1,1826 @@
+import { Conversion } from '@fgv/ts-utils';
+import { Converter } from '@fgv/ts-utils';
+import { DetailedFailure } from '@fgv/ts-utils';
+import { DetailedResult } from '@fgv/ts-utils';
+import { Result } from '@fgv/ts-utils';
+
+/**
+ * Identifies whether some `unknown` value is a {@link JsonPrimitive | primitive},
+ * {@link JsonObject | object} or {@link JsonArray | array}. Fails for any value
+ * that cannot be converted to JSON (e.g. a function) _but_ this is a shallow test -
+ * it does not test the properties of an object or elements in an array.
+ * @param from - The `unknown` value to be tested
+ * @public
+ */
+export declare function classifyJsonValue(from: unknown): Result<JsonValueType>;
+
+/**
+ * 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>;
+}
+
+/**
+ * Helper function which creates a new {@link JsonConverter | JsonConverter} which converts a
+ * supplied `unknown` to strongly-typed JSON, by first rendering any property
+ * names or string values using mustache with the supplied context, then applying
+ * multi-value property expansion and conditional flattening based on property names.
+ * @param options - {@link ConditionalJsonConverterOptions | Options and context} for
+ * the conversion.
+ * @public
+ */
+declare function conditionalJson(options?: Partial<ConditionalJsonConverterOptions>): JsonConverter;
+
+/**
+ * An \@fgv/ts-utils `Converter` from `unknown` to type-safe JSON with mustache
+ * template rendering, multi-value property name and conditional property
+ * name rules enabled regardless of initial context.
+ * @public
+ */
+export declare class ConditionalJsonConverter extends JsonEditorConverter {
+    /**
+     * Default {@link IJsonConverterOptions | JSON converter options}
+     * to enable conditional conversion.
+     */
+    static readonly conditionalOptions: Partial<IJsonConverterOptions>;
+    /**
+     * Constructs a new {@link ConditionalJsonConverter | ConditionalJsonConverter} with supplied or
+     * default options.
+     * @param options - Optional partial {@link ConditionalJsonConverterOptions | configuration or context}
+     * for the converter.
+     */
+    constructor(options?: Partial<ConditionalJsonConverterOptions>);
+    /**
+     * Constructs a new {@link ConditionalJsonConverter | ConditionalJsonConverter} with supplied or
+     * default options.
+     * @param options - Optional partial {@link ConditionalJsonConverterOptions | configuration or context}
+     * for the converter.
+     */
+    static create(options?: Partial<ConditionalJsonConverterOptions>): Result<JsonConverter>;
+}
+
+/**
+ * Options for a {@link ConditionalJsonConverter | ConditionalJsonConverter}.
+ * @public
+ */
+export declare type ConditionalJsonConverterOptions = Omit<TemplatedJsonConverterOptions, 'useConditionalNames'>;
+
+/**
+ * The {@link Editor.Rules.ConditionalJsonEditorRule | ConditionalJsonEditorRule} evaluates
+ * properties with conditional keys, omitting non-matching keys and merging keys that match,
+ * or default keys only if no other keys match.
+ *
+ * The default syntax for a conditional key is:
+ *    "?value1=value2" - matches if value1 and value2 are the same, is ignored otherwise.
+ *    "?value" - matches if value is a non-empty, non-whitespace string. Is ignored otherwise.
+ *    "?default" - matches only if no other conditional blocks in the same object were matched.
+ * @public
+ */
+declare class ConditionalJsonEditorRule extends JsonEditorRuleBase {
+    /**
+     * Stored fully-resolved {@link Editor.Rules.IConditionalJsonRuleOptions | options} for this
+     * rule.
+     * @public
+     */
+    protected _options?: IConditionalJsonRuleOptions;
+    /**
+     * Creates a new {@link Editor.Rules.ConditionalJsonEditorRule | ConditionalJsonEditorRule}.
+     * @param options - Optional {@link Editor.Rules.IConditionalJsonRuleOptions | configuration options}
+     * used for this rule.
+     */
+    constructor(options?: IConditionalJsonRuleOptions);
+    /**
+     * Creates a new {@link Editor.Rules.ConditionalJsonEditorRule | ConditionalJsonEditorRule}.
+     * @param options - Optional {@link Editor.Rules.IConditionalJsonRuleOptions | configuration options}
+     * used for this rule.
+     */
+    static create(options?: IConditionalJsonRuleOptions): Result<ConditionalJsonEditorRule>;
+    /**
+     * Evaluates a property for conditional application.
+     * @param key - The key of the property to be considered
+     * @param value - The {@link JsonValue | value} of the property to be considered.
+     * @param state - The {@link Editor.JsonEditorState | editor state} for the object being edited.
+     * @returns Returns `Success` with detail `'deferred'` and a
+     * {@link Editor.Rules.IConditionalJsonDeferredObject | IConditionalJsonDeferredObject}.
+     * for a matching, default or unconditional key. Returns `Failure` with detail `'ignore'` for
+     * a non-matching conditional, or with detail `'error'` if an error occurs. Otherwise
+     * fails with detail `'inapplicable'`.
+     */
+    editProperty(key: string, value: JsonValue, state: JsonEditorState): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;
+    /**
+     * Finalizes any deferred conditional properties. If the only deferred property is
+     * default, that property is emitted. Otherwise all matching properties are emitted.
+     * @param finalized - The deferred properties to be considered for merge.
+     * @param __state - The {@link Editor.JsonEditorState | editor state} for the object
+     * being edited.
+     */
+    finalizeProperties(finalized: JsonObject[], __state: JsonEditorState): DetailedResult<JsonObject[], JsonEditFailureReason>;
+    /**
+     * Determines if a given property key is conditional. Derived classes can override this
+     * method to use a different format for conditional properties.
+     * @param value - The {@link JsonValue | value} of the property to be considered.
+     * @param state - The {@link Editor.JsonEditorState | editor state} for the object being edited.
+     * @returns `Success` with detail `'deferred'` and a
+     * {@link Editor.Rules.IConditionalJsonKeyResult | IConditionalJsonKeyResult} describing the
+     * match for a default or matching conditional property.  Returns `Failure` with detail `'ignore'`
+     * for a non-matching conditional property. Fails with detail `'error'` if an error occurs
+     * or with detail `'inapplicable'` if the key does not represent a conditional property.
+     * @public
+     */
+    protected _tryParseCondition(key: string, state: JsonEditorState): DetailedResult<IConditionalJsonKeyResult, JsonPropertyEditFailureReason>;
+    /**
+     * Compares two strings using a supplied operator.
+     * @param left - The first string to be compared.
+     * @param right - The second string to be compared.
+     * @param operator - The operator to be applied.
+     * @returns `true` if the condition is met, `false` otherwise.
+     * @internal
+     */
+    protected _compare(left: string, right: string, operator: string): boolean;
+}
+
+/**
+ * Creates a new {@link IJsonContext | JSON context} using values supplied in an optional partial
+ * {@link IJsonConverterOptions | converter options}.
+ * @param partial - Optional partial {@link IJsonConverterOptions | IJsonConverterOptions} used to
+ * populate the context.
+ * @public
+ */
+export declare function contextFromConverterOptions(partial?: Partial<IJsonConverterOptions>): IJsonContext | undefined;
+
+/**
+ * Creates a new {@link Editor.JsonEditor | JsonEditor} from an optionally supplied partial
+ * {@link IJsonConverterOptions | JSON converter options}.
+ * Expands supplied options with default values and constructs an editor with
+ * matching configuration and defined rules.
+ * @param partial - Optional partial {@link IJsonConverterOptions | IJsonConverterOptions}
+ * used to create the editor.
+ * @public
+ */
+export declare function converterOptionsToEditor(partial?: Partial<IJsonConverterOptions>): Result<JsonEditor>;
+
+declare namespace Converters {
+    export {
+        templatedJson,
+        conditionalJson,
+        richJson,
+        json,
+        jsonObject,
+        jsonArray
+    }
+}
+export { Converters }
+
+/**
+ * Reads all JSON files from a directory and apply a supplied converter.
+ * @param srcPath - The path of the folder to be read.
+ * @param options - {@link Files.IDirectoryConvertOptions | Options} to control
+ * conversion and filtering
+ * @public
+ */
+declare function convertJsonDirectorySync<T>(srcPath: string, options: IDirectoryConvertOptions<T>): Result<IReadDirectoryItem<T>[]>;
+
+/**
+ * Reads and converts all JSON files from a directory, returning a
+ * `Map<string, T>` indexed by file base name (i.e. minus the extension)
+ * with an optional name transformation applied if present.
+ * @param srcPath - The path of the folder to be read.
+ * @param options - {@link Files.IDirectoryToMapConvertOptions | Options} to control conversion,
+ * filtering and naming.
+ * @public
+ */
+declare function convertJsonDirectoryToMapSync<T, TC = unknown>(srcPath: string, options: IDirectoryToMapConvertOptions<T, TC>): Result<Map<string, T>>;
+
+/**
+ * Convenience function to read a JSON file and apply a supplied converter.
+ * @param srcPath - Path of the file to read.
+ * @param converter - `Converter` used to convert the file contents
+ * @returns `Success` with a result of type `<T>`, or `Failure`
+ * with a message if an error occurs.
+ * @public
+ */
+declare function convertJsonFileSync<T>(srcPath: string, converter: Converter<T>): Result<T>;
+
+/**
+ * This default implementation of a {@link TemplateVarsExtendFunction | TemplateVarsExtendFunction}
+ * creates a new collection via inheritance from the supplied collection.
+ * @param base - The base {@link TemplateVars | variables} to be extended.
+ * @param values - The {@link VariableValue | values} to be added or overridden in the new variables.
+ * @public
+ */
+export declare function defaultExtendVars(base: TemplateVars | undefined, values: VariableValue[]): Result<TemplateVars | undefined>;
+
+declare namespace EditorRules {
+    export {
+        IConditionalJsonKeyResult,
+        IConditionalJsonDeferredObject,
+        IConditionalJsonRuleOptions,
+        ConditionalJsonEditorRule,
+        IMultiValuePropertyParts,
+        MultiValueJsonEditorRule,
+        ReferenceJsonEditorRule,
+        ITemplatedJsonRuleOptions,
+        TemplatedJsonEditorRule
+    }
+}
+export { EditorRules }
+
+declare namespace File_2 {
+    export {
+        readJsonFileSync,
+        convertJsonFileSync,
+        convertJsonDirectorySync,
+        convertJsonDirectoryToMapSync,
+        writeJsonFileSync,
+        IDirectoryConvertOptions,
+        IReadDirectoryItem,
+        ItemNameTransformFunction,
+        IDirectoryToMapConvertOptions
+    }
+}
+export { File_2 as File }
+
+/**
+ * On a successful match, the {@link Editor.Rules.ConditionalJsonEditorRule | ConditionalJsonEditorRule}
+ * stores a {@link Editor.Rules.IConditionalJsonDeferredObject | IConditionalJsonDeferredObject} describing the
+ * matching result, to be resolved at finalization time.
+ * @public
+ */
+declare interface IConditionalJsonDeferredObject extends IConditionalJsonKeyResult {
+    value: JsonValue;
+}
+
+/**
+ * Returned by {@link Editor.Rules.ConditionalJsonEditorRule._tryParseCondition | ConditionalJsonEditorRule._tryParseCondition}
+ * to indicate whether a successful match was due to a matching condition or a default value.
+ * @public
+ */
+declare interface IConditionalJsonKeyResult extends JsonObject {
+    matchType: 'default' | 'match' | 'unconditional';
+}
+
+/**
+ * Configuration options for the {@link Editor.Rules.ConditionalJsonEditorRule | ConditionalJsonEditorRule}.
+ * @public
+ */
+declare interface IConditionalJsonRuleOptions extends Partial<IJsonEditorOptions> {
+    /**
+     * If true (default) then properties with unconditional names
+     * (which start with !) are flattened.
+     */
+    flattenUnconditionalValues?: boolean;
+}
+
+/**
+ * Options for directory conversion.
+ * TODO: add filtering, allowed and excluded.
+ * @public
+ */
+declare interface IDirectoryConvertOptions<T, TC = unknown> {
+    /**
+     * The converter used to convert incoming JSON objects.
+     */
+    converter: Converter<T, TC>;
+}
+
+/**
+ * Options controlling conversion of a directory.
+ * @public
+ */
+declare interface IDirectoryToMapConvertOptions<T, TC = unknown> extends IDirectoryConvertOptions<T, TC> {
+    transformName?: ItemNameTransformFunction<T>;
+}
+
+/**
+ * A specialized JSON editor which does a deep clone of a supplied {@link JsonValue | JsonValue}.
+ * @public
+ */
+declare interface IJsonCloneEditor {
+    /**
+     * Returns a deep clone of a supplied {@link JsonValue | JsonValue}.
+     * @param src - The {@link JsonValue | JsonValue} to be cloned.
+     * @param context - An optional {@link IJsonContext | JSON context} used for clone
+     * conversion operations.
+     */
+    clone(src: JsonValue, context?: IJsonContext): DetailedResult<JsonValue, JsonEditFailureReason>;
+}
+
+/**
+ * Context used to convert or edit JSON objects.
+ * @public
+ */
+export declare interface IJsonContext {
+    vars?: TemplateVars;
+    refs?: IJsonReferenceMap;
+    extendVars?: TemplateVarsExtendFunction;
+}
+
+/**
+ * Conversion options for {@link JsonConverter | JsonConverter}.
+ * @public
+ */
+export declare interface IJsonConverterOptions {
+    /**
+     * If `true` and if template variables are available,
+     * then string property values will be rendered using
+     * mustache and those variable values. Otherwise string
+     * properties are copied without modification.
+     *
+     * Defaults to `true` if vars are supplied with options,
+     * `false` otherwise.
+     */
+    useValueTemplates: boolean;
+    /**
+     * If `true` and if template variables are available,
+     * then property names will be rendered using
+     * mustache and those variable values. Otherwise
+     * property names are copied without modification.
+     *
+     * Defaults to `true` if vars are supplied with options,
+     * `false` otherwise.
+     */
+    useNameTemplates: boolean;
+    /**
+     * If `true` and if template variables are available,
+     * then string property names will be considered for
+     * conditionals.
+     *
+     * Default is to match {@link IJsonConverterOptions.useNameTemplates | useNameTemplates}.
+     */
+    useConditionalNames: boolean;
+    /**
+     * If `true` (default) then properties with unconditional names
+     * (which start with !) are flattened.
+     */
+    flattenUnconditionalValues: boolean;
+    /**
+     * If `true` and if both template variables and a
+     * context derivation function is available, then properties
+     * which match the multi-value name pattern will be expanded.
+     * Default matches {@link IJsonConverterOptions.useNameTemplates | useNameTemplates}.
+     *
+     * Default is `true` unless {@link IJsonConverterOptions.extendVars | extendVars} is
+     * explicitly set to `undefined`.
+     */
+    useMultiValueTemplateNames: boolean;
+    /**
+     * The variables (mustache view) used to render templated string names
+     * and properties.  See the mustache documentation for details of mustache
+     * syntax and the template view.
+     */
+    vars?: TemplateVars;
+    /**
+     * Method used to extend variables for children of an array node during
+     * expansion. Default is to use a built-in extension function unless
+     * {@link IJsonConverterOptions.extendVars | extendVars} is explicitly set to undefined.
+     */
+    extendVars?: TemplateVarsExtendFunction;
+    /**
+     * If `true` and if a {@link IJsonReferenceMap | references map} is supplied
+     * in {@link IJsonConverterOptions.refs | refs}, then references in the source
+     * object will be replaced with the corresponding value from the reference map.
+     *
+     * Default is `true` if {@link IJsonConverterOptions.refs | refs} are present in options,
+     * `false` otherwise.
+     */
+    useReferences: boolean;
+    /**
+     * An optional {@link IJsonReferenceMap | reference map} used to insert any references
+     * in the converted JSON.
+     */
+    refs?: IJsonReferenceMap;
+    /**
+     * If {@link IJsonConverterOptions.onInvalidPropertyName | onInvalidPropertyName} is `'error'`
+     * (default) then any property name that is invalid after template rendering causes an error
+     * and stops conversion.  If {@link IJsonConverterOptions.onInvalidPropertyName | onInvalidPropertyName}
+     * is `'ignore'`, then names which are invalid after template rendering are passed through unchanged.
+     */
+    onInvalidPropertyName: 'error' | 'ignore';
+    /**
+     * If {@link IJsonConverterOptions.onInvalidPropertyValue | onInvalidPropertyValue} is `'error'`
+     * (default) then any illegal property value causes an error and stops conversion.  If
+     * {@link IJsonConverterOptions.onInvalidPropertyValue | onInvalidPropertyValue} is `'ignore'` then
+     * any invalid property values are silently ignored.
+     */
+    onInvalidPropertyValue: 'error' | 'ignore';
+    /**
+     * If {@link IJsonConverterOptions.onUndefinedPropertyValue | onUndefinedPropertyValue} is `'error'`,
+     * then any property with value `undefined` will cause an error and stop conversion.  If
+     * {@link IJsonConverterOptions.onUndefinedPropertyValue | onUndefinedPropertyValue} is `'ignore'` (default)
+     * then any property with value `undefined` is silently ignored.
+     */
+    onUndefinedPropertyValue: 'error' | 'ignore';
+}
+
+/**
+ * Initialization options for a {@link Editor.JsonEditor | JsonEditor}.
+ * @public
+ */
+export declare interface IJsonEditorOptions {
+    context?: IJsonContext;
+    validation: IJsonEditorValidationOptions;
+}
+
+/**
+ * An {@link Editor.IJsonEditorRule | IJsonEditorRule} represents a single configurable
+ * rule to be applied by a {@link Editor.JsonEditor | JsonEditor}.
+ * @public
+ */
+export declare 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>;
+}
+
+/**
+ * Validation options for a {@link Editor.JsonEditor | JsonEditor}.
+ * @public
+ */
+export declare interface IJsonEditorValidationOptions {
+    /**
+     * If `onInvalidPropertyName` is `'error'` (default) then any property name
+     * that is invalid after template rendering causes an error and stops
+     * conversion.  If `onInvalidPropertyName` is `'ignore'`, then names which
+     * are invalid after template rendering are passed through unchanged.
+     */
+    onInvalidPropertyName: 'error' | 'ignore';
+    /**
+     * If `onInvalidPropertyValue` is `'error'` (default) then any illegal
+     * property value other than `undefined` causes an error and stops
+     * conversion.  If `onInvalidPropertyValue` is `'ignore'` then any
+     * invalid property values are silently ignored.
+     */
+    onInvalidPropertyValue: 'error' | 'ignore';
+    /**
+     * If `onUndefinedPropertyValue` is `'error'`, then any property with
+     * value `undefined` will cause an error and stop conversion.  If
+     * `onUndefinedPropertyValue` is `'ignore'` (default) then any
+     * property with value `undefined` is silently ignored.
+     */
+    onUndefinedPropertyValue: 'error' | 'ignore';
+}
+
+/**
+ * Interface for a simple map that returns named {@link JsonValue | JsonValue} values with templating,
+ * conditional logic, and external reference lookups applied using an optionally supplied context.
+ * @public
+ */
+export declare interface IJsonReferenceMap {
+    /**
+     * 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 | JsonObject} specified by key.
+     * @param key - The key of the object to be retrieved.
+     * @param context - Optional {@link IJsonContext | IJsonContext} used to construct
+     * the object.
+     * @returns `Success` with the formatted {@link JsonObject | 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 | JsonValue} specified by key.
+     * @param key - The key of the object to be retrieved.
+     * @param context - Optional {@link IJsonContext | JSON Context} used to format the value
+     * @returns `Success` with the formatted {@link JsonValue | value} 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>;
+}
+
+/**
+ * Initialization options for a {@link PrefixedJsonMap | PrefixedJsonMap}
+ * @public
+ */
+declare interface IKeyPrefixOptions {
+    /**
+     * Indicates whether the prefix should be added automatically as needed (default true)
+     */
+    addPrefix?: boolean;
+    /**
+     * The prefix to be enforced
+     */
+    prefix: string;
+}
+
+/**
+ * Represents the parts of a multi-value property key.
+ * @public
+ */
+declare interface IMultiValuePropertyParts {
+    /**
+     * The original matched token.
+     */
+    readonly token: string;
+    /**
+     * The name of the variable used to project each possible
+     * property value into the child values or objects being
+     * resolved.
+     */
+    readonly propertyVariable: string;
+    /**
+     * The set of property values to be expanded.
+     */
+    readonly propertyValues: string[];
+    /**
+     * If `true`, the resolved values are added as an array
+     * with the name of the {@link Editor.Rules.IMultiValuePropertyParts.propertyVariable | propertyVariable}.
+     * If false, values are added as individual properties with names that correspond the value.
+     */
+    readonly asArray: boolean;
+}
+
+/**
+ * Return value for one item in a directory conversion.
+ * @public
+ */
+declare interface IReadDirectoryItem<T> {
+    /**
+     * Relative name of the file that was processed
+     */
+    filename: string;
+    /**
+     * The payload of the file.
+     */
+    item: T;
+}
+
+/**
+ * Options for creating a {@link ReferenceMapKeyPolicy | ReferenceMapKeyPolicy} object.
+ * @public
+ */
+export declare interface IReferenceMapKeyPolicyValidateOptions {
+    /**
+     * If `true`, the validator coerces keys to some valid value.
+     * If `false`, invalid keys cause an error.
+     */
+    makeValid?: boolean;
+}
+
+/**
+ * Initialization options for a {@link SimpleJsonMap | SimpleJsonMap}.
+ * @public
+ */
+declare interface ISimpleJsonMapOptions {
+    keyPolicy?: ReferenceMapKeyPolicy<JsonValue>;
+    editor?: JsonEditor;
+}
+
+/**
+ * Test if an `unknown` is potentially a {@link JsonArray | JsonArray}.
+ * @param from - The `unknown` to be tested.
+ * @returns `true` if the supplied parameter is an array object,
+ * `false` otherwise.
+ * @public
+ */
+export declare function isJsonArray(from: unknown): from is JsonArray;
+
+/**
+ * Test if an `unknown` is potentially a {@link JsonObject | JsonObject}.
+ * @param from - The `unknown` to be tested.
+ * @returns `true` if the supplied parameter is a non-array, non-special object,
+ * `false` otherwise.
+ * @public
+ */
+export declare function isJsonObject(from: unknown): from is JsonObject;
+
+/**
+ * Test if an `unknown` is a {@link JsonValue | JsonValue}.
+ * @param from - The `unknown` to be tested
+ * @returns `true` if the supplied parameter is a valid {@link JsonPrimitive | JsonPrimitive},
+ * `false` otherwise.
+ * @public
+ */
+export declare function isJsonPrimitive(from: unknown): from is JsonPrimitive;
+
+/**
+ * Function to transform the name of a some entity, given an original name
+ * and the contents of the entity.
+ * @public
+ */
+declare type ItemNameTransformFunction<T> = (name: string, item: T) => Result<string>;
+
+/**
+ * Configuration options for the {@link Editor.Rules.TemplatedJsonEditorRule | Templated JSON editor rule}.
+ * @public
+ */
+declare interface ITemplatedJsonRuleOptions extends Partial<IJsonEditorOptions> {
+    /**
+     * If `true` (default) then templates in property names are rendered
+     */
+    useNameTemplates?: boolean;
+    /**
+     * If `true` (default) then templates in property values are rendered
+     */
+    useValueTemplates?: boolean;
+}
+
+/**
+ * A simple validating {@link JsonConverter | JSON converter}. Converts unknown to
+ * JSON or fails if the unknown contains any invalid JSON values.
+ * @public
+ */
+declare const json: JsonConverter;
+
+/**
+ * A {@link JsonArray | JsonArray} is an array containing only valid {@link JsonValue | JsonValues}.
+ * @public
+ */
+export declare interface JsonArray extends Array<JsonValue> {
+}
+
+/**
+ * A simple validating {@link JsonConverter | JSON converter}. Converts `unknown` to a
+ * {@link JsonArray | JsonArray}, or fails if the unknown contains invalid JSON or is
+ * not an array.
+ * @public
+ */
+declare const jsonArray: Converter<JsonArray, IJsonContext>;
+
+/**
+ * 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>;
+}
+
+/**
+ * An \@fgv/ts-utils `Converter` from `unknown` to type-safe JSON, optionally
+ * rendering any string property names or values using mustache with a supplied view.
+ * @public
+ */
+export declare class JsonConverter extends JsonEditorConverter {
+    /**
+     * Constructs a new {@link JsonConverter | JsonConverter} with
+     * supplied or default options.
+     * @param options - Optional partial {@link IJsonConverterOptions | options}
+     * to configure the converter.
+     */
+    constructor(options?: Partial<IJsonConverterOptions>);
+    /**
+     * Creates a new {@link JsonConverter | JsonConverter}.
+     * @param options - Optional partial {@link IJsonConverterOptions | options}
+     * to configure the converter.
+     * @returns `Success` with a new {@link JsonConverter | JsonConverter}, or `Failure`
+     * with an informative message if an error occurs.
+     */
+    static create(options?: Partial<IJsonConverterOptions>): Result<JsonConverter>;
+}
+
+/**
+ * Possible `DetailedResult` details for various editor operations.
+ * @public
+ */
+export declare type JsonEditFailureReason = 'ignore' | 'inapplicable' | 'edited' | 'error';
+
+/**
+ * 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
+ */
+export declare class JsonEditor implements IJsonCloneEditor {
+    /**
+     * Default singleton {@link Editor.JsonEditor | JsonEditor}.
+     * @internal
+     */
+    protected static _default?: JsonEditor;
+    /**
+     * Full set of {@link Editor.IJsonEditorOptions | editor options} in effect for this editor.
+     */
+    options: IJsonEditorOptions;
+    /**
+     * The set of {@link Editor.IJsonEditorRule | editor rules} applied by this editor.
+     * @internal
+     */
+    protected _rules: IJsonEditorRule[];
+    /**
+     * 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
+     */
+    protected constructor(options?: Partial<IJsonEditorOptions>, rules?: IJsonEditorRule[]);
+    /**
+     * Default singleton {@link Editor.JsonEditor | JsonEditor} for simple use. Applies all rules
+     * but with no default context.
+     */
+    static get default(): JsonEditor;
+    /**
+     * 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?: Partial<IJsonEditorOptions>, rules?: IJsonEditorRule[]): Result<JsonEditor>;
+    /**
+     * 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?: IJsonEditorOptions): Result<IJsonEditorRule[]>;
+    /**
+     * @internal
+     */
+    protected static _getDefaultOptions(options?: Partial<IJsonEditorOptions>): Result<IJsonEditorOptions>;
+    /**
+     * 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: JsonObject, src: JsonObject, runtimeContext?: IJsonContext): Result<JsonObject>;
+    /**
+     * 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: JsonObject, srcObjects: JsonObject[]): Result<JsonObject>;
+    /**
+     * 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: IJsonContext | undefined, base: JsonObject, srcObjects: JsonObject[]): Result<JsonObject>;
+    /**
+     * 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: JsonValue, context?: IJsonContext): DetailedResult<JsonValue, JsonEditFailureReason>;
+    /**
+     *
+     * @param target -
+     * @param src -
+     * @param state -
+     * @returns
+     * @internal
+     */
+    protected _mergeObjectInPlace(target: JsonObject, src: JsonObject, state: JsonEditorState): Result<JsonObject>;
+    /**
+     *
+     * @param src -
+     * @param context -
+     * @returns
+     * @internal
+     */
+    protected _cloneArray(src: JsonArray, context?: IJsonContext): DetailedResult<JsonArray, JsonEditFailureReason>;
+    /**
+     *
+     * @param target -
+     * @param key -
+     * @param newValue -
+     * @param state -
+     * @returns
+     * @internal
+     */
+    protected _mergeClonedProperty(target: JsonObject, key: string, newValue: JsonValue, state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
+    /**
+     *
+     * @param key -
+     * @param value -
+     * @param state -
+     * @returns
+     * @internal
+     */
+    protected _editProperty(key: string, value: JsonValue, state: JsonEditorState): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;
+    /**
+     *
+     * @param value -
+     * @param state -
+     * @returns
+     * @internal
+     */
+    protected _editValue(value: JsonValue, state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
+    /**
+     *
+     * @param target -
+     * @param state -
+     * @returns
+     * @internal
+     */
+    protected _finalizeAndMerge(target: JsonObject, state: JsonEditorState): DetailedResult<JsonObject, JsonEditFailureReason>;
+}
+
+/**
+ * A thin wrapper to allow an arbitrary {@link Editor.JsonEditor | JsonEditor} to be used via the
+ * \@fgv/ts-utils `Converter` pattern.
+ * @public
+ */
+export declare class JsonEditorConverter extends Conversion.BaseConverter<JsonValue, IJsonContext> {
+    readonly editor: JsonEditor;
+    /**
+     * Constructs a new {@link Editor.JsonEditor | JsonEditor}Converter which uses the supplied editor
+     * @param editor -
+     */
+    constructor(editor: JsonEditor);
+    /**
+     * Constructs a new {@link Editor.JsonEditor | JsonEditor}Converter which uses the supplied editor
+     * @param editor -
+     */
+    static createWithEditor(editor: JsonEditor): Result<JsonEditorConverter>;
+    /**
+     * Gets a derived converter which fails if the resulting converted
+     * {@link JsonValue | JsonValue} is not a {@link JsonObject | JsonObject}.
+     */
+    object(): Converter<JsonObject, IJsonContext>;
+    /**
+     * Gets a derived converter which fails if the resulting converted
+     * {@link JsonValue | JsonValue} is not a {@link JsonArray | JsonArray}.
+     */
+    array(): Converter<JsonArray, IJsonContext>;
+    protected _convert(from: unknown, context?: IJsonContext): Result<JsonValue>;
+}
+
+/**
+ * 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
+ */
+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>;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * Possible validation rules for a {@link Editor.JsonEditor | JsonEditor}.
+ * @public
+ */
+declare type JsonEditorValidationRules = 'invalidPropertyName' | 'invalidPropertyValue' | 'undefinedPropertyValue';
+
+/**
+ * A {@link JsonObject | JsonObject} is a string-keyed object
+ * containing only valid {@link JsonValue | JSON values}.
+ * @public
+ */
+export declare interface JsonObject {
+    [key: string]: JsonValue;
+}
+
+/**
+ * A simple validating {@link JsonConverter | JSON converter}. Converts unknown
+ * to a {@link JsonObject | JsonObject}, or fails if the `unknown` contains invalid
+ * JSON or is not an object.
+ * @public
+ */
+declare const jsonObject: Converter<JsonObject, IJsonContext>;
+
+/**
+ * Primitive (terminal) values allowed in by JSON.
+ * @public
+ */
+export declare type JsonPrimitive = boolean | number | string | null;
+
+/**
+ * Possible `DetailedResult` details for property edit operations.
+ * @public
+ */
+export declare type JsonPropertyEditFailureReason = JsonEditFailureReason | 'deferred';
+
+/**
+ * Failure reason for {@link IJsonReferenceMap | IJsonReferenceMap} lookup, where `'unknown'`
+ * means that the object is not present in the map and `'error'` means
+ * that an error occurred while retrieving or converting it.
+ * @public
+ */
+export declare type JsonReferenceMapFailureReason = 'unknown' | 'error';
+
+/**
+ * A {@link JsonValue | JsonValue} is one of: a {@link JsonPrimitive | JsonPrimitive},
+ * a {@link JsonObject | JsonObject} or an {@link JsonArray | JsonArray}.
+ * @public
+ */
+export declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+
+/**
+ * Classes of {@link JsonValue | JsonValue}.
+ * @public
+ */
+export declare type JsonValueType = 'primitive' | 'object' | 'array';
+
+/**
+ * Type representing either a `Map\<string, T\>` or a `Record\<string, T\>`.
+ * @public
+ */
+declare type MapOrRecord<T> = Map<string, T> | Record<string, T>;
+
+/**
+ * Merges an optionally supplied partial set of {@link IJsonConverterOptions | options} with
+ * the default converter options and taking all dynamic rules into account (e.g. template usage enabled
+ * if variables are supplied and disabled if not),  producing a fully-resolved set of
+ * {@link IJsonConverterOptions | IJsonConverterOptions}.
+ * @param partial - An optional partial {@link IJsonConverterOptions | IJsonConverterOptions}
+ * to be merged.
+ * @public
+ */
+export declare function mergeDefaultJsonConverterOptions(partial?: Partial<IJsonConverterOptions>): IJsonConverterOptions;
+
+/**
+ * The {@link Editor.Rules.MultiValueJsonEditorRule | Multi-Value JSON editor rule}
+ * expands matching keys multiple times, projecting the value into the template
+ * context for any child objects rendered by the rule.
+ *
+ * The default syntax for a multi-value key is:
+ *  "[[var]]=value1,value2,value3"
+ * Where "var" is the name of the variable that will be passed to
+ * child template resolution, and "value1,value2,value3" is a
+ * comma-separated list of values to be expanded.
+ * @public
+ */
+declare class MultiValueJsonEditorRule extends JsonEditorRuleBase {
+    /**
+     * Stored fully-resolved {@link Editor.IJsonEditorOptions | editor options}
+     * for this rule.
+     * @public
+     */
+    protected _options?: IJsonEditorOptions;
+    /**
+     * Creates a new {@link Editor.Rules.MultiValueJsonEditorRule | MultiValueJsonEditorRule}.
+     * @param options - Optional {@link Editor.IJsonEditorOptions | configuration options}.
+     */
+    constructor(options?: IJsonEditorOptions);
+    /**
+     * Creates a new {@link Editor.Rules.MultiValueJsonEditorRule | MultiValueJsonEditorRule}.
+     * @param options - Optional {@link Editor.IJsonEditorOptions | configuration options}.
+     */
+    static create(options?: IJsonEditorOptions): Result<MultiValueJsonEditorRule>;
+    /**
+     * Evaluates a property for multi-value expansion.
+     * @param key - The key of the property to be considered
+     * @param value - The {@link JsonValue | value} of the property to be considered.
+     * @param state - The {@link Editor.JsonEditorState | editor state} for the object being edited.
+     * @returns `Success` with an object containing the fully-resolved child values to be merged for
+     * matching multi-value property. Returns `Failure` with detail `'error'` if an error occurs or
+     * with detail `'inapplicable'` if the property key is not a conditional property.
+     */
+    editProperty(key: string, value: JsonValue, state: JsonEditorState): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;
+    /**
+     * Extends the {@link IJsonContext | current context} with a supplied state and values.
+     * @param state - The {@link Editor.JsonEditorState | editor state} for the object being edited.
+     * @param values - An array of {@link VariableValue | VariableValue} to be added to the
+     * context.
+     * @returns The extended {@link IJsonContext | context}.
+     * @public
+     */
+    protected _deriveContext(state: JsonEditorState, ...values: VariableValue[]): Result<IJsonContext | undefined>;
+    /**
+     * Determines if a given property key is multi-value. Derived classes can override this
+     * method to use a different format for multi-value properties.
+     * @param value - The {@link JsonValue | value} of the property to be considered.
+     * @param state - The {@link Editor.JsonEditorState | editor state} for the object being edited.
+     * @returns `Success` with detail `'deferred'` and an
+     * {@link Editor.Rules.IMultiValuePropertyParts | IMultiValuePropertyParts}
+     * describing the match for matching multi-value property.  Returns `Failure` with detail `'error'` if an error occurs
+     * or with detail `'inapplicable'` if the key does not represent a multi-value property.
+     * @public
+     */
+    protected _tryParse(token: string, state: JsonEditorState): DetailedResult<IMultiValuePropertyParts, JsonEditFailureReason>;
+}
+
+/**
+ * Picks a nested {@link JsonObject | JsonObject} from a supplied
+ * {@link JsonObject | JsonObject}.
+ * @param src - The {@link JsonObject | object} from which the field is
+ * to be picked.
+ * @param path - Dot-separated path of the member to be picked.
+ * @returns `Success` with the property if the path is valid and the value
+ * is an object. Returns `Failure` with details if an error occurs.
+ * @public
+ */
+export declare function pickJsonObject(src: JsonObject, path: string): Result<JsonObject>;
+
+/**
+ * Picks a nested field from a supplied {@link JsonObject | JsonObject}.
+ * @param src - The {@link JsonObject | object} from which the field is to be picked.
+ * @param path - Dot-separated path of the member to be picked.
+ * @returns `Success` with the property if the path is valid, `Failure`
+ * with an error message otherwise.
+ * @public
+ */
+export declare function pickJsonValue(src: JsonObject, path: string): Result<JsonValue>;
+
+/**
+ * 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>;
+}
+
+/**
+ * Convenience function to read type-safe JSON from a file
+ * @param srcPath - Path of the file to read
+ * @returns `Success` with a {@link JsonValue | JsonValue} or `Failure`
+ * with a message if an error occurs.
+ * @public
+ */
+declare function readJsonFileSync(srcPath: string): Result<JsonValue>;
+
+/**
+ * The {@link Editor.Rules.ReferenceJsonEditorRule | Reference JSON editor rule} replaces property
+ * keys or values that match some known object with a copy of that referenced object, formatted
+ * according to the current context.
+ *
+ * A property key is matched if it matches any known referenced value.
+ * - If the value of the matched key is `'default'`, then the entire object is formatted
+ *   with the current context, flattened and merged into the current object.
+ * - If the value of the matched key is some other string, then the entire
+ *   object is formatted with the current context, and the child of the resulting
+ *   object at the specified path is flattened and merged into the current object.
+ * - If the value of the matched key is an object, then the entire object is
+ *   formatted with the current context extended to include any properties of
+ *   that object, flattened, and merged into the current object.
+ * - It is an error if the referenced value is not an object.
+ *
+ * Any property, array or literal value is matched if it matches any known
+ * value reference. The referenced value is replaced by the referenced
+ * value, formatted using the current editor context.
+ * @public
+ */
+declare class ReferenceJsonEditorRule extends JsonEditorRuleBase {
+    /**
+     * Stored fully-resolved {@link Editor.IJsonEditorOptions | editor options} for this rule.
+     * @public
+     */
+    protected _options?: IJsonEditorOptions;
+    /**
+     * Creates a new {@link Editor.Rules.ReferenceJsonEditorRule | ReferenceJsonEditorRule}.
+     * @param options - Optional {@link Editor.IJsonEditorOptions | configuration options} for this rule.
+     */
+    constructor(options?: IJsonEditorOptions);
+    /**
+     * Creates a new {@link Editor.Rules.ReferenceJsonEditorRule | ReferenceJsonEditorRule}.
+     * @param options - Optional {@link Editor.IJsonEditorOptions | configuration options} for this rule.
+     */
+    static create(options?: IJsonEditorOptions): Result<ReferenceJsonEditorRule>;
+    /**
+     * Evaluates a property for reference expansion.
+     * @param key - The key of the property to be considered.
+     * @param value - The {@link JsonValue | value} of the property to be considered.
+     * @param state - The {@link Editor.JsonEditorState | editor state} for the object being edited.
+     * @returns If the reference is successful, returns `Success` with a {@link JsonObject | JsonObject}
+     * to be flattened and merged into the current object. Returns `Failure` with detail `'inapplicable'`
+     * for non-reference keys or with detail `'error'` if an error occurs.
+     */
+    editProperty(key: string, value: JsonValue, state: JsonEditorState): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;
+    /**
+     * Evaluates a property, array or literal value for reference replacement.
+     * @param value - The {@link JsonValue | value} of the property to be considered.
+     * @param state - The {@link Editor.JsonEditorState | editor state} for the object being edited.
+     */
+    editValue(value: JsonValue, state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
+    /**
+     * Gets the template variables to use given the value of some property whose name matched a
+     * resource plus the base template context.
+     * @param state - The {@link Editor.JsonEditorState | editor state} to be extended.
+     * @param supplied - The string or object supplied in the source json.
+     * @internal
+     */
+    protected _extendContext(state: JsonEditorState, supplied: JsonValue): Result<IJsonContext | undefined>;
+}
+
+/**
+ * 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>>;
+}
+
+/**
+ * Helper function which creates a new {@link JsonConverter | JsonConverter} which converts a
+ * supplied `unknown` to strongly-typed JSON, by first rendering any property
+ * names or string values using mustache with the supplied context, then applying
+ * multi-value property expansion and conditional flattening based on property names.
+ * @param options - {@link RichJsonConverterOptions | Options and context} for
+ * the conversion.
+ * @public
+ */
+declare function richJson(options?: Partial<RichJsonConverterOptions>): JsonConverter;
+
+/**
+ * A \@fgv/ts-utils `Converter` from `unknown` to type-safe JSON with mustache
+ * template rendering, multi-value property name, conditional property
+ * name, and external reference rules enabled regardless of initial context.
+ * @public
+ */
+export declare class RichJsonConverter extends JsonEditorConverter {
+    /**
+     * Default {@link IJsonConverterOptions | JSON converter options}
+     * to enable rich conversion.
+     */
+    static readonly richOptions: Partial<IJsonConverterOptions>;
+    /**
+     * Constructs a new {@link RichJsonConverter | RichJsonConverter} with supplied or
+     * default options.
+     * @param options - Optional partial {@link RichJsonConverterOptions | configuration or context}
+     * for the converter.
+     */
+    constructor(options?: Partial<RichJsonConverterOptions>);
+    /**
+     * Constructs a new {@link RichJsonConverter | RichJsonConverter} with supplied or
+     * default options
+     * @param options - Optional partial {@link RichJsonConverterOptions | configuration or context}
+     * for the converter.
+     */
+    static create(options?: Partial<RichJsonConverterOptions>): Result<JsonConverter>;
+}
+
+/**
+ * Initialization options for a {@link RichJsonConverter | RichJsonConverter}.
+ * @public
+ */
+export declare type RichJsonConverterOptions = Omit<ConditionalJsonConverterOptions, 'useReferences'>;
+
+/**
+ * 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>;
+}
+
+/**
+ * Abstract base class with common functionality for simple
+ * {@link IJsonReferenceMap | reference map} implementations.
+ * {@link JsonValue | json values}.
+ * @public
+ */
+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>;
+    }
+
+    /**
+     * Helper function which creates a new {@link JsonConverter | JsonConverter} which converts an
+     * `unknown` value to JSON, rendering any property names or string values using mustache with
+     * the supplied context.  See the mustache documentation for details of mustache syntax and view.
+     * @param options - {@link TemplatedJsonConverterOptions | Options and context} for
+     * the conversion.
+     * @public
+     */
+    declare function templatedJson(options?: Partial<TemplatedJsonConverterOptions>): JsonConverter;
+
+    /**
+     * An \@fgv/ts-utils `Converter` from `unknown` to type-safe JSON
+     * with mustache template rendering and multi-value property name rules enabled
+     * regardless of initial context.
+     * @public
+     */
+    export declare class TemplatedJsonConverter extends JsonEditorConverter {
+        /**
+         * Default {@link IJsonConverterOptions | JSON converter options}
+         * to enable templated conversion.
+         */
+        static readonly templateOptions: Partial<IJsonConverterOptions>;
+        /**
+         * Constructs a new {@link TemplatedJsonConverter | TemplatedJsonConverter} with
+         * supplied or default options.
+         * @param options - Optional partial {@link TemplatedJsonConverterOptions | options}
+         * to configure the converter.
+         */
+        constructor(options?: Partial<TemplatedJsonConverterOptions>);
+        /**
+         * Constructs a new {@link TemplatedJsonConverter | TemplatedJsonConverter} with
+         * supplied or default options.
+         * @param options - Optional partial {@link TemplatedJsonConverterOptions | options}
+         * to configure the converter.
+         */
+        static create(options?: Partial<TemplatedJsonConverterOptions>): Result<JsonConverter>;
+    }
+
+    /**
+     * Initialization options for a {@link TemplatedJsonConverter | TemplatedJsonConverter}.
+     * @public
+     */
+    export declare type TemplatedJsonConverterOptions = Omit<IJsonConverterOptions, 'useNameTemplates' | 'useValueTemplates' | 'useMultiValueTemplateNames'>;
+
+    /**
+     * The {@link Editor.Rules.TemplatedJsonEditorRule | Templated JSON editor rule} applies mustache rendering as
+     * appropriate to any keys or values in the object being edited.
+     * @public
+     */
+    declare class TemplatedJsonEditorRule extends JsonEditorRuleBase {
+        /**
+         * Fully-resolved {@link Editor.Rules.ITemplatedJsonRuleOptions | configuration options} for this rule.
+         * @public
+         */
+        protected _options?: ITemplatedJsonRuleOptions;
+        /**
+         * Creates a new {@link Editor.Rules.TemplatedJsonEditorRule | TemplatedJsonEditorRule}.
+         * @param options - Optional {@link Editor.Rules.ITemplatedJsonRuleOptions | configuration options}
+         * for this rule.
+         */
+        constructor(options?: ITemplatedJsonRuleOptions);
+        /**
+         * Creates a new {@link Editor.Rules.TemplatedJsonEditorRule | TemplatedJsonEditorRule}.
+         * @param options - Optional {@link Editor.Rules.ITemplatedJsonRuleOptions | configuration options}
+         * for this rule.
+         */
+        static create(options?: ITemplatedJsonRuleOptions): Result<TemplatedJsonEditorRule>;
+        /**
+         * Evaluates a property name for template rendering.
+         * @param key - The key of the property to be considered.
+         * @param value - The {@link JsonValue | value} of the property to be considered.
+         * @param state - The {@link Editor.JsonEditorState | editor state} for the object being edited.
+         * @returns `Success` with detail `'edited'` and an {@link JsonObject | object} to
+         * be flattened and merged if the key contained a template. Returns `Failure` with detail `'error'`
+         * if an error occurred or with detail `'inapplicable'` if the property key does not contain
+         * a template or if name rendering is disabled.
+         */
+        editProperty(key: string, value: JsonValue, state: JsonEditorState): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;
+        /**
+         * Evaluates a property, array or literal value for template rendering.
+         * @param value - The {@link JsonValue | value} to be edited.
+         * @param state - The {@link Editor.JsonEditorState | editor state} for the object being edited.
+         * @returns `Success` with detail `'edited'` if the value contained a template and was edited.
+         * Returns `Failure` with `'ignore'` if the rendered value should be ignored, with `'error'` if
+         * an error occurs, or with `'inapplicable'` if the value was not a string with a template.
+         */
+        editValue(value: JsonValue, state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
+        /**
+         * Renders a single template string for a supplied {@link Editor.JsonEditorState | editor state}.
+         * @param template - The mustache template to be rendered.
+         * @param state - The {@link Editor.JsonEditorState | editor state} used to render the template.
+         * @returns `Success` if the template is rendered.  Returns `Failure` with detail `'error'` if the
+         * template could not be rendered (e.g. due to syntax errors) or with detail `'inapplicable'` if the
+         * string is not a template.
+         * @internal
+         */
+        protected _render(template: string, state: JsonEditorState): DetailedResult<string, JsonEditFailureReason>;
+    }
+
+    /**
+     * Collection of variables used for template replacement in a JSON edit or
+     * conversion.
+     * @public
+     */
+    export declare type TemplateVars = Record<string, unknown>;
+
+    /**
+     * Function used to create a new collection of {@link TemplateVars | TemplateVars} with
+     * one or more new or changed values.
+     * @public
+     */
+    export declare type TemplateVarsExtendFunction = (base: TemplateVars | undefined, values: VariableValue[]) => Result<TemplateVars | undefined>;
+
+    /**
+     * Describes one value in a {@link TemplateVars | TemplateVars} collection of
+     * variables.
+     * @public
+     */
+    export declare type VariableValue = [string, unknown];
+
+    /**
+     * Convenience function to write type-safe JSON to a file.
+     * @param srcPath - Path of the file to write.
+     * @param value - The {@link JsonValue | JsonValue} to be written.
+     * @public
+     */
+    declare function writeJsonFileSync(srcPath: string, value: JsonValue): Result<boolean>;
+
+    export { }