@fgv/ts-json 5.0.0-24 → 5.0.0-25

package/dist/ts-json.d.ts

@@ -0,0 +1,2341 @@
+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 { JsonArray } from '@fgv/ts-json-base';
+import { JsonObject } from '@fgv/ts-json-base';
+import { JsonValue } from '@fgv/ts-json-base';
+import { Result } from '@fgv/ts-utils';
+
+/**
+ * Array merge behavior options for a {@link JsonEditor | JsonEditor}.
+ * @public
+ */
+export declare type ArrayMergeBehavior = 'append' | 'replace';
+
+/**
+ * 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 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 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 EditorRules.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 EditorRules.IConditionalJsonRuleOptions | options} for this
+     * rule.
+     * @public
+     */
+    protected _options?: IConditionalJsonRuleOptions;
+    /**
+     * Creates a new {@link EditorRules.ConditionalJsonEditorRule | ConditionalJsonEditorRule}.
+     * @param options - Optional {@link EditorRules.IConditionalJsonRuleOptions | configuration options}
+     * used for this rule.
+     */
+    constructor(options?: IConditionalJsonRuleOptions);
+    /**
+     * Creates a new {@link EditorRules.ConditionalJsonEditorRule | ConditionalJsonEditorRule}.
+     * @param options - Optional {@link EditorRules.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 `JsonValue` of the property to be considered.
+     * @param state - The {@link JsonEditorState | editor state} for the object being edited.
+     * @returns Returns `Success` with detail `'deferred'` and a
+     * {@link EditorRules.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 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 `JsonValue` of the property to be considered.
+     * @param state - The {@link JsonEditorState | editor state} for the object being edited.
+     * @returns `Success` with detail `'deferred'` and a
+     * {@link EditorRules.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 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 }
+
+/**
+ * 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 Diff {
+    export {
+        jsonDiff,
+        jsonEquals,
+        DiffChangeType,
+        IDiffChange,
+        IDiffResult,
+        IJsonDiffOptions,
+        jsonThreeWayDiff,
+        IThreeWayDiffMetadata,
+        IThreeWayDiff
+    }
+}
+export { Diff }
+
+/**
+ * JSON Diff Utilities for TypeScript
+ *
+ * This module provides comprehensive tools for comparing JSON values and identifying
+ * differences between them. It offers two complementary approaches:
+ *
+ * ## **Detailed Diff API** (`jsonDiff`)
+ * Best for analysis, debugging, and understanding specific changes:
+ * - Returns a list of individual changes with exact paths and values
+ * - Ideal for logging, change tracking, and detailed analysis
+ * - Configurable options for array handling and path notation
+ *
+ * ## **Three-Way Diff API** (`jsonThreeWayDiff`)
+ * Best for applying changes and programmatic manipulation:
+ * - Returns three objects representing removed, unchanged, and added data
+ * - Perfect for merging, UI displays, and actionable results
+ * - Treats arrays as atomic units for simpler handling
+ *
+ * ## **Simple Equality** (`jsonEquals`)
+ * Fast boolean check for JSON equality without change details.
+ *
+ * **Key Features:**
+ * - Deep recursive comparison of nested structures
+ * - Support for all JSON types: objects, arrays, primitives, null
+ * - TypeScript-first with comprehensive type safety
+ * - Result pattern for consistent error handling
+ * - Extensive TSDoc documentation with practical examples
+ *
+ * @example Quick comparison of the two main APIs
+ * ```typescript
+ * const before = { name: "John", age: 30, city: "NYC" };
+ * const after = { name: "Jane", age: 30, country: "USA" };
+ *
+ * // Detailed analysis
+ * const detailed = jsonDiff(before, after);
+ * // Returns: [
+ * //   { path: "name", type: "modified", oldValue: "John", newValue: "Jane" },
+ * //   { path: "city", type: "removed", oldValue: "NYC" },
+ * //   { path: "country", type: "added", newValue: "USA" }
+ * // ]
+ *
+ * // Actionable objects
+ * const actionable = jsonThreeWayDiff(before, after);
+ * // Returns: {
+ * //   onlyInA: { name: "John", city: "NYC" },
+ * //   unchanged: { age: 30 },
+ * //   onlyInB: { name: "Jane", country: "USA" }
+ * // }
+ *
+ * // Apply changes: { ...unchanged, ...onlyInB }
+ * // Revert changes: { ...unchanged, ...onlyInA }
+ * ```
+ */
+/**
+ * Type of change detected in a JSON diff operation.
+ *
+ * - `'added'` - Property exists only in the second object
+ * - `'removed'` - Property exists only in the first object
+ * - `'modified'` - Property exists in both objects but with different values
+ * - `'unchanged'` - Property exists in both objects with identical values (only included when `includeUnchanged` is true)
+ *
+ * @public
+ */
+declare type DiffChangeType = 'added' | 'removed' | 'modified' | 'unchanged';
+
+declare namespace EditorRules {
+    export {
+        IConditionalJsonKeyResult,
+        IConditionalJsonDeferredObject,
+        IConditionalJsonRuleOptions,
+        ConditionalJsonEditorRule,
+        IMultiValuePropertyParts,
+        MultiValueJsonEditorRule,
+        ReferenceJsonEditorRule,
+        ITemplatedJsonRuleOptions,
+        TemplatedJsonEditorRule
+    }
+}
+export { EditorRules }
+
+/**
+ * On a successful match, the {@link EditorRules.ConditionalJsonEditorRule | ConditionalJsonEditorRule}
+ * stores a {@link EditorRules.IConditionalJsonDeferredObject | IConditionalJsonDeferredObject} describing the
+ * matching result, to be resolved at finalization time.
+ * @public
+ */
+declare interface IConditionalJsonDeferredObject extends IConditionalJsonKeyResult {
+    value: JsonValue;
+}
+
+/**
+ * Returned by {@link EditorRules.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 EditorRules.ConditionalJsonEditorRule | ConditionalJsonEditorRule}.
+ * @public
+ */
+declare interface IConditionalJsonRuleOptions extends Partial<IJsonEditorOptions> {
+    /**
+     * If true (default) then properties with unconditional names
+     * (which start with !) are flattened.
+     */
+    flattenUnconditionalValues?: boolean;
+}
+
+/**
+ * Represents a single change in a JSON diff operation.
+ *
+ * Each change describes a specific difference between two JSON values, including
+ * the location of the change and the old/new values involved.
+ *
+ * @example
+ * ```typescript
+ * // Example changes from diffing { name: "John", age: 30 } vs { name: "Jane", city: "NYC" }
+ * const changes: IDiffChange[] = [
+ *   { path: "name", type: "modified", oldValue: "John", newValue: "Jane" },
+ *   { path: "age", type: "removed", oldValue: 30 },
+ *   { path: "city", type: "added", newValue: "NYC" }
+ * ];
+ * ```
+ *
+ * @public
+ */
+declare interface IDiffChange {
+    /**
+     * The path to the changed value using dot notation.
+     *
+     * For nested objects, uses dots to separate levels (e.g., "user.profile.name").
+     * For arrays, uses numeric indices (e.g., "items.0.id", "tags.2").
+     * Empty string indicates the root value itself changed.
+     *
+     * @example "user.name", "items.0.id", "settings.theme", ""
+     */
+    path: string;
+    /**
+     * The type of change that occurred.
+     *
+     * @see {@link DiffChangeType} for detailed descriptions of each change type.
+     */
+    type: DiffChangeType;
+    /**
+     * The value in the first object.
+     *
+     * - Present for `'removed'` and `'modified'` changes
+     * - Present for `'unchanged'` changes when `includeUnchanged` is true
+     * - Undefined for `'added'` changes
+     */
+    oldValue?: JsonValue;
+    /**
+     * The value in the second object.
+     *
+     * - Present for `'added'` and `'modified'` changes
+     * - Present for `'unchanged'` changes when `includeUnchanged` is true
+     * - Undefined for `'removed'` changes
+     */
+    newValue?: JsonValue;
+}
+
+/**
+ * Result of a JSON diff operation containing all detected changes.
+ *
+ * This interface provides detailed information about every difference found
+ * between two JSON values, making it ideal for analysis, debugging, and
+ * understanding exactly what changed.
+ *
+ * @example
+ * ```typescript
+ * const result: IDiffResult = {
+ *   changes: [
+ *     { path: "name", type: "modified", oldValue: "John", newValue: "Jane" },
+ *     { path: "hobbies.1", type: "added", newValue: "gaming" }
+ *   ],
+ *   identical: false
+ * };
+ * ```
+ *
+ * @see {@link IDiffChange} for details about individual change objects
+ * @see {@link Diff.jsonDiff} for the function that produces this result
+ * @public
+ */
+declare interface IDiffResult {
+    /**
+     * Array of all changes detected between the two JSON objects.
+     *
+     * Changes are ordered by the path where they occur. For nested structures,
+     * parent changes appear before child changes.
+     */
+    changes: IDiffChange[];
+    /**
+     * True if the objects are identical, false otherwise.
+     *
+     * When true, the `changes` array will be empty (unless `includeUnchanged`
+     * option was used, in which case it may contain 'unchanged' entries).
+     */
+    identical: boolean;
+}
+
+/**
+ * A specialized JSON editor which does a deep clone of a supplied `JsonValue`.
+ * @public
+ */
+export declare interface IJsonCloneEditor {
+    /**
+     * Returns a deep clone of a supplied `JsonValue`.
+     * @param src - The `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';
+}
+
+/**
+ * Options for customizing JSON diff behavior.
+ *
+ * These options allow you to control how the diff algorithm processes
+ * different types of JSON structures and what information is included
+ * in the results.
+ *
+ * @example
+ * ```typescript
+ * // Include unchanged values and use custom path separator
+ * const options: IJsonDiffOptions = {
+ *   includeUnchanged: true,
+ *   pathSeparator: '/',
+ *   arrayOrderMatters: false
+ * };
+ *
+ * const result = jsonDiff(obj1, obj2, options);
+ * ```
+ *
+ * @public
+ */
+declare interface IJsonDiffOptions {
+    /**
+     * If true, includes unchanged values in the result.
+     *
+     * When enabled, the diff result will include entries with `type: 'unchanged'`
+     * for properties that exist in both objects with identical values. This can
+     * be useful for displaying complete side-by-side comparisons.
+     *
+     * @defaultValue false
+     */
+    includeUnchanged?: boolean;
+    /**
+     * Custom path separator for nested property paths.
+     *
+     * Controls the character used to separate levels in nested object paths.
+     * For example, with separator `'/'`, a nested property would be reported
+     * as `"user/profile/name"` instead of `"user.profile.name"`.
+     *
+     * @defaultValue "."
+     * @example "/", "-\>", "::"
+     */
+    pathSeparator?: string;
+    /**
+     * If true, treats arrays as ordered lists where position matters.
+     * If false, treats arrays as unordered sets.
+     *
+     * When `true` (default), array changes are reported by index position:
+     * `[1,2,3]` vs `[1,3,2]` shows modifications at indices 1 and 2.
+     *
+     * When `false`, arrays are compared as sets: `[1,2,3]` vs `[1,3,2]`
+     * may be considered equivalent (simplified unordered comparison).
+     *
+     * @defaultValue true
+     */
+    arrayOrderMatters?: boolean;
+}
+
+/**
+ * Merge options for a {@link JsonEditor | JsonEditor}.
+ * @public
+ */
+export declare interface IJsonEditorMergeOptions {
+    /**
+     * Controls how arrays are merged when combining JSON values.
+     * - `'append'` (default): Existing array elements are preserved and new elements are appended
+     * - `'replace'`: Existing array is completely replaced with the new array
+     */
+    arrayMergeBehavior: ArrayMergeBehavior;
+    /**
+     * Controls whether null values should be treated as property deletion during merge operations.
+     * - `false` (default): Null values are merged normally, setting the property to null
+     * - `true`: Null values delete the property from the target object during merge
+     */
+    nullAsDelete?: boolean;
+}
+
+/**
+ * Initialization options for a {@link JsonEditor | JsonEditor}.
+ * @public
+ */
+export declare interface IJsonEditorOptions {
+    context?: IJsonContext;
+    validation: IJsonEditorValidationOptions;
+    merge?: IJsonEditorMergeOptions;
+}
+
+/**
+ * An {@link IJsonEditorRule | IJsonEditorRule} represents a single configurable
+ * rule to be applied by a {@link JsonEditor | JsonEditor}.
+ * @public
+ */
+export declare interface IJsonEditorRule {
+    /**
+     * Called by a {@link 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 `JsonValue` of the property to be edited.
+     * @param state - {@link JsonEditorState | Editor state} which applies to the edit.
+     * @returns If the property was edited, returns `Success` with a `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 `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 JsonEditor | JsonEditor} to possibly edit a property value or array element.
+     * @param value - The `JsonValue` of the property to be edited.
+     * @param state - {@link JsonEditorState | Editor state} which applies to the edit.
+     * @returns Returns `Success` with the `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 JSON objects that were deferred during the first edit pass.
+     * @param state - {@link 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 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 `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 `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 JsonObject 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 `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 `JsonValue` 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 EditorRules.IMultiValuePropertyParts.propertyVariable | propertyVariable}.
+     * If false, values are added as individual properties with names that correspond the value.
+     */
+    readonly asArray: boolean;
+}
+
+/**
+ * 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
+ */
+export declare interface ISimpleJsonMapOptions {
+    keyPolicy?: ReferenceMapKeyPolicy<JsonValue>;
+    editor?: JsonEditor;
+}
+
+/**
+ * Configuration options for the {@link EditorRules.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;
+}
+
+/**
+ * Result of a three-way JSON diff operation.
+ *
+ * This interface provides an actionable representation of differences between
+ * two JSON values by separating them into three distinct objects. This approach
+ * makes it easy to apply changes, display side-by-side comparisons, perform
+ * merges, or programmatically work with the differences.
+ *
+ * **Key Benefits:**
+ * - **Actionable Results**: Objects can be directly used for merging or applying changes
+ * - **UI-Friendly**: Perfect for side-by-side diff displays with clear visual separation
+ * - **Merge-Ready**: Simplified three-way merge operations
+ * - **Structured Data**: Maintains original JSON structure rather than flattened paths
+ *
+ * @example Basic usage
+ * ```typescript
+ * const result: IThreeWayDiff = {
+ *   onlyInA: { name: "John", city: "NYC" },      // Original or removed data
+ *   unchanged: { age: 30 },                      // Stable data
+ *   onlyInB: { name: "Jane", country: "USA" },  // New or modified data
+ *   metadata: { added: 1, removed: 1, modified: 1, unchanged: 1 },
+ *   identical: false
+ * };
+ *
+ * // Apply changes: merge unchanged + onlyInB
+ * const updated = { ...result.unchanged, ...result.onlyInB };
+ * // Result: { age: 30, name: "Jane", country: "USA" }
+ *
+ * // Revert changes: merge unchanged + onlyInA
+ * const reverted = { ...result.unchanged, ...result.onlyInA };
+ * // Result: { age: 30, name: "John", city: "NYC" }
+ * ```
+ *
+ * @see {@link IThreeWayDiffMetadata} for metadata structure details
+ * @see {@link jsonThreeWayDiff} for the function that produces this result
+ * @see {@link Diff.jsonDiff} for an alternative detailed change-list approach
+ *
+ * @public
+ */
+declare interface IThreeWayDiff {
+    /**
+     * Contains properties that exist only in the first object, plus the first object's
+     * version of any properties that exist in both but have different values.
+     *
+     * This object represents the "old" or "source" state and can be used for:
+     * - Reverting changes by merging with `unchanged`
+     * - Displaying what was removed or changed from the original
+     * - Understanding the baseline state before modifications
+     *
+     * Will be `null` if no properties are unique to the first object.
+     */
+    onlyInA: JsonValue;
+    /**
+     * Contains properties that exist in both objects with identical values.
+     *
+     * This object represents the stable, consistent data between both inputs
+     * and can be used for:
+     * - The foundation for merging operations
+     * - Identifying what remained constant during changes
+     * - Building complete objects by combining with other parts
+     *
+     * Will be `null` if no properties are shared between the objects.
+     */
+    unchanged: JsonValue;
+    /**
+     * Contains properties that exist only in the second object, plus the second object's
+     * version of any properties that exist in both but have different values.
+     *
+     * This object represents the "new" or "target" state and can be used for:
+     * - Applying changes by merging with `unchanged`
+     * - Displaying what was added or changed in the update
+     * - Understanding the desired end state after modifications
+     *
+     * Will be `null` if no properties are unique to the second object.
+     */
+    onlyInB: JsonValue;
+    /**
+     * Summary metadata about the differences found.
+     *
+     * Provides counts of added, removed, modified, and unchanged properties
+     * for quick assessment of the scope and nature of changes.
+     */
+    metadata: IThreeWayDiffMetadata;
+    /**
+     * True if the objects are identical, false otherwise.
+     *
+     * When `true`, both `onlyInA` and `onlyInB` will be `null`, and `unchanged`
+     * will contain the complete shared structure. The metadata will show zero
+     * added, removed, and modified properties.
+     */
+    identical: boolean;
+}
+
+/**
+ * Metadata about the differences found in a three-way diff.
+ *
+ * Provides summary statistics about the types and quantities of changes
+ * detected between two JSON values, making it easy to understand the
+ * overall scope of differences at a glance.
+ *
+ * @example
+ * ```typescript
+ * const metadata: IThreeWayDiffMetadata = {
+ *   removed: 2,    // 2 properties only in first object
+ *   added: 1,      // 1 property only in second object
+ *   modified: 3,   // 3 properties changed between objects
+ *   unchanged: 5   // 5 properties identical in both objects
+ * };
+ *
+ * console.log(`Total changes: ${metadata.added + metadata.removed + metadata.modified}`);
+ * console.log(`Stability: ${metadata.unchanged / (metadata.unchanged + metadata.modified) * 100}%`);
+ * ```
+ *
+ * @public
+ */
+declare interface IThreeWayDiffMetadata {
+    /**
+     * Number of properties that exist only in the first object.
+     *
+     * These represent data that was removed when transitioning from
+     * the first object to the second object.
+     */
+    removed: number;
+    /**
+     * Number of properties that exist only in the second object.
+     *
+     * These represent new data that was added when transitioning from
+     * the first object to the second object.
+     */
+    added: number;
+    /**
+     * Number of properties that exist in both objects but have different values.
+     *
+     * These represent data that was modified during the transition between objects.
+     * For arrays, this counts entire array replacements as single modifications.
+     */
+    modified: number;
+    /**
+     * Number of properties that exist in both objects with identical values.
+     *
+     * These represent stable data that remained consistent between the two objects.
+     */
+    unchanged: number;
+}
+
+/**
+ * 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 simple validating {@link JsonConverter | JSON converter}. Converts `unknown` to a
+ * `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 static `JsonContextHelper.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 static `JsonContextHelper.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>;
+}
+
+/**
+ * Performs a deep diff comparison between two JSON values.
+ *
+ * This function provides detailed change tracking by analyzing every difference
+ * between two JSON structures. It returns a list of specific changes with paths,
+ * making it ideal for debugging, logging, change analysis, and understanding
+ * exactly what has changed between two data states.
+ *
+ * **Key Features:**
+ * - Deep recursive comparison of nested objects and arrays
+ * - Precise path tracking using dot notation (e.g., "user.profile.name")
+ * - Support for all JSON value types: objects, arrays, primitives, null
+ * - Configurable array comparison (ordered vs unordered)
+ * - Optional inclusion of unchanged values for complete comparisons
+ *
+ * **Use Cases:**
+ * - Debugging data changes in applications
+ * - Generating change logs or audit trails
+ * - Validating API responses against expected data
+ * - Creating detailed diff reports for data synchronization
+ *
+ * @param obj1 - The first JSON value to compare (often the "before" state)
+ * @param obj2 - The second JSON value to compare (often the "after" state)
+ * @param options - Optional configuration for customizing diff behavior
+ * @returns A Result containing the diff result with all detected changes
+ *
+ * @example Basic usage with objects
+ * ```typescript
+ * const before = { name: "John", age: 30, city: "NYC" };
+ * const after = { name: "Jane", age: 30, country: "USA" };
+ *
+ * const result = jsonDiff(before, after);
+ * if (result.success) {
+ *   result.value.changes.forEach(change => {
+ *     console.log(`${change.path}: ${change.type}`);
+ *     // Output:
+ *     // name: modified
+ *     // city: removed
+ *     // country: added
+ *   });
+ * }
+ * ```
+ *
+ * @example With arrays and nested structures
+ * ```typescript
+ * const user1 = {
+ *   profile: { name: "John", hobbies: ["reading"] },
+ *   settings: { theme: "dark" }
+ * };
+ * const user2 = {
+ *   profile: { name: "John", hobbies: ["reading", "gaming"] },
+ *   settings: { theme: "light", notifications: true }
+ * };
+ *
+ * const result = jsonDiff(user1, user2);
+ * if (result.success) {
+ *   console.log(result.value.changes);
+ *   // [
+ *   //   { path: "profile.hobbies.1", type: "added", newValue: "gaming" },
+ *   //   { path: "settings.theme", type: "modified", oldValue: "dark", newValue: "light" },
+ *   //   { path: "settings.notifications", type: "added", newValue: true }
+ *   // ]
+ * }
+ * ```
+ *
+ * @example Using options for custom behavior
+ * ```typescript
+ * const options: IJsonDiffOptions = {
+ *   includeUnchanged: true,        // Include unchanged properties
+ *   pathSeparator: '/',            // Use '/' instead of '.' in paths
+ *   arrayOrderMatters: false       // Treat arrays as unordered sets
+ * };
+ *
+ * const result = jsonDiff(obj1, obj2, options);
+ * ```
+ *
+ * @see {@link IDiffResult} for the structure of returned results
+ * @see {@link IDiffChange} for details about individual changes
+ * @see {@link IJsonDiffOptions} for available configuration options
+ * @see {@link jsonThreeWayDiff} for an alternative API focused on actionable results
+ * @see {@link jsonEquals} for simple equality checking without change details
+ *
+ * @public
+ */
+declare function jsonDiff(obj1: JsonValue, obj2: JsonValue, options?: IJsonDiffOptions): Result<IDiffResult>;
+
+/**
+ * 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 JsonEditor | JsonEditor}.
+     * @internal
+     */
+    protected static _default?: JsonEditor;
+    /**
+     * Full set of {@link IJsonEditorOptions | editor options} in effect for this editor.
+     */
+    options: IJsonEditorOptions;
+    /**
+     * The set of {@link IJsonEditorRule | editor rules} applied by this editor.
+     * @internal
+     */
+    protected _rules: IJsonEditorRule[];
+    /**
+     * Protected constructor for {@link JsonEditor | JsonEditor} and derived classes.
+     * External consumers should instantiate via the {@link JsonEditor.create | create static method}.
+     * @param options - Optional partial {@link IJsonEditorOptions | editor options} for the
+     * constructed editor.
+     * @param rules - Any {@link IJsonEditorRule | editor rules} to be applied by the editor.
+     * @internal
+     */
+    protected constructor(options?: Partial<IJsonEditorOptions>, rules?: IJsonEditorRule[]);
+    /**
+     * Default singleton {@link JsonEditor | JsonEditor} for simple use. Applies all rules
+     * but with no default context.
+     */
+    static get default(): JsonEditor;
+    /**
+     * Constructs a new {@link JsonEditor | JsonEditor}.
+     * @param options - Optional partial {@link IJsonEditorOptions | editor options} for the
+     * constructed editor.
+     * @param rules - Optional set of {@link IJsonEditorRule | editor rules} to be applied by the editor.
+     * @readonly A new {@link 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 IJsonEditorOptions | editor options} for
+     * all rules.
+     * @returns Default {@link IJsonEditorRule | editor rules} with any supplied options
+     * applied.
+     */
+    static getDefaultRules(options?: IJsonEditorOptions): Result<IJsonEditorRule[]>;
+    /**
+     * Creates a complete IJsonEditorOptions object from partial options, filling in
+     * default values for any missing properties. This ensures all editor instances
+     * have consistent, complete configuration including validation rules and merge behavior.
+     * @param options - Optional partial editor options to merge with defaults
+     * @returns Success with complete editor options, or Failure if validation fails
+     * @internal
+     */
+    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 `JsonObject` to be updated
+     * @param src - The source `JsonObject` to be merged
+     * @param runtimeContext - An optional {@link IJsonContext | IJsonContext} supplying variables
+     * and references.
+     * @returns `Success` with the original source `JsonObject` 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 `JsonObject` to be updated
+     * @param srcObjects - `JsonObject`s to be merged into the target object, in the order
+     * supplied.
+     * @returns `Success` with the original source `JsonObject` 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 `JsonObject` to be updated
+     * @param srcObjects - Objects to be merged into the target object, in the order supplied.
+     * @returns `Success` with the original source `JsonObject` 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 `JsonValue`, applying all editor rules and a default
+     * or optionally supplied context
+     * @param src - The `JsonValue` to be cloned.
+     * @param context - An optional {@link IJsonContext | JSON context} supplying variables and references.
+     */
+    clone(src: JsonValue, context?: IJsonContext): DetailedResult<JsonValue, JsonEditFailureReason>;
+    /**
+     * Merges properties from a source object into a target object, applying editor rules and
+     * null-as-delete logic. This is the core merge implementation that handles property-by-property
+     * merging with rule processing and deferred property handling.
+     * @param target - The target object to merge properties into
+     * @param src - The source object containing properties to merge
+     * @param state - The editor state containing options and context
+     * @returns Success with the modified target object, or Failure with error details
+     * @internal
+     */
+    protected _mergeObjectInPlace(target: JsonObject, src: JsonObject, state: JsonEditorState): Result<JsonObject>;
+    /**
+     * Creates a deep clone of a JSON array by recursively cloning each element.
+     * Each array element is cloned using the main clone method, preserving the
+     * editor's rules and validation settings.
+     * @param src - The source JSON array to clone
+     * @param context - Optional JSON context for cloning operations
+     * @returns Success with the cloned array, or Failure with error details
+     * @internal
+     */
+    protected _cloneArray(src: JsonArray, context?: IJsonContext): DetailedResult<JsonArray, JsonEditFailureReason>;
+    /**
+     * Merges a single cloned property value into a target object. This method handles
+     * the core merge logic including null-as-delete behavior, array merging, and
+     * recursive object merging. The null-as-delete check occurs before primitive
+     * handling to ensure null values can signal property deletion.
+     * @param target - The target object to merge the property into
+     * @param key - The property key being merged
+     * @param newValue - The cloned value to merge (from source object)
+     * @param state - The editor state containing merge options and context
+     * @returns Success with the merged value, or Failure with error details
+     * @internal
+     */
+    protected _mergeClonedProperty(target: JsonObject, key: string, newValue: JsonValue, state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
+    /**
+     * Applies editor rules to a single property during merge operations. This method
+     * iterates through all configured editor rules to process the property, handling
+     * templates, conditionals, multi-value properties, and references.
+     * @param key - The property key to edit
+     * @param value - The property value to edit
+     * @param state - The editor state containing rules and context
+     * @returns Success with transformed property object, or Failure if rules cannot process
+     * @internal
+     */
+    protected _editProperty(key: string, value: JsonValue, state: JsonEditorState): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;
+    /**
+     * Applies editor rules to a single JSON value during clone operations. This method
+     * iterates through all configured editor rules to process the value, handling
+     * templates, conditionals, multi-value expressions, and references.
+     * @param value - The JSON value to edit and transform
+     * @param state - The editor state containing rules and context
+     * @returns Success with transformed value, or Failure if rules cannot process
+     * @internal
+     */
+    protected _editValue(value: JsonValue, state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
+    /**
+     * Clone an object without applying null-as-delete behavior.
+     * This preserves null values during cloning so they can be used for deletion signaling during merge.
+     * @param target - The target object to clone into
+     * @param src - The source object to clone
+     * @param state - The editor state
+     * @returns The cloned object
+     * @internal
+     */
+    protected _cloneObjectWithoutNullAsDelete(target: JsonObject, src: JsonObject, state: JsonEditorState): DetailedResult<JsonObject, JsonEditFailureReason>;
+    /**
+     * Finalizes the merge operation by processing any deferred properties and merging
+     * them into the target object. Deferred properties are those that require special
+     * processing after the initial merge phase, such as references that depend on
+     * other properties being resolved first.
+     * @param target - The target object that has been merged
+     * @param state - The editor state containing deferred properties and rules
+     * @returns Success with the finalized target object, or Failure with error details
+     * @internal
+     */
+    protected _finalizeAndMerge(target: JsonObject, state: JsonEditorState): DetailedResult<JsonObject, JsonEditFailureReason>;
+}
+
+/**
+ * A thin wrapper to allow an arbitrary {@link 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 JsonEditor | JsonEditor}Converter which uses the supplied editor
+     * @param editor -
+     */
+    constructor(editor: JsonEditor);
+    /**
+     * Constructs a new {@link 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
+     * `JsonValue` is not a `JsonObject`.
+     */
+    object(): Converter<JsonObject, IJsonContext>;
+    /**
+     * Gets a derived converter which fails if the resulting converted
+     * `JsonValue` is not a `JsonArray`.
+     */
+    array(): Converter<JsonArray, IJsonContext>;
+    protected _convert(from: unknown, context?: IJsonContext): Result<JsonValue>;
+}
+
+/**
+ * Default base implementation of {@link IJsonEditorRule | IJsonEditorRule} returns inapplicable for all operations so that
+ * derived classes need only implement the operations they actually support.
+ * @public
+ */
+export declare class JsonEditorRuleBase implements IJsonEditorRule {
+    /**
+     * {@inheritdoc IJsonEditorRule.editProperty}
+     */
+    editProperty(__key: string, __value: JsonValue, __state: JsonEditorState): DetailedResult<JsonObject, JsonPropertyEditFailureReason>;
+    /**
+     * {@inheritdoc IJsonEditorRule.editValue}
+     */
+    editValue(__value: JsonValue, __state: JsonEditorState): DetailedResult<JsonValue, JsonEditFailureReason>;
+    /**
+     * {@inheritdoc IJsonEditorRule.finalizeProperties}
+     */
+    finalizeProperties(__deferred: JsonObject[], __state: JsonEditorState): DetailedResult<JsonObject[], JsonEditFailureReason>;
+}
+
+/**
+ * Represents the internal state of a {@link JsonEditor | JsonEditor}.
+ * @public
+ */
+export declare class JsonEditorState {
+    /**
+     * Static global counter used to assign each {@link JsonEditorState | JsonEditorState}
+     * a unique identifier.
+     * @internal
+     */
+    protected static _nextId: number;
+    /**
+     * The {@link IJsonCloneEditor | editor} for which this state applies.
+     */
+    readonly editor: IJsonCloneEditor;
+    /**
+     * Fully resolved {@link IJsonEditorOptions | editor options} that apply
+     * to the operation for which this state applies.
+     */
+    readonly options: IJsonEditorOptions;
+    /**
+     * Any deferred JSON objects to be merged during finalization.
+     * @internal
+     */
+    protected readonly _deferred: JsonObject[];
+    /**
+     * Unique global identifier for this {@link JsonEditorState | state object}.
+     * @internal
+     */
+    protected readonly _id: number;
+    /**
+     * Constructs a new {@link JsonEditorState | JsonEditorState}.
+     * @param editor - The {@link IJsonCloneEditor | editor} to which this state
+     * applies.
+     * @param baseOptions - The {@link 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 JSON objects that were deferred for merge during
+     * finalization.
+     */
+    get deferred(): JsonObject[];
+    /**
+     * Merges an optional {@link IJsonContext | JSON context} into a supplied set
+     * of {@link IJsonEditorOptions | JSON editor options}.
+     * @param options - The {@link 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 IJsonEditorOptions | options} if
+     * there was nothing to merge, or aa new {@link 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 `JsonObject` to the deferred list.
+     * @param obj - The `JsonObject` to be deferred.
+     */
+    defer(obj: JsonObject): void;
+    /**
+     * Gets a {@link TemplateVars | TemplateVars} from the context of this {@link 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 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 JsonEditorValidationRules | validation rule} that failed.
+     * @param message -  A string message describing the failed validation.
+     * @param validation - The {@link 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 JsonEditor | JsonEditor}.
+ * @public
+ */
+export declare type JsonEditorValidationRules = 'invalidPropertyName' | 'invalidPropertyValue' | 'undefinedPropertyValue';
+
+/**
+ * A simpler helper function that returns true if two JSON values are deeply equal.
+ *
+ * This function provides a fast boolean check for JSON equality without the overhead
+ * of tracking individual changes. It performs the same deep comparison logic as
+ * {@link Diff.jsonDiff} but returns only a true/false result, making it ideal for
+ * conditional logic and validation scenarios.
+ *
+ * **Key Features:**
+ * - Deep recursive comparison of all nested structures
+ * - Handles all JSON types: objects, arrays, primitives, null
+ * - Object property order independence
+ * - Array order significance (index positions matter)
+ * - Performance optimized for equality checking
+ *
+ * **Use Cases:**
+ * - Conditional logic based on data equality
+ * - Input validation and testing assertions
+ * - Caching and memoization keys
+ * - Quick checks before expensive diff operations
+ *
+ * @param obj1 - The first JSON value to compare
+ * @param obj2 - The second JSON value to compare
+ * @returns True if the values are deeply equal, false otherwise
+ *
+ * @example Basic equality checking
+ * ```typescript
+ * // Objects with same structure and values
+ * const user1 = { name: "John", hobbies: ["reading", "gaming"] };
+ * const user2 = { name: "John", hobbies: ["reading", "gaming"] };
+ * console.log(jsonEquals(user1, user2)); // true
+ *
+ * // Different property order (still equal)
+ * const obj1 = { a: 1, b: 2 };
+ * const obj2 = { b: 2, a: 1 };
+ * console.log(jsonEquals(obj1, obj2)); // true
+ *
+ * // Different values
+ * const before = { status: "pending" };
+ * const after = { status: "completed" };
+ * console.log(jsonEquals(before, after)); // false
+ * ```
+ *
+ * @example With nested structures
+ * ```typescript
+ * const config1 = {
+ *   database: { host: "localhost", port: 5432 },
+ *   features: ["auth", "cache"]
+ * };
+ * const config2 = {
+ *   database: { host: "localhost", port: 5432 },
+ *   features: ["auth", "cache"]
+ * };
+ *
+ * if (jsonEquals(config1, config2)) {
+ *   console.log("Configurations are identical");
+ * }
+ * ```
+ *
+ * @example Array order sensitivity
+ * ```typescript
+ * const list1 = [1, 2, 3];
+ * const list2 = [3, 2, 1];
+ * console.log(jsonEquals(list1, list2)); // false - order matters
+ *
+ * const list3 = [1, 2, 3];
+ * const list4 = [1, 2, 3];
+ * console.log(jsonEquals(list3, list4)); // true - same order
+ * ```
+ *
+ * @see {@link Diff.jsonDiff} for detailed change analysis when equality fails
+ * @see {@link jsonThreeWayDiff} for actionable difference results
+ *
+ * @public
+ */
+declare function jsonEquals(obj1: JsonValue, obj2: JsonValue): boolean;
+
+/**
+ * A simple validating {@link JsonConverter | JSON converter}. Converts unknown
+ * to a `JsonObject`, or fails if the `unknown` contains invalid
+ * JSON or is not an object.
+ * @public
+ */
+declare const jsonObject: Converter<JsonObject, IJsonContext>;
+
+/**
+ * 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';
+
+/**
+ * Performs a three-way diff comparison between two JSON values, returning separate
+ * objects containing the differences and similarities.
+ *
+ * This function provides an alternative to {@link Diff.jsonDiff} that focuses on actionable
+ * results rather than detailed change analysis. Instead of a list of individual changes,
+ * it returns three objects that can be directly used for merging, UI display, or
+ * programmatic manipulation.
+ *
+ * **Key Features:**
+ * - **Actionable Results**: Returns objects ready for immediate use in merging operations
+ * - **Simplified Array Handling**: Arrays are treated as atomic values for cleaner results
+ * - **Structural Preservation**: Maintains original JSON structure rather than flattened paths
+ * - **UI-Optimized**: Perfect for side-by-side diff displays and change visualization
+ * - **Merge-Friendly**: Designed specifically for three-way merge scenarios
+ *
+ * **Array Handling:**
+ * Unlike {@link Diff.jsonDiff}, this function treats arrays as complete units. If arrays differ,
+ * the entire array appears in the appropriate result object rather than computing
+ * element-by-element deltas. This approach is simpler and more predictable for most
+ * use cases involving data updates and synchronization.
+ *
+ * **Use Cases:**
+ * - Applying configuration updates while preserving unchanged settings
+ * - Creating side-by-side diff displays in user interfaces
+ * - Building three-way merge tools for data synchronization
+ * - Implementing undo/redo functionality with granular control
+ * - Generating patch objects for API updates
+ *
+ * @param obj1 - The first JSON value to compare (often the "before" or "source" state)
+ * @param obj2 - The second JSON value to compare (often the "after" or "target" state)
+ * @returns A Result containing the three-way diff with separate objects and metadata
+ *
+ * @example Basic usage for applying changes
+ * ```typescript
+ * const original = { name: "John", age: 30, city: "NYC", active: true };
+ * const updated = { name: "Jane", age: 30, country: "USA", active: true };
+ *
+ * const result = jsonThreeWayDiff(original, updated);
+ * if (result.success) {
+ *   const { onlyInA, unchanged, onlyInB } = result.value;
+ *
+ *   // Apply changes: merge unchanged + onlyInB
+ *   const applied = { ...unchanged, ...onlyInB };
+ *   console.log(applied); // { age: 30, active: true, name: "Jane", country: "USA" }
+ *
+ *   // Revert changes: merge unchanged + onlyInA
+ *   const reverted = { ...unchanged, ...onlyInA };
+ *   console.log(reverted); // { age: 30, active: true, name: "John", city: "NYC" }
+ * }
+ * ```
+ *
+ * @example UI-friendly diff display
+ * ```typescript
+ * const result = jsonThreeWayDiff(userBefore, userAfter);
+ * if (result.success) {
+ *   const { onlyInA, unchanged, onlyInB, metadata } = result.value;
+ *
+ *   // Display summary
+ *   console.log(`Changes: ${metadata.added} added, ${metadata.removed} removed, ${metadata.modified} modified`);
+ *
+ *   // Show removed/old values in red
+ *   if (onlyInA) displayInColor(onlyInA, 'red');
+ *
+ *   // Show unchanged values in gray
+ *   if (unchanged) displayInColor(unchanged, 'gray');
+ *
+ *   // Show added/new values in green
+ *   if (onlyInB) displayInColor(onlyInB, 'green');
+ * }
+ * ```
+ *
+ * @example Nested objects and array handling
+ * ```typescript
+ * const config1 = {
+ *   database: { host: "localhost", port: 5432 },
+ *   features: ["auth", "logging"],
+ *   version: "1.0"
+ * };
+ * const config2 = {
+ *   database: { host: "production.db", port: 5432 },
+ *   features: ["auth", "logging", "metrics"],  // Array treated as complete unit
+ *   version: "1.1"
+ * };
+ *
+ * const result = jsonThreeWayDiff(config1, config2);
+ * if (result.success) {
+ *   // result.value.onlyInA = { database: { host: "localhost" }, features: ["auth", "logging"], version: "1.0" }
+ *   // result.value.unchanged = { database: { port: 5432 } }
+ *   // result.value.onlyInB = { database: { host: "production.db" }, features: ["auth", "logging", "metrics"], version: "1.1" }
+ * }
+ * ```
+ *
+ * @example Conditional updates based on changes
+ * ```typescript
+ * const result = jsonThreeWayDiff(currentState, newState);
+ * if (result.success && !result.value.identical) {
+ *   const { metadata } = result.value;
+ *
+ *   if (metadata.modified > 0) {
+ *     console.log("Critical settings changed - requires restart");
+ *   } else if (metadata.added > 0) {
+ *     console.log("New features enabled");
+ *   } else if (metadata.removed > 0) {
+ *     console.log("Features disabled");
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link IThreeWayDiff} for the structure of returned results
+ * @see {@link IThreeWayDiffMetadata} for metadata details
+ * @see {@link Diff.jsonDiff} for detailed change-by-change analysis
+ * @see {@link jsonEquals} for simple equality checking
+ *
+ * @public
+ */
+declare function jsonThreeWayDiff(obj1: JsonValue, obj2: JsonValue): Result<IThreeWayDiff>;
+
+/**
+ * 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 EditorRules.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 IJsonEditorOptions | editor options}
+     * for this rule.
+     * @public
+     */
+    protected _options?: IJsonEditorOptions;
+    /**
+     * Creates a new {@link EditorRules.MultiValueJsonEditorRule | MultiValueJsonEditorRule}.
+     * @param options - Optional {@link IJsonEditorOptions | configuration options}.
+     */
+    constructor(options?: IJsonEditorOptions);
+    /**
+     * Creates a new {@link EditorRules.MultiValueJsonEditorRule | MultiValueJsonEditorRule}.
+     * @param options - Optional {@link 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 `JsonValue` of the property to be considered.
+     * @param state - The {@link 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 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 `JsonValue` of the property to be considered.
+     * @param state - The {@link JsonEditorState | editor state} for the object being edited.
+     * @returns `Success` with detail `'deferred'` and an
+     * {@link EditorRules.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>;
+}
+
+/**
+ * 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 `JsonValue` to be returned
+     * @param context - Optional {@link IJsonContext | JSON Context} used to format returned values
+     * @param editor - Optional {@link 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 `JsonValue` to be returned
+     * @param context - Optional {@link IJsonContext | JSON Context} used to format returned values
+     * @param editor - Optional {@link 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 `JsonValue` to be returned
+     * @param context - Optional {@link IJsonContext | JSON Context} used to format returned values
+     * @param editor - Optional {@link 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>;
+}
+
+/**
+ * The {@link EditorRules.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 IJsonEditorOptions | editor options} for this rule.
+     * @public
+     */
+    protected _options?: IJsonEditorOptions;
+    /**
+     * Creates a new {@link EditorRules.ReferenceJsonEditorRule | ReferenceJsonEditorRule}.
+     * @param options - Optional {@link IJsonEditorOptions | configuration options} for this rule.
+     */
+    constructor(options?: IJsonEditorOptions);
+    /**
+     * Creates a new {@link EditorRules.ReferenceJsonEditorRule | ReferenceJsonEditorRule}.
+     * @param options - Optional {@link 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 `JsonValue` of the property to be considered.
+     * @param state - The {@link JsonEditorState | editor state} for the object being edited.
+     * @returns If the reference is successful, returns `Success` with a `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 `JsonValue` of the property to be considered.
+     * @param state - The {@link 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 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 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 `JsonValue`
+     * 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 `JsonValue`
+     * 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 `JsonValue` 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.
+ * @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 `JsonObject` 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 `JsonValue` 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 EditorRules.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 EditorRules.ITemplatedJsonRuleOptions | configuration options} for this rule.
+         * @public
+         */
+        protected _options?: ITemplatedJsonRuleOptions;
+        /**
+         * Creates a new {@link EditorRules.TemplatedJsonEditorRule | TemplatedJsonEditorRule}.
+         * @param options - Optional {@link EditorRules.ITemplatedJsonRuleOptions | configuration options}
+         * for this rule.
+         */
+        constructor(options?: ITemplatedJsonRuleOptions);
+        /**
+         * Creates a new {@link EditorRules.TemplatedJsonEditorRule | TemplatedJsonEditorRule}.
+         * @param options - Optional {@link EditorRules.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 `JsonValue` of the property to be considered.
+         * @param state - The {@link JsonEditorState | editor state} for the object being edited.
+         * @returns `Success` with detail `'edited'` and an `JsonObject` 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 `JsonValue` to be edited.
+         * @param state - The {@link 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 JsonEditorState | editor state}.
+         * @param template - The mustache template to be rendered.
+         * @param state - The {@link 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];
+
+    export { }