@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/src/codec/codec.ts

@@ -0,0 +1,346 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { bufferToString, IsoBuffer } from "@fluid-internal/client-utils";
+import { assert } from "@fluidframework/core-utils";
+import type { Static, TAnySchema, TSchema } from "@sinclair/typebox";
+import { fail, JsonCompatibleReadOnly } from "../util";
+
+/**
+ * Translates decoded data to encoded data.
+ * @remarks Typically paired with an {@link IEncoder}.
+ */
+export interface IEncoder<TDecoded, TEncoded> {
+	/**
+	 * Encodes `obj` into some encoded format.
+	 */
+	encode(obj: TDecoded): TEncoded;
+}
+
+/**
+ * Translates encoded data to decoded data.
+ * @remarks Typically paired with an {@link IEncoder}.
+ */
+export interface IDecoder<TDecoded, TEncoded> {
+	/**
+	 * Decodes `obj` from some encoded format.
+	 */
+	decode(obj: TEncoded): TDecoded;
+}
+
+/**
+ * Validates data complies with some particular schema.
+ * Implementations are typically created by a {@link JsonValidator}.
+ * @internal
+ */
+export interface SchemaValidationFunction<Schema extends TSchema> {
+	/**
+	 * @returns Whether the data matches a schema.
+	 */
+	check(data: unknown): data is Static<Schema>;
+}
+
+/**
+ * JSON schema validator compliant with draft 6 schema. See https://json-schema.org.
+ * @internal
+ */
+export interface JsonValidator {
+	/**
+	 * Compiles the provided JSON schema into a validator for that schema.
+	 * @param schema - A valid draft 6 JSON schema
+	 * @remarks IFluidHandles--which have circular property references--are used in various places in SharedTree's persisted
+	 * format. Handles should only be contained in sections of data which are validated against the empty schema `{}`
+	 * (see https://datatracker.ietf.org/doc/html/draft-wright-json-schema-01#section-4.4).
+	 *
+	 * Implementations of `JsonValidator` must therefore tolerate these values, despite the input not being valid JSON.
+	 */
+	compile<Schema extends TSchema>(schema: Schema): SchemaValidationFunction<Schema>;
+}
+
+/**
+ * Options relating to handling of persisted data.
+ * @internal
+ */
+export interface ICodecOptions {
+	/**
+	 * {@link JsonValidator} which SharedTree uses to validate persisted data it reads & writes
+	 * matches the expected encoded format (i.e. the wire format for ops and summaries).
+	 *
+	 * See {@link noopValidator} and {@link typeboxValidator} for out-of-the-box implementations.
+	 *
+	 * This option is not "on-by-default" because JSON schema validation comes with a small but noticeable
+	 * runtime performance cost, and popular schema validation libraries have relatively large bundle size.
+	 *
+	 * SharedTree users are still encouraged to use a non-trivial validator (i.e. not `noopValidator`)
+	 * whenever reasonable: it gives better fail-fast behavior when unexpected encoded data is found,
+	 * which reduces the risk of unrecoverable data corruption.
+	 */
+	readonly jsonValidator: JsonValidator;
+}
+
+/**
+ * @remarks `TEncoded` should always be valid Json (i.e. not contain functions), but due to TypeScript's handling
+ * of index signatures and `JsonCompatibleReadOnly`'s index signature in the Json object case, specifying this as a
+ * type-system level constraint makes code that uses this interface more difficult to write.
+ *
+ * If provided, `TValidate` allows the input type passed to `decode` to be different than `TEncoded`.
+ * This is useful when, for example, the type being decoded is `unknown` and must be validated to be a `TEncoded` before being decoded to a `TDecoded`.
+ */
+export interface IJsonCodec<TDecoded, TEncoded = JsonCompatibleReadOnly, TValidate = TEncoded>
+	extends IEncoder<TDecoded, TEncoded>,
+		IDecoder<TDecoded, TValidate> {
+	encodedSchema?: TAnySchema;
+}
+
+/**
+ * TODO: properly integrate context
+ */
+export type IJsonCodecWithContext<TDecoded, TEncoded, TValidate, TContext> = (
+	context: TContext,
+) => IJsonCodec<TDecoded, TEncoded, TValidate>;
+
+/**
+ * @remarks TODO: We might consider using DataView or some kind of writer instead of IsoBuffer.
+ */
+export interface IBinaryCodec<TDecoded>
+	extends IEncoder<TDecoded, IsoBuffer>,
+		IDecoder<TDecoded, IsoBuffer> {}
+
+/**
+ * Contains knowledge of how to encode some in-memory type into JSON and binary formats,
+ * as well as how to decode those representations.
+ *
+ * @remarks Codecs are typically used in shared-tree to convert data into some persisted format.
+ * For this common use case, any format for encoding that was ever actually used needs to
+ * be supported for decoding in all future code versions.
+ *
+ * Using an {@link ICodecFamily} is the recommended strategy for managing this support, keeping in
+ * mind evolution of encodings over time.
+ */
+export interface IMultiFormatCodec<
+	TDecoded,
+	TJsonEncoded extends JsonCompatibleReadOnly = JsonCompatibleReadOnly,
+	TJsonValidate = TJsonEncoded,
+> {
+	json: IJsonCodec<TDecoded, TJsonEncoded, TJsonValidate>;
+	binary: IBinaryCodec<TDecoded>;
+
+	/** Ensures multi-format codecs cannot also be single-format codecs. */
+	encode?: never;
+	/** Ensures multi-format codecs cannot also be single-format codecs. */
+	decode?: never;
+}
+
+/**
+ * Represents a family of codecs that can be used to encode and decode data in different formats.
+ * The family is identified by a format version, which is typically used to select the codec to use.
+ *
+ * Separating codecs into families rather than having a single codec support multiple versions (i.e. currying
+ * the `formatVersion` parameter)
+ * allows avoiding some duplicate work at encode/decode time, since the vast majority of document usage will not
+ * involve mixed format versions.
+ */
+export interface ICodecFamily<TDecoded> {
+	/**
+	 * @returns a codec that can be used to encode and decode data in the specified format.
+	 * @throws - if the format version is not supported by this family.
+	 * @remarks Implementations should typically emit telemetry (either indirectly by throwing a well-known error with
+	 * logged properties or directly using some logger) when a format version is requested that is not supported.
+	 * This ensures that applications can diagnose compatibility issues.
+	 */
+	resolve(formatVersion: number): IMultiFormatCodec<TDecoded>;
+
+	/**
+	 * @returns an iterable of all format versions supported by this family.
+	 */
+	getSupportedFormats(): Iterable<number>;
+}
+
+/**
+ * Creates a codec family from a registry of codecs.
+ * Any codec that is not a {@link IMultiFormatCodec} will be wrapped with a default binary encoding.
+ */
+export function makeCodecFamily<TDecoded>(
+	registry: Iterable<
+		[formatVersion: number, codec: IMultiFormatCodec<TDecoded> | IJsonCodec<TDecoded>]
+	>,
+): ICodecFamily<TDecoded> {
+	const codecs: Map<number, IMultiFormatCodec<TDecoded>> = new Map();
+	for (const [formatVersion, codec] of registry) {
+		if (codecs.has(formatVersion)) {
+			fail("Duplicate codecs specified.");
+		}
+		codecs.set(formatVersion, ensureBinaryEncoding(codec));
+	}
+
+	return {
+		resolve(formatVersion: number) {
+			const codec = codecs.get(formatVersion);
+			assert(codec !== undefined, 0x5e6 /* Requested coded for unsupported format. */);
+			return codec;
+		},
+		getSupportedFormats() {
+			return codecs.keys();
+		},
+	};
+}
+
+class DefaultBinaryCodec<TDecoded> implements IBinaryCodec<TDecoded> {
+	public constructor(private readonly jsonCodec: IJsonCodec<TDecoded>) {}
+
+	public encode(change: TDecoded): IsoBuffer {
+		const jsonable = this.jsonCodec.encode(change);
+		const json = JSON.stringify(jsonable);
+		return IsoBuffer.from(json);
+	}
+
+	public decode(change: IsoBuffer): TDecoded {
+		const json = bufferToString(change, "utf8");
+		const jsonable = JSON.parse(json);
+		return this.jsonCodec.decode(jsonable);
+	}
+}
+
+function isJsonCodec<TDecoded>(
+	codec: IMultiFormatCodec<TDecoded> | IJsonCodec<TDecoded>,
+): codec is IJsonCodec<TDecoded> {
+	return typeof codec.encode === "function" && typeof codec.decode === "function";
+}
+
+/**
+ * Constructs a {@link IMultiFormatCodec} from a `IJsonCodec` using a generic binary encoding that simply writes
+ * the json representation of the object to a buffer.
+ */
+export function withDefaultBinaryEncoding<TDecoded>(
+	jsonCodec: IJsonCodec<TDecoded>,
+): IMultiFormatCodec<TDecoded> {
+	return {
+		json: jsonCodec,
+		binary: new DefaultBinaryCodec(jsonCodec),
+	};
+}
+
+/**
+ * Ensures that the provided single or multi-format codec has a binary encoding.
+ * Adapts the json encoding using {@link withDefaultBinaryEncoding} if necessary.
+ */
+export function ensureBinaryEncoding<TDecoded>(
+	codec: IMultiFormatCodec<TDecoded> | IJsonCodec<TDecoded>,
+): IMultiFormatCodec<TDecoded> {
+	return isJsonCodec(codec) ? withDefaultBinaryEncoding(codec) : codec;
+}
+
+/**
+ * Codec for objects which carry no information.
+ */
+export const unitCodec: IMultiFormatCodec<0> = {
+	json: {
+		encode: () => 0,
+		decode: () => 0,
+	},
+	binary: {
+		encode: () => IsoBuffer.from(""),
+		decode: () => 0,
+	},
+};
+
+/**
+ * Creates a json codec for objects which are just a json compatible value
+ * and can be serialized as-is.
+ *
+ * This type of encoding is only appropriate if the persisted type (which should be defined in a persisted format file)
+ * happens to be convenient for in-memory usage as well.
+ *
+ * @remarks Beware that this API can cause accidental extraneous data in the persisted format.
+ * Consider the following example:
+ * ```typescript
+ * interface MyPersistedType {
+ *     foo: string;
+ *     id: number;
+ * }
+ * const MyPersistedType = Type.Object({
+ *     foo: Type.String(),
+ *     id: Type.Number()
+ * });
+ *
+ * const codec = makeValueCodec<MyPersistedType>();
+ *
+ * // Later, in some other file...
+ * interface SomeInMemoryType extends MyPersistedType {
+ *     someOtherProperty: string;
+ * }
+ *
+ * const someInMemoryObject: SomeInMemoryType = {
+ *     foo:	"bar",
+ *     id: 0,
+ *     someOtherProperty: "this shouldn't be here and ends up in the persisted format"
+ * }
+ *
+ * const encoded = codec.encode(someInMemoryObject);
+ * ```
+ * This all typechecks and passes at runtime, but the persisted format will contain the extraneous
+ * `someOtherProperty` field.
+ * It's unlikely a real-life example would be this simple, but the principle is the same.
+ *
+ * This issue can be avoided by using JSON schema that doesn't accept additional properties:
+ *
+ * ```typescript
+ * const MyPersistedType = Type.Object({
+ *     foo: Type.String(),
+ *     id: Type.Number()
+ * }, {
+ *     additionalProperties: false
+ * });
+ * ```
+ */
+export function makeValueCodec<Schema extends TSchema>(
+	schema: Schema,
+	validator?: JsonValidator,
+): IJsonCodec<Static<Schema>> {
+	return withSchemaValidation(
+		schema,
+		{
+			encode: (x: Static<Schema>) => x as unknown as JsonCompatibleReadOnly,
+			decode: (x: JsonCompatibleReadOnly) => x as unknown as Static<Schema>,
+		},
+		validator,
+	);
+}
+
+/**
+ * Wraps a codec with JSON schema validation for its encoded type.
+ * @returns An {@link IJsonCodec} which validates the data it encodes and decodes matches the provided schema.
+ */
+export function withSchemaValidation<
+	TInMemoryFormat,
+	EncodedSchema extends TSchema,
+	TEncodedFormat = JsonCompatibleReadOnly,
+	TValidate = TEncodedFormat,
+>(
+	schema: EncodedSchema,
+	codec: IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate>,
+	validator?: JsonValidator,
+): IJsonCodec<TInMemoryFormat, TEncodedFormat, TValidate> {
+	if (!validator) {
+		return codec;
+	}
+	const compiledFormat = validator.compile(schema);
+	return {
+		encode: (obj: TInMemoryFormat) => {
+			const encoded = codec.encode(obj);
+			if (!compiledFormat.check(encoded)) {
+				fail("Encoded schema should validate");
+			}
+			return encoded;
+		},
+		decode: (encoded: TValidate) => {
+			if (!compiledFormat.check(encoded)) {
+				fail("Encoded schema should validate");
+			}
+			// TODO: would be nice to provide a more specific validate type to the inner codec than the outer one gets.
+			return codec.decode(encoded);
+		},
+	};
+}

package/src/codec/discriminatedUnions.ts

@@ -0,0 +1,114 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ObjectOptions } from "@sinclair/typebox";
+import { assert } from "@fluidframework/core-utils";
+import { _InlineTrick, fail, objectToMap } from "../util";
+
+/**
+ * This module contains utilities for an encoding of a discriminated union that is efficient to validate using
+ * a JSON schema validator.
+ * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
+ */
+
+/**
+ * Options to configure a TypeBox schema as a discriminated union that is simple to validate data against.
+ *
+ * See {@link DiscriminatedUnionDispatcher} for more information on this pattern.
+ */
+export const unionOptions: ObjectOptions = {
+	additionalProperties: false,
+	minProperties: 1,
+	maxProperties: 1,
+};
+
+/**
+ * Applies a function to the content of a [discriminated union](https://en.wikipedia.org/wiki/Tagged_union)
+ * where the function to apply depends on which value from the union it holds.
+ *
+ * This uses a rather non-standard encoding of the union where it is an object with many differently named optional fields,
+ * and which of the fields is populated determines the content type.
+ * This union encoding has the advantage that schema validation (such as that implemented by TypeBox) can validate the data efficiently.
+ * Other encodings--such as using an untagged union, then tagging the content types with a marker enum--require the schema validator to disambiguate the union members.
+ * Most JSON validator implementations fail to recognize the marker enum determines which component of the discriminated union the data must be,
+ * and end up checking against all candidate members of the union.
+ *
+ * @example
+ *
+ * The following union:
+ * ```typescript
+ * type Operation = Add | Subtract | Multiply | Divide;
+ *
+ * interface BinaryOperation {
+ *     readonly left: number;
+ *     readonly right: number;
+ * }
+ *
+ * interface Add extends BinaryOperation {
+ *     readonly type: "add";
+ * }
+ *
+ * interface Subtract extends BinaryOperation {
+ *     readonly type: "subtract";
+ * }
+ *
+ * interface Multiply extends BinaryOperation {
+ *     readonly type: "multiply";
+ * }
+ *
+ * interface Divide extends BinaryOperation {
+ *     readonly type: "divide";
+ * }
+ *
+ * ```
+ * Would be encoded using this strategy as:
+ * ```typescript
+ * interface EncodedBinaryOperation {
+ *     readonly left: number;
+ *     readonly right: number;
+ * }
+ *
+ * interface EncodedOperation {
+ *     add?: EncodedBinaryOperation;
+ *     subtract?: EncodedBinaryOperation;
+ *     multiply?: EncodedBinaryOperation;
+ *     divide?: EncodedBinaryOperation;
+ * }
+ * ```
+ * where only a single property of `EncodedOperation` is populated for a given encoded value.
+ */
+export class DiscriminatedUnionDispatcher<TUnion extends object, TArgs extends any[], TResult> {
+	private readonly library: ReadonlyMap<
+		keyof TUnion,
+		(value: unknown, ...args: TArgs) => TResult
+	>;
+
+	public constructor(
+		library: [
+			{
+				readonly [Property in keyof TUnion]-?: (
+					value: Required<TUnion>[Property],
+					...args: TArgs
+				) => TResult;
+			},
+		][_InlineTrick],
+	) {
+		this.library = objectToMap(
+			library as Record<keyof TUnion, (value: unknown, ...args: TArgs) => TResult>,
+		);
+	}
+
+	public dispatch(union: TUnion, ...args: TArgs): TResult {
+		const keys = Reflect.ownKeys(union);
+		assert(
+			keys.length === 1,
+			0x733 /* discriminated union type should have exactly one member */,
+		);
+		const key: keyof TUnion = keys[0] as keyof TUnion;
+		const value = union[key];
+		const factory = this.library.get(key) ?? fail("missing function for union member");
+		const result = factory(value, ...args);
+		return result;
+	}
+}

package/src/codec/index.ts

@@ -0,0 +1,23 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export {
+	IBinaryCodec,
+	ICodecFamily,
+	ICodecOptions,
+	IDecoder,
+	IEncoder,
+	IJsonCodec,
+	IMultiFormatCodec,
+	JsonValidator,
+	makeCodecFamily,
+	makeValueCodec,
+	SchemaValidationFunction,
+	unitCodec,
+	withDefaultBinaryEncoding,
+	withSchemaValidation,
+	IJsonCodecWithContext,
+} from "./codec";
+export { DiscriminatedUnionDispatcher, unionOptions } from "./discriminatedUnions";
+export { noopValidator } from "./noopValidator";

package/src/codec/noopValidator.ts

@@ -0,0 +1,17 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { Static, TSchema } from "@sinclair/typebox";
+import { JsonValidator } from "./codec";
+
+/**
+ * A {@link JsonValidator} implementation which performs no validation and accepts all data as valid.
+ * @privateRemarks Having this as an option unifies opting out of validation with selection of
+ * validators, simplifying code performing validation.
+ * @internal
+ */
+export const noopValidator: JsonValidator = {
+	compile: <Schema extends TSchema>() => ({ check: (data): data is Static<Schema> => true }),
+};

package/src/core/README.md

@@ -0,0 +1,9 @@
+# core
+
+Reexports the contents of the "core" libraries.
+This is the set of libraries on which [shared-tree-core](../shared-tree-core/README.md) depends.
+
+This mainly exists to simplify imports for code like [feature-libraries](../feature-libraries/README.md) and [shared-tree](../shared-tree/README.md).
+
+The core libraries could be nested inside this directory (as is done with [feature-libraries](../feature-libraries/README.md));
+for now this was avoided to keep the nesting levels lower and avoid having to move a lot of code.

package/src/core/change-family/README.md

@@ -0,0 +1,14 @@
+# change-family
+
+Abstraction for change families.
+
+A change family is a collection of types of changes which can be used within a document, and support for building, serializing and rebasing them over each-other.
+This includes things like policies for how to edit sequences, clearing optional fields, swapping trees, updating counters, schema editing etc.
+
+A change family has to handle all its supported changes identically between all clients, and across all versions.
+Support for new kinds of changes can be added, but updating applications to use the new changes must be done carefully to avoid breaking old clients.
+
+Applications that only have ephemeral sessions and never persist documents with [trailing ops](../../../../README.md#trailing-ops) may be able to relax this constraint somewhat.
+
+A change family can even include domain or application specific change types,
+though those are typically instead decomposed into simpler changes to avoid the above stability constraint for such high level concepts.

package/src/core/change-family/changeFamily.ts

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ICodecFamily } from "../../codec";
+import { ChangeRebaser } from "../rebase";
+
+export interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {
+	buildEditor(changeReceiver: (change: TChange) => void): TEditor;
+
+	readonly rebaser: ChangeRebaser<TChange>;
+	readonly codecs: ICodecFamily<TChange>;
+}
+
+export interface ChangeFamilyEditor {
+	/**
+	 * Must be called when a new transaction starts.
+	 *
+	 * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.
+	 *
+	 * For each call to this function, a matching call to `exitTransaction` must be made at a later time.
+	 * Can be called repeatedly to indicate the start of nesting transactions.
+	 */
+	enterTransaction(): void;
+
+	/**
+	 * Must be called when a transaction ends.
+	 *
+	 * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.
+	 *
+	 * For each call to this function, a matching call to `enterTransaction` must be made at an earlier time.
+	 * Can be called repeatedly to indicate the end of nesting transactions.
+	 */
+	exitTransaction(): void;
+}

package/src/core/change-family/editBuilder.ts

@@ -0,0 +1,25 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ChangeFamily, ChangeFamilyEditor } from "./changeFamily";
+
+export abstract class EditBuilder<TChange> implements ChangeFamilyEditor {
+	public constructor(
+		protected readonly changeFamily: ChangeFamily<ChangeFamilyEditor, TChange>,
+		private readonly changeReceiver: (change: TChange) => void,
+	) {}
+
+	/**
+	 * Subclasses add editing methods which call this with their generated edits.
+	 *
+	 * @sealed
+	 */
+	protected applyChange(change: TChange): void {
+		this.changeReceiver(change);
+	}
+
+	public enterTransaction(): void {}
+	public exitTransaction(): void {}
+}

package/src/core/change-family/index.ts

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { ChangeFamily, ChangeFamilyEditor } from "./changeFamily";
+export { EditBuilder } from "./editBuilder";

package/src/core/forest/README.md

@@ -0,0 +1,11 @@
+# forest
+
+An abstraction for representing, editing, and observing collections of trees.
+Forest is focused on allowing the implementation to efficiently be viewed/read and apply deltas,
+while only keeping a subset of the data in memory.
+
+Forest is not supposed to provide a friendly API (See [editable-tree](../../feature-libraries/editable-tree/README.md) for that).
+Instead, forest provides an abstraction that enables implementing nicer APIs on-top of it as a separate layer while abstracting the actual storage representation.
+This should allow forest implementations to implement compression without having to modify the forest API or its users.
+
+As the system matures more, and internal forest formats and its users are more settled, optional fast paths for accessing compressed data directly can be added when worth-while for performance reasons.

package/src/core/forest/editableForest.ts

@@ -0,0 +1,81 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils";
+import { FieldKey } from "../schema-stored";
+import {
+	DetachedField,
+	Anchor,
+	ITreeCursorSynchronous,
+	DeltaVisitor,
+	applyDelta,
+	makeDetachedFieldIndex,
+	deltaForRootInitialization,
+	DeltaRoot,
+} from "../tree";
+import { IForestSubscription, ITreeSubscriptionCursor } from "./forest";
+
+/**
+ * Editing APIs.
+ * @internal
+ */
+export interface IEditableForest extends IForestSubscription {
+	/**
+	 * Provides a visitor that can be used to mutate the forest.
+	 *
+	 * @returns a visitor that can be used to mutate the forest.
+	 *
+	 * @remarks
+	 * Mutating the forest does NOT update anchors.
+	 * The visitor must be released after use by calling {@link DeltaVisitor.free} on it.
+	 * It is invalid to acquire a visitor without releasing the previous one.
+	 */
+	acquireVisitor(): DeltaVisitor;
+}
+
+/**
+ * Sets the contents of the forest via delta.
+ * Requires the fores starts empty.
+ *
+ * @remarks
+ * This does not perform an edit: it updates the forest content as if there was an edit that did that.
+ */
+export function initializeForest(
+	forest: IEditableForest,
+	content: readonly ITreeCursorSynchronous[],
+): void {
+	assert(forest.isEmpty, 0x747 /* forest must be empty */);
+	const delta: DeltaRoot = deltaForRootInitialization(content);
+	applyDelta(delta, forest, makeDetachedFieldIndex("init"));
+}
+
+// TODO: Types below here may be useful for input into edit building APIs, but are no longer used here directly.
+
+/**
+ * Ways to refer to a node in an IEditableForest.
+ * @internal
+ */
+export type ForestLocation = ITreeSubscriptionCursor | Anchor;
+
+/**
+ * @internal
+ */
+export interface TreeLocation {
+	readonly range: FieldLocation | DetachedField;
+	readonly index: number;
+}
+
+export function isFieldLocation(range: FieldLocation | DetachedField): range is FieldLocation {
+	return typeof range === "object";
+}
+
+/**
+ * Location of a field within a tree that is not a detached/root field.
+ * @internal
+ */
+export interface FieldLocation {
+	readonly key: FieldKey;
+	readonly parent: ForestLocation;
+}