@fluid-experimental/tree 0.58.3000-61081 → 0.59.2000-61729

package/dist/SharedTree.js

@@ -24,7 +24,6 @@ const RevisionView_1 = require("./RevisionView");
 const SharedTreeEncoder_1 = require("./SharedTreeEncoder");
 const HistoryEditFactory_1 = require("./HistoryEditFactory");
 const ChangeTypes_1 = require("./ChangeTypes");
-const TransactionInternal_1 = require("./TransactionInternal");
 const id_compressor_1 = require("./id-compressor");
 const IdConversion_1 = require("./IdConversion");
 const StringInterner_1 = require("./StringInterner");
@@ -36,13 +35,10 @@ const StringInterner_1 = require("./StringInterner");
 class SharedTreeFactory {
     /**
      * Get a factory for SharedTree to register with the data store.
-     * @param writeFormat - Determines the format version the SharedTree will write summaries in.
-     * This format may be updated to a newer (supported) version at runtime if a collaborating shared-tree
-     * that was initialized with a newer write version connects to the session. Care must be taken when changing this value,
-     * as a staged rollout must have occurred such that all collaborating clients must have the code to read at least the version
-     * written.
+     * @param writeFormat - Determines the format version the SharedTree will write ops and summaries in. See [the write format
+     * documentation](../docs/Write-Format.md) for more information.
      * @param summarizeHistory - Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
-     * See docs/Breaking-Change-Migration for more details on this scheme.
+     * See the [breaking change migration documentation](docs/Breaking-Change-Migration) for more details on this scheme.
      * @param expensiveValidation - Enables expensive asserts on SharedTree.
      * @returns A factory that creates `SharedTree`s and loads them from storage.
      */
@@ -110,7 +106,7 @@ const snapshotFileName = 'header';
 const sortedWriteVersions = [persisted_types_1.WriteFormat.v0_0_2, persisted_types_1.WriteFormat.v0_1_1];
 const sharedTreeTelemetryProperties = { all: { isSharedTreeEvent: true } };
 /**
- * A distributed tree.
+ * A [distributed tree](../Readme.md).
  * @public
  */
 class SharedTree extends shared_object_base_1.SharedObject {
@@ -118,7 +114,8 @@ class SharedTree extends shared_object_base_1.SharedObject {
      * Create a new SharedTreeFactory.
      * @param runtime - The runtime the SharedTree will be associated with
      * @param id - Unique ID for the SharedTree
-     * @param writeFormat - Determines the format version the SharedTree will write summaries in.
+     * @param writeFormat - Determines the format version the SharedTree will write ops and summaries in. See [the write format
+     * documentation](../docs/Write-Format.md) for more information.
      * @param summarizeHistory - Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
      * @param expensiveValidation - Enable expensive asserts.
      */
@@ -152,7 +149,6 @@ class SharedTree extends shared_object_base_1.SharedObject {
             };
             this.emit(EventTypes_1.SharedTreeEvent.SequencedEditApplied, eventArguments);
         };
-        this.transactionFactory = TransactionInternal_1.TransactionInternal.factory;
         /**
          * Re-computes currentIsOldest and emits an event if it has changed.
          * TODO:#55900: Get rid of copy-pasted OldestClientObserver code
@@ -202,6 +198,7 @@ class SharedTree extends shared_object_base_1.SharedObject {
     /**
      * Get a factory for SharedTree to register with the data store.
      * @param summarizeHistory - Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
+     *
      * On 0.1.1 documents, due to current code limitations, this parameter is only impactful for newly created documents.
      * `SharedTree`s which load existing documents will summarize history if and only if the loaded summary included history.
      *
@@ -209,14 +206,19 @@ class SharedTree extends shared_object_base_1.SharedObject {
      * In the future we may allow modification of whether or not a particular document saves history, but only via a consensus mechanism.
      * See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
      * See docs/Breaking-Change-Migration for more details on the consensus scheme.
-     * @param writeFormat - Determines the format version the SharedTree will write summaries in.
+     * @param writeFormat - Determines the format version the SharedTree will write ops and summaries in.
      * This format may be updated to a newer (supported) version at runtime if a collaborating shared-tree
      * that was initialized with a newer write version connects to the session. Care must be taken when changing this value,
      * as a staged rollout must of occurred such that all collaborating clients must have the code to read at least the version
      * written.
+     * See [the write format documentation](../docs/Write-Format.md) for more information.
      * @returns A factory that creates `SharedTree`s and loads them from storage.
      */
     static getFactory(writeFormat, summarizeHistory = false) {
+        // 	On 0.1.1 documents, due to current code limitations, all clients MUST agree on the value of `summarizeHistory`.
+        //  Note that this means staged rollout changing this value should not be attempted.
+        //  It is possible to update shared-tree to correctly handle such a staged rollout, but that hasn't been implemented.
+        //  See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
         return new SharedTreeFactory(writeFormat, summarizeHistory);
     }
     /**
@@ -264,27 +266,60 @@ class SharedTree extends shared_object_base_1.SharedObject {
         return this.logViewer.getRevisionViewInSession(Number.POSITIVE_INFINITY);
     }
     /**
-     * {@inheritdoc NodeIdGenerator.generateNodeId}
+     * Generates a node identifier.
+     * The returned IDs may be used as the identifier of a node in the SharedTree.
+     * `NodeId`s are *always* unique and stable within the scope of the tree and session that generated them. They are *not* unique within
+     * a Fluid container, and *cannot* be compared across instances of a SharedTree. They are *not* stable across sessions/lifetimes of a
+     * SharedTree, and *cannot* be persisted (e.g. stored in payloads, uploaded in blobs, etc.). If stable persistence is needed,
+     * NodeIdConverter.convertToStableNodeId may be used to return a corresponding UUID that is globally unique and stable.
+     * @param override - if supplied, calls to `convertToStableNodeId` using the returned node ID will return the override instead of
+     * the UUID. Calls to `generateNodeId` with the same override always return the same ID. Performance note: passing an override string
+     * incurs a storage cost that is significantly higher that a node ID without one, and should be avoided if possible.
      * @public
      */
     generateNodeId(override) {
         return this.idCompressor.generateCompressedId(override);
     }
-    /** {@inheritdoc NodeIdConverter.convertToStableNodeId} */
+    /**
+     * Given a NodeId, returns the corresponding stable ID or throws if the supplied node ID was not generated with this tree (`NodeId`s
+     * may not be used across SharedTree instances, see `generateNodeId` for more).
+     * The returned value will be a UUID, unless the creation of `id` used an override string (see `generateNodeId` for more).
+     * The result is safe to persist and re-use across `SharedTree` instances, unlike `NodeId`.
+     * @public
+     */
     convertToStableNodeId(id) {
         var _a;
         return (_a = this.idCompressor.tryDecompress(id)) !== null && _a !== void 0 ? _a : Common_1.fail('Node id is not known to this SharedTree');
     }
-    /** {@inheritdoc NodeIdConverter.tryConvertToStableNodeId} */
+    /**
+     * Given a NodeId, attempt to return the corresponding stable ID.
+     * The returned value will be a UUID, unless the creation of `id` used an override string (see `generateNodeId` for more).
+     * The returned stable ID is undefined if `id` was never created with this SharedTree. If a stable ID is returned, this does not imply
+     * that there is a node with `id` in the current revision of the tree, only that `id` was at some point generated by some instance of
+     * this tree.
+     * @public
+     */
     tryConvertToStableNodeId(id) {
         return this.idCompressor.tryDecompress(id);
     }
-    /** {@inheritdoc NodeIdConverter.convertToNodeId} */
+    /**
+     * Given a stable ID, return the corresponding NodeId or throws if the supplied stable ID was never generated with this tree, either
+     * as a UUID corresponding to a `NodeId` or as an override passed to `generateNodeId`.
+     * If a stable ID is returned, this does not imply that there is a node with `id` in the current revision of the tree, only that
+     * `id` was at some point generated by an instance of this SharedTree.
+     * @public
+     */
     convertToNodeId(id) {
         var _a;
         return ((_a = this.idCompressor.tryRecompress(id)) !== null && _a !== void 0 ? _a : Common_1.fail('Stable node id is not known to this SharedTree'));
     }
-    /** {@inheritdoc NodeIdConverter.tryConvertToNodeId} */
+    /**
+     * Given a stable ID, return the corresponding NodeId or return undefined if the supplied stable ID was never generated with this tree,
+     * either as a UUID corresponding to a `NodeId` or as an override passed to `generateNodeId`.
+     * If a stable ID is returned, this does not imply that there is a node with `id` in the current revision of the tree, only that
+     * `id` was at some point generated by an instance of this SharedTree.
+     * @public
+     */
     tryConvertToNodeId(id) {
         return this.idCompressor.tryRecompress(id);
     }
@@ -528,7 +563,7 @@ class SharedTree extends shared_object_base_1.SharedObject {
             // TODO:#47830: Store multiple checkpoints in summary.
             knownRevisions = [[editLog.length, { view: currentView }]];
         }
-        const logViewer = new LogViewer_1.CachingLogViewer(editLog, RevisionView_1.RevisionView.fromTree(InitialTree_1.initialTree, this), knownRevisions, this.expensiveValidation, editStatusCallback, sequencedEditResultCallback, this.transactionFactory, 0);
+        const logViewer = new LogViewer_1.CachingLogViewer(editLog, RevisionView_1.RevisionView.fromTree(InitialTree_1.initialTree, this), knownRevisions, this.expensiveValidation, editStatusCallback, sequencedEditResultCallback, 0);
         this.editLog = editLog;
         this.cachingLogViewer = logViewer;
         return { editLog, cachingLogViewer: logViewer };
@@ -551,7 +586,7 @@ class SharedTree extends shared_object_base_1.SharedObject {
         }
     }
     /**
-     * Compares this shared tree to another for equality. Should only be used for correctness testing.
+     * Compares this shared tree to another for equality. Should only be used for internal correctness testing.
      *
      * Equality means that the histories as captured by the EditLogs are equivalent.
      *
@@ -619,7 +654,9 @@ class SharedTree extends shared_object_base_1.SharedObject {
                 }
                 // TODO: This cast can be removed on typescript 4.6
                 const edit = this.parseSequencedEdit(op);
-                this.internStringsFromEdit(edit);
+                if (op.version === persisted_types_1.WriteFormat.v0_1_1) {
+                    this.internStringsFromEdit(edit);
+                }
                 this.processSequencedEdit(edit, typedMessage);
             }
         }
@@ -739,9 +776,8 @@ class SharedTree extends shared_object_base_1.SharedObject {
         }
     }
     upgradeFrom_0_0_2_to_0_1_1() {
-        for (let i = 0; i < this.editLog.numberOfSequencedEdits; i++) {
-            this.internStringsFromEdit(this.editsInternal.getEditInSessionAtIndex(i));
-        }
+        // Reset the string interner, re-populate only with information that there is consensus on
+        this.interner = new StringInterner_1.MutableStringInterner([InitialTree_1.initialTree.definition]);
         const oldIdCompressor = this.idCompressor;
         // Create the IdCompressor that will be used after the upgrade
         const newIdCompressor = new id_compressor_1.IdCompressor(id_compressor_1.createSessionId(), persisted_types_1.reservedIdCount); // TODO: attribution info
@@ -764,12 +800,21 @@ class SharedTree extends shared_object_base_1.SharedObject {
             // All clients have the full history, and can therefore all "generate" the same final IDs for every ID in the history
             // via the ghost compressor.
             unifyHistoricalIds(ghostContext);
+            // The same logic applies to string interning, so intern all the strings in the history (superset of those in the current view)
+            for (let i = 0; i < this.editLog.numberOfSequencedEdits; i++) {
+                this.internStringsFromEdit(this.editsInternal.getEditInSessionAtIndex(i));
+            }
         }
         else {
             // Clients do not have the full history, but all share the same current view (sequenced). They can all finalize the same final
             // IDs for every ID in the view via the ghost compressor.
+            // The same logic applies for the string interner.
             for (const node of this.logViewer.getRevisionViewInSession(this.editLog.numberOfSequencedEdits)) {
                 ghostContext.generateNodeId(this.convertToStableNodeId(node.identifier));
+                this.interner.getOrCreateInternedId(node.definition);
+                for (const label of [...node.traits.keys()].sort()) {
+                    this.interner.getOrCreateInternedId(label);
+                }
             }
             // Every node in this client's history can simply be generated in the new compressor as well, preserving the UUID
             unifyHistoricalIds(newContext);
@@ -778,13 +823,8 @@ class SharedTree extends shared_object_base_1.SharedObject {
         newIdCompressor.finalizeCreationRange(ghostIdCompressor.takeNextCreationRange());
         this.idCompressor = newIdCompressor;
     }
-    /**
-     * Add an `Edit` directly.
-     * External users should use one of the more specialized functions, like applyEdit which handles constructing the actual `Edit` object.
-     * This is exposed as it is useful for testing, particularly with invalid and malformed Edits.
-     * @internal
-     */
-    applyEdit(...changes) {
+    applyEdit(headOrChanges, ...tail) {
+        const changes = Array.isArray(headOrChanges) ? headOrChanges : [headOrChanges, ...tail];
         const id = EditUtilities_1.newEditId();
         const internalEdit = {
             id,
@@ -795,6 +835,10 @@ class SharedTree extends shared_object_base_1.SharedObject {
         return internalEdit;
     }
     /**
+     * Applies a set of internal changes to this tree. The result will be reflected in `SharedTree.currentView`.
+     * External users should use one of the more specialized functions, like `applyEdit` which handles constructing the actual `Edit`
+     * and uses public Change types.
+     * This is exposed for internal use only.
      * @internal
      */
     applyEditInternal(editOrChanges) {
@@ -811,7 +855,8 @@ class SharedTree extends shared_object_base_1.SharedObject {
         return edit;
     }
     /**
-     * Given a newly constructed edit, add any necessary metadata
+     * Converts a public Change type to an internal representation.
+     * This is exposed for internal use only.
      * @internal
      */
     internalizeChange(change) {