@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/src/core/tree/visitorUtils.ts

@@ -0,0 +1,106 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IdAllocator, idAllocatorFromMaxId } from "../../util";
+import { FieldKey } from "../schema-stored";
+import { ICodecOptions } from "../../codec";
+import { PlaceIndex, Range } from "./pathTree";
+import { ForestRootId, DetachedFieldIndex } from "./detachedFieldIndex";
+import { DeltaVisitor, visitDelta } from "./visitDelta";
+import { ProtoNodes, Root } from "./delta";
+
+export function makeDetachedFieldIndex(
+	prefix: string = "Temp",
+	options?: ICodecOptions,
+): DetachedFieldIndex {
+	return new DetachedFieldIndex(
+		prefix,
+		idAllocatorFromMaxId() as IdAllocator<ForestRootId>,
+		options,
+	);
+}
+
+export function applyDelta(
+	delta: Root,
+	deltaProcessor: { acquireVisitor: () => DeltaVisitor },
+	detachedFieldIndex: DetachedFieldIndex,
+): void {
+	const visitor = deltaProcessor.acquireVisitor();
+	visitDelta(delta, visitor, detachedFieldIndex);
+	visitor.free();
+}
+
+export function announceDelta(
+	delta: Root,
+	deltaProcessor: { acquireVisitor: () => DeltaVisitor & AnnouncedVisitor },
+	detachedFieldIndex: DetachedFieldIndex,
+): void {
+	const visitor = deltaProcessor.acquireVisitor();
+	visitDelta(delta, combineVisitors([visitor], [visitor]), detachedFieldIndex);
+	visitor.free();
+}
+
+export function combineVisitors(
+	visitors: readonly DeltaVisitor[],
+	announceVisitors: readonly AnnouncedVisitor[] = [],
+): DeltaVisitor {
+	return {
+		free: () => visitors.forEach((v) => v.free()),
+		create: (...args) => {
+			visitors.forEach((v) => v.create(...args));
+			announceVisitors.forEach((v) => v.afterCreate(...args));
+		},
+		destroy: (...args) => {
+			announceVisitors.forEach((v) => v.beforeDestroy(...args));
+			visitors.forEach((v) => v.destroy(...args));
+		},
+		attach: (source: FieldKey, count: number, destination: PlaceIndex) => {
+			announceVisitors.forEach((v) => v.beforeAttach(source, count, destination));
+			visitors.forEach((v) => v.attach(source, count, destination));
+			announceVisitors.forEach((v) =>
+				v.afterAttach(source, { start: destination, end: destination + count }),
+			);
+		},
+		detach: (source: Range, destination: FieldKey) => {
+			announceVisitors.forEach((v) => v.beforeDetach(source, destination));
+			visitors.forEach((v) => v.detach(source, destination));
+			announceVisitors.forEach((v) =>
+				v.afterDetach(source.start, source.end - source.start, destination),
+			);
+		},
+		replace: (newContent: FieldKey, oldContent: Range, oldContentDestination: FieldKey) => {
+			announceVisitors.forEach((v) =>
+				v.beforeReplace(newContent, oldContent, oldContentDestination),
+			);
+			visitors.forEach((v) => v.replace(newContent, oldContent, oldContentDestination));
+			announceVisitors.forEach((v) =>
+				v.afterReplace(newContent, oldContent, oldContentDestination),
+			);
+		},
+		enterNode: (...args) => visitors.forEach((v) => v.enterNode(...args)),
+		exitNode: (...args) => visitors.forEach((v) => v.exitNode(...args)),
+		enterField: (...args) => visitors.forEach((v) => v.enterField(...args)),
+		exitField: (...args) => visitors.forEach((v) => v.exitField(...args)),
+	};
+}
+
+/**
+ * Visitor that is notified of changes before, after, and when changes are made.
+ * Must be freed after use.
+ * @internal
+ */
+export interface AnnouncedVisitor {
+	/**
+	 * A hook that is called after all nodes have been created.
+	 */
+	afterCreate(content: ProtoNodes, destination: FieldKey): void;
+	beforeDestroy(field: FieldKey, count: number): void;
+	beforeAttach(source: FieldKey, count: number, destination: PlaceIndex): void;
+	afterAttach(source: FieldKey, destination: Range): void;
+	beforeDetach(source: Range, destination: FieldKey): void;
+	afterDetach(source: PlaceIndex, count: number, destination: FieldKey): void;
+	beforeReplace(newContent: FieldKey, oldContent: Range, oldContentDestination: FieldKey): void;
+	afterReplace(newContentSource: FieldKey, newContent: Range, oldContent: FieldKey): void;
+}

package/src/domains/README.md

@@ -0,0 +1,6 @@
+# domains
+
+A collection of domain libraries.
+
+Domain libraries collect together code related to a particular content type or related sets of content types (aka a domain).
+These typically include schema, as well as an specialized code that works with objects that are related to those schema.

package/src/domains/fence.json

@@ -0,0 +1,5 @@
+{
+	"tags": ["domains"],
+	"exports": ["index"],
+	"imports": ["util", "core", "feature-libraries"]
+}

package/src/domains/index.ts

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { SchemaBuilder } from "./schemaBuilder";
+export {
+	cursorToJsonObject,
+	jsonArray,
+	jsonObject,
+	jsonRoot,
+	jsonSchema,
+	singleJsonCursor,
+} from "./json";
+
+export { nodeKeyField, nodeKeySchema, nodeKeyTreeSchema } from "./nodeKey";
+
+export { leaf } from "./leafDomain";

package/src/domains/json/fence.json

@@ -0,0 +1,5 @@
+{
+	"tags": ["domains-json"],
+	"exports": ["index"],
+	"imports": ["util", "core", "feature-libraries", "domains"]
+}

package/src/domains/json/index.ts

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { singleJsonCursor, cursorToJsonObject } from "./jsonCursor";
+export { jsonSchema, jsonObject, jsonArray, jsonRoot } from "./jsonDomainSchema";

package/src/domains/json/jsonCursor.ts

@@ -0,0 +1,137 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils";
+import {
+	ITreeCursor,
+	EmptyKey,
+	FieldKey,
+	mapCursorField,
+	mapCursorFields,
+	ITreeCursorSynchronous,
+} from "../../core";
+import { JsonCompatible } from "../../util";
+import { CursorAdapter, isFluidHandle, stackTreeNodeCursor } from "../../feature-libraries";
+import { leaf } from "../leafDomain";
+import { jsonArray, jsonObject } from "./jsonDomainSchema";
+
+const adapter: CursorAdapter<JsonCompatible> = {
+	value: (node: JsonCompatible) =>
+		node !== null && typeof node === "object"
+			? undefined // arrays and objects have no defined value
+			: node, // null, boolean, numbers, and strings are their own values
+	type: (node: JsonCompatible) => {
+		const type = typeof node;
+
+		switch (type) {
+			case "number":
+				return leaf.number.name;
+			case "string":
+				return leaf.string.name;
+			case "boolean":
+				return leaf.boolean.name;
+			default:
+				if (node === null) {
+					return leaf.null.name;
+				} else if (Array.isArray(node)) {
+					return jsonArray.name;
+				} else {
+					return jsonObject.name;
+				}
+		}
+	},
+	keysFromNode: (node: JsonCompatible): readonly FieldKey[] => {
+		switch (typeof node) {
+			case "object":
+				if (node === null) {
+					return [];
+				} else if (Array.isArray(node)) {
+					return node.length === 0 ? [] : [EmptyKey];
+				} else {
+					return Object.keys(node) as FieldKey[];
+				}
+			default:
+				return [];
+		}
+	},
+	getFieldFromNode: (node: JsonCompatible, key: FieldKey): readonly JsonCompatible[] => {
+		// Object.prototype.hasOwnProperty can return true for strings (ex: with key "0"), so we have to filter them out.
+		// Rather than just special casing strings, we can handle them with an early return for all primitives.
+		if (typeof node !== "object") {
+			return [];
+		}
+
+		if (node === null) {
+			return [];
+		}
+
+		if (Array.isArray(node)) {
+			return key === EmptyKey ? node : [];
+		}
+
+		if (Object.prototype.hasOwnProperty.call(node, key)) {
+			const field = node[key];
+			assert(
+				field !== undefined,
+				0x41e /* explicit undefined fields should not be preserved in JSON */,
+			);
+			return [field];
+		}
+
+		return [];
+	},
+};
+
+/**
+ * Used to read a Jsonable tree for testing and benchmarking.
+ *
+ * @returns an {@link ITreeCursorSynchronous} for a single {@link JsonCompatible}.
+ */
+export function singleJsonCursor(root: JsonCompatible): ITreeCursorSynchronous {
+	return stackTreeNodeCursor(adapter, root);
+}
+
+/**
+ * Extract a JS object tree from the contents of the given ITreeCursor.
+ * Assumes that ITreeCursor contains only unaugmented JsonTypes.
+ */
+export function cursorToJsonObject(reader: ITreeCursor): JsonCompatible {
+	const type = reader.type;
+
+	switch (type) {
+		case leaf.number.name:
+		case leaf.boolean.name:
+		case leaf.string.name:
+			assert(reader.value !== undefined, 0x84f /* out of schema: missing value */);
+			assert(!isFluidHandle(reader.value), 0x850 /* out of schema: unexpected FluidHandle */);
+			return reader.value;
+		case jsonArray.name: {
+			reader.enterField(EmptyKey);
+			const result = mapCursorField(reader, cursorToJsonObject);
+			reader.exitField();
+			return result;
+		}
+		case jsonObject.name: {
+			const result: JsonCompatible = {};
+			mapCursorFields(reader, (cursor) => {
+				const key = cursor.getFieldKey();
+				assert(cursor.firstNode(), 0x420 /* expected non-empty field */);
+				// like `result[key] = cursorToJsonObject(reader);` except safe when keyString == "__proto__".
+				Object.defineProperty(result, key, {
+					enumerable: true,
+					configurable: true,
+					writable: true,
+					value: cursorToJsonObject(reader),
+				});
+				assert(!cursor.nextNode(), 0x421 /* expected exactly one node */);
+			});
+			return result;
+		}
+		default: {
+			assert(type === leaf.null.name, 0x422 /* unexpected type */);
+			return null;
+		}
+	}
+}

package/src/domains/json/jsonDomainSchema.ts

@@ -0,0 +1,49 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// Adding this unused import makes the generated d.ts file produced by TypeScript stop breaking API-Extractor's rollup generation.
+// Without this import, TypeScript generates inline `import("../..")` statements in the d.ts file,
+// which API-Extractor leaves as is when generating the rollup, leaving them pointing at the wrong directory.
+// TODO: Understand and/or remove the need for this workaround.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
+import { ValueSchema } from "../../core";
+
+import {
+	AllowedTypes,
+	FieldKinds,
+	TreeFieldSchema,
+	SchemaBuilderInternal,
+} from "../../feature-libraries";
+import { requireAssignableTo } from "../../util";
+import { leaf } from "../leafDomain";
+
+const builder = new SchemaBuilderInternal({
+	scope: "com.fluidframework.json",
+	libraries: [leaf.library],
+});
+
+const jsonPrimitives = [...leaf.primitives, leaf.null] as const;
+
+/**
+ * Types allowed as roots of Json content.
+ */
+export const jsonRoot = [() => jsonObject, () => jsonArray, ...jsonPrimitives] as const;
+
+{
+	// Recursive objects don't get this type checking automatically, so confirm it
+	type _check = requireAssignableTo<typeof jsonRoot, AllowedTypes>;
+}
+
+export const jsonObject = builder.mapRecursive(
+	"object",
+	TreeFieldSchema.createUnsafe(FieldKinds.optional, jsonRoot),
+);
+
+export const jsonArray = builder.fieldNodeRecursive(
+	"array",
+	TreeFieldSchema.createUnsafe(FieldKinds.sequence, jsonRoot),
+);
+
+export const jsonSchema = builder.intoLibrary();

package/src/domains/leafDomain.ts

@@ -0,0 +1,98 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { SchemaBuilderInternal } from "../feature-libraries";
+import { ValueSchema } from "../core";
+
+/**
+ * Names in this domain follow https://en.wikipedia.org/wiki/Reverse_domain_name_notation
+ */
+const builder = new SchemaBuilderInternal({ scope: "com.fluidframework.leaf" });
+
+const number = builder.leaf("number", ValueSchema.Number);
+const boolean = builder.leaf("boolean", ValueSchema.Boolean);
+const string = builder.leaf("string", ValueSchema.String);
+const handle = builder.leaf("handle", ValueSchema.FluidHandle);
+const nullSchema = builder.leaf("null", ValueSchema.Null);
+
+const primitives = [number, boolean, string] as const;
+const all = [handle, nullSchema, ...primitives] as const;
+
+const library = builder.intoLibrary();
+
+/**
+ * Built-in {@link LeafNodeSchema}.
+ * @internal
+ */
+export const leaf = {
+	/**
+	 * {@link LeafNodeSchema} for holding a JavaScript `number`.
+	 *
+	 * @remarks
+	 * The number is a [double-precision 64-bit binary format IEEE 754](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) value, however there are some exceptions:
+	 * - `NaN`, and the infinities should not be used.
+	 * - `-0` may be converted to `0` in some cases.
+	 *
+	 * These limitations match the limitations of JSON.
+	 * @privateRemarks
+	 * TODO:
+	 * We should be much more clear about what happens if you use problematic values.
+	 * We should validate and/or normalize them when inserting content.
+	 */
+	number,
+
+	/**
+	 * {@link LeafNodeSchema} for holding a boolean.
+	 */
+	boolean,
+
+	/**
+	 * {@link LeafNodeSchema} for holding a JavaScript `string`.
+	 *
+	 * @remarks
+	 * Strings containing unpaired UTF-16 surrogate pair code units may not be handled correctly.
+	 *
+	 * These limitations come from the use of UTF-8 encoding of the strings, which requires them to be valid unicode.
+	 * JavaScript does not make this requirement for its strings so not all possible JavaScript strings are supported.
+	 * @privateRemarks
+	 * TODO:
+	 * We should be much more clear about what happens if you use problematic values.
+	 * We should validate and/or normalize them when inserting content.
+	 */
+	string,
+
+	/**
+	 * {@link LeafNodeSchema} for holding an {@link @fluidframework/core-interfaces#IFluidHandle}.
+	 */
+	handle,
+
+	/**
+	 * {@link LeafNodeSchema} for JavaScript `null`.
+	 *
+	 * @remarks
+	 * There are good [reasons to avoid using null](https://www.npmjs.com/package/%40rushstack/eslint-plugin#rushstackno-new-null) in JavaScript, however sometimes it is desired.
+	 * This {@link LeafNodeSchema} node provides the option to include nulls in trees when desired.
+	 * Unless directly inter-operating with existing data using null, consider other approaches, like wrapping the value in an optional field, or using a more specifically named empty object node.
+	 */
+	null: nullSchema,
+
+	/**
+	 * The set of {@link LeafNodeSchema} which correspond to JavaScript primitive (non-object) types.
+	 */
+	primitives,
+
+	/**
+	 * All {@link LeafNodeSchema} defined in this library..
+	 */
+	all,
+
+	/**
+	 * {@link SchemaLibrary} of the {@link LeafNodeSchema}.
+	 *
+	 * @privateRemarks
+	 * This is included by default in schema produced with {@link SchemaBuilder}.
+	 */
+	library,
+};

package/src/domains/nodeKey/fence.json

@@ -0,0 +1,5 @@
+{
+	"tags": ["node-key"],
+	"exports": ["index"],
+	"imports": ["util", "core", "feature-libraries"]
+}

package/src/domains/nodeKey/index.ts

@@ -0,0 +1,6 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { nodeKeyField, nodeKeySchema, nodeKeyTreeSchema } from "./nodeKeySchema";

package/src/domains/nodeKey/nodeKeySchema.ts

@@ -0,0 +1,43 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils";
+import { ValueSchema } from "../../core";
+import {
+	nodeKeyFieldKey,
+	FieldKinds,
+	nodeKeyTreeIdentifier,
+	SchemaBuilderInternal,
+	TreeFieldSchema,
+} from "../../feature-libraries";
+
+const builder = new SchemaBuilderInternal({ scope: "com.fluidframework.nodeKey" });
+
+/**
+ * Schema for a node which holds a {@link StableNodeKey}.
+ *
+ * @privateRemarks
+ * This being a leaf may cause issues with leaf unboxing plans.
+ * This might need to be changed to be a node holding a string node instead.
+ */
+export const nodeKeyTreeSchema = builder.leaf("NodeKey", ValueSchema.String);
+assert(nodeKeyTreeSchema.name === nodeKeyTreeIdentifier, 0x7ae /* mismatched identifiers */);
+
+/**
+ * Key and Field schema for working with {@link LocalNodeKey}s in a shared tree.
+ * Node keys are added to object nodes via a field.
+ * This object can be expanded into a schema to add the field.
+ *
+ * Requires including {@link nodeKeySchema}.
+ */
+export const nodeKeyField = {
+	[nodeKeyFieldKey]: TreeFieldSchema.create(FieldKinds.nodeKey, [nodeKeyTreeSchema]),
+};
+
+/**
+ * The schema library for working with {@link StableNodeKey}s in a tree.
+ * Required to use {@link nodeKeyField}.
+ */
+export const nodeKeySchema = builder.intoLibrary();