@fluidframework/aqueduct 2.42.0 → 2.43.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @fluidframework/aqueduct
 
+## 2.43.0
+
+Dependency updates only.
+
 ## 2.42.0
 
 Dependency updates only.

package/dist/data-objects/treeDataObject.d.ts

@@ -23,11 +23,6 @@ import { PureDataObject } from "./pureDataObject.js";
  * }
  * ```
  *
- * @privateRemarks
- * TODO: Before promoting this beyond internal, we should consider alternative API patterns that don't depend on
- * sub-classing and don't leak Fluid concepts that should ideally be internal.
- * See `tree-react-api` for an example of a pattern that avoids unnecessary leakage of implementation details.
- *
  * @internal
  */
 export declare abstract class TreeDataObject<TTreeView> extends PureDataObject {
@@ -39,8 +34,11 @@ export declare abstract class TreeDataObject<TTreeView> extends PureDataObject {
     protected abstract generateView(tree: ITree): TTreeView;
     /**
      * Gets the underlying {@link @fluidframework/tree#ITree | tree}.
+     * @remarks
+     * Note: in most cases, you will want to use {@link TreeDataObject.treeView} instead.
+     * Created once during initialization.
      */
-    get sharedTree(): ITree;
+    protected get sharedTree(): ITree;
     /**
      * Gets the derived view of the underlying tree.
      *

package/dist/data-objects/treeDataObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeDataObject.d.ts","sourceRoot":"","sources":["../../src/data-objects/treeDataObject.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,KAAK,KAAK,EAAc,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAUrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8BAAsB,cAAc,CAAC,SAAS,CAAE,SAAQ,cAAc;;IACrE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS;IAQvD;;OAEG;IACH,IAAW,UAAU,IAAI,KAAK,CAK7B;IAQD;;;;;OAKG;IACH,IAAW,QAAQ,IAAI,SAAS,CAK/B;IAEqB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CA6B1E"}
+{"version":3,"file":"treeDataObject.d.ts","sourceRoot":"","sources":["../../src/data-objects/treeDataObject.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,KAAK,KAAK,EAAc,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAUrD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8BAAsB,cAAc,CAAC,SAAS,CAAE,SAAQ,cAAc;;IACrE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS;IAQvD;;;;;OAKG;IACH,SAAS,KAAK,UAAU,IAAI,KAAK,CAKhC;IAQD;;;;;OAKG;IACH,IAAW,QAAQ,IAAI,SAAS,CAK/B;IAEqB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CA6B1E"}

package/dist/data-objects/treeDataObject.js

@@ -44,11 +44,6 @@ const uninitializedErrorString = "The tree has not yet been initialized. The dat
  * }
  * ```
  *
- * @privateRemarks
- * TODO: Before promoting this beyond internal, we should consider alternative API patterns that don't depend on
- * sub-classing and don't leak Fluid concepts that should ideally be internal.
- * See `tree-react-api` for an example of a pattern that avoids unnecessary leakage of implementation details.
- *
  * @internal
  */
 class TreeDataObject extends pureDataObject_js_1.PureDataObject {
@@ -67,6 +62,9 @@ class TreeDataObject extends pureDataObject_js_1.PureDataObject {
     }
     /**
      * Gets the underlying {@link @fluidframework/tree#ITree | tree}.
+     * @remarks
+     * Note: in most cases, you will want to use {@link TreeDataObject.treeView} instead.
+     * Created once during initialization.
      */
     get sharedTree() {
         if (__classPrivateFieldGet(this, _TreeDataObject_sharedTree, "f") === undefined) {

package/dist/data-objects/treeDataObject.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeDataObject.js","sourceRoot":"","sources":["../../src/data-objects/treeDataObject.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;AAGH,uEAAsE;AACtE,4DAAuE;AAEvE,2DAAqD;AAErD;;GAEG;AACH,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAEzC,MAAM,wBAAwB,GAC7B,8FAA8F,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAsB,cAA0B,SAAQ,kCAAc;IAAtE;;QAOC;;;WAGG;QACH,6CAA+B;QAY/B;;;WAGG;QACH,uCAA6B;IA4C9B,CAAC;IA1DA;;OAEG;IACH,IAAW,UAAU;QACpB,IAAI,uBAAA,IAAI,kCAAY,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,qBAAU,CAAC,wBAAwB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,uBAAA,IAAI,kCAAY,CAAC;IACzB,CAAC;IAQD;;;;;OAKG;IACH,IAAW,QAAQ;QAClB,IAAI,uBAAA,IAAI,4BAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,qBAAU,CAAC,wBAAwB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,uBAAA,IAAI,4BAAM,CAAC;IACnB,CAAC;IAEe,KAAK,CAAC,kBAAkB,CAAC,QAAiB;QACzD,IAAI,QAAQ,EAAE,CAAC;YACd,+FAA+F;YAC/F,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;YAE7D,0FAA0F;YAC1F,8FAA8F;YAC9F,IAAI,CAAC,qBAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CACd,mBAAmB,OAAO,CAAC,EAAE,gEAAgE,CAC7F,CAAC;YACH,CAAC;YACD,MAAM,UAAU,GAAU,OAAO,CAAC;YAElC,uBAAA,IAAI,8BAAe,UAAU,MAAA,CAAC;YAC9B,uBAAA,IAAI,wBAAS,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAA,CAAC;QAC5C,CAAC;aAAM,CAAC;YACP,MAAM,UAAU,GAAG,qBAAU,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YACjE,UAAuC,CAAC,aAAa,EAAE,CAAC;YAEzD,uBAAA,IAAI,8BAAe,UAAU,MAAA,CAAC;YAC9B,uBAAA,IAAI,wBAAS,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAA,CAAC;YAE3C,oFAAoF;YACpF,2DAA2D;QAC5D,CAAC;QAED,MAAM,KAAK,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;CACD;AAvED,wCAuEC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ISharedObject } from \"@fluidframework/shared-object-base/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { type ITree, SharedTree } from \"@fluidframework/tree/internal\";\n\nimport { PureDataObject } from \"./pureDataObject.js\";\n\n/**\n * Channel ID of {@link TreeDataObject}'s root {@link @fluidframework/tree#SharedTree}.\n */\nconst treeChannelId = \"tree-data-object\";\n\nconst uninitializedErrorString =\n\t\"The tree has not yet been initialized. The data object must be initialized before accessing.\";\n\n/**\n * {@link @fluidframework/tree#SharedTree}-backed {@link PureDataObject | data object}.\n *\n * @remarks\n *\n * Note: to initialize the tree's data for initial creation, implementers of this class will need to override {@link PureDataObject.initializingFirstTime} and set the data in {@link TreeDataObject.treeView}.\n *\n * @typeParam TTreeView - View derived from the underlying tree.\n * Can be used to derive schema-aware views of the tree.\n * See {@link TreeDataObject.generateView}.\n *\n * @example Implementing `initializingFirstTime`\n *\n * ```typescript\n * protected override async initializingFirstTime(): Promise<void> {\n * \tthis.tree.initialize(...);\n * }\n * ```\n *\n * @privateRemarks\n * TODO: Before promoting this beyond internal, we should consider alternative API patterns that don't depend on\n * sub-classing and don't leak Fluid concepts that should ideally be internal.\n * See `tree-react-api` for an example of a pattern that avoids unnecessary leakage of implementation details.\n *\n * @internal\n */\nexport abstract class TreeDataObject<TTreeView> extends PureDataObject {\n\t/**\n\t * Generates a view of the data object's {@link @fluidframework/tree#ITree | tree}.\n\t * @remarks Called once during initialization.\n\t */\n\tprotected abstract generateView(tree: ITree): TTreeView;\n\n\t/**\n\t * Implementation of SharedTree which is used to generate the view.\n\t * @remarks Created once during initialization.\n\t */\n\t#sharedTree: ITree | undefined;\n\n\t/**\n\t * Gets the underlying {@link @fluidframework/tree#ITree | tree}.\n\t */\n\tpublic get sharedTree(): ITree {\n\t\tif (this.#sharedTree === undefined) {\n\t\t\tthrow new UsageError(uninitializedErrorString);\n\t\t}\n\t\treturn this.#sharedTree;\n\t}\n\n\t/**\n\t * View derived from the underlying tree.\n\t * @remarks Populated via {@link TreeDataObject.generateView}.\n\t */\n\t#view: TTreeView | undefined;\n\n\t/**\n\t * Gets the derived view of the underlying tree.\n\t *\n\t * @throws\n\t * If the tree has not yet been initialized, this will throw an error.\n\t */\n\tpublic get treeView(): TTreeView {\n\t\tif (this.#view === undefined) {\n\t\t\tthrow new UsageError(uninitializedErrorString);\n\t\t}\n\t\treturn this.#view;\n\t}\n\n\tpublic override async initializeInternal(existing: boolean): Promise<void> {\n\t\tif (existing) {\n\t\t\t// data store has a root tree so we just need to set it before calling initializingFromExisting\n\t\t\tconst channel = await this.runtime.getChannel(treeChannelId);\n\n\t\t\t// TODO: Support using a Directory to Tree migration shim and DataObject's root channel ID\n\t\t\t// to allow migrating from DataObject to TreeDataObject instead of just erroring in that case.\n\t\t\tif (!SharedTree.is(channel)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Content with id ${channel.id} is not a SharedTree and cannot be loaded with treeDataObject.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst sharedTree: ITree = channel;\n\n\t\t\tthis.#sharedTree = sharedTree;\n\t\t\tthis.#view = this.generateView(sharedTree);\n\t\t} else {\n\t\t\tconst sharedTree = SharedTree.create(this.runtime, treeChannelId);\n\t\t\t(sharedTree as unknown as ISharedObject).bindToContext();\n\n\t\t\tthis.#sharedTree = sharedTree;\n\t\t\tthis.#view = this.generateView(sharedTree);\n\n\t\t\t// Note, the implementer is responsible for initializing the tree with initial data.\n\t\t\t// Generally, this can be done via `initializingFirstTime`.\n\t\t}\n\n\t\tawait super.initializeInternal(existing);\n\t}\n}\n"]}
+{"version":3,"file":"treeDataObject.js","sourceRoot":"","sources":["../../src/data-objects/treeDataObject.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;AAGH,uEAAsE;AACtE,4DAAuE;AAEvE,2DAAqD;AAErD;;GAEG;AACH,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAEzC,MAAM,wBAAwB,GAC7B,8FAA8F,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAsB,cAA0B,SAAQ,kCAAc;IAAtE;;QAOC;;;WAGG;QACH,6CAA+B;QAe/B;;;WAGG;QACH,uCAA6B;IA4C9B,CAAC;IA7DA;;;;;OAKG;IACH,IAAc,UAAU;QACvB,IAAI,uBAAA,IAAI,kCAAY,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,qBAAU,CAAC,wBAAwB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,uBAAA,IAAI,kCAAY,CAAC;IACzB,CAAC;IAQD;;;;;OAKG;IACH,IAAW,QAAQ;QAClB,IAAI,uBAAA,IAAI,4BAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,qBAAU,CAAC,wBAAwB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,uBAAA,IAAI,4BAAM,CAAC;IACnB,CAAC;IAEe,KAAK,CAAC,kBAAkB,CAAC,QAAiB;QACzD,IAAI,QAAQ,EAAE,CAAC;YACd,+FAA+F;YAC/F,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;YAE7D,0FAA0F;YAC1F,8FAA8F;YAC9F,IAAI,CAAC,qBAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CACd,mBAAmB,OAAO,CAAC,EAAE,gEAAgE,CAC7F,CAAC;YACH,CAAC;YACD,MAAM,UAAU,GAAU,OAAO,CAAC;YAElC,uBAAA,IAAI,8BAAe,UAAU,MAAA,CAAC;YAC9B,uBAAA,IAAI,wBAAS,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAA,CAAC;QAC5C,CAAC;aAAM,CAAC;YACP,MAAM,UAAU,GAAG,qBAAU,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YACjE,UAAuC,CAAC,aAAa,EAAE,CAAC;YAEzD,uBAAA,IAAI,8BAAe,UAAU,MAAA,CAAC;YAC9B,uBAAA,IAAI,wBAAS,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAA,CAAC;YAE3C,oFAAoF;YACpF,2DAA2D;QAC5D,CAAC;QAED,MAAM,KAAK,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;CACD;AA1ED,wCA0EC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ISharedObject } from \"@fluidframework/shared-object-base/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { type ITree, SharedTree } from \"@fluidframework/tree/internal\";\n\nimport { PureDataObject } from \"./pureDataObject.js\";\n\n/**\n * Channel ID of {@link TreeDataObject}'s root {@link @fluidframework/tree#SharedTree}.\n */\nconst treeChannelId = \"tree-data-object\";\n\nconst uninitializedErrorString =\n\t\"The tree has not yet been initialized. The data object must be initialized before accessing.\";\n\n/**\n * {@link @fluidframework/tree#SharedTree}-backed {@link PureDataObject | data object}.\n *\n * @remarks\n *\n * Note: to initialize the tree's data for initial creation, implementers of this class will need to override {@link PureDataObject.initializingFirstTime} and set the data in {@link TreeDataObject.treeView}.\n *\n * @typeParam TTreeView - View derived from the underlying tree.\n * Can be used to derive schema-aware views of the tree.\n * See {@link TreeDataObject.generateView}.\n *\n * @example Implementing `initializingFirstTime`\n *\n * ```typescript\n * protected override async initializingFirstTime(): Promise<void> {\n * \tthis.tree.initialize(...);\n * }\n * ```\n *\n * @internal\n */\nexport abstract class TreeDataObject<TTreeView> extends PureDataObject {\n\t/**\n\t * Generates a view of the data object's {@link @fluidframework/tree#ITree | tree}.\n\t * @remarks Called once during initialization.\n\t */\n\tprotected abstract generateView(tree: ITree): TTreeView;\n\n\t/**\n\t * Implementation of SharedTree which is used to generate the view.\n\t * @remarks Created once during initialization.\n\t */\n\t#sharedTree: ITree | undefined;\n\n\t/**\n\t * Gets the underlying {@link @fluidframework/tree#ITree | tree}.\n\t * @remarks\n\t * Note: in most cases, you will want to use {@link TreeDataObject.treeView} instead.\n\t * Created once during initialization.\n\t */\n\tprotected get sharedTree(): ITree {\n\t\tif (this.#sharedTree === undefined) {\n\t\t\tthrow new UsageError(uninitializedErrorString);\n\t\t}\n\t\treturn this.#sharedTree;\n\t}\n\n\t/**\n\t * View derived from the underlying tree.\n\t * @remarks Populated via {@link TreeDataObject.generateView}.\n\t */\n\t#view: TTreeView | undefined;\n\n\t/**\n\t * Gets the derived view of the underlying tree.\n\t *\n\t * @throws\n\t * If the tree has not yet been initialized, this will throw an error.\n\t */\n\tpublic get treeView(): TTreeView {\n\t\tif (this.#view === undefined) {\n\t\t\tthrow new UsageError(uninitializedErrorString);\n\t\t}\n\t\treturn this.#view;\n\t}\n\n\tpublic override async initializeInternal(existing: boolean): Promise<void> {\n\t\tif (existing) {\n\t\t\t// data store has a root tree so we just need to set it before calling initializingFromExisting\n\t\t\tconst channel = await this.runtime.getChannel(treeChannelId);\n\n\t\t\t// TODO: Support using a Directory to Tree migration shim and DataObject's root channel ID\n\t\t\t// to allow migrating from DataObject to TreeDataObject instead of just erroring in that case.\n\t\t\tif (!SharedTree.is(channel)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Content with id ${channel.id} is not a SharedTree and cannot be loaded with treeDataObject.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst sharedTree: ITree = channel;\n\n\t\t\tthis.#sharedTree = sharedTree;\n\t\t\tthis.#view = this.generateView(sharedTree);\n\t\t} else {\n\t\t\tconst sharedTree = SharedTree.create(this.runtime, treeChannelId);\n\t\t\t(sharedTree as unknown as ISharedObject).bindToContext();\n\n\t\t\tthis.#sharedTree = sharedTree;\n\t\t\tthis.#view = this.generateView(sharedTree);\n\n\t\t\t// Note, the implementer is responsible for initializing the tree with initial data.\n\t\t\t// Generally, this can be done via `initializingFirstTime`.\n\t\t}\n\n\t\tawait super.initializeInternal(existing);\n\t}\n}\n"]}

package/lib/data-objects/treeDataObject.d.ts

@@ -23,11 +23,6 @@ import { PureDataObject } from "./pureDataObject.js";
  * }
  * ```
  *
- * @privateRemarks
- * TODO: Before promoting this beyond internal, we should consider alternative API patterns that don't depend on
- * sub-classing and don't leak Fluid concepts that should ideally be internal.
- * See `tree-react-api` for an example of a pattern that avoids unnecessary leakage of implementation details.
- *
  * @internal
  */
 export declare abstract class TreeDataObject<TTreeView> extends PureDataObject {
@@ -39,8 +34,11 @@ export declare abstract class TreeDataObject<TTreeView> extends PureDataObject {
     protected abstract generateView(tree: ITree): TTreeView;
     /**
      * Gets the underlying {@link @fluidframework/tree#ITree | tree}.
+     * @remarks
+     * Note: in most cases, you will want to use {@link TreeDataObject.treeView} instead.
+     * Created once during initialization.
      */
-    get sharedTree(): ITree;
+    protected get sharedTree(): ITree;
     /**
      * Gets the derived view of the underlying tree.
      *

package/lib/data-objects/treeDataObject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeDataObject.d.ts","sourceRoot":"","sources":["../../src/data-objects/treeDataObject.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,KAAK,KAAK,EAAc,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAUrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8BAAsB,cAAc,CAAC,SAAS,CAAE,SAAQ,cAAc;;IACrE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS;IAQvD;;OAEG;IACH,IAAW,UAAU,IAAI,KAAK,CAK7B;IAQD;;;;;OAKG;IACH,IAAW,QAAQ,IAAI,SAAS,CAK/B;IAEqB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CA6B1E"}
+{"version":3,"file":"treeDataObject.d.ts","sourceRoot":"","sources":["../../src/data-objects/treeDataObject.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,KAAK,KAAK,EAAc,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAUrD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8BAAsB,cAAc,CAAC,SAAS,CAAE,SAAQ,cAAc;;IACrE;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS;IAQvD;;;;;OAKG;IACH,SAAS,KAAK,UAAU,IAAI,KAAK,CAKhC;IAQD;;;;;OAKG;IACH,IAAW,QAAQ,IAAI,SAAS,CAK/B;IAEqB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CA6B1E"}

package/lib/data-objects/treeDataObject.js

@@ -41,11 +41,6 @@ const uninitializedErrorString = "The tree has not yet been initialized. The dat
  * }
  * ```
  *
- * @privateRemarks
- * TODO: Before promoting this beyond internal, we should consider alternative API patterns that don't depend on
- * sub-classing and don't leak Fluid concepts that should ideally be internal.
- * See `tree-react-api` for an example of a pattern that avoids unnecessary leakage of implementation details.
- *
  * @internal
  */
 export class TreeDataObject extends PureDataObject {
@@ -64,6 +59,9 @@ export class TreeDataObject extends PureDataObject {
     }
     /**
      * Gets the underlying {@link @fluidframework/tree#ITree | tree}.
+     * @remarks
+     * Note: in most cases, you will want to use {@link TreeDataObject.treeView} instead.
+     * Created once during initialization.
      */
     get sharedTree() {
         if (__classPrivateFieldGet(this, _TreeDataObject_sharedTree, "f") === undefined) {

package/lib/data-objects/treeDataObject.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeDataObject.js","sourceRoot":"","sources":["../../src/data-objects/treeDataObject.ts"],"names":[],"mappings":"AAAA;;;GAGG;;;;;;;;;;;;;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AACtE,OAAO,EAAc,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;GAEG;AACH,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAEzC,MAAM,wBAAwB,GAC7B,8FAA8F,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAgB,cAA0B,SAAQ,cAAc;IAAtE;;QAOC;;;WAGG;QACH,6CAA+B;QAY/B;;;WAGG;QACH,uCAA6B;IA4C9B,CAAC;IA1DA;;OAEG;IACH,IAAW,UAAU;QACpB,IAAI,uBAAA,IAAI,kCAAY,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,UAAU,CAAC,wBAAwB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,uBAAA,IAAI,kCAAY,CAAC;IACzB,CAAC;IAQD;;;;;OAKG;IACH,IAAW,QAAQ;QAClB,IAAI,uBAAA,IAAI,4BAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,UAAU,CAAC,wBAAwB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,uBAAA,IAAI,4BAAM,CAAC;IACnB,CAAC;IAEe,KAAK,CAAC,kBAAkB,CAAC,QAAiB;QACzD,IAAI,QAAQ,EAAE,CAAC;YACd,+FAA+F;YAC/F,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;YAE7D,0FAA0F;YAC1F,8FAA8F;YAC9F,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CACd,mBAAmB,OAAO,CAAC,EAAE,gEAAgE,CAC7F,CAAC;YACH,CAAC;YACD,MAAM,UAAU,GAAU,OAAO,CAAC;YAElC,uBAAA,IAAI,8BAAe,UAAU,MAAA,CAAC;YAC9B,uBAAA,IAAI,wBAAS,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAA,CAAC;QAC5C,CAAC;aAAM,CAAC;YACP,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YACjE,UAAuC,CAAC,aAAa,EAAE,CAAC;YAEzD,uBAAA,IAAI,8BAAe,UAAU,MAAA,CAAC;YAC9B,uBAAA,IAAI,wBAAS,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAA,CAAC;YAE3C,oFAAoF;YACpF,2DAA2D;QAC5D,CAAC;QAED,MAAM,KAAK,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;CACD","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ISharedObject } from \"@fluidframework/shared-object-base/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { type ITree, SharedTree } from \"@fluidframework/tree/internal\";\n\nimport { PureDataObject } from \"./pureDataObject.js\";\n\n/**\n * Channel ID of {@link TreeDataObject}'s root {@link @fluidframework/tree#SharedTree}.\n */\nconst treeChannelId = \"tree-data-object\";\n\nconst uninitializedErrorString =\n\t\"The tree has not yet been initialized. The data object must be initialized before accessing.\";\n\n/**\n * {@link @fluidframework/tree#SharedTree}-backed {@link PureDataObject | data object}.\n *\n * @remarks\n *\n * Note: to initialize the tree's data for initial creation, implementers of this class will need to override {@link PureDataObject.initializingFirstTime} and set the data in {@link TreeDataObject.treeView}.\n *\n * @typeParam TTreeView - View derived from the underlying tree.\n * Can be used to derive schema-aware views of the tree.\n * See {@link TreeDataObject.generateView}.\n *\n * @example Implementing `initializingFirstTime`\n *\n * ```typescript\n * protected override async initializingFirstTime(): Promise<void> {\n * \tthis.tree.initialize(...);\n * }\n * ```\n *\n * @privateRemarks\n * TODO: Before promoting this beyond internal, we should consider alternative API patterns that don't depend on\n * sub-classing and don't leak Fluid concepts that should ideally be internal.\n * See `tree-react-api` for an example of a pattern that avoids unnecessary leakage of implementation details.\n *\n * @internal\n */\nexport abstract class TreeDataObject<TTreeView> extends PureDataObject {\n\t/**\n\t * Generates a view of the data object's {@link @fluidframework/tree#ITree | tree}.\n\t * @remarks Called once during initialization.\n\t */\n\tprotected abstract generateView(tree: ITree): TTreeView;\n\n\t/**\n\t * Implementation of SharedTree which is used to generate the view.\n\t * @remarks Created once during initialization.\n\t */\n\t#sharedTree: ITree | undefined;\n\n\t/**\n\t * Gets the underlying {@link @fluidframework/tree#ITree | tree}.\n\t */\n\tpublic get sharedTree(): ITree {\n\t\tif (this.#sharedTree === undefined) {\n\t\t\tthrow new UsageError(uninitializedErrorString);\n\t\t}\n\t\treturn this.#sharedTree;\n\t}\n\n\t/**\n\t * View derived from the underlying tree.\n\t * @remarks Populated via {@link TreeDataObject.generateView}.\n\t */\n\t#view: TTreeView | undefined;\n\n\t/**\n\t * Gets the derived view of the underlying tree.\n\t *\n\t * @throws\n\t * If the tree has not yet been initialized, this will throw an error.\n\t */\n\tpublic get treeView(): TTreeView {\n\t\tif (this.#view === undefined) {\n\t\t\tthrow new UsageError(uninitializedErrorString);\n\t\t}\n\t\treturn this.#view;\n\t}\n\n\tpublic override async initializeInternal(existing: boolean): Promise<void> {\n\t\tif (existing) {\n\t\t\t// data store has a root tree so we just need to set it before calling initializingFromExisting\n\t\t\tconst channel = await this.runtime.getChannel(treeChannelId);\n\n\t\t\t// TODO: Support using a Directory to Tree migration shim and DataObject's root channel ID\n\t\t\t// to allow migrating from DataObject to TreeDataObject instead of just erroring in that case.\n\t\t\tif (!SharedTree.is(channel)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Content with id ${channel.id} is not a SharedTree and cannot be loaded with treeDataObject.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst sharedTree: ITree = channel;\n\n\t\t\tthis.#sharedTree = sharedTree;\n\t\t\tthis.#view = this.generateView(sharedTree);\n\t\t} else {\n\t\t\tconst sharedTree = SharedTree.create(this.runtime, treeChannelId);\n\t\t\t(sharedTree as unknown as ISharedObject).bindToContext();\n\n\t\t\tthis.#sharedTree = sharedTree;\n\t\t\tthis.#view = this.generateView(sharedTree);\n\n\t\t\t// Note, the implementer is responsible for initializing the tree with initial data.\n\t\t\t// Generally, this can be done via `initializingFirstTime`.\n\t\t}\n\n\t\tawait super.initializeInternal(existing);\n\t}\n}\n"]}
+{"version":3,"file":"treeDataObject.js","sourceRoot":"","sources":["../../src/data-objects/treeDataObject.ts"],"names":[],"mappings":"AAAA;;;GAGG;;;;;;;;;;;;;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AACtE,OAAO,EAAc,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;GAEG;AACH,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAEzC,MAAM,wBAAwB,GAC7B,8FAA8F,CAAC;AAEhG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAgB,cAA0B,SAAQ,cAAc;IAAtE;;QAOC;;;WAGG;QACH,6CAA+B;QAe/B;;;WAGG;QACH,uCAA6B;IA4C9B,CAAC;IA7DA;;;;;OAKG;IACH,IAAc,UAAU;QACvB,IAAI,uBAAA,IAAI,kCAAY,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,UAAU,CAAC,wBAAwB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,uBAAA,IAAI,kCAAY,CAAC;IACzB,CAAC;IAQD;;;;;OAKG;IACH,IAAW,QAAQ;QAClB,IAAI,uBAAA,IAAI,4BAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,UAAU,CAAC,wBAAwB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,uBAAA,IAAI,4BAAM,CAAC;IACnB,CAAC;IAEe,KAAK,CAAC,kBAAkB,CAAC,QAAiB;QACzD,IAAI,QAAQ,EAAE,CAAC;YACd,+FAA+F;YAC/F,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;YAE7D,0FAA0F;YAC1F,8FAA8F;YAC9F,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CACd,mBAAmB,OAAO,CAAC,EAAE,gEAAgE,CAC7F,CAAC;YACH,CAAC;YACD,MAAM,UAAU,GAAU,OAAO,CAAC;YAElC,uBAAA,IAAI,8BAAe,UAAU,MAAA,CAAC;YAC9B,uBAAA,IAAI,wBAAS,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAA,CAAC;QAC5C,CAAC;aAAM,CAAC;YACP,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YACjE,UAAuC,CAAC,aAAa,EAAE,CAAC;YAEzD,uBAAA,IAAI,8BAAe,UAAU,MAAA,CAAC;YAC9B,uBAAA,IAAI,wBAAS,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAA,CAAC;YAE3C,oFAAoF;YACpF,2DAA2D;QAC5D,CAAC;QAED,MAAM,KAAK,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;CACD","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ISharedObject } from \"@fluidframework/shared-object-base/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { type ITree, SharedTree } from \"@fluidframework/tree/internal\";\n\nimport { PureDataObject } from \"./pureDataObject.js\";\n\n/**\n * Channel ID of {@link TreeDataObject}'s root {@link @fluidframework/tree#SharedTree}.\n */\nconst treeChannelId = \"tree-data-object\";\n\nconst uninitializedErrorString =\n\t\"The tree has not yet been initialized. The data object must be initialized before accessing.\";\n\n/**\n * {@link @fluidframework/tree#SharedTree}-backed {@link PureDataObject | data object}.\n *\n * @remarks\n *\n * Note: to initialize the tree's data for initial creation, implementers of this class will need to override {@link PureDataObject.initializingFirstTime} and set the data in {@link TreeDataObject.treeView}.\n *\n * @typeParam TTreeView - View derived from the underlying tree.\n * Can be used to derive schema-aware views of the tree.\n * See {@link TreeDataObject.generateView}.\n *\n * @example Implementing `initializingFirstTime`\n *\n * ```typescript\n * protected override async initializingFirstTime(): Promise<void> {\n * \tthis.tree.initialize(...);\n * }\n * ```\n *\n * @internal\n */\nexport abstract class TreeDataObject<TTreeView> extends PureDataObject {\n\t/**\n\t * Generates a view of the data object's {@link @fluidframework/tree#ITree | tree}.\n\t * @remarks Called once during initialization.\n\t */\n\tprotected abstract generateView(tree: ITree): TTreeView;\n\n\t/**\n\t * Implementation of SharedTree which is used to generate the view.\n\t * @remarks Created once during initialization.\n\t */\n\t#sharedTree: ITree | undefined;\n\n\t/**\n\t * Gets the underlying {@link @fluidframework/tree#ITree | tree}.\n\t * @remarks\n\t * Note: in most cases, you will want to use {@link TreeDataObject.treeView} instead.\n\t * Created once during initialization.\n\t */\n\tprotected get sharedTree(): ITree {\n\t\tif (this.#sharedTree === undefined) {\n\t\t\tthrow new UsageError(uninitializedErrorString);\n\t\t}\n\t\treturn this.#sharedTree;\n\t}\n\n\t/**\n\t * View derived from the underlying tree.\n\t * @remarks Populated via {@link TreeDataObject.generateView}.\n\t */\n\t#view: TTreeView | undefined;\n\n\t/**\n\t * Gets the derived view of the underlying tree.\n\t *\n\t * @throws\n\t * If the tree has not yet been initialized, this will throw an error.\n\t */\n\tpublic get treeView(): TTreeView {\n\t\tif (this.#view === undefined) {\n\t\t\tthrow new UsageError(uninitializedErrorString);\n\t\t}\n\t\treturn this.#view;\n\t}\n\n\tpublic override async initializeInternal(existing: boolean): Promise<void> {\n\t\tif (existing) {\n\t\t\t// data store has a root tree so we just need to set it before calling initializingFromExisting\n\t\t\tconst channel = await this.runtime.getChannel(treeChannelId);\n\n\t\t\t// TODO: Support using a Directory to Tree migration shim and DataObject's root channel ID\n\t\t\t// to allow migrating from DataObject to TreeDataObject instead of just erroring in that case.\n\t\t\tif (!SharedTree.is(channel)) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Content with id ${channel.id} is not a SharedTree and cannot be loaded with treeDataObject.`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst sharedTree: ITree = channel;\n\n\t\t\tthis.#sharedTree = sharedTree;\n\t\t\tthis.#view = this.generateView(sharedTree);\n\t\t} else {\n\t\t\tconst sharedTree = SharedTree.create(this.runtime, treeChannelId);\n\t\t\t(sharedTree as unknown as ISharedObject).bindToContext();\n\n\t\t\tthis.#sharedTree = sharedTree;\n\t\t\tthis.#view = this.generateView(sharedTree);\n\n\t\t\t// Note, the implementer is responsible for initializing the tree with initial data.\n\t\t\t// Generally, this can be done via `initializingFirstTime`.\n\t\t}\n\n\t\tawait super.initializeInternal(existing);\n\t}\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/aqueduct",
-  "version": "2.42.0",
+  "version": "2.43.0",
   "description": "A set of implementations for Fluid Framework interfaces.",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -69,31 +69,31 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.42.0",
-    "@fluidframework/container-definitions": "~2.42.0",
-    "@fluidframework/container-runtime": "~2.42.0",
-    "@fluidframework/container-runtime-definitions": "~2.42.0",
-    "@fluidframework/core-interfaces": "~2.42.0",
-    "@fluidframework/core-utils": "~2.42.0",
-    "@fluidframework/datastore": "~2.42.0",
-    "@fluidframework/datastore-definitions": "~2.42.0",
-    "@fluidframework/map": "~2.42.0",
-    "@fluidframework/request-handler": "~2.42.0",
-    "@fluidframework/runtime-definitions": "~2.42.0",
-    "@fluidframework/runtime-utils": "~2.42.0",
-    "@fluidframework/shared-object-base": "~2.42.0",
-    "@fluidframework/synthesize": "~2.42.0",
-    "@fluidframework/telemetry-utils": "~2.42.0",
-    "@fluidframework/tree": "~2.42.0"
+    "@fluid-internal/client-utils": "~2.43.0",
+    "@fluidframework/container-definitions": "~2.43.0",
+    "@fluidframework/container-runtime": "~2.43.0",
+    "@fluidframework/container-runtime-definitions": "~2.43.0",
+    "@fluidframework/core-interfaces": "~2.43.0",
+    "@fluidframework/core-utils": "~2.43.0",
+    "@fluidframework/datastore": "~2.43.0",
+    "@fluidframework/datastore-definitions": "~2.43.0",
+    "@fluidframework/map": "~2.43.0",
+    "@fluidframework/request-handler": "~2.43.0",
+    "@fluidframework/runtime-definitions": "~2.43.0",
+    "@fluidframework/runtime-utils": "~2.43.0",
+    "@fluidframework/shared-object-base": "~2.43.0",
+    "@fluidframework/synthesize": "~2.43.0",
+    "@fluidframework/telemetry-utils": "~2.43.0",
+    "@fluidframework/tree": "~2.43.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.42.0",
-    "@fluid-tools/build-cli": "^0.55.0",
-    "@fluidframework/aqueduct-previous": "npm:@fluidframework/aqueduct@2.41.0",
+    "@fluid-internal/mocha-test-setup": "~2.43.0",
+    "@fluid-tools/build-cli": "^0.56.0",
+    "@fluidframework/aqueduct-previous": "npm:@fluidframework/aqueduct@2.42.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.55.0",
+    "@fluidframework/build-tools": "^0.56.0",
     "@fluidframework/eslint-config-fluid": "^5.7.4",
     "@microsoft/api-extractor": "7.52.8",
     "@types/mocha": "^10.0.10",

package/src/data-objects/treeDataObject.ts

@@ -36,11 +36,6 @@ const uninitializedErrorString =
  * }
  * ```
  *
- * @privateRemarks
- * TODO: Before promoting this beyond internal, we should consider alternative API patterns that don't depend on
- * sub-classing and don't leak Fluid concepts that should ideally be internal.
- * See `tree-react-api` for an example of a pattern that avoids unnecessary leakage of implementation details.
- *
  * @internal
  */
 export abstract class TreeDataObject<TTreeView> extends PureDataObject {
@@ -58,8 +53,11 @@ export abstract class TreeDataObject<TTreeView> extends PureDataObject {
 
 	/**
 	 * Gets the underlying {@link @fluidframework/tree#ITree | tree}.
+	 * @remarks
+	 * Note: in most cases, you will want to use {@link TreeDataObject.treeView} instead.
+	 * Created once during initialization.
 	 */
-	public get sharedTree(): ITree {
+	protected get sharedTree(): ITree {
 		if (this.#sharedTree === undefined) {
 			throw new UsageError(uninitializedErrorString);
 		}