@fluid-experimental/tree 0.58.2002 → 0.58.3000-61081

package/README.md

@@ -7,7 +7,7 @@ A [Fluid](https://fluidframework.com/) SharedObject Tree with:
 -   High quality automatic merge resolution
 -   Full History Inspection, Manipulation and Metadata
 
-Revisions of the tree (see [EditLog](.\src\EditLog.ts) and [Snapshot](.\src\Snapshot.ts)) are created from sequences of Edits.
+Revisions of the tree (see [EditLog](./src/EditLog.ts) and [TreeView](./src/TreeView.ts)) are created from sequences of Edits.
 
 Semantically, the current state of the tree is defined as:
 
@@ -22,7 +22,7 @@ The order of the edits is:
 
 ## Tree Abstraction
 
-The tree abstraction used for `SharedTree` is summarized by the [TreeNode](./src/generic/PersistedTypes.ts) class. Nodes have _traits_, a _definition_, an _identity_, and optionally a payload to contain extra arbitrary data.
+The tree abstraction used for `SharedTree` is summarized by the [TreeNode](./src/persisted-types/0.0.2.ts) class. Nodes have _traits_, a _definition_, an _identity_, and optionally a payload to contain extra arbitrary data.
 
 ### Definition
 
@@ -95,10 +95,10 @@ Each operation would be performed in its own `Edit`, which is `SharedTree`'s tra
 If it is undesirable that one of the above operations could fail to apply while the other could succeed, you should instead leverage `Checkout`. A `Checkout`--whose name is inspired from source control--can be thought of as a local view of the `SharedTree` which provides [snapshot isolation](https://en.wikipedia.org/wiki/Snapshot_isolation#:~:text=In%20databases%2C%20and%20transaction%20processing,the%20transaction%20itself%20will%20successfully). Editing the `SharedTree` using a `Checkout` can be done by opening an edit, applying a number of changes, and closing the edit.
 
 ```typescript
-const checkout = new BasicCheckout(tree);
+const checkout = new EagerCheckout(tree);
 checkout.openEdit();
-checkout.applyChanges(Insert.create([fooNode], StablePlace.atStartOf({ parent: initialTree, label: 'foo' })));
-checkout.applyChanges(Insert.create([barNode], StablePlace.atStartOf({ parent: initialTree, label: 'bar' })));
+checkout.applyChanges(Change.insertTree(fooNode, StablePlace.atStartOf({ parent: initialTree, label: 'foo' })));
+checkout.applyChanges(Change.insertTree(barNode, StablePlace.atStartOf({ parent: initialTree, label: 'bar' })));
 checkout.closeEdit();
 ```
 
@@ -125,7 +125,7 @@ SharedTree is in active, but still relatively early development. As such, it is
 
 Implementation-wise:
 
--   Document format may change only in major releases, and SharedTree is committed to backwards compatibility (support for older documents). For more information on this commitment, see the notes in [PersistedTypes.ts](./src/generic/PersistedTypes.ts).
+-   Document format may change only in major releases, and SharedTree is committed to backwards compatibility (support for older documents). For more information on this commitment, see the notes in [persisted-types](./src/persisted-types/README.md).
 -   APIs are not yet stable, and those beyond what's needed for the MVP (ex: history editing and inspection) are not provided yet. Core APIs are not likely to significantly change.
 -   Performance is generally reasonable. However, this assessment was made using integration-style performance tests of consuming applications. Though it's on the road-map, there are currently no rigorous performance tests which are isolated to SharedTree.
 
@@ -137,7 +137,7 @@ Design wise:
 
 # Edits
 
-An `Edit` is the basic unit of transactionality in `SharedTree`. It specifies how to modify a document via a sequence of changes (see [PersistedTypes.ts](.\src\generic\PersistedTypes.ts)). Each edit, when applied to a version of the document (a Snapshot), produces a new version of the document.
+An `Edit` is the basic unit of transactionality in `SharedTree`. It specifies how to modify a document via a sequence of changes (see [persisted-types](./src/persisted-types/0.0.2.ts)). Each edit, when applied to a version of the document (a TreeView), produces a new version of the document.
 
 Once an edit is acknowledged by the Fluid service (and thus it has a sequence number, and will be included in summaries), the version of the document it applies to is fixed: it will not be applied to any revision other than the one produced by its preceding edit.
 There may be operations that will create new edits based on existing ones and apply them in a different context, but these are logically considered new edits.
@@ -164,7 +164,7 @@ For example, two edits could be made concurrently: one that sorts a list alphabe
 Depending on how the sorting structures its changes and exactly where the insert occurred, the sort may or may not conflict if the insert gets acknowledged first.
 In some domains, it would be desired that this conflicts.
 In such domains, a Constraint could be added that would require the list to contain the same set of items as when the sort edit was created for it to apply correctly.
-The Constraint can specify what should happen if violated: see `ConstraintEffect` in [PersistedTypes.ts](.\src\default-edits\PersistedTypes.ts) for details.
+The Constraint can specify what should happen if violated: see `ConstraintEffect` in [persisted-types](./src/persisted-types/0.0.2.ts) for details.
 
 Note that these constraints apply to more than just the case of edits that were made concurrently:
 edits to history also use conflicts (and thus constraints) to prevent historical edits from being re-contextualized in ways that break their semantics.
@@ -183,7 +183,7 @@ Edits are transactional so any invalid change in an edit will cause the entire e
 However, no combination of changes will cause the client to crash.
 Changes go through validation before they are applied and invalid changes are currently dropped.
 
-#### Example
+#### Change Rejection Example
 
 Assuming a tree with a single node, A, a client creates an edit, 1, that inserts a node after node A.
 At the same time another client creates an edit, 2, that deletes node A.

package/dist/ChangeCompression.d.ts

@@ -0,0 +1,39 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { DetachedSequenceId, OpSpaceNodeId } from './Identifiers';
+import { ChangeInternal, CompressedChangeInternal } from './persisted-types';
+import { ContextualizedNodeIdNormalizer } from './NodeIdUtilities';
+import { TreeCompressor } from './TreeCompressor';
+import { StringInterner } from './StringInterner';
+/**
+ * Encapsulates knowledge of how to compress/decompress a change into a compressed change
+ * Compression and decompression each take in a {@link StringInterner} for deduplicating shared strings.
+ * @internal
+ */
+export declare class ChangeCompressor {
+    private readonly treeCompressor;
+    constructor(treeCompressor: TreeCompressor<DetachedSequenceId>);
+    compress<TId extends OpSpaceNodeId>(change: ChangeInternal, interner: StringInterner, idNormalizer: ContextualizedNodeIdNormalizer<TId>): CompressedChangeInternal<TId>;
+    decompress<TId extends OpSpaceNodeId>(change: CompressedChangeInternal<TId>, interner: StringInterner, idNormalizer: ContextualizedNodeIdNormalizer<TId>): ChangeInternal;
+}
+/**
+ * Compresses the provided edit by applying `compressor` to each change and leaving other fields
+ * untouched.
+ */
+export declare function compressEdit<TId extends OpSpaceNodeId, TEdit extends {
+    changes: readonly ChangeInternal[];
+}>(compressor: ChangeCompressor, interner: StringInterner, idNormalizer: ContextualizedNodeIdNormalizer<TId>, edit: TEdit): Omit<TEdit, 'changes'> & {
+    changes: readonly CompressedChangeInternal<TId>[];
+};
+/**
+ * Decompresses the provided edit by applying `compressor` to each change and leaving other fields
+ * untouched.
+ */
+export declare function decompressEdit<TId extends OpSpaceNodeId, TEdit extends {
+    changes: readonly CompressedChangeInternal<TId>[];
+}>(compressor: ChangeCompressor, interner: StringInterner, idNormalizer: ContextualizedNodeIdNormalizer<TId>, edit: TEdit): Omit<TEdit, 'changes'> & {
+    changes: readonly ChangeInternal[];
+};
+//# sourceMappingURL=ChangeCompression.d.ts.map

package/dist/ChangeCompression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChangeCompression.d.ts","sourceRoot":"","sources":["../src/ChangeCompression.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,kBAAkB,EAAU,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAGN,cAAc,EACd,wBAAwB,EAQxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD;;;;GAIG;AACH,qBAAa,gBAAgB;IACT,OAAO,CAAC,QAAQ,CAAC,cAAc;gBAAd,cAAc,EAAE,cAAc,CAAC,kBAAkB,CAAC;IAE/E,QAAQ,CAAC,GAAG,SAAS,aAAa,EACxC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,8BAA8B,CAAC,GAAG,CAAC,GAC/C,wBAAwB,CAAC,GAAG,CAAC;IAiBzB,UAAU,CAAC,GAAG,SAAS,aAAa,EAC1C,MAAM,EAAE,wBAAwB,CAAC,GAAG,CAAC,EACrC,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,8BAA8B,CAAC,GAAG,CAAC,GAC/C,cAAc;CAgBjB;AAmDD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,SAAS,aAAa,EAAE,KAAK,SAAS;IAAE,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;CAAE,EAC3G,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,8BAA8B,CAAC,GAAG,CAAC,EACjD,IAAI,EAAE,KAAK,GACT,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG;IAAE,OAAO,EAAE,SAAS,wBAAwB,CAAC,GAAG,CAAC,EAAE,CAAA;CAAE,CAKhF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC7B,GAAG,SAAS,aAAa,EACzB,KAAK,SAAS;IAAE,OAAO,EAAE,SAAS,wBAAwB,CAAC,GAAG,CAAC,EAAE,CAAA;CAAE,EAEnE,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,8BAA8B,CAAC,GAAG,CAAC,EACjD,IAAI,EAAE,KAAK,GACT,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG;IAAE,OAAO,EAAE,SAAS,cAAc,EAAE,CAAA;CAAE,CAKjE"}

package/dist/ChangeCompression.js

@@ -0,0 +1,117 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decompressEdit = exports.compressEdit = exports.ChangeCompressor = void 0;
+const persisted_types_1 = require("./persisted-types");
+const Common_1 = require("./Common");
+const IdConversion_1 = require("./IdConversion");
+/**
+ * Encapsulates knowledge of how to compress/decompress a change into a compressed change
+ * Compression and decompression each take in a {@link StringInterner} for deduplicating shared strings.
+ * @internal
+ */
+class ChangeCompressor {
+    constructor(treeCompressor) {
+        this.treeCompressor = treeCompressor;
+    }
+    compress(change, interner, idNormalizer) {
+        if (change.type === persisted_types_1.ChangeTypeInternal.Build) {
+            const source = [];
+            for (const node of change.source) {
+                source.push(this.treeCompressor.compress(node, interner, idNormalizer));
+            }
+            const newChange = {
+                destination: change.destination,
+                source,
+                type: persisted_types_1.ChangeTypeInternal.CompressedBuild,
+            };
+            return newChange;
+        }
+        else {
+            return normalizeChange(change, (id) => idNormalizer.normalizeToOpSpace(id));
+        }
+    }
+    decompress(change, interner, idNormalizer) {
+        if (change.type === persisted_types_1.ChangeTypeInternal.CompressedBuild) {
+            const source = [];
+            for (const node of change.source) {
+                source.push(this.treeCompressor.decompress(node, interner, idNormalizer));
+            }
+            const newChange = {
+                destination: change.destination,
+                source,
+                type: persisted_types_1.ChangeTypeInternal.Build,
+            };
+            return newChange;
+        }
+        else {
+            return normalizeChange(change, (id) => idNormalizer.normalizeToSessionSpace(id));
+        }
+    }
+}
+exports.ChangeCompressor = ChangeCompressor;
+function normalizeChange(change, normalizeId) {
+    switch (change.type) {
+        case persisted_types_1.ChangeTypeInternal.Insert: {
+            const insert = {
+                source: change.source,
+                destination: IdConversion_1.convertStablePlaceIds(change.destination, normalizeId),
+                type: persisted_types_1.ChangeTypeInternal.Insert,
+            };
+            return insert;
+        }
+        case persisted_types_1.ChangeTypeInternal.Detach: {
+            const detach = {
+                source: IdConversion_1.convertStableRangeIds(change.source, normalizeId),
+                type: persisted_types_1.ChangeTypeInternal.Detach,
+            };
+            Common_1.copyPropertyIfDefined(change, detach, 'destination');
+            return detach;
+        }
+        case persisted_types_1.ChangeTypeInternal.SetValue: {
+            const setValue = {
+                nodeToModify: normalizeId(change.nodeToModify),
+                payload: change.payload,
+                type: persisted_types_1.ChangeTypeInternal.SetValue,
+            };
+            return setValue;
+        }
+        case persisted_types_1.ChangeTypeInternal.Constraint: {
+            const constraint = {
+                effect: change.effect,
+                toConstrain: IdConversion_1.convertStableRangeIds(change.toConstrain, normalizeId),
+                type: persisted_types_1.ChangeTypeInternal.Constraint,
+            };
+            Common_1.copyPropertyIfDefined(change, constraint, 'contentHash');
+            Common_1.copyPropertyIfDefined(change, constraint, 'identityHash');
+            Common_1.copyPropertyIfDefined(change, constraint, 'label');
+            Common_1.copyPropertyIfDefined(change, constraint, 'length');
+            if (change.parentNode !== undefined) {
+                constraint.parentNode = normalizeId(change.parentNode);
+            }
+            return constraint;
+        }
+        default:
+            Common_1.fail('unexpected change type');
+    }
+}
+/**
+ * Compresses the provided edit by applying `compressor` to each change and leaving other fields
+ * untouched.
+ */
+function compressEdit(compressor, interner, idNormalizer, edit) {
+    return Object.assign(Object.assign({}, edit), { changes: edit.changes.map((change) => compressor.compress(change, interner, idNormalizer)) });
+}
+exports.compressEdit = compressEdit;
+/**
+ * Decompresses the provided edit by applying `compressor` to each change and leaving other fields
+ * untouched.
+ */
+function decompressEdit(compressor, interner, idNormalizer, edit) {
+    return Object.assign(Object.assign({}, edit), { changes: edit.changes.map((change) => compressor.decompress(change, interner, idNormalizer)) });
+}
+exports.decompressEdit = decompressEdit;
+//# sourceMappingURL=ChangeCompression.js.map

package/dist/ChangeCompression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChangeCompression.js","sourceRoot":"","sources":["../src/ChangeCompression.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 { DetachedSequenceId, NodeId, OpSpaceNodeId } from './Identifiers';\nimport {\n\tBuildInternal,\n\tBuildNodeInternal,\n\tChangeInternal,\n\tCompressedChangeInternal,\n\tChangeTypeInternal,\n\tCompressedBuildInternal,\n\tCompressedPlaceholderTree,\n\tInsertInternal,\n\tDetachInternal,\n\tSetValueInternal,\n\tConstraintInternal,\n} from './persisted-types';\nimport { ContextualizedNodeIdNormalizer } from './NodeIdUtilities';\nimport { copyPropertyIfDefined, fail, Mutable, ReplaceRecursive } from './Common';\nimport { TreeCompressor } from './TreeCompressor';\nimport { StringInterner } from './StringInterner';\nimport { convertStablePlaceIds, convertStableRangeIds } from './IdConversion';\n\n/**\n * Encapsulates knowledge of how to compress/decompress a change into a compressed change\n * Compression and decompression each take in a {@link StringInterner} for deduplicating shared strings.\n * @internal\n */\nexport class ChangeCompressor {\n\tpublic constructor(private readonly treeCompressor: TreeCompressor<DetachedSequenceId>) {}\n\n\tpublic compress<TId extends OpSpaceNodeId>(\n\t\tchange: ChangeInternal,\n\t\tinterner: StringInterner,\n\t\tidNormalizer: ContextualizedNodeIdNormalizer<TId>\n\t): CompressedChangeInternal<TId> {\n\t\tif (change.type === ChangeTypeInternal.Build) {\n\t\t\tconst source: CompressedPlaceholderTree<TId, DetachedSequenceId>[] = [];\n\t\t\tfor (const node of change.source) {\n\t\t\t\tsource.push(this.treeCompressor.compress(node, interner, idNormalizer));\n\t\t\t}\n\t\t\tconst newChange: CompressedBuildInternal<TId> = {\n\t\t\t\tdestination: change.destination,\n\t\t\t\tsource,\n\t\t\t\ttype: ChangeTypeInternal.CompressedBuild,\n\t\t\t};\n\t\t\treturn newChange;\n\t\t} else {\n\t\t\treturn normalizeChange(change, (id) => idNormalizer.normalizeToOpSpace(id));\n\t\t}\n\t}\n\n\tpublic decompress<TId extends OpSpaceNodeId>(\n\t\tchange: CompressedChangeInternal<TId>,\n\t\tinterner: StringInterner,\n\t\tidNormalizer: ContextualizedNodeIdNormalizer<TId>\n\t): ChangeInternal {\n\t\tif (change.type === ChangeTypeInternal.CompressedBuild) {\n\t\t\tconst source: BuildNodeInternal[] = [];\n\t\t\tfor (const node of change.source) {\n\t\t\t\tsource.push(this.treeCompressor.decompress(node, interner, idNormalizer));\n\t\t\t}\n\t\t\tconst newChange: BuildInternal = {\n\t\t\t\tdestination: change.destination,\n\t\t\t\tsource,\n\t\t\t\ttype: ChangeTypeInternal.Build,\n\t\t\t};\n\t\t\treturn newChange;\n\t\t} else {\n\t\t\treturn normalizeChange(change, (id) => idNormalizer.normalizeToSessionSpace(id));\n\t\t}\n\t}\n}\n\nfunction normalizeChange<From extends NodeId | OpSpaceNodeId, To extends NodeId | OpSpaceNodeId>(\n\tchange: ReplaceRecursive<Exclude<ChangeInternal, BuildInternal>, NodeId, From>,\n\tnormalizeId: (id: From) => To\n): ReplaceRecursive<Exclude<ChangeInternal, BuildInternal>, NodeId, To> {\n\tswitch (change.type) {\n\t\tcase ChangeTypeInternal.Insert: {\n\t\t\tconst insert: ReplaceRecursive<InsertInternal, NodeId, To> = {\n\t\t\t\tsource: change.source,\n\t\t\t\tdestination: convertStablePlaceIds(change.destination, normalizeId),\n\t\t\t\ttype: ChangeTypeInternal.Insert,\n\t\t\t};\n\t\t\treturn insert;\n\t\t}\n\t\tcase ChangeTypeInternal.Detach: {\n\t\t\tconst detach: ReplaceRecursive<DetachInternal, NodeId, To> = {\n\t\t\t\tsource: convertStableRangeIds(change.source, normalizeId),\n\t\t\t\ttype: ChangeTypeInternal.Detach,\n\t\t\t};\n\t\t\tcopyPropertyIfDefined(change, detach, 'destination');\n\t\t\treturn detach;\n\t\t}\n\t\tcase ChangeTypeInternal.SetValue: {\n\t\t\tconst setValue: ReplaceRecursive<SetValueInternal, NodeId, To> = {\n\t\t\t\tnodeToModify: normalizeId(change.nodeToModify),\n\t\t\t\tpayload: change.payload,\n\t\t\t\ttype: ChangeTypeInternal.SetValue,\n\t\t\t};\n\t\t\treturn setValue;\n\t\t}\n\t\tcase ChangeTypeInternal.Constraint: {\n\t\t\tconst constraint: Mutable<ReplaceRecursive<ConstraintInternal, NodeId, To>> = {\n\t\t\t\teffect: change.effect,\n\t\t\t\ttoConstrain: convertStableRangeIds(change.toConstrain, normalizeId),\n\t\t\t\ttype: ChangeTypeInternal.Constraint,\n\t\t\t};\n\t\t\tcopyPropertyIfDefined(change, constraint, 'contentHash');\n\t\t\tcopyPropertyIfDefined(change, constraint, 'identityHash');\n\t\t\tcopyPropertyIfDefined(change, constraint, 'label');\n\t\t\tcopyPropertyIfDefined(change, constraint, 'length');\n\t\t\tif (change.parentNode !== undefined) {\n\t\t\t\tconstraint.parentNode = normalizeId(change.parentNode);\n\t\t\t}\n\t\t\treturn constraint;\n\t\t}\n\t\tdefault:\n\t\t\tfail('unexpected change type');\n\t}\n}\n\n/**\n * Compresses the provided edit by applying `compressor` to each change and leaving other fields\n * untouched.\n */\nexport function compressEdit<TId extends OpSpaceNodeId, TEdit extends { changes: readonly ChangeInternal[] }>(\n\tcompressor: ChangeCompressor,\n\tinterner: StringInterner,\n\tidNormalizer: ContextualizedNodeIdNormalizer<TId>,\n\tedit: TEdit\n): Omit<TEdit, 'changes'> & { changes: readonly CompressedChangeInternal<TId>[] } {\n\treturn {\n\t\t...edit,\n\t\tchanges: edit.changes.map((change) => compressor.compress(change, interner, idNormalizer)),\n\t};\n}\n\n/**\n * Decompresses the provided edit by applying `compressor` to each change and leaving other fields\n * untouched.\n */\nexport function decompressEdit<\n\tTId extends OpSpaceNodeId,\n\tTEdit extends { changes: readonly CompressedChangeInternal<TId>[] }\n>(\n\tcompressor: ChangeCompressor,\n\tinterner: StringInterner,\n\tidNormalizer: ContextualizedNodeIdNormalizer<TId>,\n\tedit: TEdit\n): Omit<TEdit, 'changes'> & { changes: readonly ChangeInternal[] } {\n\treturn {\n\t\t...edit,\n\t\tchanges: edit.changes.map((change) => compressor.decompress(change, interner, idNormalizer)),\n\t};\n}\n"]}

package/{lib/default-edits/PersistedTypes.d.ts → dist/ChangeTypes.d.ts}

@@ -2,40 +2,18 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { DetachedSequenceId, NodeId, TraitLabel, UuidString } from '../Identifiers';
-import { Side } from '../Snapshot';
-import { EditBase, BuildNode, NodeData, Payload, TraitLocation, TreeNodeSequence } from '../generic';
+import { NodeId, TraitLabel, UuidString } from './Identifiers';
+import { ConstraintEffect, NodeData, Payload, Side, TreeNodeSequence } from './persisted-types';
+import { TraitLocation } from './TreeView';
 /**
- * Types for Edits in Fluid Ops and Fluid summaries.
- *
- * Types describing locations in the tree are stable in the presence of other concurrent edits.
- *
- * All types are compatible with Fluid Serializable.
- *
- * These types can only be modified in ways that are both backwards and forwards compatible since they
- * are used in edits, and thus are persisted (using Fluid serialization).
- *
- * This means these types cannot be changed in any way that impacts their Fluid serialization
- * except through a very careful process:
- *
- * 1. The planned change must support all old data, and maintain the exact semantics of it.
- * This means that the change is pretty much limited to adding optional fields,
- * or making required fields optional.
- * 2. Support for the new format must be deployed to all users (This means all applications using SharedTree must do this),
- * and this deployment must be confirmed to be stable and will not be rolled back.
- * 3. Usage of the new format may start.
- *
- * Support for the old format can NEVER be removed: it must be maintained indefinably or old documents will break.
- * Because this process puts requirements on applications using shared tree,
- * step 3 should only ever be done in a Major version update,
- * and must be explicitly called out in the release notes
- * stating which versions of SharedTree are supported for documents modified by the new version.
- */
-/**
- * The information included in an edit.
+ * An object which may have traits with children of the given type underneath it
  * @public
  */
-export declare type DefaultEditBase = EditBase<Change>;
+export interface HasVariadicTraits<TChild> {
+    readonly traits?: {
+        readonly [key: string]: TChild | TreeNodeSequence<TChild> | undefined;
+    };
+}
 /**
  * The type of a Change
  * @public
@@ -52,10 +30,28 @@ export declare enum ChangeType {
  *
  * `Change` objects can be conveniently constructed with the helper methods exported on a constant of the same name.
  * @example
- * Change.insert(sourceId, destination)
+ * TreeChange.insert(sourceId, destination)
  * @public
  */
 export declare type Change = Insert | Detach | Build | SetValue | Constraint;
+/**
+ * Node or sequence of Nodes for use in a Build change.
+ *
+ * Other formats for sub-sequences of Nodes can be added here, and those formats should be supported in blobs as well.
+ * Future formats will include referenced blobs containing sequences of Nodes,
+ * template based metadata and identity deduplication, and possibly compressed and binary formats.
+ * These optimized formats should also be used within tree views.
+ * @public
+ */
+export declare type BuildNode = BuildTreeNode | number;
+/**
+ * Node for use in a Build change.
+ */
+export interface BuildTreeNode extends HasVariadicTraits<BuildNode> {
+    definition: string;
+    identifier?: NodeId;
+    payload?: Payload;
+}
 /**
  * Constructs a sequence of nodes, associates it with the supplied ID, and stores it for use in later changes.
  * Does not modify the document.
@@ -72,8 +68,8 @@ export declare type Change = Insert | Detach | Build | SetValue | Constraint;
  * @public
  */
 export interface Build {
-    readonly destination: DetachedSequenceId;
-    readonly source: TreeNodeSequence<BuildNode>;
+    readonly destination: number;
+    readonly source: BuildNode | TreeNodeSequence<BuildNode>;
     readonly type: typeof ChangeType.Build;
 }
 /**
@@ -83,7 +79,7 @@ export interface Build {
  */
 export interface Insert {
     readonly destination: StablePlace;
-    readonly source: DetachedSequenceId;
+    readonly source: number;
     readonly type: typeof ChangeType.Insert;
 }
 /**
@@ -94,7 +90,7 @@ export interface Insert {
  * @public
  */
 export interface Detach {
-    readonly destination?: DetachedSequenceId;
+    readonly destination?: number;
     readonly source: StableRange;
     readonly type: typeof ChangeType.Detach;
 }
@@ -167,66 +163,34 @@ export interface Constraint {
      */
     readonly type: typeof ChangeType.Constraint;
 }
-/**
- * What to do when a Constraint is violated.
- * @public
- */
-export declare enum ConstraintEffect {
-    /**
-     * Discard Edit.
-     */
-    InvalidAndDiscard = 0,
-    /**
-     * Discard Edit, but record metadata that application may want to try and recover this change by recreating it.
-     * Should this be the default policy for when another (non Constraint) change is invalid?
-     */
-    InvalidRetry = 1,
-    /**
-     * Apply the change, but flag it for possible reconsideration by the app
-     * (applying it is better than not, but perhaps the high level logic could produce something better).
-     */
-    ValidRetry = 2
-}
 /**
  * @public
  */
 export declare const Change: {
-    build: (source: TreeNodeSequence<BuildNode>, destination: DetachedSequenceId) => Build;
-    insert: (source: DetachedSequenceId, destination: StablePlace) => Insert;
-    detach: (source: StableRange, destination?: DetachedSequenceId | undefined) => Detach;
+    build: (source: BuildNode | TreeNodeSequence<BuildNode>, destination: number) => Build;
+    insert: (source: number, destination: StablePlace) => Insert;
+    detach: (source: StableRange, destination?: number | undefined) => Detach;
     setPayload: (nodeToModify: NodeId, payload: Payload) => SetValue;
     clearPayload: (nodeToModify: NodeId) => SetValue;
-    constraint: (toConstrain: StableRange, effect: ConstraintEffect, identityHash?: UuidString | undefined, length?: number | undefined, contentHash?: UuidString | undefined, parentNode?: NodeId | undefined, label?: TraitLabel | undefined) => Constraint;
-};
-/**
- * Helper for creating a `Delete` edit.
- * @public
- */
-export declare const Delete: {
+    constraint: (toConstrain: StableRange, effect: ConstraintEffect, identityHash?: UuidString | undefined, length?: number | undefined, contentHash?: UuidString | undefined, parentNode?: (number & {
+        readonly LocalCompressedId: "6fccb42f-e2a4-4243-bd29-f13d12b9c6d1";
+    } & import("./Identifiers").SessionUnique & import("./Identifiers").NodeIdBrand) | (number & {
+        readonly FinalCompressedId: "5d83d1e2-98b7-4e4e-a889-54c855cfa73d";
+        readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
+    } & import("./Identifiers").SessionUnique & import("./Identifiers").NodeIdBrand) | undefined, label?: TraitLabel | undefined) => Constraint;
+    /** Helpers for making high-level composite operations */
     /**
-     * @returns a Change that deletes the supplied part of the tree.
+     * @returns a change that deletes the supplied part of the tree.
      */
-    create: (stableRange: StableRange) => Change;
-};
-/**
- * Helper for creating an `Insert` edit.
- * @public
- */
-export declare const Insert: {
+    delete: (stableRange: StableRange) => Change;
     /**
-     * @returns a Change that inserts 'nodes' into the specified location in the tree.
+     * @returns changes that insert 'nodes' into the specified location in the tree.
      */
-    create: (nodes: TreeNodeSequence<BuildNode>, destination: StablePlace) => Change[];
-};
-/**
- * Helper for creating a `Move` edit.
- * @public
- */
-export declare const Move: {
+    insertTree: (nodes: BuildNode | TreeNodeSequence<BuildNode>, destination: StablePlace) => Change[];
     /**
-     * @returns a Change that moves the specified content to a new location in the tree.
+     * @returns changes that moves the specified content to a new location in the tree.
      */
-    create: (source: StableRange, destination: StablePlace) => Change[];
+    move: (source: StableRange, destination: StablePlace) => Change[];
 };
 /**
  * A location in a trait.
@@ -236,8 +200,10 @@ export declare const Move: {
  * To be well formed, either `sibling` or `trait` must be defined, but not both.
  *
  * Any given insertion location can be described by two `StablePlace` objects, one with `Side.After` and one with `Side.Before`.
- * For example, in a trait containing two strings "foo" and "bar", there are 6 places corresponding to 3 places into the trait a new node
- * could be inserted: at the start, before "foo", after "foo", before "bar", after "bar", and at the end.
+ * For example, in a trait containing two strings "foo" and "bar", there are 6 different `StablePlace`s corresponding to 3 locations in the
+ * trait a new node could be inserted: at the start, before "foo", after "foo", before "bar", after "bar", and at the end.
+ * Neither of the two ways to specify the same location are considered to be after each other.
+ *
  * The anchor (`referenceSibling` or `referenceTrait`) used for a particular `StablePlace` can have an impact in collaborative scenarios.
  *
  * `StablePlace` objects can be conveniently constructed with the helper methods exported on a constant of the same name.
@@ -268,6 +234,8 @@ export interface StablePlace {
  * Specifies the range of nodes from `start` to `end` within a trait.
  * Valid iff start and end are valid and are within the same trait and the start does not occur after the end in the trait.
  *
+ * See {@link (StablePlace:interface)} for what it means for a place to be "after" another place.
+ *
  * `StableRange` objects can be conveniently constructed with the helper methods exported on a constant of the same name.
  * @example
  * StableRange.from(StablePlace.before(startNode)).to(StablePlace.after(endNode))
@@ -291,11 +259,11 @@ export declare const StablePlace: {
     /**
      * @returns The location directly before `node`.
      */
-    before: (node: NodeData | NodeId) => StablePlace;
+    before: (node: NodeData<NodeId> | NodeId) => StablePlace;
     /**
      * @returns The location directly after `node`.
      */
-    after: (node: NodeData | NodeId) => StablePlace;
+    after: (node: NodeData<NodeId> | NodeId) => StablePlace;
     /**
      * @returns The location at the start of `trait`.
      */
@@ -321,7 +289,7 @@ export declare const StableRange: {
      * @returns a `StableRange` which contains only the provided `node`.
      * Both the start and end `StablePlace` objects used to anchor this `StableRange` are in terms of the passed in node.
      */
-    only: (node: NodeData | NodeId) => StableRange;
+    only: (node: NodeData<NodeId> | NodeId) => StableRange;
     /**
      * @returns a `StableRange` which contains everything in the trait.
      * This is anchored using the provided `trait`, and is independent of the actual contents of the trait:
@@ -329,14 +297,4 @@ export declare const StableRange: {
      */
     all: (trait: TraitLocation) => StableRange;
 };
-/**
- * @returns True iff the given `node` is of type NodeData.
- * @internal
- */
-export declare function isNodeData(node: NodeData | NodeId): node is NodeData;
-/**
- * @returns The NodeId for a given node or its id.
- * @internal
- */
-export declare function getNodeId(node: NodeData | NodeId): NodeId;
-//# sourceMappingURL=PersistedTypes.d.ts.map
+//# sourceMappingURL=ChangeTypes.d.ts.map

package/dist/ChangeTypes.d.ts.map

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