/*!
 * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
 * Licensed under the MIT License.
 */
import type { MakeNominal } from "../../util/index.js";
import { type TreeNodeSchema } from "../core/index.js";
import { type FieldSchemaAlpha, type ImplicitFieldSchema } from "../fieldSchema.js";
import type { SchemaType, SimpleNodeSchema } from "../simpleSchema.js";
import { type TreeSchema } from "../treeSchema.js";
/**
 * Options when constructing a tree view.
 * @public
 */
export interface ITreeConfigurationOptions {
    /**
     * If `true`, the tree will perform additional validation of content against its stored schema
     * and throw an error if the new content doesn't match the expected schema.
     *
     * @defaultValue `false`.
     *
     * @remarks
     * Currently most cases already have some schema validation, so this is mainly for additional validation which may be useful when debugging issues,
     * working with untyped APIs, or when the small performance overhead is a non-issue.
     *
     * Enabling schema validation has a performance penalty when inserting new content into the tree because
     * additional checks are done. Enable this option only in scenarios where you are ok with that operation being a
     * bit slower.
     *
     * For additional validation in more cases, see {@link ForestTypeExpensiveDebug}.
     */
    enableSchemaValidation?: boolean;
    /**
     * A flag used to opt into strict rules ensuring that the schema avoids cases which can make the type of nodes ambiguous when importing or exporting data.
     * @defaultValue `false`.
     *
     * @remarks
     * When this is true, it ensures that the compile time type safety for data when constructing nodes is sufficient to ensure that the runtime behavior will not give node data ambiguity errors.
     *
     * This ensures that the canonical JSON-like representation of all unions in the tree are lossless and unambiguous.
     * This canonical JSON-like representation consists of arrays, plain old JavaScript objects with string keys, booleans, numbers (excluding NaN, -0 and infinities), strings, null and {@link @fluidframework/core-interfaces#IFluidHandle}s.
     * It is compatible with the node creation APIs (such as schema class constructors) and is also compatible with JSON assuming any IFluidHandles get special handling (since they are not JSON compatible).
     * Currently these cases can cause ambiguity in a union:
     *
     * - More than one ArrayNode type: it's impossible to tell which array type is intended in the case of empty arrays (`[]`).
     *
     * - More than one MapNode type: it's impossible to tell which map type is intended in the case of an empty map (`{}`).
     *
     * - Both a MapNode and an ArrayNode: this case is not a problem for the canonical JSON representation, but is an issue when constructing from an Iterable, which is supported for both MapNode and ArrayNode.
     *
     * - Both a MapNode and an ObjectNode: when the input is valid for the ObjectNode, the current parser always considers it ambiguous with being a MapNode.
     *
     * - ObjectNodes which have fields (required or optional) which include all required fields of another ObjectNode: currently each ObjectNode is differentiated by the presence of its required fields.
     *
     * This check is conservative: some complex cases may error if the current simple algorithm cannot show no ambiguity is possible.
     * This check may become more permissive over time.
     *
     * @example Ambiguous schema (with `preventAmbiguity: false`), and how to disambiguate it using {@link Unhydrated} nodes:
     * ```typescript
     * const schemaFactory = new SchemaFactory("com.example");
     * class Feet extends schemaFactory.object("Feet", { length: schemaFactory.number }) {}
     * class Meters extends schemaFactory.object("Meters", { length: schemaFactory.number }) {}
     * const config = new TreeViewConfiguration({
     * 	// This combination of schema can lead to ambiguous cases and will error if `preventAmbiguity` is true.
     * 	schema: [Feet, Meters],
     * 	preventAmbiguity: false,
     * });
     * const view = tree.viewWith(config);
     * // This is invalid since it is ambiguous which type of node is being constructed:
     * // view.initialize({ length: 5 });
     * // To work, an explicit type can be provided by using an {@link Unhydrated} Node:
     * view.initialize(new Meters({ length: 5 }));
     * ```
     *
     * @example Schema disambiguated by adjusting field names, validated with `preventAmbiguity: true:`
     * ```typescript
     * const schemaFactory = new SchemaFactory("com.example");
     * class Feet extends schemaFactory.object("Feet", { length: schemaFactory.number }) {}
     * class Meters extends schemaFactory.object("Meters", {
     * 	// To avoid ambiguity when parsing unions of Feet and Meters, this renames the length field to "meters".
     * 	// To preserve compatibility with existing data from the ambiguous case,
     * 	// `{ key: "length" }` is set, so when persisted in the tree "length" is used as the field name.
     * 	meters: schemaFactory.required(schemaFactory.number, { key: "length" }),
     * }) {}
     * const config = new TreeViewConfiguration({
     * 	// This combination of schema is not ambiguous because `Feet` and `Meters` have different required keys.
     * 	schema: [Feet, Meters],
     * 	preventAmbiguity: true,
     * });
     * const view = tree.viewWith(config);
     * // This now works, since the field is sufficient to determine this is a `Meters` node.
     * view.initialize({ meters: 5 });
     * ```
     *
     * @privateRemarks
     * In the future, we can support lossless round tripping via the canonical JSON-like representation above when unambiguous.
     * This could be done via methods added to `Tree` to export and import such objects, which would give us a place to explicitly define the type of this representation.
     *
     * To make this more permissive in the future we can:
     *
     * - Make unhydratedFlexTreeFromInsertable more permissive (ex: allow disambiguation based on leaf type)
     * - Update this check to more tightly match unhydratedFlexTreeFromInsertable
     * - Add options to help schema authors disambiguate their types, such as "constant fields" which are not persisted, and always have a constant value.
     *
     * The above examples exist in executable form in this files tests, and should be updated there then copied back here.
     */
    readonly preventAmbiguity?: boolean;
}
/**
 * Property-bag configuration for {@link TreeViewConfiguration} construction.
 * @public
 */
export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> extends ITreeConfigurationOptions {
    /**
     * The schema which the application wants to view the tree with.
     * @remarks
     * Use {@link SchemaFactory} to construct the schema.
     * Changes to this schema between different versions have important compatibility implications.
     * See the {@link https://fluidframework.com/docs/data-structures/tree/schema-evolution | documentation on schema evolution} for more details.
     */
    readonly schema: TSchema;
}
/**
 * Configuration for {@link ViewableTree.viewWith}.
 * @sealed @public
 */
export declare class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> implements Required<ITreeViewConfiguration<TSchema>> {
    protected _typeCheck: MakeNominal;
    /**
     * {@inheritDoc ITreeViewConfiguration.schema}
     */
    readonly schema: TSchema;
    /**
     * {@inheritDoc ITreeConfigurationOptions.enableSchemaValidation}
     */
    readonly enableSchemaValidation: boolean;
    /**
     * {@inheritDoc ITreeConfigurationOptions.preventAmbiguity}
     */
    readonly preventAmbiguity: boolean;
    /**
     * Construct a new {@link TreeViewConfiguration}.
     *
     * @param props - Property bag of configuration options.
     *
     * @remarks
     * Performing this construction deeply validates the provided schema.
     * This means that when this constructor is called, all {@link LazyItem} {@link TreeNodeSchema} references will be evaluated (using {@link evaluateLazySchema}).
     * This means that the declarations for all transitively reachable {@link TreeNodeSchema} must be available at this time.
     *
     * For example, a schema reachable from this configuration cannot reference this configuration during its declaration,
     * since this would be a cyclic dependency that will cause an error when constructing this configuration.
     */
    constructor(props: ITreeViewConfiguration<TSchema>);
}
/**
 * {@link TreeViewConfiguration} extended with some alpha APIs.
 * @remarks
 * See {@link (asAlpha:2)} for an API to downcast from {@link TreeViewConfiguration} to this type.
 * @sealed @alpha
 */
export declare class TreeViewConfigurationAlpha<const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> extends TreeViewConfiguration<TSchema> implements TreeSchema {
    readonly root: FieldSchemaAlpha;
    readonly definitions: ReadonlyMap<string, SimpleNodeSchema<SchemaType.View> & TreeNodeSchema>;
    constructor(props: ITreeViewConfiguration<TSchema>);
}
/**
 * Check if union contents are valid (shallowly).
 *
 * @param union - The union of {@link TreeNodeSchema} to check.
 * @param preventAmbiguity - If true, detect cases documented in {@link ITreeConfigurationOptions.preventAmbiguity}, reporting them to `ambiguityErrors`.
 * @param ambiguityErrors - An array into which this function inserts any ambiguity errors, see {@link ITreeConfigurationOptions.preventAmbiguity}.
 *
 * @remarks
 * Includes checks for non-ambiguity errors as well: such as duplicate schemas in the union.
 * Any non-ambiguity errors are thrown as exceptions: `UsageError`s if causable by incorrect API use, and asserts if violating internal invariants.
 */
export declare function checkUnion(union: Iterable<TreeNodeSchema>, preventAmbiguity: boolean, ambiguityErrors: string[]): void;
//# sourceMappingURL=configuration.d.ts.map