/*!
 * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
 * Licensed under the MIT License.
 */
import type { IFluidHandle } from "@fluidframework/core-interfaces";
import type { IIdCompressor } from "@fluidframework/id-compressor";
import { type TreeNode, type Unhydrated, type ImplicitFieldSchema, type InsertableField, type TreeFieldFromImplicitField, type TreeLeafValue, type UnsafeUnknownSchema, type ConciseTree, type ParseOptions, type VerboseTree, type EncodeOptions, type TreeBranch } from "../simple-tree/index.js";
import { type JsonCompatible } from "../util/index.js";
import { type FluidClientVersion, type ICodecOptions } from "../codec/index.js";
/**
 * Extensions to {@link Tree} and {@link TreeBeta} which are not yet stable.
 * @sealed @alpha
 */
export declare const TreeAlpha: {
    /**
     * Retrieve the {@link TreeBranch | branch}, if any, for the given node.
     * @param node - The node to query
     * @remarks If the node has already been inserted into the tree, this will return the branch associated with that node's {@link TreeView | view}.
     * Otherwise, it will return `undefined` (because the node has not yet been inserted and is therefore not part of a branch or view).
     *
     * This does not fork a new branch, but rather retrieves the _existing_ branch for the node.
     * To create a new branch, use e.g. {@link TreeBranch.fork | `myBranch.fork()`}.
     */
    branch(node: TreeNode): TreeBranch | undefined;
    /**
     * Construct tree content that is compatible with the field defined by the provided `schema`.
     * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
     * @param data - The data used to construct the field content.
     * @remarks
     * When providing a {@link TreeNodeSchemaClass}, this is the same as invoking its constructor except that an unhydrated node can also be provided.
     * This function exists as a generalization that can be used in other cases as well,
     * such as when `undefined` might be allowed (for an optional field), or when the type should be inferred from the data when more than one type is possible.
     *
     * Like with {@link TreeNodeSchemaClass}'s constructor, it's an error to provide an existing node to this API.
     * For that case, use {@link TreeBeta.clone}.
     * @privateRemarks
     * There should be a way to provide a source for defaulted identifiers, wither via this API or some way to add them to its output later.
     */
    create<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: InsertableField<TSchema>): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;
    /**
     * Less type safe version of {@link TreeAlpha.create}, suitable for importing data.
     * @remarks
     * Due to {@link ConciseTree} relying on type inference from the data, its use is somewhat limited.
     * This does not support {@link ConciseTree|ConciseTrees} with customized handle encodings or using persisted keys.
     * Use "compressed" or "verbose" formats for more flexibility.
     *
     * When using this function,
     * it is recommend to ensure your schema is unambiguous with {@link ITreeConfigurationOptions.preventAmbiguity}.
     * If the schema is ambiguous, consider using {@link TreeAlpha.create} and {@link Unhydrated} nodes where needed,
     * or using {@link TreeAlpha.(importVerbose:1)} and specify all types.
     *
     * Documented (and thus recoverable) error handling/reporting for this is not yet implemented,
     * but for now most invalid inputs will throw a recoverable error.
     */
    importConcise<const TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema>(schema: UnsafeUnknownSchema extends TSchema ? ImplicitFieldSchema : TSchema & ImplicitFieldSchema, data: ConciseTree | undefined): Unhydrated<TSchema extends ImplicitFieldSchema ? TreeFieldFromImplicitField<TSchema> : TreeNode | TreeLeafValue | undefined>;
    /**
     * Construct tree content compatible with a field defined by the provided `schema`.
     * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
     * @param data - The data used to construct the field content. See {@link TreeAlpha.(exportVerbose:1)}.
     * @remarks
     * This overload requires that any {@link @fluidframework/core-interfaces#IFluidHandle|IFluidHandles} are encoded as actual {@link @fluidframework/core-interfaces#IFluidHandle|IFluidHandles} in the input.
     */
    importVerbose<const TSchema extends ImplicitFieldSchema>(schema: TSchema, data: VerboseTree | undefined, options?: Partial<ParseOptions<IFluidHandle>>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
    /**
     * Construct tree content compatible with a field defined by the provided `schema`.
     * @param schema - The schema for what to construct. As this is an {@link ImplicitFieldSchema}, a {@link FieldSchema}, {@link TreeNodeSchema} or {@link AllowedTypes} array can be provided.
     * @param data - The data used to construct the field content. See {@link TreeAlpha.(exportVerbose:2)}.
     *
     * @typeparam THandle - How {@link @fluidframework/core-interfaces#IFluidHandle|IFluidHandles} in the input `data` are encoded.
     * A converter from this encoding to {@link @fluidframework/core-interfaces#IFluidHandle} is required in `options`.
     */
    importVerbose<const TSchema extends ImplicitFieldSchema, THandle>(schema: TSchema, data: VerboseTree<THandle> | undefined, options: ParseOptions<THandle>): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
    /**
     * Same as {@link TreeAlpha.(exportConcise:2)}, except leaves handles as is.
     */
    exportConcise(node: TreeNode | TreeLeafValue, options?: Partial<EncodeOptions<IFluidHandle>>): ConciseTree;
    /**
     * Copy a snapshot of the current version of a TreeNode into a {@link ConciseTree}.
     *
     * @typeparam THandle - How {@link @fluidframework/core-interfaces#IFluidHandle|IFluidHandles} in the output should be encoded.
     * A converter from from {@link @fluidframework/core-interfaces#IFluidHandle} to this format is required in `options`.
     */
    exportConcise<THandle>(node: TreeNode | TreeLeafValue, options: EncodeOptions<THandle>): ConciseTree<THandle>;
    /**
     * Same {@link TreeAlpha.(exportVerbose:2)} except leaves handles as is.
     */
    exportVerbose(node: TreeNode | TreeLeafValue, options?: Partial<EncodeOptions<IFluidHandle>>): VerboseTree;
    /**
     * Copy a snapshot of the current version of a TreeNode into a JSON compatible plain old JavaScript Object.
     * Verbose tree format, with explicit type on every node.
     *
     * @typeparam THandle - How {@link @fluidframework/core-interfaces#IFluidHandle|IFluidHandles} in the output should be encoded.
     * A converter from from {@link @fluidframework/core-interfaces#IFluidHandle} to this format is required in `options`.
     *
     * @remarks
     * There are several cases this may be preferred to {@link TreeAlpha.(exportConcise:2)}:
     *
     * 1. When not using {@link ITreeConfigurationOptions.preventAmbiguity} (or when using `useStableFieldKeys`), `exportConcise` can produce ambiguous data (the type may be unclear on some nodes).
     * `exportVerbose` will always be unambiguous and thus lossless.
     *
     * 2. When the data might be interpreted without access to the exact same view schema. In such cases, the types may be unknowable if not included.
     *
     * 3. When easy access to the type is desired.
     */
    exportVerbose<T>(node: TreeNode | TreeLeafValue, options: EncodeOptions<T>): VerboseTree<T>;
    /**
     * Export the content of the provided `tree` in a compressed JSON compatible format.
     * @remarks
     * If an `idCompressor` is provided, it will be used to compress identifiers and thus will be needed to decompress the data.
     *
     * Always uses "stored" keys.
     * See {@link EncodeOptions.useStoredKeys} for details.
     * @privateRemarks
     * TODO: It is currently not clear how to work with the idCompressors correctly in the package API.
     * Better APIs should probably be provided as there is currently no way to associate an un-hydrated tree with an idCompressor,
     * Nor get the correct idCompressor from a subtree to use when exporting it.
     * Additionally using `createIdCompressor` to make an idCompressor is `@legacy` and thus not intended for use in this API surface.
     * It would probably make more sense if we provided a way to get an idCompressor from the context of a node,
     * which could be optional (and settable if missing) for un0hydrated nodes and required for hydrated ones.
     * Add in a stable public APi for creating idCompressors, and a way to get them from a tree (without view schema), and that should address the anticipated use-cases.
     */
    exportCompressed(tree: TreeNode | TreeLeafValue, options: {
        oldestCompatibleClient: FluidClientVersion;
        idCompressor?: IIdCompressor;
    }): JsonCompatible<IFluidHandle>;
    /**
     * Import data encoded by {@link TreeAlpha.exportCompressed}.
     *
     * @param schema - Schema with which the data must be compatible. This compatibility is not verified and must be ensured by the caller.
     * @param compressedData - Data compressed by {@link TreeAlpha.exportCompressed}.
     * @param options - If {@link TreeAlpha.exportCompressed} was given an `idCompressor`, it must be provided here.
     *
     * @remarks
     * If the data could have been encoded with a different schema, consider encoding the schema along side it using {@link extractPersistedSchema} and loading the data using {@link independentView}.
     *
     * @privateRemarks
     * This API could be improved:
     *
     * 1. It could validate that the schema is compatible, and return or throw an error in the invalid case (maybe add a "try" version).
     * 2. A "try" version of this could return an error if the data isn't in a supported format (as determined by version and/or JasonValidator).
     * 3. Requiring the caller provide a JsonValidator isn't the most friendly API. It might be practical to provide a default.
     */
    importCompressed<const TSchema extends ImplicitFieldSchema>(schema: TSchema, compressedData: JsonCompatible<IFluidHandle>, options: {
        idCompressor?: IIdCompressor;
    } & ICodecOptions): Unhydrated<TreeFieldFromImplicitField<TSchema>>;
};
//# sourceMappingURL=treeApiAlpha.d.ts.map