@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,QAAQ,EAKR,SAAS,EAgCT,YAAY,EACZ,SAAS,EAET,kBAAkB,EAIlB,oBAAoB,EAOpB,4BAA4B,EAG5B,WAAW,EACX,oBAAoB,EAYpB,UAAU,EAKV,iBAAiB,EAMjB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,4BAA4B,GAG5B,MAAM,QAAQ,CAAC;AAEhB,OAAO,EAGN,iBAAiB,EACjB,KAAK,EAOL,IAAI,EAEJ,iBAAiB,EAKjB,UAAU,EACV,aAAa,GAEb,MAAM,QAAQ,CAAC;AAEhB,OAAO,EAIN,aAAa,GAIb,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACN,SAAS,EACT,YAAY,EACZ,YAAY,EAEZ,cAAc,EACd,WAAW,EAIX,iCAAiC,EACjC,mBAAmB,EACnB,sBAAsB,EAGtB,oBAAoB,EAKpB,UAAU,EACV,eAAe,EACf,yBAAyB,IAAI,gBAAgB,EAC7C,mBAAmB,EAInB,wBAAwB,EAExB,UAAU,EAEV,wBAAwB,EAMxB,eAAe,EACf,GAAG,EAGH,sBAAsB,EAItB,eAAe,EAEf,UAAU,EAmBV,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,aAAa,EACb,gBAAgB,EAEhB,iBAAiB,EAIjB,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,kBAAkB,EAKlB,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,GAUpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACN,aAAa,EAGb,uBAAuB,EACvB,QAAQ,GACR,MAAM,eAAe,CAAC;AAEvB,OAAO,EAIN,cAAc,EACd,iBAAiB,EAQjB,UAAU,EAIV,sBAAsB,GAGtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAGN,iBAAiB,EAEjB,aAAa,EACb,IAAI;AAUJ,+BAA+B;AAC/B,SAAS,EACT,eAAe,EACf,eAAe,EACf,iBAAiB;AAEjB,8EAA8E;AAC9E,oBAAoB,EACpB,yBAAyB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAe,MAAM,eAAe,CAAC;AAGrE,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,6FAA6F;AAC7F,OAAO,KAAK,aAAa,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,oKAAoK;AACpK,OAAO,EAIN,WAAW,EAYX,UAAU,GAEV,MAAM,QAAQ,CAAC;AAEhB,OAAO,EAYN,cAAc,EACd,kBAAkB,GAclB,MAAM,qBAAqB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport {\n\tEmptyKey,\n\tFieldKey,\n\tTreeType,\n\tValue,\n\tTreeValue,\n\tAnchorSet,\n\tDetachedField,\n\tUpPath,\n\tRange,\n\tRangeUpPath,\n\tPlaceUpPath,\n\tDetachedRangeUpPath,\n\tDetachedPlaceUpPath,\n\tPlaceIndex,\n\tNodeIndex,\n\tFieldUpPath,\n\tAnchor,\n\tRootField,\n\tChildCollection,\n\tChildLocation,\n\tDeltaVisitor,\n\tAnnouncedVisitor,\n\tFieldMapObject,\n\tNodeData,\n\tGenericTreeNode,\n\tJsonableTree,\n\tProtoNodes,\n\tDeltaRoot,\n\tDeltaProtoNode,\n\tDeltaMark,\n\tDeltaDetachedNodeId,\n\tDeltaFieldMap,\n\tDeltaDetachedNodeChanges,\n\tDeltaDetachedNodeBuild,\n\tDeltaDetachedNodeDestruction,\n\tDeltaDetachedNodeRename,\n\tDeltaFieldChanges,\n\trootFieldKey,\n\trootField,\n\tITreeCursor,\n\tCursorLocationType,\n\tITreeCursorSynchronous,\n\tGenericFieldsNode,\n\tAnchorLocator,\n\tTreeNavigationResult,\n\tIEditableForest,\n\tIForestSubscription,\n\tTreeLocation,\n\tFieldLocation,\n\tForestLocation,\n\tITreeSubscriptionCursor,\n\tITreeSubscriptionCursorState,\n\tTreeNodeSchemaIdentifier,\n\tTreeFieldStoredSchema,\n\tValueSchema,\n\tTreeNodeStoredSchema,\n\tTreeStoredSchemaSubscription,\n\tFieldKindIdentifier,\n\tTreeTypeSet,\n\tTreeStoredSchema,\n\tFieldAnchor,\n\tSchemaEvents,\n\tChangesetLocalId,\n\tForestEvents,\n\tPathRootPrefix,\n\tAnchorSlot,\n\tAnchorNode,\n\tanchorSlot,\n\tUpPathDefault,\n\tAnchorEvents,\n\tAnchorSetRootEvents,\n\tFieldKindSpecifier,\n\tAllowedUpdateType,\n\tPathVisitor,\n\tAdapters,\n\tTreeAdapter,\n\tMapTree,\n\tRevertible,\n\tRevertibleKind,\n\tRevertResult,\n\tDiscardResult,\n\tforbiddenFieldKindIdentifier,\n\tStoredSchemaCollection,\n\tErasedTreeNodeSchemaDataFormat,\n} from \"./core\";\n\nexport {\n\tBrand,\n\tOpaque,\n\textractFromOpaque,\n\tbrand,\n\tValueFromBranded,\n\tNameFromBranded,\n\tJsonCompatibleReadOnly,\n\tJsonCompatible,\n\tJsonCompatibleObject,\n\tNestedMap,\n\tfail,\n\tIdAllocator,\n\tTransactionResult,\n\tBrandedKey,\n\tBrandedMapSubset,\n\tRangeQueryResult,\n\tNamed,\n\toneFromSet,\n\tdisposeSymbol,\n\tIDisposable,\n} from \"./util\";\n\nexport {\n\tEvents,\n\tIsEvent,\n\tISubscribable,\n\tcreateEmitter,\n\tIEmitter,\n\tNoListenersCallback,\n\tHasListeners,\n} from \"./events\";\n\nexport { leaf } from \"./domains\";\n\nexport {\n\tFieldKind,\n\tMultiplicity,\n\tisNeverField,\n\tFullSchemaPolicy,\n\ttypeNameSymbol,\n\tvalueSymbol,\n\tContextuallyTypedNodeDataObject,\n\tContextuallyTypedNodeData,\n\tMarkedArrayLike,\n\tisContextuallyTypedNodeDataObject,\n\tdefaultSchemaPolicy,\n\tjsonableTreeFromCursor,\n\tStableNodeKey,\n\tLocalNodeKey,\n\tcompareLocalNodeKeys,\n\tIDefaultEditBuilder,\n\tValueFieldEditBuilder,\n\tOptionalFieldEditBuilder,\n\tSequenceFieldEditBuilder,\n\tprefixPath,\n\tprefixFieldPath,\n\tcursorForJsonableTreeNode as singleTextCursor,\n\tstackTreeNodeCursor,\n\tCursorAdapter,\n\tCursorWithNode,\n\tEditableTreeEvents,\n\tInternalTypedSchemaTypes,\n\tArrayLikeMut,\n\tFieldKinds,\n\tContextuallyTypedFieldData,\n\tcursorFromContextualData,\n\tAllowedTypes,\n\tTreeNodeSchema as FlexTreeNodeSchema,\n\tFlexTreeSchema,\n\tSchemaLibrary,\n\tSchemaLibraryData,\n\tTreeFieldSchema,\n\tAny,\n\tNewFieldContent,\n\tNodeExistsConstraint,\n\tcursorForTypedTreeData,\n\tLazyTreeNodeSchema,\n\tFieldGenerator,\n\tTreeDataContext,\n\tnodeKeyFieldKey,\n\tSchemaLintConfiguration,\n\tTreeStatus,\n\tFlexTreeFieldNode,\n\tFlexibleFieldContent,\n\tFlexibleNodeContent,\n\tFlexTreeLeafNode,\n\tFlexTreeMapNode,\n\tFlexTreeOptionalField,\n\tFlexTreeRequiredField,\n\tFlexTreeSequenceField,\n\tFlexTreeObjectNode,\n\tFlexTreeObjectNodeTyped,\n\tAssignableFieldKinds,\n\tFlexTreeContext as TreeContext,\n\tFlexTreeTypedField,\n\tFlexTreeTypedNode,\n\tFlexTreeTypedNodeUnion,\n\tFlexTreeEntity,\n\tFlexTreeField,\n\tFlexTreeNode,\n\tTreeNodeSchemaBase,\n\tFieldNodeSchema,\n\tLeafNodeSchema,\n\tMapNodeSchema,\n\tObjectNodeSchema,\n\tCheckTypesOverlap,\n\tSchemaBuilderBase,\n\tImplicitFieldSchema as FlexImplicitFieldSchema,\n\tImplicitAllowedTypes,\n\tUnenforced,\n\tschemaIsFieldNode,\n\tschemaIsLeaf,\n\tschemaIsMap,\n\tschemaIsObjectNode,\n\tAllowedTypeSet,\n\tSchemaBuilderOptions,\n\tTreeEvent,\n\tSchemaCollection,\n\tTreeCompressionStrategy,\n\ttreeSchemaFromStoredSchema,\n\tencodeTreeSchema,\n\tstackTreeFieldCursor,\n\tFlexTreeUnknownUnboxed,\n\tInsertableFlexNode,\n\tInsertableFlexField,\n\tAllowedTypesToFlexInsertableTree,\n\tApplyMultiplicity,\n\tNormalizeObjectNodeFields,\n\tNormalizeFieldSchema,\n\tFields,\n\tMapFieldSchema,\n} from \"./feature-libraries\";\n\nexport {\n\tTreeArrayNode,\n\tTreeMapNodeBase,\n\tUnhydrated,\n\tIterableTreeListContent,\n\tTreeNode,\n} from \"./simple-tree\";\n\nexport {\n\tISharedTree,\n\tITreeCheckout,\n\tITransaction,\n\trunSynchronous,\n\tSharedTreeFactory,\n\tSharedTreeOptions,\n\tITreeCheckoutFork,\n\tCheckoutEvents,\n\tSchematizeConfiguration,\n\tTreeContent,\n\tInitializeAndSchematizeConfiguration,\n\tSchemaConfiguration,\n\tForestType,\n\tSharedTreeContentSnapshot,\n\tFlexTreeView,\n\tITreeViewFork,\n\tbuildTreeConfiguration,\n\tISharedTreeEditor,\n\tISchemaEditor,\n} from \"./shared-tree\";\n\nexport {\n\tITree,\n\tTreeNodeSchema,\n\tTreeConfiguration,\n\tTreeView,\n\tSchemaFactory,\n\tTree,\n\tTreeApi,\n\tImplicitFieldSchema,\n\tTreeFieldFromImplicitField,\n\tTreeNodeEvents,\n\tNodeFromSchema,\n\tTreeMapNode,\n\tInsertableTreeNodeFromImplicitAllowedTypes,\n\tTreeLeafValue,\n\n\t// experimental @internal APIs:\n\tadaptEnum,\n\tenumFromStrings,\n\tsingletonSchema,\n\ttypedObjectValues,\n\n\t// test recursive schema for checking that d.ts files handles schema correctly\n\ttest_RecursiveObject,\n\ttest_RecursiveObject_base,\n} from \"./class-tree\";\nexport { SharedTree, TreeFactory, TreeOptions } from \"./treeFactory\";\n\nexport type { ICodecOptions, JsonValidator, SchemaValidationFunction } from \"./codec\";\nexport { noopValidator } from \"./codec\";\nexport { typeboxValidator } from \"./external-utilities\";\n\n// Below here are things that are used by the above, but not part of the desired API surface.\nimport * as InternalTypes from \"./internal\";\nexport { InternalTypes };\n\n// TODO: When previously tagged '@internal', these types could not be included in `InternalClassTreeTypes` due to https://github.com/microsoft/rushstack/issues/3639\nexport {\n\tInvariant,\n\tContravariant,\n\tCovariant,\n\tBrandedType,\n\tExtractFromOpaque,\n\tAssume,\n\tAllowOptional,\n\tRequiredFields,\n\tOptionalFields,\n\t_InlineTrick,\n\t_RecursiveTrick,\n\tFlattenKeys,\n\tAllowOptionalNotFlattened,\n\tisAny,\n\tBrandedKeyContent,\n\tErasedType,\n\tErased,\n} from \"./util\";\n\nexport {\n\tNormalizeField,\n\tNormalizeAllowedTypes,\n\tFlexTreeTypedFieldInner,\n\tFlexTreeUnboxFieldInner,\n\tFlexTreeObjectNodeFields,\n\tFlexTreeUnboxField,\n\tFlexTreeUnboxNode,\n\tFlexTreeUnboxNodeUnion,\n\tFlexTreeNodeKeyField,\n\tIsArrayOfOne,\n\tFlexibleNodeSubSequence,\n\tflexTreeMarker,\n\tFlexTreeEntityKind,\n\tNodeKeys,\n\tCollectOptions,\n\tTypedFields,\n\tUnbrandedName,\n\tEmptyObject,\n\n\t// These field kind types really only need to show up via FieldKinds.name, and not as top level names in the package.\n\t// These names also are collision prone.\n\tRequired,\n\tOptional,\n\tNodeKeyFieldKind,\n\tForbidden,\n\tSequence,\n} from \"./feature-libraries\";\n"]}

package/lib/internal.d.ts

@@ -0,0 +1,8 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export { MakeNominal, RestrictiveReadonlyRecord } from "./util";
+export { NodeKind, TreeNodeSchemaClass, TreeNodeSchemaNonClass, TreeNodeSchemaCore, InternalClassTreeTypes, } from "./class-tree";
+export { TreeArrayNodeBase } from "./simple-tree";
+//# sourceMappingURL=internal.d.ts.map

package/lib/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AAEhE,OAAO,EACN,QAAQ,EACR,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/lib/internal.js

@@ -0,0 +1,6 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export { NodeKind, InternalClassTreeTypes, } from "./class-tree";
+//# sourceMappingURL=internal.js.map

package/lib/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EACN,QAAQ,EAIR,sBAAsB,GACtB,MAAM,cAAc,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n// Used by public types, but not part of the desired API surface.\nexport { MakeNominal, RestrictiveReadonlyRecord } from \"./util\";\n\nexport {\n\tNodeKind,\n\tTreeNodeSchemaClass,\n\tTreeNodeSchemaNonClass,\n\tTreeNodeSchemaCore,\n\tInternalClassTreeTypes,\n} from \"./class-tree\";\n\nexport { TreeArrayNodeBase } from \"./simple-tree\";\n"]}

package/lib/shared-tree/index.d.ts

@@ -0,0 +1,10 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export { ISharedTree, SharedTreeFactory, SharedTreeOptions, SharedTree, ForestType, SharedTreeContentSnapshot, } from "./sharedTree";
+export { createTreeCheckout, ITreeCheckout, runSynchronous, CheckoutEvents, ITransaction, ITreeCheckoutFork, } from "./treeCheckout";
+export { SchematizeConfiguration, TreeContent, InitializeAndSchematizeConfiguration, SchemaConfiguration, buildTreeConfiguration, } from "./schematizedTree";
+export { FlexTreeView, CheckoutFlexTreeView, ITreeViewFork } from "./treeView";
+export { ISharedTreeEditor, ISchemaEditor } from "./sharedTreeEditBuilder";
+//# sourceMappingURL=index.d.ts.map

package/lib/shared-tree/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shared-tree/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,yBAAyB,GACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,cAAc,EACd,YAAY,EACZ,iBAAiB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACN,uBAAuB,EACvB,WAAW,EACX,oCAAoC,EACpC,mBAAmB,EACnB,sBAAsB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/E,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC"}

package/lib/shared-tree/index.js

@@ -0,0 +1,9 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export { SharedTreeFactory, SharedTree, ForestType, } from "./sharedTree";
+export { createTreeCheckout, runSynchronous, } from "./treeCheckout";
+export { buildTreeConfiguration, } from "./schematizedTree";
+export { CheckoutFlexTreeView } from "./treeView";
+//# sourceMappingURL=index.js.map

package/lib/shared-tree/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shared-tree/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEN,iBAAiB,EAEjB,UAAU,EACV,UAAU,GAEV,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,kBAAkB,EAElB,cAAc,GAId,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAKN,sBAAsB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAgB,oBAAoB,EAAiB,MAAM,YAAY,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport {\n\tISharedTree,\n\tSharedTreeFactory,\n\tSharedTreeOptions,\n\tSharedTree,\n\tForestType,\n\tSharedTreeContentSnapshot,\n} from \"./sharedTree\";\n\nexport {\n\tcreateTreeCheckout,\n\tITreeCheckout,\n\trunSynchronous,\n\tCheckoutEvents,\n\tITransaction,\n\tITreeCheckoutFork,\n} from \"./treeCheckout\";\n\nexport {\n\tSchematizeConfiguration,\n\tTreeContent,\n\tInitializeAndSchematizeConfiguration,\n\tSchemaConfiguration,\n\tbuildTreeConfiguration,\n} from \"./schematizedTree\";\n\nexport { FlexTreeView, CheckoutFlexTreeView, ITreeViewFork } from \"./treeView\";\n\nexport { ISharedTreeEditor, ISchemaEditor } from \"./sharedTreeEditBuilder\";\n"]}

package/lib/shared-tree/schematizedTree.d.ts

@@ -0,0 +1,94 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AllowedUpdateType, ITreeCursorSynchronous } from "../core";
+import { FlexTreeSchema, TreeFieldSchema, InsertableFlexField } from "../feature-libraries";
+import { ISubscribable } from "../events";
+import { CheckoutEvents, ITreeCheckout } from "./treeCheckout";
+/**
+ * Modify `storedSchema` and invoke `setInitialTree` when it's time to set the tree content.
+ *
+ * Requires `storedSchema` to be in its default/empty state.
+ *
+ * This is done in such a way that if the content (implicitly assumed to start empty)
+ * is never out of schema.
+ * This means that if the root field of the new schema requires content (like a value field),
+ * a temporary intermediate schema is used so the initial empty state is not out of schema.
+ *
+ * Since this makes multiple changes, callers may want to wrap it in a transaction.
+ */
+export declare function initializeContent(schemaRepository: {
+    storedSchema: ITreeCheckout["storedSchema"];
+    updateSchema: ITreeCheckout["updateSchema"];
+}, newSchema: FlexTreeSchema, setInitialTree: () => void): void;
+/**
+ * See {@link ISharedTree.schematize} for more details.
+ *
+ * TODO:
+ * - Support adapters for handling out of schema data.
+ * - Handle initialization via an adapter.
+ * - Support per adapter update policy.
+ * - Support lazy schema updates.
+ * - Better error for change to invalid schema approach than throwing on later event.
+ */
+export declare function schematize(events: ISubscribable<CheckoutEvents>, schemaRepository: {
+    storedSchema: ITreeCheckout["storedSchema"];
+    updateSchema: ITreeCheckout["updateSchema"];
+}, config: SchematizeConfiguration): void;
+/**
+ * @param callback - run after a schema change. If returns true, will run after next change as well.
+ */
+export declare function afterSchemaChanges(events: ISubscribable<CheckoutEvents>, schemaRepository: {
+    storedSchema: ITreeCheckout["storedSchema"];
+    updateSchema: ITreeCheckout["updateSchema"];
+}, callback: () => boolean): void;
+/**
+ * View Schema for a `SharedTree`.
+ *
+ * @internal
+ */
+export interface SchemaConfiguration<TRoot extends TreeFieldSchema = TreeFieldSchema> {
+    /**
+     * The schema which the application wants to view the tree with.
+     */
+    readonly schema: FlexTreeSchema<TRoot>;
+}
+/**
+ * Content that can populate a `SharedTree`.
+ *
+ * @internal
+ */
+export interface TreeContent<TRoot extends TreeFieldSchema = TreeFieldSchema> extends SchemaConfiguration<TRoot> {
+    /**
+     * Default tree content to initialize the tree with iff the tree is uninitialized
+     * (meaning it does not even have any schema set at all).
+     */
+    readonly initialTree: InsertableFlexField<TRoot> | readonly ITreeCursorSynchronous[] | ITreeCursorSynchronous;
+}
+/**
+ * Options used to schematize a `SharedTree`.
+ *
+ * @internal
+ */
+export interface SchematizeConfiguration<TRoot extends TreeFieldSchema = TreeFieldSchema> extends SchemaConfiguration<TRoot> {
+    /**
+     * Controls if and how schema from existing documents can be updated to accommodate the view schema.
+     */
+    readonly allowedSchemaModifications: AllowedUpdateType;
+}
+/**
+ * Options used to initialize (if needed) and schematize a `SharedTree`.
+ *
+ * @internal
+ */
+export interface InitializeAndSchematizeConfiguration<TRoot extends TreeFieldSchema = TreeFieldSchema> extends TreeContent<TRoot>, SchematizeConfiguration<TRoot> {
+}
+/**
+ * Options used to initialize (if needed) and schematize a `SharedTree`.
+ * @remarks
+ * Using this builder improves type safety and error quality over just constructing the configuration as a object.
+ * @internal
+ */
+export declare function buildTreeConfiguration<T extends TreeFieldSchema>(config: InitializeAndSchematizeConfiguration<T>): InitializeAndSchematizeConfiguration<T>;
+//# sourceMappingURL=schematizedTree.d.ts.map

package/lib/shared-tree/schematizedTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schematizedTree.d.ts","sourceRoot":"","sources":["../../src/shared-tree/schematizedTree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACN,iBAAiB,EAGjB,sBAAsB,EAEtB,MAAM,SAAS,CAAC;AACjB,OAAO,EAIN,cAAc,EACd,eAAe,EAEf,mBAAmB,EAEnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAChC,gBAAgB,EAAE;IACjB,YAAY,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC5C,YAAY,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CAC5C,EACD,SAAS,EAAE,cAAc,EACzB,cAAc,EAAE,MAAM,IAAI,GACxB,IAAI,CAgDN;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACzB,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,EACrC,gBAAgB,EAAE;IACjB,YAAY,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC5C,YAAY,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CAC5C,EACD,MAAM,EAAE,uBAAuB,GAC7B,IAAI,CAqDN;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,EACrC,gBAAgB,EAAE;IACjB,YAAY,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC5C,YAAY,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;CAC5C,EACD,QAAQ,EAAE,MAAM,OAAO,GACrB,IAAI,CA6BN;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,KAAK,SAAS,eAAe,GAAG,eAAe;IACnF;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,SAAS,eAAe,GAAG,eAAe,CAC3E,SAAQ,mBAAmB,CAAC,KAAK,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EACjB,mBAAmB,CAAC,KAAK,CAAC,GAC1B,SAAS,sBAAsB,EAAE,GACjC,sBAAsB,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB,CAAC,KAAK,SAAS,eAAe,GAAG,eAAe,CACvF,SAAQ,mBAAmB,CAAC,KAAK,CAAC;IAClC;;OAEG;IACH,QAAQ,CAAC,0BAA0B,EAAE,iBAAiB,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,oCAAoC,CACpD,KAAK,SAAS,eAAe,GAAG,eAAe,CAC9C,SAAQ,WAAW,CAAC,KAAK,CAAC,EAC1B,uBAAuB,CAAC,KAAK,CAAC;CAAG;AAEnC;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,eAAe,EAC/D,MAAM,EAAE,oCAAoC,CAAC,CAAC,CAAC,GAC7C,oCAAoC,CAAC,CAAC,CAAC,CAEzC"}

package/lib/shared-tree/schematizedTree.js

@@ -0,0 +1,151 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { assert, unreachableCase } from "@fluidframework/core-utils";
+import { AllowedUpdateType, Compatibility, schemaDataIsEmpty, } from "../core";
+import { defaultSchemaPolicy, FieldKinds, allowsRepoSuperset, ViewSchema, intoStoredSchema, } from "../feature-libraries";
+import { fail } from "../util";
+/**
+ * Modify `storedSchema` and invoke `setInitialTree` when it's time to set the tree content.
+ *
+ * Requires `storedSchema` to be in its default/empty state.
+ *
+ * This is done in such a way that if the content (implicitly assumed to start empty)
+ * is never out of schema.
+ * This means that if the root field of the new schema requires content (like a value field),
+ * a temporary intermediate schema is used so the initial empty state is not out of schema.
+ *
+ * Since this makes multiple changes, callers may want to wrap it in a transaction.
+ */
+export function initializeContent(schemaRepository, newSchema, setInitialTree) {
+    assert(schemaDataIsEmpty(schemaRepository.storedSchema), 0x743 /* cannot initialize after a schema is set */);
+    const schema = intoStoredSchema(newSchema);
+    const rootSchema = schema.rootFieldSchema;
+    const rootKind = rootSchema.kind.identifier;
+    // To keep the data in schema during the update, first define a schema that tolerates the current (empty) tree as well as the final (initial) tree.
+    let incrementalSchemaUpdate;
+    if (rootKind === FieldKinds.sequence.identifier ||
+        rootKind === FieldKinds.optional.identifier) {
+        // These kinds are known to tolerate empty, so use the schema as is:
+        incrementalSchemaUpdate = schema;
+    }
+    else {
+        assert(rootKind === FieldKinds.required.identifier, 0x5c8 /* Unexpected kind */);
+        // Replace value kind with optional kind in root field schema:
+        incrementalSchemaUpdate = {
+            nodeSchema: schema.nodeSchema,
+            rootFieldSchema: {
+                kind: FieldKinds.optional,
+                types: rootSchema.types,
+            },
+        };
+    }
+    // TODO: fix issues with schema comparison and enable this.
+    // assert(
+    // 	allowsRepoSuperset(defaultSchemaPolicy, tree.storedSchema, incrementalSchemaUpdate),
+    // 	"Incremental Schema update should support the existing empty tree",
+    // );
+    assert(allowsRepoSuperset(defaultSchemaPolicy, schema, incrementalSchemaUpdate), 0x5c9 /* Incremental Schema during update should be a allow a superset of the final schema */);
+    // Update to intermediate schema
+    schemaRepository.updateSchema(incrementalSchemaUpdate);
+    // Insert initial tree
+    setInitialTree();
+    // If intermediate schema is not final desired schema, update to the final schema:
+    if (incrementalSchemaUpdate !== schema) {
+        schemaRepository.updateSchema(schema);
+    }
+}
+/**
+ * See {@link ISharedTree.schematize} for more details.
+ *
+ * TODO:
+ * - Support adapters for handling out of schema data.
+ * - Handle initialization via an adapter.
+ * - Support per adapter update policy.
+ * - Support lazy schema updates.
+ * - Better error for change to invalid schema approach than throwing on later event.
+ */
+export function schematize(events, schemaRepository, config) {
+    // TODO: support adapters and include them here.
+    const viewSchema = new ViewSchema(defaultSchemaPolicy, {}, config.schema);
+    {
+        const compatibility = viewSchema.checkCompatibility(schemaRepository.storedSchema);
+        switch (config.allowedSchemaModifications) {
+            case AllowedUpdateType.None: {
+                if (compatibility.read !== Compatibility.Compatible) {
+                    fail("Existing stored schema permits trees which are incompatible with the view schema");
+                }
+                if (compatibility.write !== Compatibility.Compatible) {
+                    // TODO: support readonly mode in this case.
+                    fail("View schema permits trees which are incompatible with the stored schema");
+                }
+                break;
+            }
+            case AllowedUpdateType.SchemaCompatible: {
+                if (compatibility.read !== Compatibility.Compatible) {
+                    fail("Existing stored schema permits trees which are incompatible with the view schema, so schema can not be updated");
+                }
+                if (compatibility.write !== Compatibility.Compatible) {
+                    schemaRepository.updateSchema(intoStoredSchema(config.schema));
+                }
+                break;
+            }
+            default: {
+                unreachableCase(config.allowedSchemaModifications);
+            }
+        }
+    }
+    afterSchemaChanges(events, schemaRepository, () => {
+        const compatibility = viewSchema.checkCompatibility(schemaRepository.storedSchema);
+        if (compatibility.read !== Compatibility.Compatible) {
+            fail("Stored schema changed to one that permits data incompatible with the view schema");
+        }
+        if (compatibility.write !== Compatibility.Compatible) {
+            // TODO: support readonly mode in this case.
+            fail("Stored schema changed to one that does not support all data allowed by view schema");
+        }
+        return true;
+    });
+}
+/**
+ * @param callback - run after a schema change. If returns true, will run after next change as well.
+ */
+export function afterSchemaChanges(events, schemaRepository, callback) {
+    // Callback to cleanup afterBatch schema checking.
+    // Set only when such a callback is pending.
+    let afterBatchCheck;
+    // TODO: errors thrown by this will usually be in response to remote edits, and thus may not surface to the app.
+    // Two fixes should be done related to this:
+    // 1. Ensure errors in response to edits like this crash app and report telemetry.
+    // 2. Replace these (and the above) exception based errors with
+    // out of schema handlers which update the schematized view of the tree instead of throwing.
+    const unregister = schemaRepository.storedSchema.on("afterSchemaChange", () => {
+        // On schema change, setup a callback (deduplicated so its only run once) after a batch of changes.
+        // This avoids erroring about invalid schema in the middle of a batch of changes.
+        // TODO:
+        // Ideally this would run at the end of the batch containing the schema change, but currently schema changes don't trigger afterBatch.
+        // Fortunately this works out ok, since the tree can't actually become out of schema until its actually edited, which should trigger after batch.
+        // When batching properly handles schema edits, this documentation and related tests should be updated.
+        // TODO:
+        // With the the updated incremental batch application policy, this behavior is not valid.
+        afterBatchCheck ?? (afterBatchCheck = events.on("afterBatch", () => {
+            assert(afterBatchCheck !== undefined, 0x728 /* unregistered event ran */);
+            afterBatchCheck();
+            afterBatchCheck = undefined;
+            if (!callback()) {
+                unregister();
+            }
+        }));
+    });
+}
+/**
+ * Options used to initialize (if needed) and schematize a `SharedTree`.
+ * @remarks
+ * Using this builder improves type safety and error quality over just constructing the configuration as a object.
+ * @internal
+ */
+export function buildTreeConfiguration(config) {
+    return config;
+}
+//# sourceMappingURL=schematizedTree.js.map

package/lib/shared-tree/schematizedTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schematizedTree.js","sourceRoot":"","sources":["../../src/shared-tree/schematizedTree.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert, unreachableCase } from \"@fluidframework/core-utils\";\nimport {\n\tAllowedUpdateType,\n\tCompatibility,\n\tTreeStoredSchema,\n\tITreeCursorSynchronous,\n\tschemaDataIsEmpty,\n} from \"../core\";\nimport {\n\tdefaultSchemaPolicy,\n\tFieldKinds,\n\tallowsRepoSuperset,\n\tFlexTreeSchema,\n\tTreeFieldSchema,\n\tViewSchema,\n\tInsertableFlexField,\n\tintoStoredSchema,\n} from \"../feature-libraries\";\nimport { fail } from \"../util\";\nimport { ISubscribable } from \"../events\";\nimport { CheckoutEvents, ITreeCheckout } from \"./treeCheckout\";\n\n/**\n * Modify `storedSchema` and invoke `setInitialTree` when it's time to set the tree content.\n *\n * Requires `storedSchema` to be in its default/empty state.\n *\n * This is done in such a way that if the content (implicitly assumed to start empty)\n * is never out of schema.\n * This means that if the root field of the new schema requires content (like a value field),\n * a temporary intermediate schema is used so the initial empty state is not out of schema.\n *\n * Since this makes multiple changes, callers may want to wrap it in a transaction.\n */\nexport function initializeContent(\n\tschemaRepository: {\n\t\tstoredSchema: ITreeCheckout[\"storedSchema\"];\n\t\tupdateSchema: ITreeCheckout[\"updateSchema\"];\n\t},\n\tnewSchema: FlexTreeSchema,\n\tsetInitialTree: () => void,\n): void {\n\tassert(\n\t\tschemaDataIsEmpty(schemaRepository.storedSchema),\n\t\t0x743 /* cannot initialize after a schema is set */,\n\t);\n\n\tconst schema = intoStoredSchema(newSchema);\n\tconst rootSchema = schema.rootFieldSchema;\n\tconst rootKind = rootSchema.kind.identifier;\n\n\t// To keep the data in schema during the update, first define a schema that tolerates the current (empty) tree as well as the final (initial) tree.\n\tlet incrementalSchemaUpdate: TreeStoredSchema;\n\tif (\n\t\trootKind === FieldKinds.sequence.identifier ||\n\t\trootKind === FieldKinds.optional.identifier\n\t) {\n\t\t// These kinds are known to tolerate empty, so use the schema as is:\n\t\tincrementalSchemaUpdate = schema;\n\t} else {\n\t\tassert(rootKind === FieldKinds.required.identifier, 0x5c8 /* Unexpected kind */);\n\t\t// Replace value kind with optional kind in root field schema:\n\t\tincrementalSchemaUpdate = {\n\t\t\tnodeSchema: schema.nodeSchema,\n\t\t\trootFieldSchema: {\n\t\t\t\tkind: FieldKinds.optional,\n\t\t\t\ttypes: rootSchema.types,\n\t\t\t},\n\t\t};\n\t}\n\n\t// TODO: fix issues with schema comparison and enable this.\n\t// assert(\n\t// \tallowsRepoSuperset(defaultSchemaPolicy, tree.storedSchema, incrementalSchemaUpdate),\n\t// \t\"Incremental Schema update should support the existing empty tree\",\n\t// );\n\tassert(\n\t\tallowsRepoSuperset(defaultSchemaPolicy, schema, incrementalSchemaUpdate),\n\t\t0x5c9 /* Incremental Schema during update should be a allow a superset of the final schema */,\n\t);\n\t// Update to intermediate schema\n\tschemaRepository.updateSchema(incrementalSchemaUpdate);\n\t// Insert initial tree\n\tsetInitialTree();\n\n\t// If intermediate schema is not final desired schema, update to the final schema:\n\tif (incrementalSchemaUpdate !== schema) {\n\t\tschemaRepository.updateSchema(schema);\n\t}\n}\n\n/**\n * See {@link ISharedTree.schematize} for more details.\n *\n * TODO:\n * - Support adapters for handling out of schema data.\n * - Handle initialization via an adapter.\n * - Support per adapter update policy.\n * - Support lazy schema updates.\n * - Better error for change to invalid schema approach than throwing on later event.\n */\nexport function schematize(\n\tevents: ISubscribable<CheckoutEvents>,\n\tschemaRepository: {\n\t\tstoredSchema: ITreeCheckout[\"storedSchema\"];\n\t\tupdateSchema: ITreeCheckout[\"updateSchema\"];\n\t},\n\tconfig: SchematizeConfiguration,\n): void {\n\t// TODO: support adapters and include them here.\n\tconst viewSchema = new ViewSchema(defaultSchemaPolicy, {}, config.schema);\n\t{\n\t\tconst compatibility = viewSchema.checkCompatibility(schemaRepository.storedSchema);\n\t\tswitch (config.allowedSchemaModifications) {\n\t\t\tcase AllowedUpdateType.None: {\n\t\t\t\tif (compatibility.read !== Compatibility.Compatible) {\n\t\t\t\t\tfail(\n\t\t\t\t\t\t\"Existing stored schema permits trees which are incompatible with the view schema\",\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\tif (compatibility.write !== Compatibility.Compatible) {\n\t\t\t\t\t// TODO: support readonly mode in this case.\n\t\t\t\t\tfail(\"View schema permits trees which are incompatible with the stored schema\");\n\t\t\t\t}\n\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tcase AllowedUpdateType.SchemaCompatible: {\n\t\t\t\tif (compatibility.read !== Compatibility.Compatible) {\n\t\t\t\t\tfail(\n\t\t\t\t\t\t\"Existing stored schema permits trees which are incompatible with the view schema, so schema can not be updated\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tif (compatibility.write !== Compatibility.Compatible) {\n\t\t\t\t\tschemaRepository.updateSchema(intoStoredSchema(config.schema));\n\t\t\t\t}\n\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tdefault: {\n\t\t\t\tunreachableCase(config.allowedSchemaModifications);\n\t\t\t}\n\t\t}\n\t}\n\tafterSchemaChanges(events, schemaRepository, () => {\n\t\tconst compatibility = viewSchema.checkCompatibility(schemaRepository.storedSchema);\n\t\tif (compatibility.read !== Compatibility.Compatible) {\n\t\t\tfail(\n\t\t\t\t\"Stored schema changed to one that permits data incompatible with the view schema\",\n\t\t\t);\n\t\t}\n\n\t\tif (compatibility.write !== Compatibility.Compatible) {\n\t\t\t// TODO: support readonly mode in this case.\n\t\t\tfail(\n\t\t\t\t\"Stored schema changed to one that does not support all data allowed by view schema\",\n\t\t\t);\n\t\t}\n\t\treturn true;\n\t});\n}\n\n/**\n * @param callback - run after a schema change. If returns true, will run after next change as well.\n */\nexport function afterSchemaChanges(\n\tevents: ISubscribable<CheckoutEvents>,\n\tschemaRepository: {\n\t\tstoredSchema: ITreeCheckout[\"storedSchema\"];\n\t\tupdateSchema: ITreeCheckout[\"updateSchema\"];\n\t},\n\tcallback: () => boolean,\n): void {\n\t// Callback to cleanup afterBatch schema checking.\n\t// Set only when such a callback is pending.\n\tlet afterBatchCheck: undefined | (() => void);\n\n\t// TODO: errors thrown by this will usually be in response to remote edits, and thus may not surface to the app.\n\t// Two fixes should be done related to this:\n\t// 1. Ensure errors in response to edits like this crash app and report telemetry.\n\t// 2. Replace these (and the above) exception based errors with\n\t// out of schema handlers which update the schematized view of the tree instead of throwing.\n\tconst unregister = schemaRepository.storedSchema.on(\"afterSchemaChange\", () => {\n\t\t// On schema change, setup a callback (deduplicated so its only run once) after a batch of changes.\n\t\t// This avoids erroring about invalid schema in the middle of a batch of changes.\n\t\t// TODO:\n\t\t// Ideally this would run at the end of the batch containing the schema change, but currently schema changes don't trigger afterBatch.\n\t\t// Fortunately this works out ok, since the tree can't actually become out of schema until its actually edited, which should trigger after batch.\n\t\t// When batching properly handles schema edits, this documentation and related tests should be updated.\n\t\t// TODO:\n\t\t// With the the updated incremental batch application policy, this behavior is not valid.\n\t\tafterBatchCheck ??= events.on(\"afterBatch\", () => {\n\t\t\tassert(afterBatchCheck !== undefined, 0x728 /* unregistered event ran */);\n\t\t\tafterBatchCheck();\n\t\t\tafterBatchCheck = undefined;\n\n\t\t\tif (!callback()) {\n\t\t\t\tunregister();\n\t\t\t}\n\t\t});\n\t});\n}\n\n/**\n * View Schema for a `SharedTree`.\n *\n * @internal\n */\nexport interface SchemaConfiguration<TRoot extends TreeFieldSchema = TreeFieldSchema> {\n\t/**\n\t * The schema which the application wants to view the tree with.\n\t */\n\treadonly schema: FlexTreeSchema<TRoot>;\n}\n\n/**\n * Content that can populate a `SharedTree`.\n *\n * @internal\n */\nexport interface TreeContent<TRoot extends TreeFieldSchema = TreeFieldSchema>\n\textends SchemaConfiguration<TRoot> {\n\t/**\n\t * Default tree content to initialize the tree with iff the tree is uninitialized\n\t * (meaning it does not even have any schema set at all).\n\t */\n\treadonly initialTree:\n\t\t| InsertableFlexField<TRoot>\n\t\t| readonly ITreeCursorSynchronous[]\n\t\t| ITreeCursorSynchronous;\n}\n\n/**\n * Options used to schematize a `SharedTree`.\n *\n * @internal\n */\nexport interface SchematizeConfiguration<TRoot extends TreeFieldSchema = TreeFieldSchema>\n\textends SchemaConfiguration<TRoot> {\n\t/**\n\t * Controls if and how schema from existing documents can be updated to accommodate the view schema.\n\t */\n\treadonly allowedSchemaModifications: AllowedUpdateType;\n}\n\n/**\n * Options used to initialize (if needed) and schematize a `SharedTree`.\n *\n * @internal\n */\nexport interface InitializeAndSchematizeConfiguration<\n\tTRoot extends TreeFieldSchema = TreeFieldSchema,\n> extends TreeContent<TRoot>,\n\t\tSchematizeConfiguration<TRoot> {}\n\n/**\n * Options used to initialize (if needed) and schematize a `SharedTree`.\n * @remarks\n * Using this builder improves type safety and error quality over just constructing the configuration as a object.\n * @internal\n */\nexport function buildTreeConfiguration<T extends TreeFieldSchema>(\n\tconfig: InitializeAndSchematizeConfiguration<T>,\n): InitializeAndSchematizeConfiguration<T> {\n\treturn config;\n}\n"]}

package/lib/shared-tree/sharedTree.d.ts

@@ -0,0 +1,143 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { IChannelAttributes, IChannelFactory, IChannelServices, IChannelStorageService, IFluidDataStoreRuntime } from "@fluidframework/datastore-definitions";
+import { ISharedObject } from "@fluidframework/shared-object-base";
+import { ICodecOptions } from "../codec";
+import { FieldKey, TreeStoredSchemaRepository, JsonableTree, TreeStoredSchema } from "../core";
+import { SharedTreeCore } from "../shared-tree-core";
+import { TreeFieldSchema, TreeCompressionStrategy, FlexTreeSchema, NodeKeyManager } from "../feature-libraries";
+import { ITree, TreeConfiguration, ImplicitFieldSchema, TreeFieldFromImplicitField, TreeView } from "../class-tree";
+import { InitializeAndSchematizeConfiguration } from "./schematizedTree";
+import { TreeCheckout } from "./treeCheckout";
+import { FlexTreeView, CheckoutFlexTreeView } from "./treeView";
+import { SharedTreeChange } from "./sharedTreeChangeTypes";
+import { SharedTreeEditBuilder } from "./sharedTreeEditBuilder";
+/**
+ * Copy of data from an {@link ISharedTree} at some point in time.
+ * @remarks
+ * This is unrelated to Fluids concept of "snapshots".
+ * @internal
+ */
+export interface SharedTreeContentSnapshot {
+    /**
+     * The schema stored in the document.
+     *
+     * @remarks
+     * Edits to the schema can mutate the schema stored of the tree which took this snapshot (but this snapshot will remain the same)
+     * This is mainly useful for debugging cases where schematize reports an incompatible view schema.
+     */
+    readonly schema: TreeStoredSchema;
+    /**
+     * All {@link TreeStatus#InDocument} content.
+     */
+    readonly tree: JsonableTree[];
+    /**
+     * All {@link TreeStatus#Removed} content.
+     */
+    readonly removed: [string | number | undefined, number, JsonableTree][];
+}
+/**
+ * Collaboratively editable tree distributed data-structure,
+ * powered by {@link @fluidframework/shared-object-base#ISharedObject}.
+ *
+ * See [the README](../../README.md) for details.
+ * @internal
+ */
+export interface ISharedTree extends ISharedObject, ITree {
+    /**
+     * Provides a copy of the current content of the tree.
+     * This can be useful for inspecting the tree when no suitable view schema is available.
+     * This is only intended for use in testing and exceptional code paths: it is not performant.
+     *
+     * This does not include everything that is included in a tree summary, since information about how to merge future edits is omitted.
+     */
+    contentSnapshot(): SharedTreeContentSnapshot;
+    /**
+     * Like {@link ITree.schematize}, but uses the flex-tree schema system and exposes the tree as a flex-tree.
+     * @privateRemarks
+     * This has to avoid its name colliding with `schematize`.
+     * TODO: Either ITree and ISharedTree should be split into separate objects, the methods should be merged or a better convention for resolving such name conflicts should be selected.
+     */
+    schematizeInternal<TRoot extends TreeFieldSchema>(config: InitializeAndSchematizeConfiguration<TRoot>): FlexTreeView<TRoot>;
+    /**
+     * Like {@link ISharedTree.schematizeInternal}, but will never modify the document.
+     *
+     * @param schema - The view schema to use.
+     * @param onSchemaIncompatible - A callback.
+     * Invoked when the returned ISharedTreeView becomes invalid to use due to a change to the stored schema which makes it incompatible with the view schema.
+     * Called at most once.
+     * @returns a view compatible with the provided schema, or undefined if the stored schema is not compatible with the provided view schema.
+     * If this becomes invalid to use due to a change in the stored schema, onSchemaIncompatible will be invoked.
+     *
+     * @privateRemarks
+     * TODO:
+     * Once views actually have a view schema, onSchemaIncompatible can become an event on the view (which ends its lifetime),
+     * instead of a separate callback.
+     */
+    requireSchema<TRoot extends TreeFieldSchema>(schema: FlexTreeSchema<TRoot>, onSchemaIncompatible: () => void): FlexTreeView<TRoot> | undefined;
+}
+/**
+ * Shared tree, configured with a good set of indexes and field kinds which will maintain compatibility over time.
+ *
+ * TODO: detail compatibility requirements.
+ */
+export declare class SharedTree extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange> implements ISharedTree {
+    private readonly _events;
+    readonly view: TreeCheckout;
+    get storedSchema(): TreeStoredSchemaRepository;
+    /**
+     * Creating multiple editable tree contexts for the same branch, and thus with the same underlying AnchorSet does not work due to how TreeNode caching works.
+     * This flag is used to detect if one already exists for the main branch and error if creating a second.
+     * THis should catch most accidental violations of this restriction but there are still ways to create two conflicting contexts (for example calling constructing one manually).
+     *
+     * TODO:
+     * 1. API docs need to reflect this limitation or the limitation has to be removed.
+     */
+    private hasView2;
+    constructor(id: string, runtime: IFluidDataStoreRuntime, attributes: IChannelAttributes, optionsParam: SharedTreeOptions, telemetryContextPrefix: string);
+    requireSchema<TRoot extends TreeFieldSchema>(schema: FlexTreeSchema<TRoot>, onSchemaIncompatible: () => void, nodeKeyManager?: NodeKeyManager, nodeKeyFieldKey?: FieldKey): CheckoutFlexTreeView<TRoot> | undefined;
+    contentSnapshot(): SharedTreeContentSnapshot;
+    schematizeInternal<TRoot extends TreeFieldSchema>(config: InitializeAndSchematizeConfiguration<TRoot>, nodeKeyManager?: NodeKeyManager, nodeKeyFieldKey?: FieldKey): CheckoutFlexTreeView<TRoot>;
+    schematize<TRoot extends ImplicitFieldSchema>(config: TreeConfiguration<TRoot>): TreeView<TreeFieldFromImplicitField<TRoot>>;
+    protected loadCore(services: IChannelStorageService): Promise<void>;
+}
+/**
+ * @internal
+ */
+export interface SharedTreeOptions extends Partial<ICodecOptions> {
+    /**
+     * The {@link ForestType} indicating which forest type should be created for the SharedTree.
+     */
+    forest?: ForestType;
+    summaryEncodeType?: TreeCompressionStrategy;
+}
+/**
+ * Used to distinguish between different forest types.
+ * @internal
+ */
+export declare enum ForestType {
+    /**
+     * The "ObjectForest" forest type.
+     */
+    Reference = 0,
+    /**
+     * The "ChunkedForest" forest type.
+     */
+    Optimized = 1
+}
+export declare const defaultSharedTreeOptions: Required<SharedTreeOptions>;
+/**
+ * A channel factory that creates {@link ISharedTree}s.
+ * @internal
+ */
+export declare class SharedTreeFactory implements IChannelFactory {
+    private readonly options;
+    readonly type: string;
+    readonly attributes: IChannelAttributes;
+    constructor(options?: SharedTreeOptions);
+    load(runtime: IFluidDataStoreRuntime, id: string, services: IChannelServices, channelAttributes: Readonly<IChannelAttributes>): Promise<ISharedTree>;
+    create(runtime: IFluidDataStoreRuntime, id: string): ISharedTree;
+}
+//# sourceMappingURL=sharedTree.d.ts.map

package/lib/shared-tree/sharedTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedTree.d.ts","sourceRoot":"","sources":["../../src/shared-tree/sharedTree.ts"],"names":[],"mappings":"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"}