/*!
 * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
 * Licensed under the MIT License.
 */
import type { IFluidHandle } from "@fluidframework/core-interfaces";
import { type FieldKey, type ITreeCursor, type TreeNodeSchemaIdentifier, type TreeNodeStoredSchema, type TreeTypeSet } from "../../core/index.js";
import type { TreeNodeSchema, TreeLeafValue } from "../core/index.js";
/**
 * Options for how to interpret or encode a tree when schema information is available.
 * @alpha
 */
export interface TreeEncodingOptions {
    /**
     * If true, use the stored keys of object nodes.
     * If false, use the property keys.
     * @remarks
     * Has no effect on {@link NodeKind}s other than {@link NodeKind.Object}.
     *
     * {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields|Unknown optional field} will be omitted when using property keys.
     * @defaultValue false.
     * @privateRemarks
     * TODO AB#43548:
     * Replace this with an enum that provides three options:
     * - `usePropertyKeys`: use property keys. Supported for import and export.
     * - `allStoredKeys`: use stored keys, and include unknown optional fields. Supported for export only, at least for the short term.
     * - `knownStoredKeys`: use stored keys but do not include unknown optional fields. Supported for import and export.
     */
    readonly useStoredKeys?: boolean;
}
/**
 * Options for how to interpret a `ConciseTree<TCustom>` without relying on schema.
 */
export interface SchemalessParseOptions {
    /**
     * Converts stored keys into whatever key the tree is using in its encoding.
     */
    keyConverter?: {
        parse(type: string, inputKey: string): FieldKey;
        encode(type: string, key: FieldKey): string;
    };
}
/**
 * Tree representation with fields as properties and customized handle and child representations.
 */
export type CustomTree<TChild> = CustomTreeNode<TChild> | CustomTreeValue;
/**
 * TreeLeafValue except the handle type is customized.
 */
export type CustomTreeValue = TreeLeafValue;
/**
 * Tree node representation with fields as properties and customized child representation.
 */
export type CustomTreeNode<TChild> = TChild[] | {
    [key: string]: TChild;
};
/**
 * Builds an {@link CustomTree} from a cursor in Nodes mode.
 *
 * @param reader - The cursor to read from.
 * @param options - Options for how to interpret the tree.
 * @param storedSchema - Schema which the cursor must comply with.
 * Must be be possible to map to a view schema (mainly that sequences can only occur in the special ArrayNode pattern).
 * Must include even unknown optional fields.
 * @param schema - View schema used to derive the property keys for fields when `options` selects them via {@link TreeEncodingOptions.useStoredKeys}.
 * @param childHandler - Function to handle children of the cursor.
 *
 * @remarks
 * This can handle unknown optional fields only because they are included in the `storedSchema` and `schema` is only needed when using property keys, which also skips unknown optional fields.
 */
export declare function customFromCursor<TChild>(reader: ITreeCursor, options: Required<TreeEncodingOptions>, storedSchema: ReadonlyMap<string, TreeNodeStoredSchema>, schema: ReadonlyMap<string, TreeNodeSchema>, childHandler: (reader: ITreeCursor, options: Required<TreeEncodingOptions>, storedSchema: ReadonlyMap<string, TreeNodeStoredSchema>, schema: ReadonlyMap<string, TreeNodeSchema>) => TChild): CustomTree<TChild>;
/**
 * Builds an {@link CustomTree} from a cursor in Nodes mode.
 * @remarks
 * Uses stored keys and stored schema.
 */
export declare function customFromCursorStored<TChild>(reader: ITreeCursor, schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>, childHandler: (reader: ITreeCursor, schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>) => TChild): CustomTree<TChild>;
/**
 * Checks if `schema` could correspond to a simple-tree array node.
 * If it is an array schema, returns the allowed types for the array field.
 * Otherwise returns `undefined`.
 * @remarks
 * If the schema was defined by the public API, this will be accurate since there is no way to define an object node with a sequence field.
 */
export declare function tryStoredSchemaAsArray(schema: TreeNodeStoredSchema): TreeTypeSet | undefined;
/**
 * Options for how to transcode handles.
 * @remarks
 * Can be applied using {@link replaceHandles}.
 * @alpha
 */
export type HandleConverter<TCustom> = (data: IFluidHandle) => TCustom;
/**
 * Clones tree, replacing any handles.
 * @remarks
 * This can be useful converting data containing handles to JSON compatible formats,
 * or just asserting that data does not contain handles.
 *
 * Reversing this replacement depends on how the replacer encodes handles, and can often be impossible if the replacer
 * does not have all the necessary context to restore the handles
 * (e.g. if the handles are something insufficiently descriptive,
 * if data referenced by the handle got garbage collected,
 * if the encoded form of the handle can't be differentiated from other data,
 * or the replacer doesn't have access to the correct Fluid container to to restore them from).
 *
 * Code attempting to reverse this replacement may want to use {@link cloneWithReplacements}.
 * @alpha
 */
export declare function replaceHandles<T>(tree: unknown, replacer: HandleConverter<T>): unknown;
/**
 * Throws a `UsageError` indicating that a type is unknown in the current context.
 */
export declare function unknownTypeError(type: string): never;
//# sourceMappingURL=customTree.d.ts.map