@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/src/feature-libraries/typed-schema/view.ts

@@ -0,0 +1,157 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Named, fail } from "../../util";
+import {
+	TreeFieldStoredSchema,
+	TreeNodeStoredSchema,
+	TreeNodeSchemaIdentifier,
+	TreeStoredSchema,
+	Adapters,
+	AdaptedViewSchema,
+	Compatibility,
+} from "../../core";
+import { FullSchemaPolicy, allowsRepoSuperset, isNeverTree } from "../modular-schema";
+import { FlexTreeSchema, intoStoredSchema } from "./typedTreeSchema";
+
+/**
+ * A collection of View information for schema, including policy.
+ */
+export class ViewSchema {
+	/**
+	 * Cached conversion of `schema` into a stored schema.
+	 */
+	public readonly storedSchema: TreeStoredSchema;
+	public constructor(
+		public readonly policy: FullSchemaPolicy,
+		public readonly adapters: Adapters,
+		public readonly schema: FlexTreeSchema,
+	) {
+		this.storedSchema = intoStoredSchema(schema);
+	}
+
+	/**
+	 * Determines the compatibility of a stored document
+	 * (based on its stored schema) with a viewer (based on its view schema).
+	 *
+	 * Adapters can be provided to handle differences between the two schema.
+	 * Adapters should only use to types in the `view` SchemaRepository.
+	 *
+	 * TODO: this API violates the parse don't validate design philosophy.
+	 * It should be wrapped with (or replaced by) a parse style API.
+	 */
+	public checkCompatibility(stored: TreeStoredSchema): {
+		read: Compatibility;
+		write: Compatibility;
+		writeAllowingStoredSchemaUpdates: Compatibility;
+	} {
+		const adapted = this.adaptRepo(stored);
+
+		const read = allowsRepoSuperset(this.policy, stored, this.storedSchema)
+			? Compatibility.Compatible
+			: allowsRepoSuperset(this.policy, adapted.adaptedForViewSchema, this.storedSchema)
+			? Compatibility.RequiresAdapters
+			: Compatibility.Incompatible;
+		// TODO: Extract subset of adapters that are valid to use on stored
+		// TODO: separate adapters from schema updates
+		const write = allowsRepoSuperset(this.policy, this.storedSchema, stored)
+			? Compatibility.Compatible
+			: allowsRepoSuperset(this.policy, this.storedSchema, adapted.adaptedForViewSchema)
+			? // TODO: IThis assumes adapters are bidirectional.
+			  Compatibility.RequiresAdapters
+			: Compatibility.Incompatible;
+
+		// TODO: compute this properly (and maybe include the set of schema changes needed for it?).
+		// Maybe updates would happen lazily when needed to store data?
+		// When willingness to updates can avoid need for some adapters,
+		// how should it be decided if the adapter should be used to avoid the update?
+		// TODO: is this case actually bi-variant, making this correct if we did it for each schema independently?
+		let writeAllowingStoredSchemaUpdates =
+			// TODO: This should consider just the updates needed
+			// (ex: when view covers a subset of stored after stored has a update to that subset).
+			allowsRepoSuperset(this.policy, stored, this.storedSchema)
+				? Compatibility.Compatible
+				: // TODO: this assumes adapters can translate in both directions. In general this will not be true.
+				// TODO: this also assumes that schema updates to the adapted repo would translate to
+				// updates on the stored schema, which is also likely untrue.
+				allowsRepoSuperset(this.policy, adapted.adaptedForViewSchema, this.storedSchema)
+				? Compatibility.RequiresAdapters // Requires schema updates. TODO: consider adapters that can update writes.
+				: Compatibility.Incompatible;
+
+		// Since the above does not consider partial updates,
+		// we can improve the tolerance a bit by considering the op-op update:
+		writeAllowingStoredSchemaUpdates = Math.max(writeAllowingStoredSchemaUpdates, write);
+
+		return { read, write, writeAllowingStoredSchemaUpdates };
+	}
+
+	/**
+	 * Compute a schema that `original` could be viewed as using adapters as needed.
+	 *
+	 * TODO: have a way for callers to get invalidated on schema updates.
+	 */
+	public adaptRepo(stored: TreeStoredSchema): AdaptedViewSchema {
+		// Sanity check on adapters:
+		// it's probably a bug it they use the never types,
+		// since there never is a reason to have a never type as an adapter input,
+		// and its impossible for an adapter to be correctly implemented if its output type is never
+		// (unless its input is also never).
+		for (const adapter of this.adapters?.tree ?? []) {
+			if (
+				isNeverTree(
+					this.policy,
+					this.storedSchema,
+					this.storedSchema.nodeSchema.get(adapter.output),
+				)
+			) {
+				fail("tree adapter for stored adapter.output should not be never");
+			}
+		}
+
+		const adapted = {
+			rootFieldSchema: this.adaptField(stored.rootFieldSchema),
+			nodeSchema: new Map<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>(),
+		};
+
+		for (const [key, schema] of stored.nodeSchema) {
+			const adapatedTree = this.adaptTree(schema);
+			adapted.nodeSchema.set(key, adapatedTree);
+		}
+
+		// TODO: subset these adapters to the ones that were needed/used.
+		return new AdaptedViewSchema(this.adapters, adapted);
+	}
+
+	/**
+	 * Adapt original such that it allows member types which can be adapted to its specified types.
+	 */
+	private adaptField(original: TreeFieldStoredSchema): TreeFieldStoredSchema {
+		if (original.types !== undefined) {
+			const types: Set<TreeNodeSchemaIdentifier> = new Set(original.types);
+			for (const treeAdapter of this.adapters?.tree ?? []) {
+				if (types.has(treeAdapter.input)) {
+					types.delete(treeAdapter.input);
+					types.add(treeAdapter.output);
+				}
+			}
+
+			return { kind: original.kind, types };
+		}
+		return original;
+	}
+
+	private adaptTree(original: TreeNodeStoredSchema): TreeNodeStoredSchema {
+		// TODO: support adapters like missing field adapters.
+		return original;
+	}
+}
+
+/**
+ * Record where a schema came from for error reporting purposes.
+ * @internal
+ */
+export interface Sourced {
+	readonly builder: Named<string>;
+}

package/src/feature-libraries/utils.ts

@@ -0,0 +1,35 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IJsonCodec } from "../codec";
+import { RevisionTag, EncodedRevisionTag, ChangeAtomId, EncodedChangeAtomId } from "../core";
+
+export function encodeChangeAtomId(
+	revisionTagCodec: IJsonCodec<RevisionTag, EncodedRevisionTag>,
+	changeAtomId: ChangeAtomId,
+): EncodedChangeAtomId {
+	if (changeAtomId.revision === undefined) {
+		return { localId: changeAtomId.localId };
+	}
+
+	return {
+		localId: changeAtomId.localId,
+		revision: revisionTagCodec.encode(changeAtomId.revision),
+	};
+}
+
+export function decodeChangeAtomId(
+	revisionTagCodec: IJsonCodec<RevisionTag, EncodedRevisionTag>,
+	changeAtomId: EncodedChangeAtomId,
+): ChangeAtomId {
+	if (changeAtomId.revision === undefined) {
+		return { localId: changeAtomId.localId };
+	}
+
+	return {
+		localId: changeAtomId.localId,
+		revision: revisionTagCodec.decode(changeAtomId.revision),
+	};
+}

package/src/feature-libraries/valueUtilities.ts

@@ -0,0 +1,93 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert, unreachableCase } from "@fluidframework/core-utils";
+import { IFluidHandle } from "@fluidframework/core-interfaces";
+import { Value, ValueSchema, TreeValue } from "../core";
+
+export function allowsValue(schema: ValueSchema | undefined, nodeValue: Value): boolean {
+	if (schema === undefined) {
+		return nodeValue === undefined;
+	}
+	return valueSchemaAllows(schema, nodeValue);
+}
+
+export function valueSchemaAllows<TSchema extends ValueSchema>(
+	schema: TSchema,
+	nodeValue: Value,
+): nodeValue is TreeValue<TSchema> {
+	switch (schema) {
+		case ValueSchema.String:
+			return typeof nodeValue === "string";
+		case ValueSchema.Number:
+			return typeof nodeValue === "number";
+		case ValueSchema.Boolean:
+			return typeof nodeValue === "boolean";
+		case ValueSchema.FluidHandle:
+			return isFluidHandle(nodeValue);
+		case ValueSchema.Null:
+			return nodeValue === null;
+		default:
+			unreachableCase(schema);
+	}
+}
+
+/**
+ * Use for readonly view of Json compatible data that can also contain IFluidHandles.
+ *
+ * Note that this does not robustly forbid non json comparable data via type checking,
+ * but instead mostly restricts access to it.
+ */
+export type FluidSerializableReadOnly =
+	| IFluidHandle
+	| string
+	| number
+	| boolean
+	// eslint-disable-next-line @rushstack/no-new-null
+	| null
+	| readonly FluidSerializableReadOnly[]
+	| {
+			readonly [P in string]?: FluidSerializableReadOnly;
+	  };
+
+// TODO: replace test in FluidSerializer.encodeValue with this.
+export function isFluidHandle(value: unknown): value is IFluidHandle {
+	if (typeof value !== "object" || value === null || !("IFluidHandle" in value)) {
+		return false;
+	}
+
+	const handle = (value as Partial<IFluidHandle>).IFluidHandle;
+	// Regular Json compatible data can have fields named "IFluidHandle" (especially if field names come from user data).
+	// Separate this case from actual Fluid handles by checking for a circular reference: Json data can't have this circular reference so it is a safe way to detect IFluidHandles.
+	const isHandle = handle === value;
+	// Since the requirement for this reference to be cyclic isn't particularly clear in the interface (typescript can't model that very well)
+	// do an extra test.
+	// Since json compatible data shouldn't have methods, and IFluidHandle requires one, use that as a redundant check:
+	const getMember = (value as Partial<IFluidHandle>).get;
+	if (typeof getMember !== "function") {
+		return false;
+	}
+
+	return isHandle;
+}
+
+export function assertAllowedValue(
+	value: undefined | FluidSerializableReadOnly,
+): asserts value is Value {
+	assert(isAllowedValue(value), 0x843 /* invalid value */);
+}
+
+export function isAllowedValue(value: undefined | FluidSerializableReadOnly): value is Value {
+	switch (typeof value) {
+		case "string":
+		case "number":
+		case "boolean":
+			return true;
+		case "object":
+			return value === null || isFluidHandle(value);
+		default:
+			return false;
+	}
+}

package/src/feature-libraries/versioned/codec.ts

@@ -0,0 +1,62 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils";
+import { TSchema } from "@sinclair/typebox";
+import { ICodecOptions, IJsonCodec, withSchemaValidation } from "../../codec";
+import { JsonCompatibleReadOnly } from "../../util";
+import { Versioned } from "./format";
+
+export function makeVersionedCodec<
+	TDecoded,
+	TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,
+	TValidate = TEncoded,
+>(
+	supportedVersions: Set<number>,
+	{ jsonValidator: validator }: ICodecOptions,
+	inner: IJsonCodec<TDecoded, TEncoded, TValidate>,
+): IJsonCodec<TDecoded, TEncoded, TValidate> {
+	return withSchemaValidation(
+		Versioned,
+		{
+			encode: (data: TDecoded): TEncoded => {
+				const encoded = inner.encode(data);
+				assert(
+					supportedVersions.has(encoded.version),
+					"version being encoded should be supported",
+				);
+				return encoded;
+			},
+			decode: (data: TValidate): TDecoded => {
+				const versioned = data as Versioned; // Validated by withSchemaValidation
+				assert(
+					supportedVersions.has(versioned.version),
+					"version being decoded is not supported",
+				);
+				const decoded = inner.decode(data);
+				return decoded;
+			},
+		},
+		validator,
+	);
+}
+
+export function makeVersionedValidatedCodec<
+	EncodedSchema extends TSchema,
+	TDecoded,
+	TEncoded extends Versioned = JsonCompatibleReadOnly & Versioned,
+	TValidate = TEncoded,
+>(
+	options: ICodecOptions,
+	supportedVersions: Set<number>,
+	schema: EncodedSchema,
+	codec: IJsonCodec<TDecoded, TEncoded, TValidate>,
+): IJsonCodec<TDecoded, TEncoded, TValidate> {
+	return makeVersionedCodec(
+		supportedVersions,
+		options,
+		withSchemaValidation(schema, codec, options.jsonValidator),
+	);
+}

package/src/feature-libraries/versioned/format.ts

@@ -0,0 +1,11 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Static, Type } from "@sinclair/typebox";
+
+export const Versioned = Type.Object({
+	version: Type.Number(),
+});
+export type Versioned = Static<typeof Versioned>;

package/src/feature-libraries/versioned/index.ts

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { Versioned } from "./format";
+export { makeVersionedCodec, makeVersionedValidatedCodec } from "./codec";

package/src/index.ts

@@ -0,0 +1,341 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	EmptyKey,
+	FieldKey,
+	TreeType,
+	Value,
+	TreeValue,
+	AnchorSet,
+	DetachedField,
+	UpPath,
+	Range,
+	RangeUpPath,
+	PlaceUpPath,
+	DetachedRangeUpPath,
+	DetachedPlaceUpPath,
+	PlaceIndex,
+	NodeIndex,
+	FieldUpPath,
+	Anchor,
+	RootField,
+	ChildCollection,
+	ChildLocation,
+	DeltaVisitor,
+	AnnouncedVisitor,
+	FieldMapObject,
+	NodeData,
+	GenericTreeNode,
+	JsonableTree,
+	ProtoNodes,
+	DeltaRoot,
+	DeltaProtoNode,
+	DeltaMark,
+	DeltaDetachedNodeId,
+	DeltaFieldMap,
+	DeltaDetachedNodeChanges,
+	DeltaDetachedNodeBuild,
+	DeltaDetachedNodeDestruction,
+	DeltaDetachedNodeRename,
+	DeltaFieldChanges,
+	rootFieldKey,
+	rootField,
+	ITreeCursor,
+	CursorLocationType,
+	ITreeCursorSynchronous,
+	GenericFieldsNode,
+	AnchorLocator,
+	TreeNavigationResult,
+	IEditableForest,
+	IForestSubscription,
+	TreeLocation,
+	FieldLocation,
+	ForestLocation,
+	ITreeSubscriptionCursor,
+	ITreeSubscriptionCursorState,
+	TreeNodeSchemaIdentifier,
+	TreeFieldStoredSchema,
+	ValueSchema,
+	TreeNodeStoredSchema,
+	TreeStoredSchemaSubscription,
+	FieldKindIdentifier,
+	TreeTypeSet,
+	TreeStoredSchema,
+	FieldAnchor,
+	SchemaEvents,
+	ChangesetLocalId,
+	ForestEvents,
+	PathRootPrefix,
+	AnchorSlot,
+	AnchorNode,
+	anchorSlot,
+	UpPathDefault,
+	AnchorEvents,
+	AnchorSetRootEvents,
+	FieldKindSpecifier,
+	AllowedUpdateType,
+	PathVisitor,
+	Adapters,
+	TreeAdapter,
+	MapTree,
+	Revertible,
+	RevertibleKind,
+	RevertResult,
+	DiscardResult,
+	forbiddenFieldKindIdentifier,
+	StoredSchemaCollection,
+	ErasedTreeNodeSchemaDataFormat,
+} from "./core";
+
+export {
+	Brand,
+	Opaque,
+	extractFromOpaque,
+	brand,
+	ValueFromBranded,
+	NameFromBranded,
+	JsonCompatibleReadOnly,
+	JsonCompatible,
+	JsonCompatibleObject,
+	NestedMap,
+	fail,
+	IdAllocator,
+	TransactionResult,
+	BrandedKey,
+	BrandedMapSubset,
+	RangeQueryResult,
+	Named,
+	oneFromSet,
+	disposeSymbol,
+	IDisposable,
+} from "./util";
+
+export {
+	Events,
+	IsEvent,
+	ISubscribable,
+	createEmitter,
+	IEmitter,
+	NoListenersCallback,
+	HasListeners,
+} from "./events";
+
+export { leaf } from "./domains";
+
+export {
+	FieldKind,
+	Multiplicity,
+	isNeverField,
+	FullSchemaPolicy,
+	typeNameSymbol,
+	valueSymbol,
+	ContextuallyTypedNodeDataObject,
+	ContextuallyTypedNodeData,
+	MarkedArrayLike,
+	isContextuallyTypedNodeDataObject,
+	defaultSchemaPolicy,
+	jsonableTreeFromCursor,
+	StableNodeKey,
+	LocalNodeKey,
+	compareLocalNodeKeys,
+	IDefaultEditBuilder,
+	ValueFieldEditBuilder,
+	OptionalFieldEditBuilder,
+	SequenceFieldEditBuilder,
+	prefixPath,
+	prefixFieldPath,
+	cursorForJsonableTreeNode as singleTextCursor,
+	stackTreeNodeCursor,
+	CursorAdapter,
+	CursorWithNode,
+	EditableTreeEvents,
+	InternalTypedSchemaTypes,
+	ArrayLikeMut,
+	FieldKinds,
+	ContextuallyTypedFieldData,
+	cursorFromContextualData,
+	AllowedTypes,
+	TreeNodeSchema as FlexTreeNodeSchema,
+	FlexTreeSchema,
+	SchemaLibrary,
+	SchemaLibraryData,
+	TreeFieldSchema,
+	Any,
+	NewFieldContent,
+	NodeExistsConstraint,
+	cursorForTypedTreeData,
+	LazyTreeNodeSchema,
+	FieldGenerator,
+	TreeDataContext,
+	nodeKeyFieldKey,
+	SchemaLintConfiguration,
+	TreeStatus,
+	FlexTreeFieldNode,
+	FlexibleFieldContent,
+	FlexibleNodeContent,
+	FlexTreeLeafNode,
+	FlexTreeMapNode,
+	FlexTreeOptionalField,
+	FlexTreeRequiredField,
+	FlexTreeSequenceField,
+	FlexTreeObjectNode,
+	FlexTreeObjectNodeTyped,
+	AssignableFieldKinds,
+	FlexTreeContext as TreeContext,
+	FlexTreeTypedField,
+	FlexTreeTypedNode,
+	FlexTreeTypedNodeUnion,
+	FlexTreeEntity,
+	FlexTreeField,
+	FlexTreeNode,
+	TreeNodeSchemaBase,
+	FieldNodeSchema,
+	LeafNodeSchema,
+	MapNodeSchema,
+	ObjectNodeSchema,
+	CheckTypesOverlap,
+	SchemaBuilderBase,
+	ImplicitFieldSchema as FlexImplicitFieldSchema,
+	ImplicitAllowedTypes,
+	Unenforced,
+	schemaIsFieldNode,
+	schemaIsLeaf,
+	schemaIsMap,
+	schemaIsObjectNode,
+	AllowedTypeSet,
+	SchemaBuilderOptions,
+	TreeEvent,
+	SchemaCollection,
+	TreeCompressionStrategy,
+	treeSchemaFromStoredSchema,
+	encodeTreeSchema,
+	stackTreeFieldCursor,
+	FlexTreeUnknownUnboxed,
+	InsertableFlexNode,
+	InsertableFlexField,
+	AllowedTypesToFlexInsertableTree,
+	ApplyMultiplicity,
+	NormalizeObjectNodeFields,
+	NormalizeFieldSchema,
+	Fields,
+	MapFieldSchema,
+} from "./feature-libraries";
+
+export {
+	TreeArrayNode,
+	TreeMapNodeBase,
+	Unhydrated,
+	IterableTreeListContent,
+	TreeNode,
+} from "./simple-tree";
+
+export {
+	ISharedTree,
+	ITreeCheckout,
+	ITransaction,
+	runSynchronous,
+	SharedTreeFactory,
+	SharedTreeOptions,
+	ITreeCheckoutFork,
+	CheckoutEvents,
+	SchematizeConfiguration,
+	TreeContent,
+	InitializeAndSchematizeConfiguration,
+	SchemaConfiguration,
+	ForestType,
+	SharedTreeContentSnapshot,
+	FlexTreeView,
+	ITreeViewFork,
+	buildTreeConfiguration,
+	ISharedTreeEditor,
+	ISchemaEditor,
+} from "./shared-tree";
+
+export {
+	ITree,
+	TreeNodeSchema,
+	TreeConfiguration,
+	TreeView,
+	SchemaFactory,
+	Tree,
+	TreeApi,
+	ImplicitFieldSchema,
+	TreeFieldFromImplicitField,
+	TreeNodeEvents,
+	NodeFromSchema,
+	TreeMapNode,
+	InsertableTreeNodeFromImplicitAllowedTypes,
+	TreeLeafValue,
+
+	// experimental @internal APIs:
+	adaptEnum,
+	enumFromStrings,
+	singletonSchema,
+	typedObjectValues,
+
+	// test recursive schema for checking that d.ts files handles schema correctly
+	test_RecursiveObject,
+	test_RecursiveObject_base,
+} from "./class-tree";
+export { SharedTree, TreeFactory, TreeOptions } from "./treeFactory";
+
+export type { ICodecOptions, JsonValidator, SchemaValidationFunction } from "./codec";
+export { noopValidator } from "./codec";
+export { typeboxValidator } from "./external-utilities";
+
+// Below here are things that are used by the above, but not part of the desired API surface.
+import * as InternalTypes from "./internal";
+export { InternalTypes };
+
+// TODO: When previously tagged '@internal', these types could not be included in `InternalClassTreeTypes` due to https://github.com/microsoft/rushstack/issues/3639
+export {
+	Invariant,
+	Contravariant,
+	Covariant,
+	BrandedType,
+	ExtractFromOpaque,
+	Assume,
+	AllowOptional,
+	RequiredFields,
+	OptionalFields,
+	_InlineTrick,
+	_RecursiveTrick,
+	FlattenKeys,
+	AllowOptionalNotFlattened,
+	isAny,
+	BrandedKeyContent,
+	ErasedType,
+	Erased,
+} from "./util";
+
+export {
+	NormalizeField,
+	NormalizeAllowedTypes,
+	FlexTreeTypedFieldInner,
+	FlexTreeUnboxFieldInner,
+	FlexTreeObjectNodeFields,
+	FlexTreeUnboxField,
+	FlexTreeUnboxNode,
+	FlexTreeUnboxNodeUnion,
+	FlexTreeNodeKeyField,
+	IsArrayOfOne,
+	FlexibleNodeSubSequence,
+	flexTreeMarker,
+	FlexTreeEntityKind,
+	NodeKeys,
+	CollectOptions,
+	TypedFields,
+	UnbrandedName,
+	EmptyObject,
+
+	// These field kind types really only need to show up via FieldKinds.name, and not as top level names in the package.
+	// These names also are collision prone.
+	Required,
+	Optional,
+	NodeKeyFieldKind,
+	Forbidden,
+	Sequence,
+} from "./feature-libraries";