@fluidframework/tree 2.72.0 → 2.73.0

package/src/feature-libraries/chunked-forest/codec/schemaBasedEncode.ts

@@ -16,8 +16,8 @@ import {
 	ValueSchema,
 	Multiplicity,
 	identifierFieldKindIdentifier,
+	type SchemaPolicy,
 } from "../../../core/index.js";
-import type { FullSchemaPolicy } from "../../modular-schema/index.js";
 
 import {
 	EncoderContext,
@@ -31,11 +31,61 @@ import {
 	incrementalFieldEncoder,
 } from "./compressedEncode.js";
 import type { FieldBatch } from "./fieldBatch.js";
-import { type EncodedFieldBatch, type EncodedValueShape, SpecialField } from "./format.js";
+import {
+	type EncodedFieldBatch,
+	type EncodedFieldBatchV1,
+	type EncodedFieldBatchV2,
+	type EncodedValueShape,
+	FieldBatchFormatVersion,
+	SpecialField,
+} from "./format.js";
 import type { IncrementalEncoder } from "./codecs.js";
 import { NodeShapeBasedEncoder } from "./nodeEncoder.js";
 import { defaultIncrementalEncodingPolicy } from "./incrementalEncodingPolicy.js";
-import { oneFromIterable } from "../../../util/index.js";
+import { brand, oneFromIterable } from "../../../util/index.js";
+
+/**
+ * Encode data from `fieldBatch` in into an `EncodedChunk` using {@link FieldBatchFormatVersion.v1}.
+ * @remarks See {@link schemaCompressedEncode} for more details.
+ * This version does not support incremental encoding.
+ */
+export function schemaCompressedEncodeV1(
+	schema: StoredSchemaCollection,
+	policy: SchemaPolicy,
+	fieldBatch: FieldBatch,
+	idCompressor: IIdCompressor,
+): EncodedFieldBatchV1 {
+	return schemaCompressedEncode(
+		schema,
+		policy,
+		fieldBatch,
+		idCompressor,
+		undefined /* incrementalEncoder */,
+		brand(FieldBatchFormatVersion.v1),
+	);
+}
+
+/**
+ * Encode data from `fieldBatch` in into an `EncodedChunk` using {@link FieldBatchFormatVersion.v2}.
+ * @remarks See {@link schemaCompressedEncode} for more details.
+ * Incremental encoding is supported from this version onwards.
+ */
+export function schemaCompressedEncodeV2(
+	schema: StoredSchemaCollection,
+	policy: SchemaPolicy,
+	fieldBatch: FieldBatch,
+	idCompressor: IIdCompressor,
+	incrementalEncoder: IncrementalEncoder | undefined,
+): EncodedFieldBatchV2 {
+	return schemaCompressedEncode(
+		schema,
+		policy,
+		fieldBatch,
+		idCompressor,
+		incrementalEncoder,
+		brand(FieldBatchFormatVersion.v2),
+	);
+}
 
 /**
  * Encode data from `fieldBatch` in into an `EncodedChunk`.
@@ -47,24 +97,26 @@ import { oneFromIterable } from "../../../util/index.js";
  * Optimized for encoded size and encoding performance.
  * TODO: This function should eventually also take in the root FieldSchema to more efficiently compress the nodes.
  */
-export function schemaCompressedEncode(
+function schemaCompressedEncode(
 	schema: StoredSchemaCollection,
-	policy: FullSchemaPolicy,
+	policy: SchemaPolicy,
 	fieldBatch: FieldBatch,
 	idCompressor: IIdCompressor,
-	incrementalEncoder?: IncrementalEncoder,
+	incrementalEncoder: IncrementalEncoder | undefined,
+	version: FieldBatchFormatVersion,
 ): EncodedFieldBatch {
 	return compressedEncode(
 		fieldBatch,
-		buildContext(schema, policy, idCompressor, incrementalEncoder),
+		buildContext(schema, policy, idCompressor, incrementalEncoder, version),
 	);
 }
 
 export function buildContext(
 	storedSchema: StoredSchemaCollection,
-	policy: FullSchemaPolicy,
+	policy: SchemaPolicy,
 	idCompressor: IIdCompressor,
-	incrementalEncoder?: IncrementalEncoder,
+	incrementalEncoder: IncrementalEncoder | undefined,
+	version: FieldBatchFormatVersion,
 ): EncoderContext {
 	const context: EncoderContext = new EncoderContext(
 		(fieldBuilder: FieldEncodeBuilder, schemaName: TreeNodeSchemaIdentifier) =>
@@ -74,6 +126,7 @@ export function buildContext(
 		policy.fieldKinds,
 		idCompressor,
 		incrementalEncoder,
+		version,
 	);
 	return context;
 }

package/src/feature-libraries/chunked-forest/codec/uncompressedEncode.ts

@@ -8,17 +8,36 @@ import {
 	forEachField,
 	forEachNode,
 } from "../../../core/index.js";
+import { brand } from "../../../util/index.js";
 import type { FluidSerializableReadOnly } from "../../valueUtilities.js";
 
 import type { FieldBatch } from "./fieldBatch.js";
 import {
 	FieldBatchFormatVersion,
 	type EncodedFieldBatch,
+	type EncodedFieldBatchV1,
+	type EncodedFieldBatchV2,
 	type EncodedNestedArrayShape,
 	type EncodedNodeShape,
 } from "./format.js";
 import type { ShapeIndex } from "./formatGeneric.js";
 
+/**
+ * Encode data from `cursor` in the simplest way supported by `EncodedChunk` using {@link FieldBatchFormatVersion.v1}.
+ * @remarks See {@link uncompressedEncode} for more details.
+ */
+export function uncompressedEncodeV1(batch: FieldBatch): EncodedFieldBatchV1 {
+	return uncompressedEncode(batch, brand(FieldBatchFormatVersion.v1));
+}
+
+/**
+ * Encode data from `cursor` in the simplest way supported by `EncodedChunk` using {@link FieldBatchFormatVersion.v2}.
+ * @remarks See {@link uncompressedEncode} for more details.
+ */
+export function uncompressedEncodeV2(batch: FieldBatch): EncodedFieldBatchV2 {
+	return uncompressedEncode(batch, brand(FieldBatchFormatVersion.v2));
+}
+
 /**
  * Encode data from `cursor` in the simplest way supported by `EncodedChunk`.
  *
@@ -27,10 +46,13 @@ import type { ShapeIndex } from "./formatGeneric.js";
  *
  * This is intended as a simple reference implementation with minimal code and dependencies.
  */
-export function uncompressedEncode(batch: FieldBatch): EncodedFieldBatch {
+function uncompressedEncode(
+	batch: FieldBatch,
+	version: FieldBatchFormatVersion,
+): EncodedFieldBatch {
 	const rootFields = batch.map(encodeSequence);
 	return {
-		version: FieldBatchFormatVersion.v1,
+		version,
 		identifiers: [],
 		// A single shape used to encode all fields.
 		shapes: [{ c: anyNodeShape }, { a: anyArray }],

package/src/feature-libraries/chunked-forest/index.ts

@@ -17,7 +17,7 @@ export {
 export { buildChunkedForest } from "./chunkedForest.js";
 export {
 	EncodedFieldBatch,
-	type FieldBatchFormatVersion,
+	FieldBatchFormatVersion,
 	getCodecTreeForFieldBatchFormat,
 	type FieldBatch,
 	type FieldBatchCodec,

package/src/feature-libraries/default-schema/defaultFieldKinds.ts

@@ -18,22 +18,26 @@ import {
 	type FieldEditor,
 	type FieldKindConfiguration,
 	type FieldKindConfigurationEntry,
-	FieldKindWithEditor,
-	type FlexFieldKind,
+	FlexFieldKind,
+	type FullSchemaPolicy,
 	type ToDelta,
 	allowsTreeSchemaIdentifierSuperset,
 	referenceFreeFieldChangeRebaser,
 } from "../modular-schema/index.js";
 import {
 	type OptionalChangeset,
+	type OptionalFieldEditor,
 	optionalChangeHandler,
 	optionalFieldEditor,
 } from "../optional-field/index.js";
-import { sequenceFieldChangeHandler } from "../sequence-field/index.js";
+import {
+	sequenceFieldChangeHandler,
+	type SequenceFieldEditor,
+} from "../sequence-field/index.js";
 
 import { noChangeCodecFamily } from "./noChangeCodecs.js";
 import type { CodecTree } from "../../codec/index.js";
-import { brand, type Brand } from "../../util/index.js";
+import { brand, brandConst, type Brand } from "../../util/index.js";
 
 /**
  * ChangeHandler that only handles no-op / identity changes.
@@ -55,7 +59,15 @@ export const noChangeHandler: FieldChangeHandler<0> = {
 	getCrossFieldKeys: () => [],
 };
 
-export interface ValueFieldEditor extends FieldEditor<OptionalChangeset> {
+/**
+ * {@link FieldEditor} for required fields (always contain exactly 1 child).
+ * @remarks
+ * This shares code with optional fields, since they are the same edit wise except setting to empty is not allowed,
+ * and the content is always assumed to not be empty.
+ * This means the actual edits implemented for optional fields are sufficient to support required fields
+ * which is why this is defined and implemented in terms of optional fields.
+ */
+export interface RequiredFieldEditor extends FieldEditor<OptionalChangeset> {
 	/**
 	 * Creates a change which replaces the current value of the field with `newValue`.
 	 * @param ids - The ids for the fill and detach fields.
@@ -63,21 +75,19 @@ export interface ValueFieldEditor extends FieldEditor<OptionalChangeset> {
 	set(ids: { fill: ChangeAtomId; detach: ChangeAtomId }): OptionalChangeset;
 }
 
-const optionalIdentifier = "Optional";
+const optionalIdentifier = brandConst("Optional")<FieldKindIdentifier>();
+
 /**
  * 0 or 1 items.
  */
-export const optional = new FieldKindWithEditor(
-	optionalIdentifier,
-	Multiplicity.Optional,
-	optionalChangeHandler,
-	(types, other) =>
+export const optional = new FlexFieldKind(optionalIdentifier, Multiplicity.Optional, {
+	changeHandler: optionalChangeHandler,
+	allowsTreeSupersetOf: (types, other) =>
 		(other.kind === sequence.identifier || other.kind === optionalIdentifier) &&
 		allowsTreeSchemaIdentifierSuperset(types, other.types),
-	new Set([]),
-);
+});
 
-export const valueFieldEditor: ValueFieldEditor = {
+export const requiredFieldEditor: RequiredFieldEditor = {
 	...optionalFieldEditor,
 	set: (ids: {
 		fill: ChangeAtomId;
@@ -85,21 +95,22 @@ export const valueFieldEditor: ValueFieldEditor = {
 	}): OptionalChangeset => optionalFieldEditor.set(false, ids),
 };
 
-export const valueChangeHandler: FieldChangeHandler<OptionalChangeset, ValueFieldEditor> = {
-	...optional.changeHandler,
-	editor: valueFieldEditor,
+export const requiredFieldChangeHandler: FieldChangeHandler<
+	OptionalChangeset,
+	RequiredFieldEditor
+> = {
+	...optionalChangeHandler,
+	editor: requiredFieldEditor,
 };
 
-const requiredIdentifier = "Value";
+const requiredIdentifier = brandConst("Value")<FieldKindIdentifier>();
 
 /**
  * Exactly one item.
  */
-export const required = new FieldKindWithEditor(
-	requiredIdentifier,
-	Multiplicity.Single,
-	valueChangeHandler,
-	(types, other) =>
+export const required = new FlexFieldKind(requiredIdentifier, Multiplicity.Single, {
+	changeHandler: requiredFieldChangeHandler,
+	allowsTreeSupersetOf: (types, other) =>
 		// By omitting Identifier here,
 		// this is making a policy choice that a schema upgrade cannot be done from required to identifier.
 		// Since an identifier can be upgraded into a required field,
@@ -109,43 +120,35 @@ export const required = new FieldKindWithEditor(
 			other.kind === requiredIdentifier ||
 			other.kind === optional.identifier) &&
 		allowsTreeSchemaIdentifierSuperset(types, other.types),
-	new Set(),
-);
+});
 
-const sequenceIdentifier = "Sequence";
+const sequenceIdentifier = brandConst("Sequence")<FieldKindIdentifier>();
 
 /**
  * 0 or more items.
  */
-export const sequence = new FieldKindWithEditor(
-	sequenceIdentifier,
-	Multiplicity.Sequence,
-	sequenceFieldChangeHandler,
-	(types, other) =>
+export const sequence = new FlexFieldKind(sequenceIdentifier, Multiplicity.Sequence, {
+	changeHandler: sequenceFieldChangeHandler,
+	allowsTreeSupersetOf: (types, other) =>
 		other.kind === sequenceIdentifier &&
 		allowsTreeSchemaIdentifierSuperset(types, other.types),
-	// TODO: add normalizer/importers for handling ops from other kinds.
-	new Set([]),
-);
+});
 
-const identifierFieldIdentifier = "Identifier";
+const identifierFieldIdentifier = brandConst("Identifier")<FieldKindIdentifier>();
 
 /**
  * Exactly one identifier.
  */
-export const identifier = new FieldKindWithEditor(
-	identifierFieldIdentifier,
-	Multiplicity.Single,
-	noChangeHandler,
-	(types, other) =>
+export const identifier = new FlexFieldKind(identifierFieldIdentifier, Multiplicity.Single, {
+	changeHandler: noChangeHandler,
+	allowsTreeSupersetOf: (types, other) =>
 		// Allows upgrading from identifier to required: which way this upgrade is allowed to go is a subjective policy choice.
 		(other.kind === sequence.identifier ||
 			other.kind === requiredIdentifier ||
 			other.kind === optional.identifier ||
 			other.kind === identifierFieldIdentifier) &&
 		allowsTreeSchemaIdentifierSuperset(types, other.types),
-	new Set(),
-);
+});
 
 /**
  * Exactly 0 items.
@@ -175,39 +178,21 @@ export const identifier = new FieldKindWithEditor(
  *
  * See {@link emptyField} for a constant, reusable field using Forbidden.
  */
-export const forbidden = new FieldKindWithEditor(
+export const forbidden = new FlexFieldKind(
 	forbiddenFieldKindIdentifier,
 	Multiplicity.Forbidden,
-	noChangeHandler,
-	// All multiplicities other than Value support empty.
-	(types, other) => fieldKinds.get(other.kind)?.multiplicity !== Multiplicity.Single,
-	new Set(),
+	{
+		changeHandler: noChangeHandler,
+		// All multiplicities other than Value support empty.
+		allowsTreeSupersetOf: (types, other) =>
+			fieldKinds.get(other.kind)?.multiplicity !== Multiplicity.Single,
+	},
 );
 
 export const fieldKindConfigurations: ReadonlyMap<
 	ModularChangeFormatVersion,
 	FieldKindConfiguration
 > = new Map([
-	[
-		brand(1),
-		new Map<FieldKindIdentifier, FieldKindConfigurationEntry>([
-			[required.identifier, { kind: required, formatVersion: 1 }],
-			[optional.identifier, { kind: optional, formatVersion: 1 }],
-			[sequence.identifier, { kind: sequence, formatVersion: 1 }],
-			[forbidden.identifier, { kind: forbidden, formatVersion: 1 }],
-			[identifier.identifier, { kind: identifier, formatVersion: 1 }],
-		]),
-	],
-	[
-		brand(2),
-		new Map<FieldKindIdentifier, FieldKindConfigurationEntry>([
-			[required.identifier, { kind: required, formatVersion: 2 }],
-			[optional.identifier, { kind: optional, formatVersion: 2 }],
-			[sequence.identifier, { kind: sequence, formatVersion: 1 }],
-			[forbidden.identifier, { kind: forbidden, formatVersion: 1 }],
-			[identifier.identifier, { kind: identifier, formatVersion: 1 }],
-		]),
-	],
 	[
 		brand(3),
 		new Map<FieldKindIdentifier, FieldKindConfigurationEntry>([
@@ -230,7 +215,7 @@ export const fieldKindConfigurations: ReadonlyMap<
 	],
 ]);
 
-export type ModularChangeFormatVersion = Brand<1 | 2 | 3 | 4, "ModularChangeFormatVersion">;
+export type ModularChangeFormatVersion = Brand<3 | 4, "ModularChangeFormatVersion">;
 export function getCodecTreeForModularChangeFormat(
 	version: ModularChangeFormatVersion,
 ): CodecTree {
@@ -256,7 +241,7 @@ export function getCodecTreeForModularChangeFormat(
  * Before making a SharedTree format change which impacts which set of field kinds are allowed,
  * code which uses this should be audited for compatibility considerations.
  */
-export const fieldKinds: ReadonlyMap<FieldKindIdentifier, FieldKindWithEditor> = new Map(
+export const fieldKinds: ReadonlyMap<FieldKindIdentifier, FlexFieldKind> = new Map(
 	[required, optional, sequence, identifier, forbidden].map((s) => [s.identifier, s]),
 );
 
@@ -265,12 +250,32 @@ export const fieldKinds: ReadonlyMap<FieldKindIdentifier, FieldKindWithEditor> =
 // TODO: Find a way to make docs like {@inheritDoc required} work in vscode.
 // TODO: ensure thy work in generated docs.
 // TODO: add these comments to the rest of the cases below.
-export interface Required extends FlexFieldKind<"Value", Multiplicity.Single> {}
-export interface Optional extends FlexFieldKind<"Optional", Multiplicity.Optional> {}
-export interface Sequence extends FlexFieldKind<"Sequence", Multiplicity.Sequence> {}
-export interface Identifier extends FlexFieldKind<"Identifier", Multiplicity.Single> {}
+export interface Required
+	extends FlexFieldKind<RequiredFieldEditor, typeof requiredIdentifier, Multiplicity.Single> {}
+export interface Optional
+	extends FlexFieldKind<
+		OptionalFieldEditor,
+		typeof optionalIdentifier,
+		Multiplicity.Optional
+	> {}
+export interface Sequence
+	extends FlexFieldKind<
+		SequenceFieldEditor,
+		typeof sequenceIdentifier,
+		Multiplicity.Sequence
+	> {}
+export interface Identifier
+	extends FlexFieldKind<
+		FieldEditor<0>,
+		typeof identifierFieldIdentifier,
+		Multiplicity.Single
+	> {}
 export interface Forbidden
-	extends FlexFieldKind<typeof forbiddenFieldKindIdentifier, Multiplicity.Forbidden> {}
+	extends FlexFieldKind<
+		FieldEditor<0>,
+		typeof forbiddenFieldKindIdentifier,
+		Multiplicity.Forbidden
+	> {}
 
 /**
  * Default FieldKinds with their editor types erased.
@@ -283,3 +288,10 @@ export const FieldKinds: {
 	readonly identifier: Identifier;
 	readonly forbidden: Forbidden;
 } = { required, optional, sequence, identifier, forbidden };
+
+/**
+ * FullSchemaPolicy with the default field kinds.
+ */
+export const defaultSchemaPolicy: FullSchemaPolicy = {
+	fieldKinds,
+};

package/src/feature-libraries/default-schema/index.ts

@@ -14,6 +14,7 @@ export {
 	fieldKindConfigurations,
 	getCodecTreeForModularChangeFormat,
 	type ModularChangeFormatVersion,
+	defaultSchemaPolicy,
 } from "./defaultFieldKinds.js";
 
 export {
@@ -28,13 +29,4 @@ export {
 	relevantRemovedRoots,
 } from "./defaultEditBuilder.js";
 
-export {
-	SchemaValidationError,
-	isNodeInSchema,
-	isFieldInSchema,
-	throwOutOfSchema,
-} from "./schemaChecker.js";
-
-export { defaultSchemaPolicy } from "./defaultSchema.js";
-
 export { MappedEditBuilder } from "./mappedEditBuilder.js";

package/src/feature-libraries/forest-summary/format.ts

@@ -7,7 +7,7 @@ import { type Static, Type } from "@sinclair/typebox";
 
 import { Versioned } from "../../codec/index.js";
 import { schemaFormatV1 } from "../../core/index.js";
-import type { Brand } from "../../util/index.js";
+import { brand, type Brand } from "../../util/index.js";
 
 /**
  * The format version for the forest.
@@ -20,13 +20,19 @@ export type ForestFormatVersion = Brand<
 	"ForestFormatVersion"
 >;
 
-export const Format = Type.Object(
-	{
-		version: Type.Literal(ForestFormatVersion.v1),
-		keys: Type.Array(schemaFormatV1.FieldKeySchema),
-		fields: Versioned,
-	},
-	{ additionalProperties: false },
-);
+const FormatGeneric = (
+	version: ForestFormatVersion,
+	// Return type is intentionally derived.
+	// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+) =>
+	Type.Object(
+		{
+			version: Type.Literal(version),
+			keys: Type.Array(schemaFormatV1.FieldKeySchema),
+			fields: Versioned,
+		},
+		{ additionalProperties: false },
+	);
 
+export const Format = FormatGeneric(brand<ForestFormatVersion>(ForestFormatVersion.v1));
 export type Format = Static<typeof Format>;

package/src/feature-libraries/index.ts

@@ -81,7 +81,6 @@ export {
 	genericFieldKind,
 	type HasFieldChanges,
 	type NodeExistsConstraint,
-	FieldKindWithEditor,
 	ModularChangeFamily,
 	type RelevantRemovedRootsFromChild,
 	EncodedModularChangeset,
@@ -104,7 +103,7 @@ export {
 	defaultChunkPolicy,
 	type FieldBatch,
 	type FieldBatchCodec,
-	type FieldBatchFormatVersion,
+	FieldBatchFormatVersion,
 	getCodecTreeForFieldBatchFormat,
 	makeTreeChunker,
 	makeFieldBatchCodec,
@@ -145,13 +144,16 @@ export {
 	fieldKindConfigurations,
 	intoDelta,
 	relevantRemovedRoots,
+	getCodecTreeForModularChangeFormat,
+	type ModularChangeFormatVersion,
+} from "./default-schema/index.js";
+
+export {
 	SchemaValidationError,
 	isNodeInSchema,
 	isFieldInSchema,
 	throwOutOfSchema,
-	getCodecTreeForModularChangeFormat,
-	type ModularChangeFormatVersion,
-} from "./default-schema/index.js";
+} from "./schemaChecker.js";
 
 export {
 	type FlexTreeOptionalField,

package/src/feature-libraries/modular-schema/comparison.ts

@@ -19,7 +19,6 @@ import {
 import { compareSets } from "../../util/index.js";
 
 import type { FullSchemaPolicy } from "./fieldKind.js";
-import { withEditor } from "./fieldKindWithEditor.js";
 import { isNeverTree } from "./isNeverTree.js";
 
 /**
@@ -133,8 +132,8 @@ export function allowsFieldSuperset(
 	original: TreeFieldStoredSchema,
 	superset: TreeFieldStoredSchema,
 ): boolean {
-	return withEditor(
-		policy.fieldKinds.get(original.kind) ?? fail(0xb1b /* missing kind */),
+	return (
+		policy.fieldKinds.get(original.kind) ?? fail(0xb1b /* missing kind */)
 	).allowsFieldSuperset(policy, originalData, original.types, superset);
 }