@fluidframework/driver-definitions 2.118.0 → 3.0.0

package/CHANGELOG.md

@@ -1,12 +1,42 @@
 # @fluidframework/driver-definitions
 
-## 2.118.0
+## 3.0.0
 
-Dependency updates only.
+### Minor Changes
 
-## 2.117.0
+- Removal of direct CommonJS support ([#28124](https://github.com/microsoft/FluidFramework/pull/28124)) [0f84e3b8878](https://github.com/microsoft/FluidFramework/commit/0f84e3b8878a5e75b2253976d98fd963bbd9db88)
 
-Dependency updates only.
+  Direct `require()` import is no longer directly supported.
+  Package is transpiled as ECMAScript Module.
+
+  See [Removal of direct CommonJS support in v3.0](https://github.com/microsoft/FluidFramework/issues/27444) for more information.
+
+- Require modern TypeScript module resolution ([#27970](https://github.com/microsoft/FluidFramework/pull/27970)) [325e2016ca9](https://github.com/microsoft/FluidFramework/commit/325e2016ca9978d4a1f7552c97ba34feac9df41f)
+
+  Fluid Framework Client packages no longer include type declaration compatibility entrypoints for TypeScript's legacy Node10 resolution mode (`"moduleResolution": "node"` or `"node10"`).
+  Applications upgrading to Fluid Framework 3.0 must use one of the following supported configurations:
+  - `"module": "Node16"` with `"moduleResolution": "Node16"`
+  - `"module": "NodeNext"` with `"moduleResolution": "NodeNext"`
+  - `"module": "ESNext"` with `"moduleResolution": "Bundler"`
+
+  Existing public package entrypoints exposed through `package.json` exports, including `/alpha`, `/beta`, and `/legacy`, remain available under supported module resolution modes.
+
+  See [Removal of Node10 resolutions in v3.0](https://github.com/microsoft/FluidFramework/issues/27457) for more information.
+
+- Client packages now target ES2022 ([#27846](https://github.com/microsoft/FluidFramework/pull/27846)) [91c78541bdd](https://github.com/microsoft/FluidFramework/commit/91c78541bddcbca5d6c5f357b023eeaee617d885)
+
+  The TypeScript compilation `target` and `lib` for the Fluid Framework client packages have been raised from ES2021/ES2020 to **ES2022**.
+  The published JavaScript now uses ES2022 language features (with correspondingly less down-leveling), so consuming these packages requires a runtime that supports ES2022.
+  All actively supported Node.js versions and evergreen browsers already meet this requirement.
+
+  Note that Fluid Framework has not officially supported targets older than ES2022 since before 2.0: this is documented in [ClientRequirements.md](https://github.com/microsoft/FluidFramework/blob/main/ClientRequirements.md) as well as the README for every client package.
+
+  It is possible this change could impact users of less up to date JavaScript runtimes.
+  Impacted users can use a tool like [babel](https://babeljs.io/) to transpile out unsupported language features.
+
+- Build with TypeScript 6 ([#28052](https://github.com/microsoft/FluidFramework/pull/28052)) [7ab015c49de](https://github.com/microsoft/FluidFramework/commit/7ab015c49deec84833cdfe1fb5e1606b901f6e81)
+
+  FluidFramework Client SDK is now built using TypeScript 6. Consumers should build with TypeScript v6 or v7 or compatible tooling.
 
 ## 2.116.0
 

package/README.md

@@ -9,15 +9,15 @@ Interfaces for Fluid Drivers
 
 ## Using Fluid Framework libraries
 
-When taking a dependency on a Fluid Framework library's public APIs, we recommend using a `^` (caret) version range, such as `^1.3.4`.
-While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries,
-library consumers should always prefer `^`.
+For a dependency on a Fluid Framework library's public APIs, we recommend a `^` (caret) version range.
+For example, use `^1.3.4`.
 
-If using any of Fluid Framework's unstable APIs (for example, its `beta` APIs), we recommend using a more constrained version range, such as `~`.
+For a dependency on an unstable API, such as a `beta` API, we recommend a more restrictive version range.
+For example, use a `~` version range.
 
 ## Installation
 
-To get started, install the package by running the following command:
+Run this command to install the package:
 
 ```bash
 npm i @fluidframework/driver-definitions
@@ -25,16 +25,16 @@ npm i @fluidframework/driver-definitions
 
 ## Importing from this package
 
-This package leverages [package.json exports](https://nodejs.org/api/packages.html#exports) to separate its APIs by support level.
-For more information on the related support guarantees, see [API Support Levels](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels).
+This package uses [package.json exports](https://nodejs.org/api/packages.html#exports) to separate APIs by support level.
+For information about the support guarantees, read [API Support Levels](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels).
 
-To access the `public` ([SemVer](https://semver.org/)) APIs, import via `@fluidframework/driver-definitions` like normal.
+Import the `public` APIs from `@fluidframework/driver-definitions`.
 
-To access the `legacy` APIs, import via `@fluidframework/driver-definitions/legacy`.
+Import the `legacy` APIs from `@fluidframework/driver-definitions/legacy`.
 
 ## API Documentation
 
-API documentation for **@fluidframework/driver-definitions** is available at <https://fluidframework.com/docs/apis/driver-definitions>.
+Read the **@fluidframework/driver-definitions** API documentation at <https://fluidframework.com/docs/apis/driver-definitions>.
 
 <!-- prettier-ignore-end -->
 
@@ -47,62 +47,69 @@ API documentation for **@fluidframework/driver-definitions** is available at <ht
 
 ## Minimum Client Requirements
 
-These are the platform requirements for the current version of Fluid Framework Client Packages.
-These requirements err on the side of being too strict since within a major version they can be relaxed over time, but not made stricter.
-For Long Term Support (LTS) versions this can require supporting these platforms for several years.
+Fluid Framework client libraries support the platforms in this document.
+These requirements are intentionally restrictive.
+Within a major version series, we can relax these requirements, but we cannot make them stricter.
+For a Long Term Support (LTS) version, we might need to support these platforms for several years.
 
-It is likely that other configurations will work, but they are not supported: if they stop working, we do not consider that a bug.
-If you would benefit from support for something not listed here, file an issue and the product team will evaluate your request.
-When making such a request please include if the configuration already works (and thus the request is just that it becomes officially supported), or if changes are required to get it working.
+Other configurations can work, but Fluid Framework does not support them.
+If an unsupported configuration stops working, we do not classify this as a bug.
+To request support for a configuration that is not listed, file an issue.
+The product team will evaluate your request.
+In the issue, specify the current status of the configuration:
+
+-   The configuration works but needs official support.
+-   The configuration does not work and requires changes.
 
 ### Supported Runtimes
 
--   NodeJs ^22.22.2 except that we will drop support for it [when NodeJs 22 loses its upstream support on 2027-04-30](https://github.com/nodejs/release#release-schedule), and will support a newer LTS version of NodeJS at least 1 year before 22 is end-of-life.
-    -   Running Fluid in a Node.js environment with the `--no-experimental-fetch` flag is not supported.
--   Modern browsers supporting the es2022 standard library: in response to asks we can add explicit support for using babel to polyfill to target specific standards or runtimes (meaning we can avoid/remove use of things that don't polyfill robustly, but otherwise target modern standards).
+-   Fluid Framework supports Node.js versions 22 and 24 while they receive [upstream support](https://nodejs.org/en/about/previous-releases).
+    -   Fluid Framework will stop support for version 22 [when upstream support ends on 2027-04-30](https://github.com/nodejs/release#release-schedule).
+    -   Fluid Framework does not support Node.js with the `--no-experimental-fetch` flag.
+-   Fluid Framework supports modern browsers that support the ES2022 standard library.
 
 ### Supported Tools
 
--   TypeScript 5.4:
-    -   All [`strict`](https://www.typescriptlang.org/tsconfig) options are supported.
-    -   [`strictNullChecks`](https://www.typescriptlang.org/tsconfig) is required.
-    -   [Configuration options deprecated in 5.0](https://github.com/microsoft/TypeScript/issues/51909) are not supported.
-    -   `exactOptionalPropertyTypes` is currently not fully supported.
-        If used, narrowing members of Fluid Framework types types using `in`, `Reflect.has`, `Object.hasOwn` or `Object.prototype.hasOwnProperty` should be avoided as they may incorrectly exclude `undefined` from the possible values in some cases.
+-   [TypeScript 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0):
+    -   Fluid Framework supports all [`strict`](https://www.typescriptlang.org/tsconfig) options.
+    -   Set the build targets (`lib`, `target`) to `ES2022` or later.
+    -   Enable [`strictNullChecks`](https://www.typescriptlang.org/tsconfig).
+    -   Fluid Framework does not support [configuration options deprecated in TypeScript 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0#breaking-changes-and-deprecations-in-typescript-6-0).
+    -   Fluid Framework does not fully support `exactOptionalPropertyTypes`.
+        If you enable this option, do not use `in`, `Reflect.has`, `Object.hasOwn`, or `Object.prototype.hasOwnProperty` to narrow members of Fluid Framework types.
+        These methods can incorrectly exclude `undefined` from the possible values.
 -   [webpack](https://webpack.js.org/) 5
-    -   We are not intending to be prescriptive about what bundler to use.
-        Other bundlers which can handle ES Modules should work, but webpack is the only one we actively test.
+    -   We do not require a specific bundler.
+        Other bundlers that handle ES Modules can work, but we actively test only webpack.
 
 ### Module Resolution
 
-[`Node16`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) resolution should be used with TypeScript compilerOptions to follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm).
-Node10 resolution is not supported as it does not support Fluid Framework's API structuring pattern that is used to distinguish stable APIs from those that are in development.
+In TypeScript `compilerOptions`, use [`Node16`, `Node20`, `NodeNext`, or `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) module resolution.
+These settings follow the [Node.js v12+ ESM Resolution and Loading algorithm](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm).
+
+Do not use `Node10` module resolution.
 
 ### Module Formats
 
 -   ES Modules:
-    ES Modules are the preferred way to consume our client packages (including in NodeJs) and consuming our client packages from ES Modules is fully supported.
--   CommonJs:
-    Consuming our client packages as CommonJs is supported only in NodeJS and only for the cases listed below.
-    This is done to accommodate some workflows without good ES Module support.
-    If you have a workflow you would like included in this list, file an issue.
-    Once this list of workflows motivating CommonJS support is empty, we may drop support for CommonJS one year after notice of the change is posted here.
-
-    -   Testing with Jest (which lacks [stable ESM support](https://jestjs.io/docs/ecmascript-modules) due to [unstable APIs in NodeJs](https://github.com/nodejs/node/issues/37648))
+    Use ES Modules to consume Fluid Framework client packages, including in Node.js.
+-   CommonJS:
+    Fluid Framework does not officially support CommonJS in version 3.0 or later.
 
 ## Contribution Guidelines
 
-There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid.
+You can [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid Framework in these ways:
 
--   Participate in Q&A in our [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
--   [Submit bugs](https://github.com/microsoft/FluidFramework/issues) and help us verify fixes as they are checked in.
--   Review the [source code changes](https://github.com/microsoft/FluidFramework/pulls).
+-   Answer questions in [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
+-   [Submit bug reports](https://github.com/microsoft/FluidFramework/issues) and help verify fixes.
+-   Review [source code changes](https://github.com/microsoft/FluidFramework/pulls).
 -   [Contribute bug fixes](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md).
 
-Detailed instructions for working in the repo can be found in the [Wiki](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md).
+For detailed instructions, read the [repo documentation](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md).
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+This project follows the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information, read the [Code of Conduct frequently asked questions](https://opensource.microsoft.com/codeofconduct/faq/).
+For questions or comments, contact [opencode@microsoft.com](mailto:opencode@microsoft.com).
 
 This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
 Use of these trademarks or logos must follow Microsoft’s [Trademark & Brand Guidelines](https://www.microsoft.com/trademarks).
@@ -110,13 +117,9 @@ Use of Microsoft trademarks or logos in modified versions of this project must n
 
 ## Help
 
-Not finding what you're looking for in this README?
-Check out [fluidframework.com](https://fluidframework.com/docs/).
-
-Still not finding what you're looking for?
-Please [file an issue](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Contributing/Submitting-Bugs-and-Feature-Requests.md).
+Read the [Fluid Framework documentation](https://fluidframework.com/docs/) for information about Fluid Framework concepts and APIs.
 
-Thank you!
+To request information that the documentation does not contain, [create an issue](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Contributing/Submitting-Bugs-and-Feature-Requests.md).
 
 ## Trademark
 

package/{api-extractor.json → api-extractor/api-extractor-model.json}

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-model.esm.json"
+	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-model.esm.json"
 }

package/dist/protocol/summary.d.ts

@@ -88,10 +88,10 @@ export type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryT
  * @example
  * To illustrate, if a DataStore did not change since last summary, the framework runtime will use a handle for the
  * entire DataStore instead of re-sending the entire subtree. The same concept applies for a DDS.
- * An example of a handle string generated when the DDS did not change would be: '/.channels/<DataStoreId>/.channels/<DDSId>'.
- * An example of a handle string generated when the DataStore did not change would be: '/.channels/<DataStoreId>'.
- * An example of a handle string generated when the DDS blob did not change would be: `/.channels/<DataStoreId>/.channels/<DDSId>/<BlobId>`.
- * An example of a handle string generated when the DataStore .attributes blob did not change would be: `/.channels/<DataStoreId>/.attributes`.
+ * An example of a handle string generated when the DDS did not change would be: `/.channels/{dataStoreId}/.channels/{ddsId}`.
+ * An example of a handle string generated when the DataStore did not change would be: `/.channels/{dataStoreId}`.
+ * An example of a handle string generated when the DDS blob did not change would be: `/.channels/{dataStoreId}/.channels/{ddsId}/{blobId}`.
+ * An example of a handle string generated when the DataStore .attributes blob did not change would be: `/.channels/{dataStoreId}/.attributes`.
  * @public
  */
 export interface ISummaryHandle {

package/dist/protocol/summary.js.map

@@ -1 +1 @@
-{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../src/protocol/summary.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAiBH;;;GAGG;AACH,2DAA2D;AAC3D,IAAiB,WAAW,CA6C3B;AA7CD,WAAiB,WAAW;IAkB3B;;;OAGG;IACU,gBAAI,GAAS,CAAC,CAAC;IAE5B;;;;;OAKG;IACU,gBAAI,GAAS,CAAC,CAAC;IAE5B;;;OAGG;IACU,kBAAM,GAAW,CAAC,CAAC;IAEhC;;;;;OAKG;IACU,sBAAU,GAAe,CAAC,CAAC;AACzC,CAAC,EA7CgB,WAAW,2BAAX,WAAW,QA6C3B","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Object representing a node within a summary tree.\n *\n * @remarks\n * If any particular node is an {@link ISummaryTree}, it can contain additional `SummaryObject`s as its children.\n * @public\n */\nexport type SummaryObject = ISummaryTree | ISummaryBlob | ISummaryHandle | ISummaryAttachment;\n\n/**\n * The root of the summary tree.\n * @legacy @beta\n */\nexport type SummaryTree = ISummaryTree | ISummaryHandle;\n\n/**\n * Type tag used to distinguish different types of nodes in a {@link ISummaryTree}.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/no-namespace\nexport namespace SummaryType {\n\t/**\n\t * @internal\n\t */\n\texport type Tree = 1;\n\t/**\n\t * @internal\n\t */\n\texport type Blob = 2;\n\t/**\n\t * @internal\n\t */\n\texport type Handle = 3;\n\t/**\n\t * @internal\n\t */\n\texport type Attachment = 4;\n\n\t/**\n\t * Represents a sub-tree in the summary.\n\t * @public\n\t */\n\texport const Tree: Tree = 1;\n\n\t/**\n\t * Represents a blob of data that is added to the summary.\n\t * Such as the user data that is added to the DDS or metadata added by runtime\n\t * such as data store / channel attributes.\n\t * @public\n\t */\n\texport const Blob: Blob = 2;\n\n\t/**\n\t * Path to a summary tree object from the last successful summary.\n\t * @public\n\t */\n\texport const Handle: Handle = 3;\n\n\t/**\n\t * Unique identifier to larger blobs uploaded outside of the summary.\n\t * Ex. DDS has large images or video that will be uploaded by the BlobManager and\n\t * receive an Id that can be used in the summary.\n\t * @public\n\t */\n\texport const Attachment: Attachment = 4;\n}\n\n/**\n * {@inheritDoc (SummaryType:namespace)}\n * @public\n */\nexport type SummaryType =\n\t| SummaryType.Attachment\n\t| SummaryType.Blob\n\t| SummaryType.Handle\n\t| SummaryType.Tree;\n\n/**\n * Summary type that {@link ISummaryHandle} points to.\n *\n * @remarks\n * Summary handles are often used to point to summary tree objects contained within older summaries, thus avoiding\n * the need to re-send the entire subtree if summary object has not changed.\n * @public\n */\nexport type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment;\n\n/**\n * Path to a summary tree object from the last successful summary indicating the summary object hasn't\n * changed since it was uploaded.\n *\n * Special characters include '/'. '/' is used as a separator between different parts of the path as a way to traverse\n * different nodes in the previous summary/snapshot tree.\n *\n * Note, our algorithms use encodeURIComponent and decodeURIComponent to handle special characters in the path. If a string\n * causes this path to fail, the id will be invalid.\n *\n * @example\n * To illustrate, if a DataStore did not change since last summary, the framework runtime will use a handle for the\n * entire DataStore instead of re-sending the entire subtree. The same concept applies for a DDS.\n * An example of a handle string generated when the DDS did not change would be: '/.channels/<DataStoreId>/.channels/<DDSId>'.\n * An example of a handle string generated when the DataStore did not change would be: '/.channels/<DataStoreId>'.\n * An example of a handle string generated when the DDS blob did not change would be: `/.channels/<DataStoreId>/.channels/<DDSId>/<BlobId>`.\n * An example of a handle string generated when the DataStore .attributes blob did not change would be: `/.channels/<DataStoreId>/.attributes`.\n * @public\n */\nexport interface ISummaryHandle {\n\ttype: SummaryType.Handle;\n\n\t/**\n\t * Type of Summary Handle (SummaryType.Handle is not supported).\n\t */\n\thandleType: SummaryTypeNoHandle;\n\n\t/**\n\t * Unique path that identifies the corresponding sub-tree in a previous summary.\n\t */\n\thandle: string;\n}\n\n/**\n * String or Binary data to be uploaded to the server as part of the container's Summary.\n *\n * @remarks\n * Note: Already uploaded blobs would be referenced by an {@link ISummaryAttachment}.\n * Additional information can be found here: {@link https://github.com/microsoft/FluidFramework/issues/6568}\n *\n * @example\n * \"content\": \"\\{ \\\"pkg\\\":\\\"[\\\\\\\"OfficeRootComponent\\\\\\\",\\\\\\\"LastEditedComponent\\\\\\\"]\\\",\n *                    \\\"summaryFormatVersion\\\":2,\\\"isRootDataStore\\\":false \\}\"\n * @public\n */\nexport interface ISummaryBlob {\n\ttype: SummaryType.Blob;\n\tcontent: string | Uint8Array;\n}\n\n/**\n * Unique identifier for blobs uploaded outside of the summary.\n *\n * @remarks\n *\n * Attachment Blobs are uploaded and downloaded separately and do not take part of the snapshot payload.\n * The ID gets returned from the backend after the attachment has been uploaded.\n * Additional information can be found here: {@link https://github.com/microsoft/FluidFramework/issues/6374}\n *\n * @example\n * \"id\": \"bQAQKARDdMdTgqICmBa_ZB86YXwGP\"\n * @public\n */\nexport interface ISummaryAttachment {\n\ttype: SummaryType.Attachment;\n\tid: string;\n}\n\n/**\n * Tree Node data structure with children that are nodes of SummaryObject type:\n * Blob, Handle, Attachment or another Tree.\n * @public\n */\nexport interface ISummaryTree {\n\ttype: SummaryType.Tree;\n\n\t/**\n\t * The object containing all the tree's {@link SummaryObject} children.\n\t *\n\t * @param path - The key to store the SummaryObject at in the current summary tree being generated. Should not contain any \"/\" characters and should not change when encodeURIComponent is called on it.\n\t */\n\ttree: { [path: string]: SummaryObject };\n\n\t/**\n\t * Indicates that this tree entry is unreferenced.\n\t * If this is not present, the tree entry is considered referenced.\n\t */\n\tunreferenced?: true;\n\n\t/**\n\t * Represents the loading group to which the summary tree belongs to. Please refer to this readme for more context.\n\t * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}\n\t * Also note that \"groupId\" is the same as \"loadingGroupId\" used elsewhere in the repo. The naming discrepancy is\n\t * intentional to minimize snapshot/summary size.\n\t */\n\tgroupId?: string;\n}\n"]}
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../src/protocol/summary.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAiBH;;;GAGG;AACH,2DAA2D;AAC3D,IAAiB,WAAW,CA6C3B;AA7CD,WAAiB,WAAW;IAkB3B;;;OAGG;IACU,gBAAI,GAAS,CAAC,CAAC;IAE5B;;;;;OAKG;IACU,gBAAI,GAAS,CAAC,CAAC;IAE5B;;;OAGG;IACU,kBAAM,GAAW,CAAC,CAAC;IAEhC;;;;;OAKG;IACU,sBAAU,GAAe,CAAC,CAAC;AACzC,CAAC,EA7CgB,WAAW,2BAAX,WAAW,QA6C3B","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Object representing a node within a summary tree.\n *\n * @remarks\n * If any particular node is an {@link ISummaryTree}, it can contain additional `SummaryObject`s as its children.\n * @public\n */\nexport type SummaryObject = ISummaryTree | ISummaryBlob | ISummaryHandle | ISummaryAttachment;\n\n/**\n * The root of the summary tree.\n * @legacy @beta\n */\nexport type SummaryTree = ISummaryTree | ISummaryHandle;\n\n/**\n * Type tag used to distinguish different types of nodes in a {@link ISummaryTree}.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/no-namespace\nexport namespace SummaryType {\n\t/**\n\t * @internal\n\t */\n\texport type Tree = 1;\n\t/**\n\t * @internal\n\t */\n\texport type Blob = 2;\n\t/**\n\t * @internal\n\t */\n\texport type Handle = 3;\n\t/**\n\t * @internal\n\t */\n\texport type Attachment = 4;\n\n\t/**\n\t * Represents a sub-tree in the summary.\n\t * @public\n\t */\n\texport const Tree: Tree = 1;\n\n\t/**\n\t * Represents a blob of data that is added to the summary.\n\t * Such as the user data that is added to the DDS or metadata added by runtime\n\t * such as data store / channel attributes.\n\t * @public\n\t */\n\texport const Blob: Blob = 2;\n\n\t/**\n\t * Path to a summary tree object from the last successful summary.\n\t * @public\n\t */\n\texport const Handle: Handle = 3;\n\n\t/**\n\t * Unique identifier to larger blobs uploaded outside of the summary.\n\t * Ex. DDS has large images or video that will be uploaded by the BlobManager and\n\t * receive an Id that can be used in the summary.\n\t * @public\n\t */\n\texport const Attachment: Attachment = 4;\n}\n\n/**\n * {@inheritDoc (SummaryType:namespace)}\n * @public\n */\nexport type SummaryType =\n\t| SummaryType.Attachment\n\t| SummaryType.Blob\n\t| SummaryType.Handle\n\t| SummaryType.Tree;\n\n/**\n * Summary type that {@link ISummaryHandle} points to.\n *\n * @remarks\n * Summary handles are often used to point to summary tree objects contained within older summaries, thus avoiding\n * the need to re-send the entire subtree if summary object has not changed.\n * @public\n */\nexport type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment;\n\n/**\n * Path to a summary tree object from the last successful summary indicating the summary object hasn't\n * changed since it was uploaded.\n *\n * Special characters include '/'. '/' is used as a separator between different parts of the path as a way to traverse\n * different nodes in the previous summary/snapshot tree.\n *\n * Note, our algorithms use encodeURIComponent and decodeURIComponent to handle special characters in the path. If a string\n * causes this path to fail, the id will be invalid.\n *\n * @example\n * To illustrate, if a DataStore did not change since last summary, the framework runtime will use a handle for the\n * entire DataStore instead of re-sending the entire subtree. The same concept applies for a DDS.\n * An example of a handle string generated when the DDS did not change would be: `/.channels/{dataStoreId}/.channels/{ddsId}`.\n * An example of a handle string generated when the DataStore did not change would be: `/.channels/{dataStoreId}`.\n * An example of a handle string generated when the DDS blob did not change would be: `/.channels/{dataStoreId}/.channels/{ddsId}/{blobId}`.\n * An example of a handle string generated when the DataStore .attributes blob did not change would be: `/.channels/{dataStoreId}/.attributes`.\n * @public\n */\nexport interface ISummaryHandle {\n\ttype: SummaryType.Handle;\n\n\t/**\n\t * Type of Summary Handle (SummaryType.Handle is not supported).\n\t */\n\thandleType: SummaryTypeNoHandle;\n\n\t/**\n\t * Unique path that identifies the corresponding sub-tree in a previous summary.\n\t */\n\thandle: string;\n}\n\n/**\n * String or Binary data to be uploaded to the server as part of the container's Summary.\n *\n * @remarks\n * Note: Already uploaded blobs would be referenced by an {@link ISummaryAttachment}.\n * Additional information can be found here: {@link https://github.com/microsoft/FluidFramework/issues/6568}\n *\n * @example\n * \"content\": \"\\{ \\\"pkg\\\":\\\"[\\\\\\\"OfficeRootComponent\\\\\\\",\\\\\\\"LastEditedComponent\\\\\\\"]\\\",\n *                    \\\"summaryFormatVersion\\\":2,\\\"isRootDataStore\\\":false \\}\"\n * @public\n */\nexport interface ISummaryBlob {\n\ttype: SummaryType.Blob;\n\tcontent: string | Uint8Array;\n}\n\n/**\n * Unique identifier for blobs uploaded outside of the summary.\n *\n * @remarks\n *\n * Attachment Blobs are uploaded and downloaded separately and do not take part of the snapshot payload.\n * The ID gets returned from the backend after the attachment has been uploaded.\n * Additional information can be found here: {@link https://github.com/microsoft/FluidFramework/issues/6374}\n *\n * @example\n * \"id\": \"bQAQKARDdMdTgqICmBa_ZB86YXwGP\"\n * @public\n */\nexport interface ISummaryAttachment {\n\ttype: SummaryType.Attachment;\n\tid: string;\n}\n\n/**\n * Tree Node data structure with children that are nodes of SummaryObject type:\n * Blob, Handle, Attachment or another Tree.\n * @public\n */\nexport interface ISummaryTree {\n\ttype: SummaryType.Tree;\n\n\t/**\n\t * The object containing all the tree's {@link SummaryObject} children.\n\t *\n\t * @param path - The key to store the SummaryObject at in the current summary tree being generated. Should not contain any \"/\" characters and should not change when encodeURIComponent is called on it.\n\t */\n\ttree: { [path: string]: SummaryObject };\n\n\t/**\n\t * Indicates that this tree entry is unreferenced.\n\t * If this is not present, the tree entry is considered referenced.\n\t */\n\tunreferenced?: true;\n\n\t/**\n\t * Represents the loading group to which the summary tree belongs to. Please refer to this readme for more context.\n\t * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}\n\t * Also note that \"groupId\" is the same as \"loadingGroupId\" used elsewhere in the repo. The naming discrepancy is\n\t * intentional to minimize snapshot/summary size.\n\t */\n\tgroupId?: string;\n}\n"]}

package/dist/serviceClient.d.ts

@@ -96,7 +96,7 @@ export declare function createBasicRegistryKey<T>(type: string): RegistryKey<T,
  * Oldest Fluid Framework client version that must be able to open and process documents written
  * by a service client.
  * @remarks
- * A string in SemVer format indicating a specific version of the Fluid Framework client package, or the special case of {@link @fluidframework/runtime-utils#defaultMinVersionForCollab}.
+ * A string in SemVer format indicating a specific stable version of the Fluid Framework client package.
  *
  * Service clients use this value to select write formats and features. Clients using this version
  * or newer must be able to open and process documents written by the service client. Choosing an
@@ -110,16 +110,15 @@ export declare function createBasicRegistryKey<T>(type: string): RegistryKey<T,
  * This differs in that:
  * - This is `alpha` instead of `public`.
  * - This is available to drivers due to its location in `driver-definitions` instead of `runtime-definitions`.
- * - This does not allow requesting collaboration with pre-2.0.0 versions, including the special case of `2.0.0-defaults`.
  * - Patch versions cannot be set: a given minor release is not guaranteed to be greater or equal compat wise to all patches of the previous release, so we do not enable features based on patch versions (instead fall back to the next minor if needed).
  * Therefore allowing patch versions here could be misleading and could lead to bugs.
  *
  * @input
  * @alpha
  */
-export type OldestSupportedServiceClientVersion = `2.${bigint}.0`;
+export type OldestSupportedServiceClientVersion = `${2 | 3}.${bigint}.0`;
 /**
- * Strips patch and prerelease from a SemVer string, returning only the major and minor version.
+ * Strips patch and prerelease from a SemVer string, returning only the major and minor version with a ".0" patch.
  * @remarks
  * This formats a version in the same style used by {@link OldestSupportedServiceClientVersion}, specifying only the major and minor versions,
  * which are the portions used for feature selection.

package/dist/serviceClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serviceClient.d.ts","sourceRoot":"","sources":["../src/serviceClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"serviceClient.d.ts","sourceRoot":"","sources":["../src/serviceClient.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,CAAC,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO;IAC/C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;OAUG;IACH,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,GAAG,EACzC,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,EACvB,GAAG,EAAE,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,GACzB,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAKzE;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,mCAAmC,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,MAAM,IAAI,CAAC;AAEzE;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,GAAG,MAAM,EAAE,EAAE,KAAK,SAAS,GAAG,MAAM,EAAE,EAClF,OAAO,EAAE,GAAG,KAAK,IAAI,KAAK,IAAI,MAAM,IAAI,MAAM,EAAE,GAAG,GAAG,KAAK,IAAI,KAAK,IAAI,MAAM,EAAE,GAC9E,GAAG,KAAK,IAAI,KAAK,IAAI,CAMvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,mCAAmC,CAAC;CACrE;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,IAAI,GAAG,OAAO,IAAI,WAAW,CACxD,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EACzB,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAC5B,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;OAOG;IACH,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,GAAG,OAAO,CAC9C,SAAQ,gBAAgB,EACvB,cAAc,CAAC,SAAS,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEjC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAErB;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,IAAI,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,cAAc,CAAC,KAAK,CAAC;IACxF;;;;OAIG;IACH,MAAM,IAAI,OAAO,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC;CAGjD;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,cAAc,CAAC,KAAK,CAAC;IACrF;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,aAAa,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAC7C,SAAQ,YAAY,CAAC,CAAC,CAAC,EACtB,cAAc,CAAC,SAAS,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;CAAG;AAElD;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,IAAI,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAErF;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAAC;IAElF;;;;;;;;OAQG;IACH,eAAe,CAAC,CAAC,EAChB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EACrB,QAAQ,EAAE,iBAAiB,GACzB,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzC;;;;;;;;;;OAUG;IACH,uBAAuB,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;IAEvF;;;;;;OAMG;IACH,uBAAuB,CAAC,CAAC,EACxB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EACrB,QAAQ,EAAE,iBAAiB,GACzB,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,CAAC,EACd,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAC3C,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC;CACtC"}

package/dist/serviceClient.js

@@ -4,7 +4,9 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.featureVersion = exports.createBasicRegistryKey = exports.lookupInRegistry = void 0;
+exports.lookupInRegistry = lookupInRegistry;
+exports.createBasicRegistryKey = createBasicRegistryKey;
+exports.featureVersion = featureVersion;
 /**
  * Lookup an entry in a {@link Registry} using a {@link RegistryKey}.
  * @typeParam TOut - The type produced from the looked-up entry.
@@ -14,7 +16,6 @@ exports.featureVersion = exports.createBasicRegistryKey = exports.lookupInRegist
 function lookupInRegistry(registry, key) {
     return key.adapt(registry(key.type));
 }
-exports.lookupInRegistry = lookupInRegistry;
 /**
  * Creates a simple {@link RegistryKey} which does no type conversion.
  * @typeParam T - The type of the registry entry, which is returned unchanged by the key.
@@ -26,9 +27,8 @@ function createBasicRegistryKey(type) {
         adapt: (value) => value,
     };
 }
-exports.createBasicRegistryKey = createBasicRegistryKey;
 /**
- * Strips patch and prerelease from a SemVer string, returning only the major and minor version.
+ * Strips patch and prerelease from a SemVer string, returning only the major and minor version with a ".0" patch.
  * @remarks
  * This formats a version in the same style used by {@link OldestSupportedServiceClientVersion}, specifying only the major and minor versions,
  * which are the portions used for feature selection.
@@ -47,6 +47,5 @@ function featureVersion(version) {
     const parsed = version.split(".");
     return `${parsed[0]}.${parsed[1]}.0`;
 }
-exports.featureVersion = featureVersion;
 // #endregion
 //# sourceMappingURL=serviceClient.js.map

package/dist/serviceClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"serviceClient.js","sourceRoot":"","sources":["../src/serviceClient.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAsFH;;;;;GAKG;AACH,SAAgB,gBAAgB,CAC/B,QAAuB,EACvB,GAA2B;IAE3B,OAAO,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACtC,CAAC;AALD,4CAKC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB,CAAI,IAAY;IACrD,OAAO;QACN,IAAI;QACJ,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK;KACvB,CAAC;AACH,CAAC;AALD,wDAKC;AAiCD;;;;;;;;;;;;GAYG;AACH,SAAgB,cAAc,CAC7B,OAAgF;IAEhF,6KAA6K;IAC7K,2JAA2J;IAC3J,6KAA6K;IAC7K,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAU,IAAI,MAAM,CAAC,CAAC,CAAU,IAAI,CAAC;AACxD,CAAC;AARD,wCAQC;AAoRD,aAAa","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ErasedBaseType } from \"@fluidframework/core-interfaces/internal\";\n\n/**\n * This file defines the external facing API for the {@link ServiceClient} and related types.\n *\n * It provides an API surface at a similar abstraction level to aqueduct and fluid-static, but is intended to be a replacement for those which solves several problems with them.\n * Mainly it strives to have the encapsulation of implementation details (including all legacy APIs from aqueduct and lower level internals) like fluid-static\n * while being both more flexible and simpler.\n *\n * This aims to be the cleanest practical way to build applications on the Fluid Framework Client.\n * There are however several known cases where the API quality was sacrificed to ease initial implementation,\n * since some of the unification desired in this API's design are not yet implemented in the underlying Fluid Framework Client code or require additional work to implement.\n * These cases are called out with TODOs in this file.\n * These should be considered and addressed before stabilizing this API past alpha.\n *\n * All code interacting through this API surface within a single client must avoid using multiple copies of any Fluid Framework client package (at the same or different versions).\n * This mirrors the `@public` \"declarative model\" APIs and is a deliberate simplification of what is allowed in the legacy API surface.\n * It is enforced best-effort only: `@sealed` nominal erased types catch many mismatches at compile time, and factory identity checks throw a UsageError (\"Conflicting ... with same type\") at run time, but the checking is not exhaustive.\n * See `LayerCompatibilityUnified.md` for the full policy, rationale, and failure signatures.\n *\n * TODO:\n * Before stabilizing any of this past beta, evaluate whether this single-copy requirement must be relaxed, and if so how.\n * Whatever rule is chosen (relaxed or not) should be enforced at both compile time and run time as much as possible.\n *\n * TODO:\n * Fault isolation should be considered in this API design.\n * When are exceptions recoverable and how?\n * Likely we can fault isolate exceptions to containers in most cases,\n * and containers can indicate their status by being closed or disposed.\n * Non fatal errors should not be exceptions.\n */\n\n// #region Registry types\n\n/**\n * A collection of entries looked up by a `type` string.\n * @remarks\n * Use of a function for this allows a few things that most collections would not:\n * 1. It's possible to generate placeholder / error values on demand.\n * 2. It makes loading from some external registry on demand practical.\n * 3. The lookup can throw an exception if appropriate (this would typically indicate a bug and produce a fatal error).\n * 4. Generation of values can be lazy, and even asynchronous if `T` allows for a promise.\n *\n * This flexibility lets the implementer decide how to handle requests for unknown types.\n * They can produce placeholders, assert, fall back to a generic implementation etc.\n * @typeParam T - The type of entry produced for any given `type` string.\n * @input\n * @alpha\n */\nexport type Registry<T> = (type: string) => T;\n\n/**\n * A strongly typed key for a {@link Registry}.\n * Use with {@link lookupInRegistry}.\n * @remarks\n * Used to look up a `TIn` in a `Registry<TIn>`, and produce a `TOut` from it.\n * @typeParam TOut - The type produced by {@link RegistryKey.adapt} from a looked-up entry.\n * @typeParam TIn - The type of the entries in the {@link Registry} this key is used with.\n * @privateRemarks\n * This is currently input and sealed, meaning effectively type erased since the design might change.\n * @input\n * @sealed\n * @alpha\n */\nexport interface RegistryKey<TOut, TIn = unknown> {\n\t/**\n\t * Identifier to provide to the {@link Registry}.\n\t */\n\treadonly type: string;\n\n\t/**\n\t * Convert a value from the registry to the desired output type.\n\t * @remarks\n\t * How this is done is up to the implementation.\n\t *\n\t * This might be a type guard which throws if the input is not valid.\n\t * Or it could be a conversion, an identity function, or something else.\n\t *\n\t * @param value - The value from the registry.\n\t * @returns The converted value.\n\t */\n\tadapt(value: TIn): TOut;\n}\n\n/**\n * Lookup an entry in a {@link Registry} using a {@link RegistryKey}.\n * @typeParam TOut - The type produced from the looked-up entry.\n * @typeParam TIn - The type of the entries in `registry`.\n * @alpha\n */\nexport function lookupInRegistry<TOut, TIn>(\n\tregistry: Registry<TIn>,\n\tkey: RegistryKey<TOut, TIn>,\n): TOut {\n\treturn key.adapt(registry(key.type));\n}\n\n/**\n * Creates a simple {@link RegistryKey} which does no type conversion.\n * @typeParam T - The type of the registry entry, which is returned unchanged by the key.\n * @alpha\n */\nexport function createBasicRegistryKey<T>(type: string): RegistryKey<T, T> {\n\treturn {\n\t\ttype,\n\t\tadapt: (value) => value,\n\t};\n}\n\n// #endregion\n\n// #region ServiceClient types\n\n/**\n * Oldest Fluid Framework client version that must be able to open and process documents written\n * by a service client.\n * @remarks\n * A string in SemVer format indicating a specific version of the Fluid Framework client package, or the special case of {@link @fluidframework/runtime-utils#defaultMinVersionForCollab}.\n *\n * Service clients use this value to select write formats and features. Clients using this version\n * or newer must be able to open and process documents written by the service client. Choosing an\n * older version may limit the features and write formats the application can use to those\n * supported by that version.\n *\n * Cannot exceed the version of any Fluid Framework client package in use by the local client.\n *\n * @privateRemarks\n * This is similar to, and a subset of, the `OldestSupportedClientVersion` type in `@fluidframework/runtime-definitions`.\n * This differs in that:\n * - This is `alpha` instead of `public`.\n * - This is available to drivers due to its location in `driver-definitions` instead of `runtime-definitions`.\n * - This does not allow requesting collaboration with pre-2.0.0 versions, including the special case of `2.0.0-defaults`.\n * - Patch versions cannot be set: a given minor release is not guaranteed to be greater or equal compat wise to all patches of the previous release, so we do not enable features based on patch versions (instead fall back to the next minor if needed).\n * Therefore allowing patch versions here could be misleading and could lead to bugs.\n *\n * @input\n * @alpha\n */\nexport type OldestSupportedServiceClientVersion = `2.${bigint}.0`;\n\n/**\n * Strips patch and prerelease from a SemVer string, returning only the major and minor version.\n * @remarks\n * This formats a version in the same style used by {@link OldestSupportedServiceClientVersion}, specifying only the major and minor versions,\n * which are the portions used for feature selection.\n * @typeParam major - The major version number of `version` as a string, preserved in the result type.\n * @typeParam minor - The minor version number of `version` as a string, preserved in the result type.\n * @privateRemarks\n * This fills a similar role as cleanedPackageVersion in `@fluidframework/runtime-utils`.\n * It can be used to workaround our generated pkgVersion values being invalid\n * `OldestSupportedServiceClientVersion` on CI due to prerelease or patched release branches.\n * @alpha\n */\nexport function featureVersion<major extends `${bigint}`, minor extends `${bigint}`>(\n\tversion: `${major}.${minor}.${bigint}-${string}` | `${major}.${minor}.${bigint}`,\n): `${major}.${minor}.0` {\n\t// The SemVer package could be used to parse this version, but it wouldn't gain us anything, and would just make it harder to determine that the down casting below is valid.\n\t// Since we have a strongly typed string input, we know exactly which formats are allowed, so we don't need its more general parsing and validation either.\n\t// If we wanted to preserve the patch or prerelease version, that would require more complex parsing and would justify using the SemVer package, but we don't need that here.\n\tconst parsed = version.split(\".\");\n\treturn `${parsed[0] as major}.${parsed[1] as minor}.0`;\n}\n\n/**\n * Options for configuring a {@link ServiceClient}.\n * @remarks\n * These are the options which apply to all services.\n *\n * Individual services will extend with additional options.\n *\n * @input\n * @alpha\n */\nexport interface ServiceOptions {\n\t/**\n\t * Oldest Fluid Framework client version that must be able to open and process documents written\n\t * by the service client.\n\t *\n\t * @remarks\n\t * Choosing an older version may limit the features and write formats the application can use to\n\t * those supported by that version.\n\t *\n\t * A service may provide a default when this option is omitted.\n\t */\n\treadonly oldestSupportedClient?: OldestSupportedServiceClientVersion;\n}\n\n/**\n * A {@link RegistryKey} for a {@link DataStoreKind}.\n * @remarks\n * This is implemented by {@link DataStoreKind}, but alternative implementations can be used if needed.\n *\n * If you want lazy loading and need a key that does not eagerly load the {@link DataStoreKind}, an alternative {@link DataStoreKey} can be implemented.\n * @typeParam T - The type to expose from the {@link DataStoreKind} this key resolves to.\n * @typeParam TAll - The type covering all {@link DataStoreKind}s in the {@link Registry} this key is used with.\n * @privateRemarks\n * TODO: A built in common pattern for the lazy key case should be provided.\n * TODO: things probably break if \"adapt\" does anything except throw or return the result from the input promise.\n * @input\n * @alpha\n */\nexport type DataStoreKey<T, TAll = unknown> = RegistryKey<\n\tPromise<DataStoreKind<T>>,\n\tPromise<DataStoreKind<TAll>>\n>;\n\n/**\n * A context which has a registry and can create data stores using it.\n * @sealed\n * @alpha\n */\nexport interface DataStoreCreator {\n\t/**\n\t * Create a new detached data store `T` which can be attached to the {@link FluidContainer}.\n\t * by adding a handle to a data store or shared object which is already attached to the {@link FluidContainer}.\n\t * @remarks\n\t * `kind` will be looked up in the {@link Registry} used to create or load this {@link DataStoreCreator}.\n\t * It is up to that registry to decide how it handles unknown types, for example by throwing an exception or returning a placeholder.\n\t * @typeParam T - type implemented by the data store to expose in the result, as defined by `kind`.\n\t */\n\tcreateDataStore<T>(kind: DataStoreKey<T>): Promise<T>;\n}\n\n/**\n * A Fluid container.\n * @remarks\n * A document which can be stored to or loaded from a Fluid service using a {@link ServiceClient}.\n *\n * @typeParam TData - The type of the container's root data store, exposed via {@link FluidContainer.data}.\n * @privateRemarks\n * This will likely end up needing many of IFluidContainer's APIs, like disconnect, connectionState, events etc.\n * Before adding them though, care should be taken to consider if they can be improved or simplified.\n * For example maybe a single status enum for `detached -> attaching -> dirty -> saved -> closed` would be good.\n * Or maybe `detached -> attaching -> attached -> closed` and a timer for how long since the last unsaved change was created.\n *\n * The underlying IContainer has a lifecycle which includes both a closed and disposed state.\n * This should be avoidable: the closed but not disposed state exists so its possible to read out some state at that time.\n * We have made the close remove all the timers, so the the dispose step should be unnecessary and we can just have a single closed state.\n *\n * @sealed\n * @alpha\n */\nexport interface FluidContainer<TData = unknown>\n\textends DataStoreCreator,\n\t\tErasedBaseType<readonly [\"FluidContainer\", TData]> {\n\t/**\n\t * The unique identifier for this container within its service.\n\t * @remarks\n\t * `undefined` if the container has not yet been attached to a service.\n\t * This can be used to load another instance of this container from the service using {@link ServiceClient.loadContainer}.\n\t */\n\treadonly id?: string | undefined;\n\n\t/**\n\t * The root data store of the container.\n\t * @remarks\n\t * The type of the root data store is defined by the {@link DataStoreKind} used to create the container.\n\t */\n\treadonly data: TData;\n\n\t/**\n\t * Close the container, stopping all networking and cancelling runtime timers.\n\t *\n\t * @remarks\n\t * After calling `close()`, the container's data can still be read but no further operations can be sent.\n\t * @privateRemarks\n\t * TODO: we should document the what the expected behavior is if one tries to modify the data after close, or tries to call close multiple times.\n\t * TODO: we also likely want to have a way to detect if closed and events for on close.\n\t * TODO: ensure this truly closes all timers: it seems like we might still leak some related to the summarizer.\n\t * TODO: we should clarify how this interacts with unsaved content including inprogress summaries,\n\t * and likely also provide an async API with some options for how to handle that.\n\t */\n\tclose(): void;\n}\n\n/**\n * A Fluid container with an associated {@link ServiceClient} it can attach to.\n * @typeParam TData - The type of the container's root data store.\n * @sealed\n * @alpha\n */\nexport interface FluidContainerWithService<TData = unknown> extends FluidContainer<TData> {\n\t/**\n\t * Attaches this container to the associated service client.\n\t *\n\t * The returned promise resolves once the container is attached: the container from the promise is the same one passed in as the argument.\n\t */\n\tattach(): Promise<FluidContainerAttached<TData>>;\n\n\t// This could expose access to the ServiceClient if needed.\n}\n\n/**\n * A Fluid container that has been attached to a service.\n * @typeParam TData - The type of the container's root data store.\n * @sealed\n * @alpha\n */\nexport interface FluidContainerAttached<TData = unknown> extends FluidContainer<TData> {\n\t/**\n\t * {@inheritdoc FluidContainer.id}\n\t */\n\treadonly id: string;\n}\n\n/**\n * Defines a {@link https://en.wikipedia.org/wiki/Kind_(type_theory) | kind} of data store, allowing creating and loading instances of it.\n * @remarks\n * A `DataStoreKind` acts as the factory and type descriptor for a category of data store:\n * it defines the `type` used to identify the data store in a {@link DataStoreRegistry},\n * and the `T` API surface that instances of that data store expose.\n *\n * Provide a `DataStoreKind` to {@link ServiceClient.(createContainer:1)} or {@link DataStoreCreator.createDataStore}\n * to create new instances, and to {@link ServiceClient.loadContainer} to load existing ones.\n *\n * A `DataStoreKind` is not constructed directly.\n * Instead, obtain one from a framework-provided factory:\n * use {@link @fluidframework/shared-object-base#defineDataStore} to define a data store which wraps a root shared object,\n * or use a more specific wrapper around that,\n * such as {@link @fluidframework/tree#defineTreeDataStore} for a {@link @fluidframework/tree#TreeView}-backed data store.\n *\n * Since it implements {@link DataStoreKey}, a `DataStoreKind` can also be used directly as the key to look\n * itself up in a {@link Registry}.\n * @typeParam T - The API surface that instances of this data store kind expose.\n * @privateRemarks\n * TODO:\n * SharedObjects should be usable as these (though putting shared objects directly in the container might need special logic).\n * Type erased {@link IFluidDataStoreFactory}.\n * @sealed\n * @alpha\n */\nexport interface DataStoreKind<out T = unknown>\n\textends DataStoreKey<T>,\n\t\tErasedBaseType<readonly [\"DataStoreKind\", T]> {}\n\n/**\n * A registry of {@link DataStoreKind}s.\n * @privateRemarks\n * TODO: unify this with SharedObjectRegistry.\n *\n * @typeParam T - The type covering all {@link DataStoreKind}s in the registry.\n * @input\n * @alpha\n */\nexport type DataStoreRegistry<out T = unknown> = Registry<Promise<DataStoreKind<T>>>;\n\n/**\n * A connection to a Fluid storage service.\n * @sealed\n * @alpha\n */\nexport interface ServiceClient {\n\t/**\n\t * Creates a detached container associated with this service client.\n\t * @typeParam T - The type of the container's root data store, as defined by `root`.\n\t * @param root - A {@link DataStoreKind} to use for the root.\n\t * @remarks\n\t * This overload is a shorthand for a simple case of {@link ServiceClient.(createContainer:2)}\n\t * where a single item registry is produced which contains only the root.\n\t * This is usable only when the root {@link DataStoreKind} is available eagerly (e.g. not lazy loaded),\n\t * and when the container does not need a registry for creating additional data stores beyond the root.\n\t * @privateRemarks\n\t * TODO: As this is a detached container, it should be able to be created synchronously.\n\t *\n\t * TODO: Provide more general alternative to this in the form of a service-independent `createContainer` free function.\n\t * It would work with a `ServiceClient.attachContainer<T>(detached: FluidContainer<T>): Promise<FluidContainerAttached<T>>`\n\t * which returns a promise that resolves once the detached container has been attached\n\t * (pointing to the same container object, but with the new type).\n\t *\n\t * Challenges:\n\t *\n\t * Currently the service must be provided at creation time because `IContainer.attach` does not accept a service client,\n\t * making it unclear whether a truly service-independent path is feasible in the near term.\n\t */\n\tcreateContainer<T>(root: DataStoreKind<T>): Promise<FluidContainerWithService<T>>;\n\n\t/**\n\t * Creates a detached container associated with this service client.\n\t * @typeParam T - The type of the container's root data store, as defined by `root`.\n\t * @param root - A {@link DataStoreKey} used to look up the root's {@link DataStoreKind} from `registry`.\n\t * @param registry - The {@link DataStoreRegistry} supplying the {@link DataStoreKind} for the root and any other data stores the container may need to create.\n\t * @remarks\n\t * Use this overload when the root {@link DataStoreKind} is not available eagerly (e.g. for lazy loading),\n\t * or when the container needs a registry for creating additional data stores beyond the root.\n\t */\n\tcreateContainer<T>(\n\t\troot: DataStoreKey<T>,\n\t\tregistry: DataStoreRegistry,\n\t): Promise<FluidContainerWithService<T>>;\n\n\t/**\n\t * A shorthand for {@link ServiceClient.(createContainer:1)} followed by {@link FluidContainerWithService.attach}.\n\t * @remarks\n\t * Due to current implementation limitations making container creation async and service specific,\n\t * creating then attaching one is a bit verbose with two awaits that are messy to include inline.\n\t * This provides a convenient way to create and attach a container in a single step.\n\t * @privateRemarks\n\t * TODO: We should fix ergonomics issues that make this helpful,\n\t * then remove (or deprecate) this method in favor of `service.attach(createContainer(root))` as a better orthogonalized API.\n\t * See private remarks on {@link ServiceClient.(createContainer:1)}.\n\t */\n\tcreateAttachedContainer<T>(root: DataStoreKind<T>): Promise<FluidContainerAttached<T>>;\n\n\t/**\n\t * A shorthand for {@link ServiceClient.(createContainer:2)} followed by {@link FluidContainerWithService.attach}.\n\t * @remarks\n\t * Due to current implementation limitations making container creation async and service specific,\n\t * creating then attaching one is a bit verbose with two awaits that are messy to include inline.\n\t * This provides a convenient way to create and attach a container in a single step.\n\t */\n\tcreateAttachedContainer<T>(\n\t\troot: DataStoreKey<T>,\n\t\tregistry: DataStoreRegistry,\n\t): Promise<FluidContainerAttached<T>>;\n\n\t/**\n\t * Loads an existing container from the service.\n\t * @typeParam T - The type of the container's root data store.\n\t * @param id - The unique identifier of the container to load.\n\t * @param root - The {@link DataStoreKind} for the root, or a registry which will be used to look up the root based on its type.\n\t *\n\t * @throws a {@link @fluidframework/telemetry-utils#UsageError} if the DataStoreKind's type (either the root directly or looked up from the registry) does not match the type of the root data store in the container.\n\t *\n\t * @privateRemarks\n\t * The ability to provide a registry here means that it's possible to:\n\t * 1. Load a container which might have a few different possible roots, for example because of versioning.\n\t * 2. Generate the DataStoreKind on demand based on the type: this approach could be used for things like debug tools which can load any possible container.\n\t * 3. Generating the DataStoreKind if the type is unrecognized, for example to provide a placeholder which might support some minimal functionality (like debug inspection, and summary).\n\t *\n\t * The ability to provide just a single DataStoreKind<T> is purely a convenience to make it cleaner to use this in simple cases.\n\t */\n\tloadContainer<T>(\n\t\tid: string,\n\t\troot: DataStoreKind<T> | DataStoreRegistry<T>,\n\t): Promise<FluidContainerAttached<T>>;\n}\n\n// #endregion\n"]}
+{"version":3,"file":"serviceClient.js","sourceRoot":"","sources":["../src/serviceClient.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AA4FH,4CAKC;AAOD,wDAKC;AA6CD,wCAQC;AA5ED;;;;;GAKG;AACH,SAAgB,gBAAgB,CAC/B,QAAuB,EACvB,GAA2B;IAE3B,OAAO,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB,CAAI,IAAY;IACrD,OAAO;QACN,IAAI;QACJ,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK;KACvB,CAAC;AACH,CAAC;AAgCD;;;;;;;;;;;;GAYG;AACH,SAAgB,cAAc,CAC7B,OAAgF;IAEhF,6KAA6K;IAC7K,2JAA2J;IAC3J,6KAA6K;IAC7K,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAU,IAAI,MAAM,CAAC,CAAC,CAAU,IAAI,CAAC;AACxD,CAAC;AAoRD,aAAa","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ErasedBaseType } from \"@fluidframework/core-interfaces/internal\";\n\n/**\n * This file defines the external facing API for the {@link ServiceClient} and related types.\n *\n * It provides an API surface at a similar abstraction level to aqueduct and fluid-static, but is intended to be a replacement for those which solves several problems with them.\n * Mainly it strives to have the encapsulation of implementation details (including all legacy APIs from aqueduct and lower level internals) like fluid-static\n * while being both more flexible and simpler.\n *\n * This aims to be the cleanest practical way to build applications on the Fluid Framework Client.\n * There are however several known cases where the API quality was sacrificed to ease initial implementation,\n * since some of the unification desired in this API's design are not yet implemented in the underlying Fluid Framework Client code or require additional work to implement.\n * These cases are called out with TODOs in this file.\n * These should be considered and addressed before stabilizing this API past alpha.\n *\n * All code interacting through this API surface within a single client must avoid using multiple copies of any Fluid Framework client package (at the same or different versions).\n * This mirrors the `@public` \"declarative model\" APIs and is a deliberate simplification of what is allowed in the legacy API surface.\n * It is enforced best-effort only: `@sealed` nominal erased types catch many mismatches at compile time, and factory identity checks throw a UsageError (\"Conflicting ... with same type\") at run time, but the checking is not exhaustive.\n * See `LayerCompatibilityUnified.md` for the full policy, rationale, and failure signatures.\n *\n * TODO:\n * Before stabilizing any of this past beta, evaluate whether this single-copy requirement must be relaxed, and if so how.\n * Whatever rule is chosen (relaxed or not) should be enforced at both compile time and run time as much as possible.\n *\n * TODO:\n * Fault isolation should be considered in this API design.\n * When are exceptions recoverable and how?\n * Likely we can fault isolate exceptions to containers in most cases,\n * and containers can indicate their status by being closed or disposed.\n * Non fatal errors should not be exceptions.\n */\n\n// #region Registry types\n\n/**\n * A collection of entries looked up by a `type` string.\n * @remarks\n * Use of a function for this allows a few things that most collections would not:\n * 1. It's possible to generate placeholder / error values on demand.\n * 2. It makes loading from some external registry on demand practical.\n * 3. The lookup can throw an exception if appropriate (this would typically indicate a bug and produce a fatal error).\n * 4. Generation of values can be lazy, and even asynchronous if `T` allows for a promise.\n *\n * This flexibility lets the implementer decide how to handle requests for unknown types.\n * They can produce placeholders, assert, fall back to a generic implementation etc.\n * @typeParam T - The type of entry produced for any given `type` string.\n * @input\n * @alpha\n */\nexport type Registry<T> = (type: string) => T;\n\n/**\n * A strongly typed key for a {@link Registry}.\n * Use with {@link lookupInRegistry}.\n * @remarks\n * Used to look up a `TIn` in a `Registry<TIn>`, and produce a `TOut` from it.\n * @typeParam TOut - The type produced by {@link RegistryKey.adapt} from a looked-up entry.\n * @typeParam TIn - The type of the entries in the {@link Registry} this key is used with.\n * @privateRemarks\n * This is currently input and sealed, meaning effectively type erased since the design might change.\n * @input\n * @sealed\n * @alpha\n */\nexport interface RegistryKey<TOut, TIn = unknown> {\n\t/**\n\t * Identifier to provide to the {@link Registry}.\n\t */\n\treadonly type: string;\n\n\t/**\n\t * Convert a value from the registry to the desired output type.\n\t * @remarks\n\t * How this is done is up to the implementation.\n\t *\n\t * This might be a type guard which throws if the input is not valid.\n\t * Or it could be a conversion, an identity function, or something else.\n\t *\n\t * @param value - The value from the registry.\n\t * @returns The converted value.\n\t */\n\tadapt(value: TIn): TOut;\n}\n\n/**\n * Lookup an entry in a {@link Registry} using a {@link RegistryKey}.\n * @typeParam TOut - The type produced from the looked-up entry.\n * @typeParam TIn - The type of the entries in `registry`.\n * @alpha\n */\nexport function lookupInRegistry<TOut, TIn>(\n\tregistry: Registry<TIn>,\n\tkey: RegistryKey<TOut, TIn>,\n): TOut {\n\treturn key.adapt(registry(key.type));\n}\n\n/**\n * Creates a simple {@link RegistryKey} which does no type conversion.\n * @typeParam T - The type of the registry entry, which is returned unchanged by the key.\n * @alpha\n */\nexport function createBasicRegistryKey<T>(type: string): RegistryKey<T, T> {\n\treturn {\n\t\ttype,\n\t\tadapt: (value) => value,\n\t};\n}\n\n// #endregion\n\n// #region ServiceClient types\n\n/**\n * Oldest Fluid Framework client version that must be able to open and process documents written\n * by a service client.\n * @remarks\n * A string in SemVer format indicating a specific stable version of the Fluid Framework client package.\n *\n * Service clients use this value to select write formats and features. Clients using this version\n * or newer must be able to open and process documents written by the service client. Choosing an\n * older version may limit the features and write formats the application can use to those\n * supported by that version.\n *\n * Cannot exceed the version of any Fluid Framework client package in use by the local client.\n *\n * @privateRemarks\n * This is similar to, and a subset of, the `OldestSupportedClientVersion` type in `@fluidframework/runtime-definitions`.\n * This differs in that:\n * - This is `alpha` instead of `public`.\n * - This is available to drivers due to its location in `driver-definitions` instead of `runtime-definitions`.\n * - Patch versions cannot be set: a given minor release is not guaranteed to be greater or equal compat wise to all patches of the previous release, so we do not enable features based on patch versions (instead fall back to the next minor if needed).\n * Therefore allowing patch versions here could be misleading and could lead to bugs.\n *\n * @input\n * @alpha\n */\nexport type OldestSupportedServiceClientVersion = `${2 | 3}.${bigint}.0`;\n\n/**\n * Strips patch and prerelease from a SemVer string, returning only the major and minor version with a \".0\" patch.\n * @remarks\n * This formats a version in the same style used by {@link OldestSupportedServiceClientVersion}, specifying only the major and minor versions,\n * which are the portions used for feature selection.\n * @typeParam major - The major version number of `version` as a string, preserved in the result type.\n * @typeParam minor - The minor version number of `version` as a string, preserved in the result type.\n * @privateRemarks\n * This fills a similar role as cleanedPackageVersion in `@fluidframework/runtime-utils`.\n * It can be used to workaround our generated pkgVersion values being invalid\n * `OldestSupportedServiceClientVersion` on CI due to prerelease or patched release branches.\n * @alpha\n */\nexport function featureVersion<major extends `${bigint}`, minor extends `${bigint}`>(\n\tversion: `${major}.${minor}.${bigint}-${string}` | `${major}.${minor}.${bigint}`,\n): `${major}.${minor}.0` {\n\t// The SemVer package could be used to parse this version, but it wouldn't gain us anything, and would just make it harder to determine that the down casting below is valid.\n\t// Since we have a strongly typed string input, we know exactly which formats are allowed, so we don't need its more general parsing and validation either.\n\t// If we wanted to preserve the patch or prerelease version, that would require more complex parsing and would justify using the SemVer package, but we don't need that here.\n\tconst parsed = version.split(\".\");\n\treturn `${parsed[0] as major}.${parsed[1] as minor}.0`;\n}\n\n/**\n * Options for configuring a {@link ServiceClient}.\n * @remarks\n * These are the options which apply to all services.\n *\n * Individual services will extend with additional options.\n *\n * @input\n * @alpha\n */\nexport interface ServiceOptions {\n\t/**\n\t * Oldest Fluid Framework client version that must be able to open and process documents written\n\t * by the service client.\n\t *\n\t * @remarks\n\t * Choosing an older version may limit the features and write formats the application can use to\n\t * those supported by that version.\n\t *\n\t * A service may provide a default when this option is omitted.\n\t */\n\treadonly oldestSupportedClient?: OldestSupportedServiceClientVersion;\n}\n\n/**\n * A {@link RegistryKey} for a {@link DataStoreKind}.\n * @remarks\n * This is implemented by {@link DataStoreKind}, but alternative implementations can be used if needed.\n *\n * If you want lazy loading and need a key that does not eagerly load the {@link DataStoreKind}, an alternative {@link DataStoreKey} can be implemented.\n * @typeParam T - The type to expose from the {@link DataStoreKind} this key resolves to.\n * @typeParam TAll - The type covering all {@link DataStoreKind}s in the {@link Registry} this key is used with.\n * @privateRemarks\n * TODO: A built in common pattern for the lazy key case should be provided.\n * TODO: things probably break if \"adapt\" does anything except throw or return the result from the input promise.\n * @input\n * @alpha\n */\nexport type DataStoreKey<T, TAll = unknown> = RegistryKey<\n\tPromise<DataStoreKind<T>>,\n\tPromise<DataStoreKind<TAll>>\n>;\n\n/**\n * A context which has a registry and can create data stores using it.\n * @sealed\n * @alpha\n */\nexport interface DataStoreCreator {\n\t/**\n\t * Create a new detached data store `T` which can be attached to the {@link FluidContainer}.\n\t * by adding a handle to a data store or shared object which is already attached to the {@link FluidContainer}.\n\t * @remarks\n\t * `kind` will be looked up in the {@link Registry} used to create or load this {@link DataStoreCreator}.\n\t * It is up to that registry to decide how it handles unknown types, for example by throwing an exception or returning a placeholder.\n\t * @typeParam T - type implemented by the data store to expose in the result, as defined by `kind`.\n\t */\n\tcreateDataStore<T>(kind: DataStoreKey<T>): Promise<T>;\n}\n\n/**\n * A Fluid container.\n * @remarks\n * A document which can be stored to or loaded from a Fluid service using a {@link ServiceClient}.\n *\n * @typeParam TData - The type of the container's root data store, exposed via {@link FluidContainer.data}.\n * @privateRemarks\n * This will likely end up needing many of IFluidContainer's APIs, like disconnect, connectionState, events etc.\n * Before adding them though, care should be taken to consider if they can be improved or simplified.\n * For example maybe a single status enum for `detached -> attaching -> dirty -> saved -> closed` would be good.\n * Or maybe `detached -> attaching -> attached -> closed` and a timer for how long since the last unsaved change was created.\n *\n * The underlying IContainer has a lifecycle which includes both a closed and disposed state.\n * This should be avoidable: the closed but not disposed state exists so its possible to read out some state at that time.\n * We have made the close remove all the timers, so the the dispose step should be unnecessary and we can just have a single closed state.\n *\n * @sealed\n * @alpha\n */\nexport interface FluidContainer<TData = unknown>\n\textends DataStoreCreator,\n\t\tErasedBaseType<readonly [\"FluidContainer\", TData]> {\n\t/**\n\t * The unique identifier for this container within its service.\n\t * @remarks\n\t * `undefined` if the container has not yet been attached to a service.\n\t * This can be used to load another instance of this container from the service using {@link ServiceClient.loadContainer}.\n\t */\n\treadonly id?: string | undefined;\n\n\t/**\n\t * The root data store of the container.\n\t * @remarks\n\t * The type of the root data store is defined by the {@link DataStoreKind} used to create the container.\n\t */\n\treadonly data: TData;\n\n\t/**\n\t * Close the container, stopping all networking and cancelling runtime timers.\n\t *\n\t * @remarks\n\t * After calling `close()`, the container's data can still be read but no further operations can be sent.\n\t * @privateRemarks\n\t * TODO: we should document the what the expected behavior is if one tries to modify the data after close, or tries to call close multiple times.\n\t * TODO: we also likely want to have a way to detect if closed and events for on close.\n\t * TODO: ensure this truly closes all timers: it seems like we might still leak some related to the summarizer.\n\t * TODO: we should clarify how this interacts with unsaved content including inprogress summaries,\n\t * and likely also provide an async API with some options for how to handle that.\n\t */\n\tclose(): void;\n}\n\n/**\n * A Fluid container with an associated {@link ServiceClient} it can attach to.\n * @typeParam TData - The type of the container's root data store.\n * @sealed\n * @alpha\n */\nexport interface FluidContainerWithService<TData = unknown> extends FluidContainer<TData> {\n\t/**\n\t * Attaches this container to the associated service client.\n\t *\n\t * The returned promise resolves once the container is attached: the container from the promise is the same one passed in as the argument.\n\t */\n\tattach(): Promise<FluidContainerAttached<TData>>;\n\n\t// This could expose access to the ServiceClient if needed.\n}\n\n/**\n * A Fluid container that has been attached to a service.\n * @typeParam TData - The type of the container's root data store.\n * @sealed\n * @alpha\n */\nexport interface FluidContainerAttached<TData = unknown> extends FluidContainer<TData> {\n\t/**\n\t * {@inheritdoc FluidContainer.id}\n\t */\n\treadonly id: string;\n}\n\n/**\n * Defines a {@link https://en.wikipedia.org/wiki/Kind_(type_theory) | kind} of data store, allowing creating and loading instances of it.\n * @remarks\n * A `DataStoreKind` acts as the factory and type descriptor for a category of data store:\n * it defines the `type` used to identify the data store in a {@link DataStoreRegistry},\n * and the `T` API surface that instances of that data store expose.\n *\n * Provide a `DataStoreKind` to {@link ServiceClient.(createContainer:1)} or {@link DataStoreCreator.createDataStore}\n * to create new instances, and to {@link ServiceClient.loadContainer} to load existing ones.\n *\n * A `DataStoreKind` is not constructed directly.\n * Instead, obtain one from a framework-provided factory:\n * use {@link @fluidframework/shared-object-base#defineDataStore} to define a data store which wraps a root shared object,\n * or use a more specific wrapper around that,\n * such as {@link @fluidframework/tree#defineTreeDataStore} for a {@link @fluidframework/tree#TreeView}-backed data store.\n *\n * Since it implements {@link DataStoreKey}, a `DataStoreKind` can also be used directly as the key to look\n * itself up in a {@link Registry}.\n * @typeParam T - The API surface that instances of this data store kind expose.\n * @privateRemarks\n * TODO:\n * SharedObjects should be usable as these (though putting shared objects directly in the container might need special logic).\n * Type erased {@link IFluidDataStoreFactory}.\n * @sealed\n * @alpha\n */\nexport interface DataStoreKind<out T = unknown>\n\textends DataStoreKey<T>,\n\t\tErasedBaseType<readonly [\"DataStoreKind\", T]> {}\n\n/**\n * A registry of {@link DataStoreKind}s.\n * @privateRemarks\n * TODO: unify this with SharedObjectRegistry.\n *\n * @typeParam T - The type covering all {@link DataStoreKind}s in the registry.\n * @input\n * @alpha\n */\nexport type DataStoreRegistry<out T = unknown> = Registry<Promise<DataStoreKind<T>>>;\n\n/**\n * A connection to a Fluid storage service.\n * @sealed\n * @alpha\n */\nexport interface ServiceClient {\n\t/**\n\t * Creates a detached container associated with this service client.\n\t * @typeParam T - The type of the container's root data store, as defined by `root`.\n\t * @param root - A {@link DataStoreKind} to use for the root.\n\t * @remarks\n\t * This overload is a shorthand for a simple case of {@link ServiceClient.(createContainer:2)}\n\t * where a single item registry is produced which contains only the root.\n\t * This is usable only when the root {@link DataStoreKind} is available eagerly (e.g. not lazy loaded),\n\t * and when the container does not need a registry for creating additional data stores beyond the root.\n\t * @privateRemarks\n\t * TODO: As this is a detached container, it should be able to be created synchronously.\n\t *\n\t * TODO: Provide more general alternative to this in the form of a service-independent `createContainer` free function.\n\t * It would work with a `ServiceClient.attachContainer<T>(detached: FluidContainer<T>): Promise<FluidContainerAttached<T>>`\n\t * which returns a promise that resolves once the detached container has been attached\n\t * (pointing to the same container object, but with the new type).\n\t *\n\t * Challenges:\n\t *\n\t * Currently the service must be provided at creation time because `IContainer.attach` does not accept a service client,\n\t * making it unclear whether a truly service-independent path is feasible in the near term.\n\t */\n\tcreateContainer<T>(root: DataStoreKind<T>): Promise<FluidContainerWithService<T>>;\n\n\t/**\n\t * Creates a detached container associated with this service client.\n\t * @typeParam T - The type of the container's root data store, as defined by `root`.\n\t * @param root - A {@link DataStoreKey} used to look up the root's {@link DataStoreKind} from `registry`.\n\t * @param registry - The {@link DataStoreRegistry} supplying the {@link DataStoreKind} for the root and any other data stores the container may need to create.\n\t * @remarks\n\t * Use this overload when the root {@link DataStoreKind} is not available eagerly (e.g. for lazy loading),\n\t * or when the container needs a registry for creating additional data stores beyond the root.\n\t */\n\tcreateContainer<T>(\n\t\troot: DataStoreKey<T>,\n\t\tregistry: DataStoreRegistry,\n\t): Promise<FluidContainerWithService<T>>;\n\n\t/**\n\t * A shorthand for {@link ServiceClient.(createContainer:1)} followed by {@link FluidContainerWithService.attach}.\n\t * @remarks\n\t * Due to current implementation limitations making container creation async and service specific,\n\t * creating then attaching one is a bit verbose with two awaits that are messy to include inline.\n\t * This provides a convenient way to create and attach a container in a single step.\n\t * @privateRemarks\n\t * TODO: We should fix ergonomics issues that make this helpful,\n\t * then remove (or deprecate) this method in favor of `service.attach(createContainer(root))` as a better orthogonalized API.\n\t * See private remarks on {@link ServiceClient.(createContainer:1)}.\n\t */\n\tcreateAttachedContainer<T>(root: DataStoreKind<T>): Promise<FluidContainerAttached<T>>;\n\n\t/**\n\t * A shorthand for {@link ServiceClient.(createContainer:2)} followed by {@link FluidContainerWithService.attach}.\n\t * @remarks\n\t * Due to current implementation limitations making container creation async and service specific,\n\t * creating then attaching one is a bit verbose with two awaits that are messy to include inline.\n\t * This provides a convenient way to create and attach a container in a single step.\n\t */\n\tcreateAttachedContainer<T>(\n\t\troot: DataStoreKey<T>,\n\t\tregistry: DataStoreRegistry,\n\t): Promise<FluidContainerAttached<T>>;\n\n\t/**\n\t * Loads an existing container from the service.\n\t * @typeParam T - The type of the container's root data store.\n\t * @param id - The unique identifier of the container to load.\n\t * @param root - The {@link DataStoreKind} for the root, or a registry which will be used to look up the root based on its type.\n\t *\n\t * @throws a {@link @fluidframework/telemetry-utils#UsageError} if the DataStoreKind's type (either the root directly or looked up from the registry) does not match the type of the root data store in the container.\n\t *\n\t * @privateRemarks\n\t * The ability to provide a registry here means that it's possible to:\n\t * 1. Load a container which might have a few different possible roots, for example because of versioning.\n\t * 2. Generate the DataStoreKind on demand based on the type: this approach could be used for things like debug tools which can load any possible container.\n\t * 3. Generating the DataStoreKind if the type is unrecognized, for example to provide a placeholder which might support some minimal functionality (like debug inspection, and summary).\n\t *\n\t * The ability to provide just a single DataStoreKind<T> is purely a convenience to make it cleaner to use this in simple cases.\n\t */\n\tloadContainer<T>(\n\t\tid: string,\n\t\troot: DataStoreKind<T> | DataStoreRegistry<T>,\n\t): Promise<FluidContainerAttached<T>>;\n}\n\n// #endregion\n"]}

package/lib/legacy.d.ts

@@ -5,7 +5,7 @@
 
 /*
  * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
+ * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib" in @fluid-tools/build-cli.
  */
 
 export {

package/lib/protocol/summary.d.ts

@@ -88,10 +88,10 @@ export type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryT
  * @example
  * To illustrate, if a DataStore did not change since last summary, the framework runtime will use a handle for the
  * entire DataStore instead of re-sending the entire subtree. The same concept applies for a DDS.
- * An example of a handle string generated when the DDS did not change would be: '/.channels/<DataStoreId>/.channels/<DDSId>'.
- * An example of a handle string generated when the DataStore did not change would be: '/.channels/<DataStoreId>'.
- * An example of a handle string generated when the DDS blob did not change would be: `/.channels/<DataStoreId>/.channels/<DDSId>/<BlobId>`.
- * An example of a handle string generated when the DataStore .attributes blob did not change would be: `/.channels/<DataStoreId>/.attributes`.
+ * An example of a handle string generated when the DDS did not change would be: `/.channels/{dataStoreId}/.channels/{ddsId}`.
+ * An example of a handle string generated when the DataStore did not change would be: `/.channels/{dataStoreId}`.
+ * An example of a handle string generated when the DDS blob did not change would be: `/.channels/{dataStoreId}/.channels/{ddsId}/{blobId}`.
+ * An example of a handle string generated when the DataStore .attributes blob did not change would be: `/.channels/{dataStoreId}/.attributes`.
  * @public
  */
 export interface ISummaryHandle {

package/lib/protocol/summary.js.map

@@ -1 +1 @@
-{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../src/protocol/summary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH;;;GAGG;AACH,2DAA2D;AAC3D,MAAM,KAAW,WAAW,CA6C3B;AA7CD,WAAiB,WAAW;IAkB3B;;;OAGG;IACU,gBAAI,GAAS,CAAC,CAAC;IAE5B;;;;;OAKG;IACU,gBAAI,GAAS,CAAC,CAAC;IAE5B;;;OAGG;IACU,kBAAM,GAAW,CAAC,CAAC;IAEhC;;;;;OAKG;IACU,sBAAU,GAAe,CAAC,CAAC;AACzC,CAAC,EA7CgB,WAAW,KAAX,WAAW,QA6C3B","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Object representing a node within a summary tree.\n *\n * @remarks\n * If any particular node is an {@link ISummaryTree}, it can contain additional `SummaryObject`s as its children.\n * @public\n */\nexport type SummaryObject = ISummaryTree | ISummaryBlob | ISummaryHandle | ISummaryAttachment;\n\n/**\n * The root of the summary tree.\n * @legacy @beta\n */\nexport type SummaryTree = ISummaryTree | ISummaryHandle;\n\n/**\n * Type tag used to distinguish different types of nodes in a {@link ISummaryTree}.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/no-namespace\nexport namespace SummaryType {\n\t/**\n\t * @internal\n\t */\n\texport type Tree = 1;\n\t/**\n\t * @internal\n\t */\n\texport type Blob = 2;\n\t/**\n\t * @internal\n\t */\n\texport type Handle = 3;\n\t/**\n\t * @internal\n\t */\n\texport type Attachment = 4;\n\n\t/**\n\t * Represents a sub-tree in the summary.\n\t * @public\n\t */\n\texport const Tree: Tree = 1;\n\n\t/**\n\t * Represents a blob of data that is added to the summary.\n\t * Such as the user data that is added to the DDS or metadata added by runtime\n\t * such as data store / channel attributes.\n\t * @public\n\t */\n\texport const Blob: Blob = 2;\n\n\t/**\n\t * Path to a summary tree object from the last successful summary.\n\t * @public\n\t */\n\texport const Handle: Handle = 3;\n\n\t/**\n\t * Unique identifier to larger blobs uploaded outside of the summary.\n\t * Ex. DDS has large images or video that will be uploaded by the BlobManager and\n\t * receive an Id that can be used in the summary.\n\t * @public\n\t */\n\texport const Attachment: Attachment = 4;\n}\n\n/**\n * {@inheritDoc (SummaryType:namespace)}\n * @public\n */\nexport type SummaryType =\n\t| SummaryType.Attachment\n\t| SummaryType.Blob\n\t| SummaryType.Handle\n\t| SummaryType.Tree;\n\n/**\n * Summary type that {@link ISummaryHandle} points to.\n *\n * @remarks\n * Summary handles are often used to point to summary tree objects contained within older summaries, thus avoiding\n * the need to re-send the entire subtree if summary object has not changed.\n * @public\n */\nexport type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment;\n\n/**\n * Path to a summary tree object from the last successful summary indicating the summary object hasn't\n * changed since it was uploaded.\n *\n * Special characters include '/'. '/' is used as a separator between different parts of the path as a way to traverse\n * different nodes in the previous summary/snapshot tree.\n *\n * Note, our algorithms use encodeURIComponent and decodeURIComponent to handle special characters in the path. If a string\n * causes this path to fail, the id will be invalid.\n *\n * @example\n * To illustrate, if a DataStore did not change since last summary, the framework runtime will use a handle for the\n * entire DataStore instead of re-sending the entire subtree. The same concept applies for a DDS.\n * An example of a handle string generated when the DDS did not change would be: '/.channels/<DataStoreId>/.channels/<DDSId>'.\n * An example of a handle string generated when the DataStore did not change would be: '/.channels/<DataStoreId>'.\n * An example of a handle string generated when the DDS blob did not change would be: `/.channels/<DataStoreId>/.channels/<DDSId>/<BlobId>`.\n * An example of a handle string generated when the DataStore .attributes blob did not change would be: `/.channels/<DataStoreId>/.attributes`.\n * @public\n */\nexport interface ISummaryHandle {\n\ttype: SummaryType.Handle;\n\n\t/**\n\t * Type of Summary Handle (SummaryType.Handle is not supported).\n\t */\n\thandleType: SummaryTypeNoHandle;\n\n\t/**\n\t * Unique path that identifies the corresponding sub-tree in a previous summary.\n\t */\n\thandle: string;\n}\n\n/**\n * String or Binary data to be uploaded to the server as part of the container's Summary.\n *\n * @remarks\n * Note: Already uploaded blobs would be referenced by an {@link ISummaryAttachment}.\n * Additional information can be found here: {@link https://github.com/microsoft/FluidFramework/issues/6568}\n *\n * @example\n * \"content\": \"\\{ \\\"pkg\\\":\\\"[\\\\\\\"OfficeRootComponent\\\\\\\",\\\\\\\"LastEditedComponent\\\\\\\"]\\\",\n *                    \\\"summaryFormatVersion\\\":2,\\\"isRootDataStore\\\":false \\}\"\n * @public\n */\nexport interface ISummaryBlob {\n\ttype: SummaryType.Blob;\n\tcontent: string | Uint8Array;\n}\n\n/**\n * Unique identifier for blobs uploaded outside of the summary.\n *\n * @remarks\n *\n * Attachment Blobs are uploaded and downloaded separately and do not take part of the snapshot payload.\n * The ID gets returned from the backend after the attachment has been uploaded.\n * Additional information can be found here: {@link https://github.com/microsoft/FluidFramework/issues/6374}\n *\n * @example\n * \"id\": \"bQAQKARDdMdTgqICmBa_ZB86YXwGP\"\n * @public\n */\nexport interface ISummaryAttachment {\n\ttype: SummaryType.Attachment;\n\tid: string;\n}\n\n/**\n * Tree Node data structure with children that are nodes of SummaryObject type:\n * Blob, Handle, Attachment or another Tree.\n * @public\n */\nexport interface ISummaryTree {\n\ttype: SummaryType.Tree;\n\n\t/**\n\t * The object containing all the tree's {@link SummaryObject} children.\n\t *\n\t * @param path - The key to store the SummaryObject at in the current summary tree being generated. Should not contain any \"/\" characters and should not change when encodeURIComponent is called on it.\n\t */\n\ttree: { [path: string]: SummaryObject };\n\n\t/**\n\t * Indicates that this tree entry is unreferenced.\n\t * If this is not present, the tree entry is considered referenced.\n\t */\n\tunreferenced?: true;\n\n\t/**\n\t * Represents the loading group to which the summary tree belongs to. Please refer to this readme for more context.\n\t * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}\n\t * Also note that \"groupId\" is the same as \"loadingGroupId\" used elsewhere in the repo. The naming discrepancy is\n\t * intentional to minimize snapshot/summary size.\n\t */\n\tgroupId?: string;\n}\n"]}
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../src/protocol/summary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiBH;;;GAGG;AACH,2DAA2D;AAC3D,MAAM,KAAW,WAAW,CA6C3B;AA7CD,WAAiB,WAAW;IAkB3B;;;OAGG;IACU,gBAAI,GAAS,CAAC,CAAC;IAE5B;;;;;OAKG;IACU,gBAAI,GAAS,CAAC,CAAC;IAE5B;;;OAGG;IACU,kBAAM,GAAW,CAAC,CAAC;IAEhC;;;;;OAKG;IACU,sBAAU,GAAe,CAAC,CAAC;AACzC,CAAC,EA7CgB,WAAW,KAAX,WAAW,QA6C3B","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Object representing a node within a summary tree.\n *\n * @remarks\n * If any particular node is an {@link ISummaryTree}, it can contain additional `SummaryObject`s as its children.\n * @public\n */\nexport type SummaryObject = ISummaryTree | ISummaryBlob | ISummaryHandle | ISummaryAttachment;\n\n/**\n * The root of the summary tree.\n * @legacy @beta\n */\nexport type SummaryTree = ISummaryTree | ISummaryHandle;\n\n/**\n * Type tag used to distinguish different types of nodes in a {@link ISummaryTree}.\n * @public\n */\n// eslint-disable-next-line @typescript-eslint/no-namespace\nexport namespace SummaryType {\n\t/**\n\t * @internal\n\t */\n\texport type Tree = 1;\n\t/**\n\t * @internal\n\t */\n\texport type Blob = 2;\n\t/**\n\t * @internal\n\t */\n\texport type Handle = 3;\n\t/**\n\t * @internal\n\t */\n\texport type Attachment = 4;\n\n\t/**\n\t * Represents a sub-tree in the summary.\n\t * @public\n\t */\n\texport const Tree: Tree = 1;\n\n\t/**\n\t * Represents a blob of data that is added to the summary.\n\t * Such as the user data that is added to the DDS or metadata added by runtime\n\t * such as data store / channel attributes.\n\t * @public\n\t */\n\texport const Blob: Blob = 2;\n\n\t/**\n\t * Path to a summary tree object from the last successful summary.\n\t * @public\n\t */\n\texport const Handle: Handle = 3;\n\n\t/**\n\t * Unique identifier to larger blobs uploaded outside of the summary.\n\t * Ex. DDS has large images or video that will be uploaded by the BlobManager and\n\t * receive an Id that can be used in the summary.\n\t * @public\n\t */\n\texport const Attachment: Attachment = 4;\n}\n\n/**\n * {@inheritDoc (SummaryType:namespace)}\n * @public\n */\nexport type SummaryType =\n\t| SummaryType.Attachment\n\t| SummaryType.Blob\n\t| SummaryType.Handle\n\t| SummaryType.Tree;\n\n/**\n * Summary type that {@link ISummaryHandle} points to.\n *\n * @remarks\n * Summary handles are often used to point to summary tree objects contained within older summaries, thus avoiding\n * the need to re-send the entire subtree if summary object has not changed.\n * @public\n */\nexport type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment;\n\n/**\n * Path to a summary tree object from the last successful summary indicating the summary object hasn't\n * changed since it was uploaded.\n *\n * Special characters include '/'. '/' is used as a separator between different parts of the path as a way to traverse\n * different nodes in the previous summary/snapshot tree.\n *\n * Note, our algorithms use encodeURIComponent and decodeURIComponent to handle special characters in the path. If a string\n * causes this path to fail, the id will be invalid.\n *\n * @example\n * To illustrate, if a DataStore did not change since last summary, the framework runtime will use a handle for the\n * entire DataStore instead of re-sending the entire subtree. The same concept applies for a DDS.\n * An example of a handle string generated when the DDS did not change would be: `/.channels/{dataStoreId}/.channels/{ddsId}`.\n * An example of a handle string generated when the DataStore did not change would be: `/.channels/{dataStoreId}`.\n * An example of a handle string generated when the DDS blob did not change would be: `/.channels/{dataStoreId}/.channels/{ddsId}/{blobId}`.\n * An example of a handle string generated when the DataStore .attributes blob did not change would be: `/.channels/{dataStoreId}/.attributes`.\n * @public\n */\nexport interface ISummaryHandle {\n\ttype: SummaryType.Handle;\n\n\t/**\n\t * Type of Summary Handle (SummaryType.Handle is not supported).\n\t */\n\thandleType: SummaryTypeNoHandle;\n\n\t/**\n\t * Unique path that identifies the corresponding sub-tree in a previous summary.\n\t */\n\thandle: string;\n}\n\n/**\n * String or Binary data to be uploaded to the server as part of the container's Summary.\n *\n * @remarks\n * Note: Already uploaded blobs would be referenced by an {@link ISummaryAttachment}.\n * Additional information can be found here: {@link https://github.com/microsoft/FluidFramework/issues/6568}\n *\n * @example\n * \"content\": \"\\{ \\\"pkg\\\":\\\"[\\\\\\\"OfficeRootComponent\\\\\\\",\\\\\\\"LastEditedComponent\\\\\\\"]\\\",\n *                    \\\"summaryFormatVersion\\\":2,\\\"isRootDataStore\\\":false \\}\"\n * @public\n */\nexport interface ISummaryBlob {\n\ttype: SummaryType.Blob;\n\tcontent: string | Uint8Array;\n}\n\n/**\n * Unique identifier for blobs uploaded outside of the summary.\n *\n * @remarks\n *\n * Attachment Blobs are uploaded and downloaded separately and do not take part of the snapshot payload.\n * The ID gets returned from the backend after the attachment has been uploaded.\n * Additional information can be found here: {@link https://github.com/microsoft/FluidFramework/issues/6374}\n *\n * @example\n * \"id\": \"bQAQKARDdMdTgqICmBa_ZB86YXwGP\"\n * @public\n */\nexport interface ISummaryAttachment {\n\ttype: SummaryType.Attachment;\n\tid: string;\n}\n\n/**\n * Tree Node data structure with children that are nodes of SummaryObject type:\n * Blob, Handle, Attachment or another Tree.\n * @public\n */\nexport interface ISummaryTree {\n\ttype: SummaryType.Tree;\n\n\t/**\n\t * The object containing all the tree's {@link SummaryObject} children.\n\t *\n\t * @param path - The key to store the SummaryObject at in the current summary tree being generated. Should not contain any \"/\" characters and should not change when encodeURIComponent is called on it.\n\t */\n\ttree: { [path: string]: SummaryObject };\n\n\t/**\n\t * Indicates that this tree entry is unreferenced.\n\t * If this is not present, the tree entry is considered referenced.\n\t */\n\tunreferenced?: true;\n\n\t/**\n\t * Represents the loading group to which the summary tree belongs to. Please refer to this readme for more context.\n\t * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}\n\t * Also note that \"groupId\" is the same as \"loadingGroupId\" used elsewhere in the repo. The naming discrepancy is\n\t * intentional to minimize snapshot/summary size.\n\t */\n\tgroupId?: string;\n}\n"]}

package/lib/public.d.ts

@@ -5,7 +5,7 @@
 
 /*
  * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
+ * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib" in @fluid-tools/build-cli.
  */
 
 export {

package/lib/serviceClient.d.ts

@@ -96,7 +96,7 @@ export declare function createBasicRegistryKey<T>(type: string): RegistryKey<T,
  * Oldest Fluid Framework client version that must be able to open and process documents written
  * by a service client.
  * @remarks
- * A string in SemVer format indicating a specific version of the Fluid Framework client package, or the special case of {@link @fluidframework/runtime-utils#defaultMinVersionForCollab}.
+ * A string in SemVer format indicating a specific stable version of the Fluid Framework client package.
  *
  * Service clients use this value to select write formats and features. Clients using this version
  * or newer must be able to open and process documents written by the service client. Choosing an
@@ -110,16 +110,15 @@ export declare function createBasicRegistryKey<T>(type: string): RegistryKey<T,
  * This differs in that:
  * - This is `alpha` instead of `public`.
  * - This is available to drivers due to its location in `driver-definitions` instead of `runtime-definitions`.
- * - This does not allow requesting collaboration with pre-2.0.0 versions, including the special case of `2.0.0-defaults`.
  * - Patch versions cannot be set: a given minor release is not guaranteed to be greater or equal compat wise to all patches of the previous release, so we do not enable features based on patch versions (instead fall back to the next minor if needed).
  * Therefore allowing patch versions here could be misleading and could lead to bugs.
  *
  * @input
  * @alpha
  */
-export type OldestSupportedServiceClientVersion = `2.${bigint}.0`;
+export type OldestSupportedServiceClientVersion = `${2 | 3}.${bigint}.0`;
 /**
- * Strips patch and prerelease from a SemVer string, returning only the major and minor version.
+ * Strips patch and prerelease from a SemVer string, returning only the major and minor version with a ".0" patch.
  * @remarks
  * This formats a version in the same style used by {@link OldestSupportedServiceClientVersion}, specifying only the major and minor versions,
  * which are the portions used for feature selection.

package/lib/serviceClient.d.ts.map

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

package/lib/serviceClient.js

@@ -23,7 +23,7 @@ export function createBasicRegistryKey(type) {
     };
 }
 /**
- * Strips patch and prerelease from a SemVer string, returning only the major and minor version.
+ * Strips patch and prerelease from a SemVer string, returning only the major and minor version with a ".0" patch.
  * @remarks
  * This formats a version in the same style used by {@link OldestSupportedServiceClientVersion}, specifying only the major and minor versions,
  * which are the portions used for feature selection.

package/lib/serviceClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"serviceClient.js","sourceRoot":"","sources":["../src/serviceClient.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsFH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC/B,QAAuB,EACvB,GAA2B;IAE3B,OAAO,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAI,IAAY;IACrD,OAAO;QACN,IAAI;QACJ,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK;KACvB,CAAC;AACH,CAAC;AAiCD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAC7B,OAAgF;IAEhF,6KAA6K;IAC7K,2JAA2J;IAC3J,6KAA6K;IAC7K,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAU,IAAI,MAAM,CAAC,CAAC,CAAU,IAAI,CAAC;AACxD,CAAC;AAoRD,aAAa","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ErasedBaseType } from \"@fluidframework/core-interfaces/internal\";\n\n/**\n * This file defines the external facing API for the {@link ServiceClient} and related types.\n *\n * It provides an API surface at a similar abstraction level to aqueduct and fluid-static, but is intended to be a replacement for those which solves several problems with them.\n * Mainly it strives to have the encapsulation of implementation details (including all legacy APIs from aqueduct and lower level internals) like fluid-static\n * while being both more flexible and simpler.\n *\n * This aims to be the cleanest practical way to build applications on the Fluid Framework Client.\n * There are however several known cases where the API quality was sacrificed to ease initial implementation,\n * since some of the unification desired in this API's design are not yet implemented in the underlying Fluid Framework Client code or require additional work to implement.\n * These cases are called out with TODOs in this file.\n * These should be considered and addressed before stabilizing this API past alpha.\n *\n * All code interacting through this API surface within a single client must avoid using multiple copies of any Fluid Framework client package (at the same or different versions).\n * This mirrors the `@public` \"declarative model\" APIs and is a deliberate simplification of what is allowed in the legacy API surface.\n * It is enforced best-effort only: `@sealed` nominal erased types catch many mismatches at compile time, and factory identity checks throw a UsageError (\"Conflicting ... with same type\") at run time, but the checking is not exhaustive.\n * See `LayerCompatibilityUnified.md` for the full policy, rationale, and failure signatures.\n *\n * TODO:\n * Before stabilizing any of this past beta, evaluate whether this single-copy requirement must be relaxed, and if so how.\n * Whatever rule is chosen (relaxed or not) should be enforced at both compile time and run time as much as possible.\n *\n * TODO:\n * Fault isolation should be considered in this API design.\n * When are exceptions recoverable and how?\n * Likely we can fault isolate exceptions to containers in most cases,\n * and containers can indicate their status by being closed or disposed.\n * Non fatal errors should not be exceptions.\n */\n\n// #region Registry types\n\n/**\n * A collection of entries looked up by a `type` string.\n * @remarks\n * Use of a function for this allows a few things that most collections would not:\n * 1. It's possible to generate placeholder / error values on demand.\n * 2. It makes loading from some external registry on demand practical.\n * 3. The lookup can throw an exception if appropriate (this would typically indicate a bug and produce a fatal error).\n * 4. Generation of values can be lazy, and even asynchronous if `T` allows for a promise.\n *\n * This flexibility lets the implementer decide how to handle requests for unknown types.\n * They can produce placeholders, assert, fall back to a generic implementation etc.\n * @typeParam T - The type of entry produced for any given `type` string.\n * @input\n * @alpha\n */\nexport type Registry<T> = (type: string) => T;\n\n/**\n * A strongly typed key for a {@link Registry}.\n * Use with {@link lookupInRegistry}.\n * @remarks\n * Used to look up a `TIn` in a `Registry<TIn>`, and produce a `TOut` from it.\n * @typeParam TOut - The type produced by {@link RegistryKey.adapt} from a looked-up entry.\n * @typeParam TIn - The type of the entries in the {@link Registry} this key is used with.\n * @privateRemarks\n * This is currently input and sealed, meaning effectively type erased since the design might change.\n * @input\n * @sealed\n * @alpha\n */\nexport interface RegistryKey<TOut, TIn = unknown> {\n\t/**\n\t * Identifier to provide to the {@link Registry}.\n\t */\n\treadonly type: string;\n\n\t/**\n\t * Convert a value from the registry to the desired output type.\n\t * @remarks\n\t * How this is done is up to the implementation.\n\t *\n\t * This might be a type guard which throws if the input is not valid.\n\t * Or it could be a conversion, an identity function, or something else.\n\t *\n\t * @param value - The value from the registry.\n\t * @returns The converted value.\n\t */\n\tadapt(value: TIn): TOut;\n}\n\n/**\n * Lookup an entry in a {@link Registry} using a {@link RegistryKey}.\n * @typeParam TOut - The type produced from the looked-up entry.\n * @typeParam TIn - The type of the entries in `registry`.\n * @alpha\n */\nexport function lookupInRegistry<TOut, TIn>(\n\tregistry: Registry<TIn>,\n\tkey: RegistryKey<TOut, TIn>,\n): TOut {\n\treturn key.adapt(registry(key.type));\n}\n\n/**\n * Creates a simple {@link RegistryKey} which does no type conversion.\n * @typeParam T - The type of the registry entry, which is returned unchanged by the key.\n * @alpha\n */\nexport function createBasicRegistryKey<T>(type: string): RegistryKey<T, T> {\n\treturn {\n\t\ttype,\n\t\tadapt: (value) => value,\n\t};\n}\n\n// #endregion\n\n// #region ServiceClient types\n\n/**\n * Oldest Fluid Framework client version that must be able to open and process documents written\n * by a service client.\n * @remarks\n * A string in SemVer format indicating a specific version of the Fluid Framework client package, or the special case of {@link @fluidframework/runtime-utils#defaultMinVersionForCollab}.\n *\n * Service clients use this value to select write formats and features. Clients using this version\n * or newer must be able to open and process documents written by the service client. Choosing an\n * older version may limit the features and write formats the application can use to those\n * supported by that version.\n *\n * Cannot exceed the version of any Fluid Framework client package in use by the local client.\n *\n * @privateRemarks\n * This is similar to, and a subset of, the `OldestSupportedClientVersion` type in `@fluidframework/runtime-definitions`.\n * This differs in that:\n * - This is `alpha` instead of `public`.\n * - This is available to drivers due to its location in `driver-definitions` instead of `runtime-definitions`.\n * - This does not allow requesting collaboration with pre-2.0.0 versions, including the special case of `2.0.0-defaults`.\n * - Patch versions cannot be set: a given minor release is not guaranteed to be greater or equal compat wise to all patches of the previous release, so we do not enable features based on patch versions (instead fall back to the next minor if needed).\n * Therefore allowing patch versions here could be misleading and could lead to bugs.\n *\n * @input\n * @alpha\n */\nexport type OldestSupportedServiceClientVersion = `2.${bigint}.0`;\n\n/**\n * Strips patch and prerelease from a SemVer string, returning only the major and minor version.\n * @remarks\n * This formats a version in the same style used by {@link OldestSupportedServiceClientVersion}, specifying only the major and minor versions,\n * which are the portions used for feature selection.\n * @typeParam major - The major version number of `version` as a string, preserved in the result type.\n * @typeParam minor - The minor version number of `version` as a string, preserved in the result type.\n * @privateRemarks\n * This fills a similar role as cleanedPackageVersion in `@fluidframework/runtime-utils`.\n * It can be used to workaround our generated pkgVersion values being invalid\n * `OldestSupportedServiceClientVersion` on CI due to prerelease or patched release branches.\n * @alpha\n */\nexport function featureVersion<major extends `${bigint}`, minor extends `${bigint}`>(\n\tversion: `${major}.${minor}.${bigint}-${string}` | `${major}.${minor}.${bigint}`,\n): `${major}.${minor}.0` {\n\t// The SemVer package could be used to parse this version, but it wouldn't gain us anything, and would just make it harder to determine that the down casting below is valid.\n\t// Since we have a strongly typed string input, we know exactly which formats are allowed, so we don't need its more general parsing and validation either.\n\t// If we wanted to preserve the patch or prerelease version, that would require more complex parsing and would justify using the SemVer package, but we don't need that here.\n\tconst parsed = version.split(\".\");\n\treturn `${parsed[0] as major}.${parsed[1] as minor}.0`;\n}\n\n/**\n * Options for configuring a {@link ServiceClient}.\n * @remarks\n * These are the options which apply to all services.\n *\n * Individual services will extend with additional options.\n *\n * @input\n * @alpha\n */\nexport interface ServiceOptions {\n\t/**\n\t * Oldest Fluid Framework client version that must be able to open and process documents written\n\t * by the service client.\n\t *\n\t * @remarks\n\t * Choosing an older version may limit the features and write formats the application can use to\n\t * those supported by that version.\n\t *\n\t * A service may provide a default when this option is omitted.\n\t */\n\treadonly oldestSupportedClient?: OldestSupportedServiceClientVersion;\n}\n\n/**\n * A {@link RegistryKey} for a {@link DataStoreKind}.\n * @remarks\n * This is implemented by {@link DataStoreKind}, but alternative implementations can be used if needed.\n *\n * If you want lazy loading and need a key that does not eagerly load the {@link DataStoreKind}, an alternative {@link DataStoreKey} can be implemented.\n * @typeParam T - The type to expose from the {@link DataStoreKind} this key resolves to.\n * @typeParam TAll - The type covering all {@link DataStoreKind}s in the {@link Registry} this key is used with.\n * @privateRemarks\n * TODO: A built in common pattern for the lazy key case should be provided.\n * TODO: things probably break if \"adapt\" does anything except throw or return the result from the input promise.\n * @input\n * @alpha\n */\nexport type DataStoreKey<T, TAll = unknown> = RegistryKey<\n\tPromise<DataStoreKind<T>>,\n\tPromise<DataStoreKind<TAll>>\n>;\n\n/**\n * A context which has a registry and can create data stores using it.\n * @sealed\n * @alpha\n */\nexport interface DataStoreCreator {\n\t/**\n\t * Create a new detached data store `T` which can be attached to the {@link FluidContainer}.\n\t * by adding a handle to a data store or shared object which is already attached to the {@link FluidContainer}.\n\t * @remarks\n\t * `kind` will be looked up in the {@link Registry} used to create or load this {@link DataStoreCreator}.\n\t * It is up to that registry to decide how it handles unknown types, for example by throwing an exception or returning a placeholder.\n\t * @typeParam T - type implemented by the data store to expose in the result, as defined by `kind`.\n\t */\n\tcreateDataStore<T>(kind: DataStoreKey<T>): Promise<T>;\n}\n\n/**\n * A Fluid container.\n * @remarks\n * A document which can be stored to or loaded from a Fluid service using a {@link ServiceClient}.\n *\n * @typeParam TData - The type of the container's root data store, exposed via {@link FluidContainer.data}.\n * @privateRemarks\n * This will likely end up needing many of IFluidContainer's APIs, like disconnect, connectionState, events etc.\n * Before adding them though, care should be taken to consider if they can be improved or simplified.\n * For example maybe a single status enum for `detached -> attaching -> dirty -> saved -> closed` would be good.\n * Or maybe `detached -> attaching -> attached -> closed` and a timer for how long since the last unsaved change was created.\n *\n * The underlying IContainer has a lifecycle which includes both a closed and disposed state.\n * This should be avoidable: the closed but not disposed state exists so its possible to read out some state at that time.\n * We have made the close remove all the timers, so the the dispose step should be unnecessary and we can just have a single closed state.\n *\n * @sealed\n * @alpha\n */\nexport interface FluidContainer<TData = unknown>\n\textends DataStoreCreator,\n\t\tErasedBaseType<readonly [\"FluidContainer\", TData]> {\n\t/**\n\t * The unique identifier for this container within its service.\n\t * @remarks\n\t * `undefined` if the container has not yet been attached to a service.\n\t * This can be used to load another instance of this container from the service using {@link ServiceClient.loadContainer}.\n\t */\n\treadonly id?: string | undefined;\n\n\t/**\n\t * The root data store of the container.\n\t * @remarks\n\t * The type of the root data store is defined by the {@link DataStoreKind} used to create the container.\n\t */\n\treadonly data: TData;\n\n\t/**\n\t * Close the container, stopping all networking and cancelling runtime timers.\n\t *\n\t * @remarks\n\t * After calling `close()`, the container's data can still be read but no further operations can be sent.\n\t * @privateRemarks\n\t * TODO: we should document the what the expected behavior is if one tries to modify the data after close, or tries to call close multiple times.\n\t * TODO: we also likely want to have a way to detect if closed and events for on close.\n\t * TODO: ensure this truly closes all timers: it seems like we might still leak some related to the summarizer.\n\t * TODO: we should clarify how this interacts with unsaved content including inprogress summaries,\n\t * and likely also provide an async API with some options for how to handle that.\n\t */\n\tclose(): void;\n}\n\n/**\n * A Fluid container with an associated {@link ServiceClient} it can attach to.\n * @typeParam TData - The type of the container's root data store.\n * @sealed\n * @alpha\n */\nexport interface FluidContainerWithService<TData = unknown> extends FluidContainer<TData> {\n\t/**\n\t * Attaches this container to the associated service client.\n\t *\n\t * The returned promise resolves once the container is attached: the container from the promise is the same one passed in as the argument.\n\t */\n\tattach(): Promise<FluidContainerAttached<TData>>;\n\n\t// This could expose access to the ServiceClient if needed.\n}\n\n/**\n * A Fluid container that has been attached to a service.\n * @typeParam TData - The type of the container's root data store.\n * @sealed\n * @alpha\n */\nexport interface FluidContainerAttached<TData = unknown> extends FluidContainer<TData> {\n\t/**\n\t * {@inheritdoc FluidContainer.id}\n\t */\n\treadonly id: string;\n}\n\n/**\n * Defines a {@link https://en.wikipedia.org/wiki/Kind_(type_theory) | kind} of data store, allowing creating and loading instances of it.\n * @remarks\n * A `DataStoreKind` acts as the factory and type descriptor for a category of data store:\n * it defines the `type` used to identify the data store in a {@link DataStoreRegistry},\n * and the `T` API surface that instances of that data store expose.\n *\n * Provide a `DataStoreKind` to {@link ServiceClient.(createContainer:1)} or {@link DataStoreCreator.createDataStore}\n * to create new instances, and to {@link ServiceClient.loadContainer} to load existing ones.\n *\n * A `DataStoreKind` is not constructed directly.\n * Instead, obtain one from a framework-provided factory:\n * use {@link @fluidframework/shared-object-base#defineDataStore} to define a data store which wraps a root shared object,\n * or use a more specific wrapper around that,\n * such as {@link @fluidframework/tree#defineTreeDataStore} for a {@link @fluidframework/tree#TreeView}-backed data store.\n *\n * Since it implements {@link DataStoreKey}, a `DataStoreKind` can also be used directly as the key to look\n * itself up in a {@link Registry}.\n * @typeParam T - The API surface that instances of this data store kind expose.\n * @privateRemarks\n * TODO:\n * SharedObjects should be usable as these (though putting shared objects directly in the container might need special logic).\n * Type erased {@link IFluidDataStoreFactory}.\n * @sealed\n * @alpha\n */\nexport interface DataStoreKind<out T = unknown>\n\textends DataStoreKey<T>,\n\t\tErasedBaseType<readonly [\"DataStoreKind\", T]> {}\n\n/**\n * A registry of {@link DataStoreKind}s.\n * @privateRemarks\n * TODO: unify this with SharedObjectRegistry.\n *\n * @typeParam T - The type covering all {@link DataStoreKind}s in the registry.\n * @input\n * @alpha\n */\nexport type DataStoreRegistry<out T = unknown> = Registry<Promise<DataStoreKind<T>>>;\n\n/**\n * A connection to a Fluid storage service.\n * @sealed\n * @alpha\n */\nexport interface ServiceClient {\n\t/**\n\t * Creates a detached container associated with this service client.\n\t * @typeParam T - The type of the container's root data store, as defined by `root`.\n\t * @param root - A {@link DataStoreKind} to use for the root.\n\t * @remarks\n\t * This overload is a shorthand for a simple case of {@link ServiceClient.(createContainer:2)}\n\t * where a single item registry is produced which contains only the root.\n\t * This is usable only when the root {@link DataStoreKind} is available eagerly (e.g. not lazy loaded),\n\t * and when the container does not need a registry for creating additional data stores beyond the root.\n\t * @privateRemarks\n\t * TODO: As this is a detached container, it should be able to be created synchronously.\n\t *\n\t * TODO: Provide more general alternative to this in the form of a service-independent `createContainer` free function.\n\t * It would work with a `ServiceClient.attachContainer<T>(detached: FluidContainer<T>): Promise<FluidContainerAttached<T>>`\n\t * which returns a promise that resolves once the detached container has been attached\n\t * (pointing to the same container object, but with the new type).\n\t *\n\t * Challenges:\n\t *\n\t * Currently the service must be provided at creation time because `IContainer.attach` does not accept a service client,\n\t * making it unclear whether a truly service-independent path is feasible in the near term.\n\t */\n\tcreateContainer<T>(root: DataStoreKind<T>): Promise<FluidContainerWithService<T>>;\n\n\t/**\n\t * Creates a detached container associated with this service client.\n\t * @typeParam T - The type of the container's root data store, as defined by `root`.\n\t * @param root - A {@link DataStoreKey} used to look up the root's {@link DataStoreKind} from `registry`.\n\t * @param registry - The {@link DataStoreRegistry} supplying the {@link DataStoreKind} for the root and any other data stores the container may need to create.\n\t * @remarks\n\t * Use this overload when the root {@link DataStoreKind} is not available eagerly (e.g. for lazy loading),\n\t * or when the container needs a registry for creating additional data stores beyond the root.\n\t */\n\tcreateContainer<T>(\n\t\troot: DataStoreKey<T>,\n\t\tregistry: DataStoreRegistry,\n\t): Promise<FluidContainerWithService<T>>;\n\n\t/**\n\t * A shorthand for {@link ServiceClient.(createContainer:1)} followed by {@link FluidContainerWithService.attach}.\n\t * @remarks\n\t * Due to current implementation limitations making container creation async and service specific,\n\t * creating then attaching one is a bit verbose with two awaits that are messy to include inline.\n\t * This provides a convenient way to create and attach a container in a single step.\n\t * @privateRemarks\n\t * TODO: We should fix ergonomics issues that make this helpful,\n\t * then remove (or deprecate) this method in favor of `service.attach(createContainer(root))` as a better orthogonalized API.\n\t * See private remarks on {@link ServiceClient.(createContainer:1)}.\n\t */\n\tcreateAttachedContainer<T>(root: DataStoreKind<T>): Promise<FluidContainerAttached<T>>;\n\n\t/**\n\t * A shorthand for {@link ServiceClient.(createContainer:2)} followed by {@link FluidContainerWithService.attach}.\n\t * @remarks\n\t * Due to current implementation limitations making container creation async and service specific,\n\t * creating then attaching one is a bit verbose with two awaits that are messy to include inline.\n\t * This provides a convenient way to create and attach a container in a single step.\n\t */\n\tcreateAttachedContainer<T>(\n\t\troot: DataStoreKey<T>,\n\t\tregistry: DataStoreRegistry,\n\t): Promise<FluidContainerAttached<T>>;\n\n\t/**\n\t * Loads an existing container from the service.\n\t * @typeParam T - The type of the container's root data store.\n\t * @param id - The unique identifier of the container to load.\n\t * @param root - The {@link DataStoreKind} for the root, or a registry which will be used to look up the root based on its type.\n\t *\n\t * @throws a {@link @fluidframework/telemetry-utils#UsageError} if the DataStoreKind's type (either the root directly or looked up from the registry) does not match the type of the root data store in the container.\n\t *\n\t * @privateRemarks\n\t * The ability to provide a registry here means that it's possible to:\n\t * 1. Load a container which might have a few different possible roots, for example because of versioning.\n\t * 2. Generate the DataStoreKind on demand based on the type: this approach could be used for things like debug tools which can load any possible container.\n\t * 3. Generating the DataStoreKind if the type is unrecognized, for example to provide a placeholder which might support some minimal functionality (like debug inspection, and summary).\n\t *\n\t * The ability to provide just a single DataStoreKind<T> is purely a convenience to make it cleaner to use this in simple cases.\n\t */\n\tloadContainer<T>(\n\t\tid: string,\n\t\troot: DataStoreKind<T> | DataStoreRegistry<T>,\n\t): Promise<FluidContainerAttached<T>>;\n}\n\n// #endregion\n"]}
+{"version":3,"file":"serviceClient.js","sourceRoot":"","sources":["../src/serviceClient.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsFH;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC/B,QAAuB,EACvB,GAA2B;IAE3B,OAAO,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAI,IAAY;IACrD,OAAO;QACN,IAAI;QACJ,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK;KACvB,CAAC;AACH,CAAC;AAgCD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAC7B,OAAgF;IAEhF,6KAA6K;IAC7K,2JAA2J;IAC3J,6KAA6K;IAC7K,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAU,IAAI,MAAM,CAAC,CAAC,CAAU,IAAI,CAAC;AACxD,CAAC;AAoRD,aAAa","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ErasedBaseType } from \"@fluidframework/core-interfaces/internal\";\n\n/**\n * This file defines the external facing API for the {@link ServiceClient} and related types.\n *\n * It provides an API surface at a similar abstraction level to aqueduct and fluid-static, but is intended to be a replacement for those which solves several problems with them.\n * Mainly it strives to have the encapsulation of implementation details (including all legacy APIs from aqueduct and lower level internals) like fluid-static\n * while being both more flexible and simpler.\n *\n * This aims to be the cleanest practical way to build applications on the Fluid Framework Client.\n * There are however several known cases where the API quality was sacrificed to ease initial implementation,\n * since some of the unification desired in this API's design are not yet implemented in the underlying Fluid Framework Client code or require additional work to implement.\n * These cases are called out with TODOs in this file.\n * These should be considered and addressed before stabilizing this API past alpha.\n *\n * All code interacting through this API surface within a single client must avoid using multiple copies of any Fluid Framework client package (at the same or different versions).\n * This mirrors the `@public` \"declarative model\" APIs and is a deliberate simplification of what is allowed in the legacy API surface.\n * It is enforced best-effort only: `@sealed` nominal erased types catch many mismatches at compile time, and factory identity checks throw a UsageError (\"Conflicting ... with same type\") at run time, but the checking is not exhaustive.\n * See `LayerCompatibilityUnified.md` for the full policy, rationale, and failure signatures.\n *\n * TODO:\n * Before stabilizing any of this past beta, evaluate whether this single-copy requirement must be relaxed, and if so how.\n * Whatever rule is chosen (relaxed or not) should be enforced at both compile time and run time as much as possible.\n *\n * TODO:\n * Fault isolation should be considered in this API design.\n * When are exceptions recoverable and how?\n * Likely we can fault isolate exceptions to containers in most cases,\n * and containers can indicate their status by being closed or disposed.\n * Non fatal errors should not be exceptions.\n */\n\n// #region Registry types\n\n/**\n * A collection of entries looked up by a `type` string.\n * @remarks\n * Use of a function for this allows a few things that most collections would not:\n * 1. It's possible to generate placeholder / error values on demand.\n * 2. It makes loading from some external registry on demand practical.\n * 3. The lookup can throw an exception if appropriate (this would typically indicate a bug and produce a fatal error).\n * 4. Generation of values can be lazy, and even asynchronous if `T` allows for a promise.\n *\n * This flexibility lets the implementer decide how to handle requests for unknown types.\n * They can produce placeholders, assert, fall back to a generic implementation etc.\n * @typeParam T - The type of entry produced for any given `type` string.\n * @input\n * @alpha\n */\nexport type Registry<T> = (type: string) => T;\n\n/**\n * A strongly typed key for a {@link Registry}.\n * Use with {@link lookupInRegistry}.\n * @remarks\n * Used to look up a `TIn` in a `Registry<TIn>`, and produce a `TOut` from it.\n * @typeParam TOut - The type produced by {@link RegistryKey.adapt} from a looked-up entry.\n * @typeParam TIn - The type of the entries in the {@link Registry} this key is used with.\n * @privateRemarks\n * This is currently input and sealed, meaning effectively type erased since the design might change.\n * @input\n * @sealed\n * @alpha\n */\nexport interface RegistryKey<TOut, TIn = unknown> {\n\t/**\n\t * Identifier to provide to the {@link Registry}.\n\t */\n\treadonly type: string;\n\n\t/**\n\t * Convert a value from the registry to the desired output type.\n\t * @remarks\n\t * How this is done is up to the implementation.\n\t *\n\t * This might be a type guard which throws if the input is not valid.\n\t * Or it could be a conversion, an identity function, or something else.\n\t *\n\t * @param value - The value from the registry.\n\t * @returns The converted value.\n\t */\n\tadapt(value: TIn): TOut;\n}\n\n/**\n * Lookup an entry in a {@link Registry} using a {@link RegistryKey}.\n * @typeParam TOut - The type produced from the looked-up entry.\n * @typeParam TIn - The type of the entries in `registry`.\n * @alpha\n */\nexport function lookupInRegistry<TOut, TIn>(\n\tregistry: Registry<TIn>,\n\tkey: RegistryKey<TOut, TIn>,\n): TOut {\n\treturn key.adapt(registry(key.type));\n}\n\n/**\n * Creates a simple {@link RegistryKey} which does no type conversion.\n * @typeParam T - The type of the registry entry, which is returned unchanged by the key.\n * @alpha\n */\nexport function createBasicRegistryKey<T>(type: string): RegistryKey<T, T> {\n\treturn {\n\t\ttype,\n\t\tadapt: (value) => value,\n\t};\n}\n\n// #endregion\n\n// #region ServiceClient types\n\n/**\n * Oldest Fluid Framework client version that must be able to open and process documents written\n * by a service client.\n * @remarks\n * A string in SemVer format indicating a specific stable version of the Fluid Framework client package.\n *\n * Service clients use this value to select write formats and features. Clients using this version\n * or newer must be able to open and process documents written by the service client. Choosing an\n * older version may limit the features and write formats the application can use to those\n * supported by that version.\n *\n * Cannot exceed the version of any Fluid Framework client package in use by the local client.\n *\n * @privateRemarks\n * This is similar to, and a subset of, the `OldestSupportedClientVersion` type in `@fluidframework/runtime-definitions`.\n * This differs in that:\n * - This is `alpha` instead of `public`.\n * - This is available to drivers due to its location in `driver-definitions` instead of `runtime-definitions`.\n * - Patch versions cannot be set: a given minor release is not guaranteed to be greater or equal compat wise to all patches of the previous release, so we do not enable features based on patch versions (instead fall back to the next minor if needed).\n * Therefore allowing patch versions here could be misleading and could lead to bugs.\n *\n * @input\n * @alpha\n */\nexport type OldestSupportedServiceClientVersion = `${2 | 3}.${bigint}.0`;\n\n/**\n * Strips patch and prerelease from a SemVer string, returning only the major and minor version with a \".0\" patch.\n * @remarks\n * This formats a version in the same style used by {@link OldestSupportedServiceClientVersion}, specifying only the major and minor versions,\n * which are the portions used for feature selection.\n * @typeParam major - The major version number of `version` as a string, preserved in the result type.\n * @typeParam minor - The minor version number of `version` as a string, preserved in the result type.\n * @privateRemarks\n * This fills a similar role as cleanedPackageVersion in `@fluidframework/runtime-utils`.\n * It can be used to workaround our generated pkgVersion values being invalid\n * `OldestSupportedServiceClientVersion` on CI due to prerelease or patched release branches.\n * @alpha\n */\nexport function featureVersion<major extends `${bigint}`, minor extends `${bigint}`>(\n\tversion: `${major}.${minor}.${bigint}-${string}` | `${major}.${minor}.${bigint}`,\n): `${major}.${minor}.0` {\n\t// The SemVer package could be used to parse this version, but it wouldn't gain us anything, and would just make it harder to determine that the down casting below is valid.\n\t// Since we have a strongly typed string input, we know exactly which formats are allowed, so we don't need its more general parsing and validation either.\n\t// If we wanted to preserve the patch or prerelease version, that would require more complex parsing and would justify using the SemVer package, but we don't need that here.\n\tconst parsed = version.split(\".\");\n\treturn `${parsed[0] as major}.${parsed[1] as minor}.0`;\n}\n\n/**\n * Options for configuring a {@link ServiceClient}.\n * @remarks\n * These are the options which apply to all services.\n *\n * Individual services will extend with additional options.\n *\n * @input\n * @alpha\n */\nexport interface ServiceOptions {\n\t/**\n\t * Oldest Fluid Framework client version that must be able to open and process documents written\n\t * by the service client.\n\t *\n\t * @remarks\n\t * Choosing an older version may limit the features and write formats the application can use to\n\t * those supported by that version.\n\t *\n\t * A service may provide a default when this option is omitted.\n\t */\n\treadonly oldestSupportedClient?: OldestSupportedServiceClientVersion;\n}\n\n/**\n * A {@link RegistryKey} for a {@link DataStoreKind}.\n * @remarks\n * This is implemented by {@link DataStoreKind}, but alternative implementations can be used if needed.\n *\n * If you want lazy loading and need a key that does not eagerly load the {@link DataStoreKind}, an alternative {@link DataStoreKey} can be implemented.\n * @typeParam T - The type to expose from the {@link DataStoreKind} this key resolves to.\n * @typeParam TAll - The type covering all {@link DataStoreKind}s in the {@link Registry} this key is used with.\n * @privateRemarks\n * TODO: A built in common pattern for the lazy key case should be provided.\n * TODO: things probably break if \"adapt\" does anything except throw or return the result from the input promise.\n * @input\n * @alpha\n */\nexport type DataStoreKey<T, TAll = unknown> = RegistryKey<\n\tPromise<DataStoreKind<T>>,\n\tPromise<DataStoreKind<TAll>>\n>;\n\n/**\n * A context which has a registry and can create data stores using it.\n * @sealed\n * @alpha\n */\nexport interface DataStoreCreator {\n\t/**\n\t * Create a new detached data store `T` which can be attached to the {@link FluidContainer}.\n\t * by adding a handle to a data store or shared object which is already attached to the {@link FluidContainer}.\n\t * @remarks\n\t * `kind` will be looked up in the {@link Registry} used to create or load this {@link DataStoreCreator}.\n\t * It is up to that registry to decide how it handles unknown types, for example by throwing an exception or returning a placeholder.\n\t * @typeParam T - type implemented by the data store to expose in the result, as defined by `kind`.\n\t */\n\tcreateDataStore<T>(kind: DataStoreKey<T>): Promise<T>;\n}\n\n/**\n * A Fluid container.\n * @remarks\n * A document which can be stored to or loaded from a Fluid service using a {@link ServiceClient}.\n *\n * @typeParam TData - The type of the container's root data store, exposed via {@link FluidContainer.data}.\n * @privateRemarks\n * This will likely end up needing many of IFluidContainer's APIs, like disconnect, connectionState, events etc.\n * Before adding them though, care should be taken to consider if they can be improved or simplified.\n * For example maybe a single status enum for `detached -> attaching -> dirty -> saved -> closed` would be good.\n * Or maybe `detached -> attaching -> attached -> closed` and a timer for how long since the last unsaved change was created.\n *\n * The underlying IContainer has a lifecycle which includes both a closed and disposed state.\n * This should be avoidable: the closed but not disposed state exists so its possible to read out some state at that time.\n * We have made the close remove all the timers, so the the dispose step should be unnecessary and we can just have a single closed state.\n *\n * @sealed\n * @alpha\n */\nexport interface FluidContainer<TData = unknown>\n\textends DataStoreCreator,\n\t\tErasedBaseType<readonly [\"FluidContainer\", TData]> {\n\t/**\n\t * The unique identifier for this container within its service.\n\t * @remarks\n\t * `undefined` if the container has not yet been attached to a service.\n\t * This can be used to load another instance of this container from the service using {@link ServiceClient.loadContainer}.\n\t */\n\treadonly id?: string | undefined;\n\n\t/**\n\t * The root data store of the container.\n\t * @remarks\n\t * The type of the root data store is defined by the {@link DataStoreKind} used to create the container.\n\t */\n\treadonly data: TData;\n\n\t/**\n\t * Close the container, stopping all networking and cancelling runtime timers.\n\t *\n\t * @remarks\n\t * After calling `close()`, the container's data can still be read but no further operations can be sent.\n\t * @privateRemarks\n\t * TODO: we should document the what the expected behavior is if one tries to modify the data after close, or tries to call close multiple times.\n\t * TODO: we also likely want to have a way to detect if closed and events for on close.\n\t * TODO: ensure this truly closes all timers: it seems like we might still leak some related to the summarizer.\n\t * TODO: we should clarify how this interacts with unsaved content including inprogress summaries,\n\t * and likely also provide an async API with some options for how to handle that.\n\t */\n\tclose(): void;\n}\n\n/**\n * A Fluid container with an associated {@link ServiceClient} it can attach to.\n * @typeParam TData - The type of the container's root data store.\n * @sealed\n * @alpha\n */\nexport interface FluidContainerWithService<TData = unknown> extends FluidContainer<TData> {\n\t/**\n\t * Attaches this container to the associated service client.\n\t *\n\t * The returned promise resolves once the container is attached: the container from the promise is the same one passed in as the argument.\n\t */\n\tattach(): Promise<FluidContainerAttached<TData>>;\n\n\t// This could expose access to the ServiceClient if needed.\n}\n\n/**\n * A Fluid container that has been attached to a service.\n * @typeParam TData - The type of the container's root data store.\n * @sealed\n * @alpha\n */\nexport interface FluidContainerAttached<TData = unknown> extends FluidContainer<TData> {\n\t/**\n\t * {@inheritdoc FluidContainer.id}\n\t */\n\treadonly id: string;\n}\n\n/**\n * Defines a {@link https://en.wikipedia.org/wiki/Kind_(type_theory) | kind} of data store, allowing creating and loading instances of it.\n * @remarks\n * A `DataStoreKind` acts as the factory and type descriptor for a category of data store:\n * it defines the `type` used to identify the data store in a {@link DataStoreRegistry},\n * and the `T` API surface that instances of that data store expose.\n *\n * Provide a `DataStoreKind` to {@link ServiceClient.(createContainer:1)} or {@link DataStoreCreator.createDataStore}\n * to create new instances, and to {@link ServiceClient.loadContainer} to load existing ones.\n *\n * A `DataStoreKind` is not constructed directly.\n * Instead, obtain one from a framework-provided factory:\n * use {@link @fluidframework/shared-object-base#defineDataStore} to define a data store which wraps a root shared object,\n * or use a more specific wrapper around that,\n * such as {@link @fluidframework/tree#defineTreeDataStore} for a {@link @fluidframework/tree#TreeView}-backed data store.\n *\n * Since it implements {@link DataStoreKey}, a `DataStoreKind` can also be used directly as the key to look\n * itself up in a {@link Registry}.\n * @typeParam T - The API surface that instances of this data store kind expose.\n * @privateRemarks\n * TODO:\n * SharedObjects should be usable as these (though putting shared objects directly in the container might need special logic).\n * Type erased {@link IFluidDataStoreFactory}.\n * @sealed\n * @alpha\n */\nexport interface DataStoreKind<out T = unknown>\n\textends DataStoreKey<T>,\n\t\tErasedBaseType<readonly [\"DataStoreKind\", T]> {}\n\n/**\n * A registry of {@link DataStoreKind}s.\n * @privateRemarks\n * TODO: unify this with SharedObjectRegistry.\n *\n * @typeParam T - The type covering all {@link DataStoreKind}s in the registry.\n * @input\n * @alpha\n */\nexport type DataStoreRegistry<out T = unknown> = Registry<Promise<DataStoreKind<T>>>;\n\n/**\n * A connection to a Fluid storage service.\n * @sealed\n * @alpha\n */\nexport interface ServiceClient {\n\t/**\n\t * Creates a detached container associated with this service client.\n\t * @typeParam T - The type of the container's root data store, as defined by `root`.\n\t * @param root - A {@link DataStoreKind} to use for the root.\n\t * @remarks\n\t * This overload is a shorthand for a simple case of {@link ServiceClient.(createContainer:2)}\n\t * where a single item registry is produced which contains only the root.\n\t * This is usable only when the root {@link DataStoreKind} is available eagerly (e.g. not lazy loaded),\n\t * and when the container does not need a registry for creating additional data stores beyond the root.\n\t * @privateRemarks\n\t * TODO: As this is a detached container, it should be able to be created synchronously.\n\t *\n\t * TODO: Provide more general alternative to this in the form of a service-independent `createContainer` free function.\n\t * It would work with a `ServiceClient.attachContainer<T>(detached: FluidContainer<T>): Promise<FluidContainerAttached<T>>`\n\t * which returns a promise that resolves once the detached container has been attached\n\t * (pointing to the same container object, but with the new type).\n\t *\n\t * Challenges:\n\t *\n\t * Currently the service must be provided at creation time because `IContainer.attach` does not accept a service client,\n\t * making it unclear whether a truly service-independent path is feasible in the near term.\n\t */\n\tcreateContainer<T>(root: DataStoreKind<T>): Promise<FluidContainerWithService<T>>;\n\n\t/**\n\t * Creates a detached container associated with this service client.\n\t * @typeParam T - The type of the container's root data store, as defined by `root`.\n\t * @param root - A {@link DataStoreKey} used to look up the root's {@link DataStoreKind} from `registry`.\n\t * @param registry - The {@link DataStoreRegistry} supplying the {@link DataStoreKind} for the root and any other data stores the container may need to create.\n\t * @remarks\n\t * Use this overload when the root {@link DataStoreKind} is not available eagerly (e.g. for lazy loading),\n\t * or when the container needs a registry for creating additional data stores beyond the root.\n\t */\n\tcreateContainer<T>(\n\t\troot: DataStoreKey<T>,\n\t\tregistry: DataStoreRegistry,\n\t): Promise<FluidContainerWithService<T>>;\n\n\t/**\n\t * A shorthand for {@link ServiceClient.(createContainer:1)} followed by {@link FluidContainerWithService.attach}.\n\t * @remarks\n\t * Due to current implementation limitations making container creation async and service specific,\n\t * creating then attaching one is a bit verbose with two awaits that are messy to include inline.\n\t * This provides a convenient way to create and attach a container in a single step.\n\t * @privateRemarks\n\t * TODO: We should fix ergonomics issues that make this helpful,\n\t * then remove (or deprecate) this method in favor of `service.attach(createContainer(root))` as a better orthogonalized API.\n\t * See private remarks on {@link ServiceClient.(createContainer:1)}.\n\t */\n\tcreateAttachedContainer<T>(root: DataStoreKind<T>): Promise<FluidContainerAttached<T>>;\n\n\t/**\n\t * A shorthand for {@link ServiceClient.(createContainer:2)} followed by {@link FluidContainerWithService.attach}.\n\t * @remarks\n\t * Due to current implementation limitations making container creation async and service specific,\n\t * creating then attaching one is a bit verbose with two awaits that are messy to include inline.\n\t * This provides a convenient way to create and attach a container in a single step.\n\t */\n\tcreateAttachedContainer<T>(\n\t\troot: DataStoreKey<T>,\n\t\tregistry: DataStoreRegistry,\n\t): Promise<FluidContainerAttached<T>>;\n\n\t/**\n\t * Loads an existing container from the service.\n\t * @typeParam T - The type of the container's root data store.\n\t * @param id - The unique identifier of the container to load.\n\t * @param root - The {@link DataStoreKind} for the root, or a registry which will be used to look up the root based on its type.\n\t *\n\t * @throws a {@link @fluidframework/telemetry-utils#UsageError} if the DataStoreKind's type (either the root directly or looked up from the registry) does not match the type of the root data store in the container.\n\t *\n\t * @privateRemarks\n\t * The ability to provide a registry here means that it's possible to:\n\t * 1. Load a container which might have a few different possible roots, for example because of versioning.\n\t * 2. Generate the DataStoreKind on demand based on the type: this approach could be used for things like debug tools which can load any possible container.\n\t * 3. Generating the DataStoreKind if the type is unrecognized, for example to provide a placeholder which might support some minimal functionality (like debug inspection, and summary).\n\t *\n\t * The ability to provide just a single DataStoreKind<T> is purely a convenience to make it cleaner to use this in simple cases.\n\t */\n\tloadContainer<T>(\n\t\tid: string,\n\t\troot: DataStoreKind<T> | DataStoreRegistry<T>,\n\t): Promise<FluidContainerAttached<T>>;\n}\n\n// #endregion\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/driver-definitions",
-  "version": "2.118.0",
+  "version": "3.0.0",
   "description": "Fluid driver definitions",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -14,40 +14,26 @@
   "type": "module",
   "exports": {
     ".": {
-      "import": {
-        "types": "./lib/public.d.ts",
-        "default": "./lib/index.js"
-      },
-      "require": {
-        "types": "./dist/public.d.ts",
-        "default": "./dist/index.js"
+      "types": "./lib/public.d.ts",
+      "default": "./lib/index.js",
+      "internal-entrypoint-generation": {
+        "types": "./dist/public.d.ts"
       }
     },
     "./legacy": {
-      "import": {
-        "types": "./lib/legacy.d.ts",
-        "default": "./lib/index.js"
-      },
-      "require": {
-        "types": "./dist/legacy.d.ts",
-        "default": "./dist/index.js"
+      "types": "./lib/legacy.d.ts",
+      "default": "./lib/index.js",
+      "internal-entrypoint-generation": {
+        "types": "./dist/legacy.d.ts"
       }
     },
     "./internal": {
-      "import": {
-        "types": "./lib/index.d.ts",
-        "default": "./lib/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
     }
   },
-  "main": "lib/index.js",
-  "types": "lib/public.d.ts",
   "dependencies": {
-    "@fluidframework/core-interfaces": "~2.118.0"
+    "@fluidframework/core-interfaces": "~3.0.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
@@ -63,7 +49,7 @@
     "eslint": "~9.39.1",
     "jiti": "^2.6.1",
     "rimraf": "^6.1.3",
-    "typescript": "~5.4.5"
+    "typescript": "~6.0.3"
   },
   "typeValidation": {
     "broken": {},
@@ -72,18 +58,19 @@
   "scripts": {
     "build": "fluid-build . --task build",
     "build:api-reports": "concurrently \"npm:build:api-reports:*\"",
-    "build:api-reports:current": "api-extractor run --local --config api-extractor/api-extractor.current.json",
-    "build:api-reports:legacy": "api-extractor run --local --config api-extractor/api-extractor.legacy.json",
+    "build:api-reports:current": "api-extractor run --local --config api-extractor/api-extractor-report.current.json",
+    "build:api-reports:legacy": "api-extractor run --local --config api-extractor/api-extractor-report.legacy.json",
+    "build:cjs": "fluid-tsc commonjs --project ./tsconfig.cjs.json && npm run place:cjs:package-stub",
     "build:compile": "fluid-build . --task compile",
-    "build:docs": "api-extractor run --local",
+    "build:docs": "api-extractor run --local --config api-extractor/api-extractor-model.json",
     "build:entrypoints": "fluid-build . --task build:entrypoints",
     "build:entrypoints:cjs": "flub generate entrypoints --resolutionConditions require --outFileLegacyBeta legacy --outDir ./dist",
-    "build:entrypoints:esm": "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib --node10TypeCompat",
-    "build:esnext": "tsc --project ./tsconfig.json",
+    "build:entrypoints:esm": "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib",
+    "build:esm": "tsc --project ./tsconfig.json",
     "build:test": "concurrently npm:build:test:esm npm:build:test:cjs",
     "build:test:cjs": "fluid-tsc commonjs --project ./src/test/tsconfig.cjs.json",
     "build:test:esm": "tsc --project ./src/test/tsconfig.json",
-    "check:are-the-types-wrong": "attw --pack .",
+    "check:are-the-types-wrong": "attw --pack . --profile esm-only",
     "check:biome": "biome check .",
     "check:exports": "concurrently \"npm:check:exports:*\"",
     "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json",
@@ -92,10 +79,11 @@
     "check:exports:esm:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.esm.json",
     "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json",
     "check:format": "npm run check:biome",
+    "check:types:inexactOptionalPropertyTypes": "tsc --project ./tsconfig.json --noEmit --exactOptionalPropertyTypes false --skipLibCheck --emitDeclarationOnly false --tsBuildInfoFile ./tsconfig.inexactOptionalPropertyTypes.tsbuildinfo",
     "ci:build:api-reports": "concurrently \"npm:ci:build:api-reports:*\"",
-    "ci:build:api-reports:current": "api-extractor run --config api-extractor/api-extractor.current.json",
-    "ci:build:api-reports:legacy": "api-extractor run --config api-extractor/api-extractor.legacy.json",
-    "ci:build:docs": "api-extractor run",
+    "ci:build:api-reports:current": "api-extractor run --config api-extractor/api-extractor-report.current.json",
+    "ci:build:api-reports:legacy": "api-extractor run --config api-extractor/api-extractor-report.legacy.json",
+    "ci:build:docs": "api-extractor run --config api-extractor/api-extractor-model.json",
     "ci:test": "echo No test for this package",
     "ci:test:coverage": "echo No test for this package",
     "clean": "rimraf --glob dist lib {alpha,beta,internal,legacy}.d.ts \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp",
@@ -106,8 +94,7 @@
     "lint": "fluid-build . --task lint",
     "lint:fix": "fluid-build . --task eslint:fix --task format",
     "place:cjs:package-stub": "copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
-    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && npm run place:cjs:package-stub",
-    "tsc:watch": "npm run place:cjs:package-stub && fluid-tsc commonjs --project ./tsconfig.cjs.json --watch",
-    "typetests:gen": "flub generate typetests --dir . -v"
+    "typetests:gen": "flub generate typetests --dir . -v",
+    "watch:cjs": "npm run place:cjs:package-stub && fluid-tsc commonjs --project ./tsconfig.cjs.json --watch"
   }
 }

package/src/protocol/summary.ts

@@ -103,10 +103,10 @@ export type SummaryTypeNoHandle = SummaryType.Tree | SummaryType.Blob | SummaryT
  * @example
  * To illustrate, if a DataStore did not change since last summary, the framework runtime will use a handle for the
  * entire DataStore instead of re-sending the entire subtree. The same concept applies for a DDS.
- * An example of a handle string generated when the DDS did not change would be: '/.channels/<DataStoreId>/.channels/<DDSId>'.
- * An example of a handle string generated when the DataStore did not change would be: '/.channels/<DataStoreId>'.
- * An example of a handle string generated when the DDS blob did not change would be: `/.channels/<DataStoreId>/.channels/<DDSId>/<BlobId>`.
- * An example of a handle string generated when the DataStore .attributes blob did not change would be: `/.channels/<DataStoreId>/.attributes`.
+ * An example of a handle string generated when the DDS did not change would be: `/.channels/{dataStoreId}/.channels/{ddsId}`.
+ * An example of a handle string generated when the DataStore did not change would be: `/.channels/{dataStoreId}`.
+ * An example of a handle string generated when the DDS blob did not change would be: `/.channels/{dataStoreId}/.channels/{ddsId}/{blobId}`.
+ * An example of a handle string generated when the DataStore .attributes blob did not change would be: `/.channels/{dataStoreId}/.attributes`.
  * @public
  */
 export interface ISummaryHandle {

package/src/serviceClient.ts

@@ -120,7 +120,7 @@ export function createBasicRegistryKey<T>(type: string): RegistryKey<T, T> {
  * Oldest Fluid Framework client version that must be able to open and process documents written
  * by a service client.
  * @remarks
- * A string in SemVer format indicating a specific version of the Fluid Framework client package, or the special case of {@link @fluidframework/runtime-utils#defaultMinVersionForCollab}.
+ * A string in SemVer format indicating a specific stable version of the Fluid Framework client package.
  *
  * Service clients use this value to select write formats and features. Clients using this version
  * or newer must be able to open and process documents written by the service client. Choosing an
@@ -134,17 +134,16 @@ export function createBasicRegistryKey<T>(type: string): RegistryKey<T, T> {
  * This differs in that:
  * - This is `alpha` instead of `public`.
  * - This is available to drivers due to its location in `driver-definitions` instead of `runtime-definitions`.
- * - This does not allow requesting collaboration with pre-2.0.0 versions, including the special case of `2.0.0-defaults`.
  * - Patch versions cannot be set: a given minor release is not guaranteed to be greater or equal compat wise to all patches of the previous release, so we do not enable features based on patch versions (instead fall back to the next minor if needed).
  * Therefore allowing patch versions here could be misleading and could lead to bugs.
  *
  * @input
  * @alpha
  */
-export type OldestSupportedServiceClientVersion = `2.${bigint}.0`;
+export type OldestSupportedServiceClientVersion = `${2 | 3}.${bigint}.0`;
 
 /**
- * Strips patch and prerelease from a SemVer string, returning only the major and minor version.
+ * Strips patch and prerelease from a SemVer string, returning only the major and minor version with a ".0" patch.
  * @remarks
  * This formats a version in the same style used by {@link OldestSupportedServiceClientVersion}, specifying only the major and minor versions,
  * which are the portions used for feature selection.

package/tsconfig.json

@@ -1,5 +1,5 @@
 {
-	"extends": "../../../common/build/build-common/tsconfig.node16.json",
+	"extends": "../../../common/build/build-common/tsconfig.node20.json",
 	"include": ["src/**/*"],
 	"exclude": ["src/test/**/*"],
 	"compilerOptions": {

package/internal.d.ts

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
- */
-
-export * from "./lib/index.js";

package/legacy.d.ts

@@ -1,11 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/*
- * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib --node10TypeCompat" in @fluid-tools/build-cli.
- */
-
-export * from "./lib/legacy.js";