@fluidframework/datastore-definitions 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.224419

package/.eslintrc.cjs

@@ -0,0 +1,11 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+module.exports = {
+	parserOptions: {
+		project: ["./tsconfig.json", "./src/test/tsconfig.json"],
+	},
+	extends: ["@fluidframework/eslint-config-fluid/minimal", "prettier"],
+};

package/CHANGELOG.md

@@ -0,0 +1,215 @@
+# @fluidframework/datastore-definitions
+
+## 2.0.0-internal.8.0.0
+
+### Major Changes
+
+-   datastore-definitions: Removed request and IFluidRouter from IFluidDataStoreRuntime [9a451d4946](https://github.com/microsoft/FluidFramework/commits/9a451d4946b5c51a52e4d1ab5bf51e7b285b0d74)
+
+    The `request` method and `IFluidRouter` property have been removed from `IFluidDataStoreRuntime`. Please migrate all
+    usage to the `IFluidDataStoreRuntime.entryPoint` API.
+
+    See
+    [Removing-IFluidRouter.md](https://github.com/microsoft/FluidFramework/blob/main/packages/common/core-interfaces/Removing-IFluidRouter.md)
+    for more details.
+
+-   datastore-definitions: Jsonable and Serializable now require a generic parameter [9a451d4946](https://github.com/microsoft/FluidFramework/commits/9a451d4946b5c51a52e4d1ab5bf51e7b285b0d74)
+
+    The `Jsonable` and `Serializable` types from @fluidframework/datastore-definitions now require a generic parameter and
+    if that type is `any` or `unknown`will return a new result `JsonableTypeWith<>` that more accurately represents the
+    limitation of serialization.
+
+    Additional modifications:
+
+    -   `Jsonable`'s `TReplacement` parameter default has also been changed from `void` to `never`, which now disallows
+        `void`.
+    -   Unrecognized primitive types like `symbol` are now filtered to `never` instead of `{}`.
+    -   Recursive types with arrays (`[]`) are now supported.
+
+    `Serializable` is commonly used for DDS values and now requires more precision when using them. For example SharedMatrix
+    (unqualified) has an `any` default that meant values were `Serializable<any>` (i.e. `any`), but now `Serializable<any>`
+    is `JsonableTypeWith<IFluidHandle>` which may be problematic for reading or writing. Preferred correction is to specify
+    the value type but casting through `any` may provide a quick fix.
+
+## 2.0.0-internal.7.4.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.3.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.2.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.1.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.0.0
+
+### Major Changes
+
+-   Dependencies on @fluidframework/protocol-definitions package updated to 3.0.0 [871b3493dd](https://github.com/microsoft/FluidFramework/commits/871b3493dd0d7ea3a89be64998ceb6cb9021a04e)
+
+    This included the following changes from the protocol-definitions release:
+
+    -   Updating signal interfaces for some planned improvements. The intention is split the interface between signals
+        submitted by clients to the server and the resulting signals sent from the server to clients.
+        -   A new optional type member is available on the ISignalMessage interface and a new ISentSignalMessage interface has
+            been added, which will be the typing for signals sent from the client to the server. Both extend a new
+            ISignalMessageBase interface that contains common members.
+    -   The @fluidframework/common-definitions package dependency has been updated to version 1.0.0.
+
+-   Server upgrade: dependencies on Fluid server packages updated to 2.0.1 [871b3493dd](https://github.com/microsoft/FluidFramework/commits/871b3493dd0d7ea3a89be64998ceb6cb9021a04e)
+
+    Dependencies on the following Fluid server package have been updated to version 2.0.1:
+
+    -   @fluidframework/gitresources: 2.0.1
+    -   @fluidframework/server-kafka-orderer: 2.0.1
+    -   @fluidframework/server-lambdas: 2.0.1
+    -   @fluidframework/server-lambdas-driver: 2.0.1
+    -   @fluidframework/server-local-server: 2.0.1
+    -   @fluidframework/server-memory-orderer: 2.0.1
+    -   @fluidframework/protocol-base: 2.0.1
+    -   @fluidframework/server-routerlicious: 2.0.1
+    -   @fluidframework/server-routerlicious-base: 2.0.1
+    -   @fluidframework/server-services: 2.0.1
+    -   @fluidframework/server-services-client: 2.0.1
+    -   @fluidframework/server-services-core: 2.0.1
+    -   @fluidframework/server-services-ordering-kafkanode: 2.0.1
+    -   @fluidframework/server-services-ordering-rdkafka: 2.0.1
+    -   @fluidframework/server-services-ordering-zookeeper: 2.0.1
+    -   @fluidframework/server-services-shared: 2.0.1
+    -   @fluidframework/server-services-telemetry: 2.0.1
+    -   @fluidframework/server-services-utils: 2.0.1
+    -   @fluidframework/server-test-utils: 2.0.1
+    -   tinylicious: 2.0.1
+
+-   test-utils: provideEntryPoint is required [871b3493dd](https://github.com/microsoft/FluidFramework/commits/871b3493dd0d7ea3a89be64998ceb6cb9021a04e)
+
+    The optional `provideEntryPoint` method has become required on a number of constructors. A value will need to be provided to the following classes:
+
+    -   `BaseContainerRuntimeFactory`
+    -   `RuntimeFactory`
+    -   `ContainerRuntime` (constructor and `loadRuntime`)
+    -   `FluidDataStoreRuntime`
+
+    See [testContainerRuntimeFactoryWithDefaultDataStore.ts](https://github.com/microsoft/FluidFramework/tree/main/packages/test/test-utils/src/testContainerRuntimeFactoryWithDefaultDataStore.ts) for an example implemtation of `provideEntryPoint` for ContainerRuntime.
+    See [pureDataObjectFactory.ts](https://github.com/microsoft/FluidFramework/tree/main/packages/framework/aqueduct/src/data-object-factories/pureDataObjectFactory.ts#L83) for an example implementation of `provideEntryPoint` for DataStoreRuntime.
+
+    Subsequently, various `entryPoint` and `getEntryPoint()` endpoints have become required. Please see [containerRuntime.ts](https://github.com/microsoft/FluidFramework/tree/main/packages/runtime/container-runtime/src/containerRuntime.ts) for example implementations of these APIs.
+
+    For more details, see [Removing-IFluidRouter.md](https://github.com/microsoft/FluidFramework/blob/main/packages/common/core-interfaces/Removing-IFluidRouter.md)
+
+-   Minimum TypeScript version now 5.1.6 [871b3493dd](https://github.com/microsoft/FluidFramework/commits/871b3493dd0d7ea3a89be64998ceb6cb9021a04e)
+
+    The minimum supported TypeScript version for Fluid 2.0 clients is now 5.1.6.
+
+## 2.0.0-internal.6.4.0
+
+Dependency updates only.
+
+## 2.0.0-internal.6.3.0
+
+Dependency updates only.
+
+## 2.0.0-internal.6.2.0
+
+### Minor Changes
+
+-   Remove use of @fluidframework/common-definitions ([#16638](https://github.com/microsoft/FluidFramework/issues/16638)) [a8c81509c9](https://github.com/microsoft/FluidFramework/commits/a8c81509c9bf09cfb2092ebcf7265205f9eb6dbf)
+
+    The **@fluidframework/common-definitions** package is being deprecated, so the following interfaces and types are now
+    imported from the **@fluidframework/core-interfaces** package:
+
+    -   interface IDisposable
+    -   interface IErrorEvent
+    -   interface IErrorEvent
+    -   interface IEvent
+    -   interface IEventProvider
+    -   interface ILoggingError
+    -   interface ITaggedTelemetryPropertyType
+    -   interface ITelemetryBaseEvent
+    -   interface ITelemetryBaseLogger
+    -   interface ITelemetryErrorEvent
+    -   interface ITelemetryGenericEvent
+    -   interface ITelemetryLogger
+    -   interface ITelemetryPerformanceEvent
+    -   interface ITelemetryProperties
+    -   type ExtendEventProvider
+    -   type IEventThisPlaceHolder
+    -   type IEventTransformer
+    -   type ReplaceIEventThisPlaceHolder
+    -   type ReplaceIEventThisPlaceHolder
+    -   type TelemetryEventCategory
+    -   type TelemetryEventPropertyType
+
+## 2.0.0-internal.6.1.0
+
+Dependency updates only.
+
+## 2.0.0-internal.6.0.0
+
+### Major Changes
+
+-   Request APIs deprecated from many places [8abce8cdb4](https://github.com/microsoft/FluidFramework/commits/8abce8cdb4e2832fb6405fb44e393bef03d5648a)
+
+    The `request` API (associated with the `IFluidRouter` interface) has been deprecated on a number of classes and interfaces. The following are impacted:
+
+    -   `IRuntime` and `ContainerRuntime`
+    -   `IFluidDataStoreRuntime` and `FluidDataStoreRuntime`
+    -   `IFluidDataStoreChannel`
+    -   `MockFluidDataStoreRuntime`
+    -   `TestFluidObject`
+
+    Please migrate usage to the corresponding `entryPoint` or `getEntryPoint()` of the object. The value for these "entryPoint" related APIs is determined from factories (for `IRuntime` and `IFluidDataStoreRuntime`) via the `initializeEntryPoint` method. If no method is passed to the factory, the corresponding `entryPoint` and `getEntryPoint()` will be undefined.
+
+    For an example implementation of `initializeEntryPoint`, see [pureDataObjectFactory.ts](https://github.com/microsoft/FluidFramework/blob/next/packages/framework/aqueduct/src/data-object-factories/pureDataObjectFactory.ts#L84).
+
+    More information of the migration off the request pattern, and current status of its removal, is documented in [Removing-IFluidRouter.md](https://github.com/microsoft/FluidFramework/blob/main/packages/common/core-interfaces/Removing-IFluidRouter.md).
+
+-   IChannel.owner removed [8abce8cdb4](https://github.com/microsoft/FluidFramework/commits/8abce8cdb4e2832fb6405fb44e393bef03d5648a)
+
+    The owner property on IChannel was deprecated in 2.0.0-internal.5.1.0 and has now been removed.
+
+-   Upgraded typescript transpilation target to ES2020 [8abce8cdb4](https://github.com/microsoft/FluidFramework/commits/8abce8cdb4e2832fb6405fb44e393bef03d5648a)
+
+    Upgraded typescript transpilation target to ES2020. This is done in order to decrease the bundle sizes of Fluid Framework packages. This has provided size improvements across the board for ex. Loader, Driver, Runtime etc. Reduced bundle sizes helps to load lesser code in apps and hence also helps to improve the perf.If any app wants to target any older versions of browsers with which this target version is not compatible, then they can use packages like babel to transpile to a older target.
+
+-   IDeltaManager members disposed and dispose() removed [8abce8cdb4](https://github.com/microsoft/FluidFramework/commits/8abce8cdb4e2832fb6405fb44e393bef03d5648a)
+
+    IDeltaManager members disposed and dispose() were deprecated in 2.0.0-internal.5.3.0 and have now been removed.
+
+## 2.0.0-internal.5.4.0
+
+Dependency updates only.
+
+## 2.0.0-internal.5.3.0
+
+Dependency updates only.
+
+## 2.0.0-internal.5.2.0
+
+Dependency updates only.
+
+## 2.0.0-internal.5.1.0
+
+### Minor Changes
+
+-   IChannel.owner deprecated ([#16024](https://github.com/microsoft/FluidFramework/issues/16024)) [92997468e7](https://github.com/microsoft/FluidFramework/commits/92997468e72c48ff39afb9e15fcdca4e87ac8dca)
+
+    The owner property on IChannel has been deprecated and will be removed in an upcoming release. This property does nothing.
+
+## 2.0.0-internal.5.0.0
+
+Dependency updates only.
+
+## 2.0.0-internal.4.4.0
+
+Dependency updates only.
+
+## 2.0.0-internal.4.1.0
+
+Dependency updates only.

package/README.md

@@ -2,17 +2,38 @@
 
 Interface `IFluidDataStoreRuntime` specifies the data store developer API.
 
+<!-- AUTO-GENERATED-CONTENT:START (README_DEPENDENCY_GUIDELINES_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Using Fluid Framework libraries
+
+When taking a dependency on a Fluid Framework library, 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 `^`.
+
+Note that when depending on a library version of the form `2.0.0-internal.x.y.z`, called the Fluid internal version scheme,
+you must use a `>= <` dependency range (such as `>=2.0.0-internal.x.y.z <2.0.0-internal.w.0.0` where `w` is `x+1`).
+Standard `^` and `~` ranges will not work as expected.
+See the [@fluid-tools/version-tools](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/version-tools/README.md)
+package for more information including tools to convert between version schemes.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
 ## Capabilities exposed on `IFluidDataStoreRuntime`
 
 _TODO: The full set of functionality is under review_
 
-- DDS creation and management APIs
-- Container info and states (connection state, documentId, quorum, audience, etc.)
-- Loader
-- Op/Signal submission
-- Snapshotting
-- DeltaManager
-- Blob Management API.
+-   DDS creation and management APIs
+-   Container info and states (connection state, documentId, quorum, audience, etc.)
+-   Loader
+-   Op/Signal submission
+-   Snapshotting
+-   DeltaManager
+-   Blob Management API.
 
 ### Signals
 
@@ -25,3 +46,20 @@ For this reason people usually stick the currentSeq on the signal, so other clie
 
 You can send a signal via the container or data store runtime. The container will emit the signal event on all signals,
 but a data store will emit the signal event only on signals emitted on that data store runtime.
+
+<!-- AUTO-GENERATED-CONTENT:START (README_TRADEMARK_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Trademark
+
+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/en-us/legal/intellectualproperty/trademarks/usage/general).
+
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->

package/api-extractor-lint.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-lint.json"
+}

package/api-extractor.json

@@ -1,4 +1,4 @@
 {
-  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-  "extends": "@fluidframework/build-common/api-extractor-common-report.json"
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-base.json"
 }

package/api-report/datastore-definitions.api.md

@@ -0,0 +1,156 @@
+## API Report File for "@fluidframework/datastore-definitions"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { AttachState } from '@fluidframework/container-definitions';
+import { FluidObject } from '@fluidframework/core-interfaces';
+import { IAudience } from '@fluidframework/container-definitions';
+import { IDeltaManager } from '@fluidframework/container-definitions';
+import { IDisposable } from '@fluidframework/core-interfaces';
+import { IDocumentMessage } from '@fluidframework/protocol-definitions';
+import { IEvent } from '@fluidframework/core-interfaces';
+import { IEventProvider } from '@fluidframework/core-interfaces';
+import { IExperimentalIncrementalSummaryContext } from '@fluidframework/runtime-definitions';
+import { IFluidHandle } from '@fluidframework/core-interfaces';
+import { IFluidHandleContext } from '@fluidframework/core-interfaces';
+import { IFluidLoadable } from '@fluidframework/core-interfaces';
+import { IGarbageCollectionData } from '@fluidframework/runtime-definitions';
+import { IIdCompressor } from '@fluidframework/id-compressor';
+import { IInboundSignalMessage } from '@fluidframework/runtime-definitions';
+import { ILoaderOptions } from '@fluidframework/container-definitions';
+import { IQuorumClients } from '@fluidframework/protocol-definitions';
+import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+import { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
+import { ITelemetryContext } from '@fluidframework/runtime-definitions';
+import { ITelemetryLogger } from '@fluidframework/core-interfaces';
+
+// @public (undocumented)
+export interface IChannel extends IFluidLoadable {
+    // (undocumented)
+    readonly attributes: IChannelAttributes;
+    connect(services: IChannelServices): void;
+    getAttachSummary(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
+    getGCData(fullGC?: boolean): IGarbageCollectionData;
+    readonly id: string;
+    isAttached(): boolean;
+    summarize(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext, incrementalSummaryContext?: IExperimentalIncrementalSummaryContext): Promise<ISummaryTreeWithStats>;
+}
+
+// @public
+export interface IChannelAttributes {
+    readonly packageVersion?: string;
+    readonly snapshotFormatVersion: string;
+    readonly type: string;
+}
+
+// @public
+export interface IChannelFactory {
+    readonly attributes: IChannelAttributes;
+    create(runtime: IFluidDataStoreRuntime, id: string): IChannel;
+    load(runtime: IFluidDataStoreRuntime, id: string, services: IChannelServices, channelAttributes: Readonly<IChannelAttributes>): Promise<IChannel>;
+    readonly type: string;
+}
+
+// @public
+export interface IChannelServices {
+    // (undocumented)
+    deltaConnection: IDeltaConnection;
+    // (undocumented)
+    objectStorage: IChannelStorageService;
+}
+
+// @public
+export interface IChannelStorageService {
+    contains(path: string): Promise<boolean>;
+    list(path: string): Promise<string[]>;
+    readBlob(path: string): Promise<ArrayBufferLike>;
+}
+
+// @public
+export interface IDeltaConnection {
+    addedGCOutboundReference?(srcHandle: IFluidHandle, outboundHandle: IFluidHandle): void;
+    attach(handler: IDeltaHandler): void;
+    // (undocumented)
+    connected: boolean;
+    dirty(): void;
+    submit(messageContent: any, localOpMetadata: unknown): void;
+}
+
+// @public
+export interface IDeltaHandler {
+    applyStashedOp(message: any): unknown;
+    process: (message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown) => void;
+    reSubmit(message: any, localOpMetadata: unknown): void;
+    rollback?(message: any, localOpMetadata: unknown): void;
+    setConnectionState(connected: boolean): void;
+}
+
+// @public
+export interface IFluidDataStoreRuntime extends IEventProvider<IFluidDataStoreRuntimeEvents>, IDisposable {
+    readonly attachState: AttachState;
+    bindChannel(channel: IChannel): void;
+    // (undocumented)
+    readonly channelsRoutingContext: IFluidHandleContext;
+    // (undocumented)
+    readonly clientId: string | undefined;
+    // (undocumented)
+    readonly connected: boolean;
+    createChannel(id: string | undefined, type: string): IChannel;
+    // (undocumented)
+    readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
+    ensureNoDataModelChanges<T>(callback: () => T): T;
+    readonly entryPoint: IFluidHandle<FluidObject>;
+    getAudience(): IAudience;
+    getChannel(id: string): Promise<IChannel>;
+    getQuorum(): IQuorumClients;
+    // (undocumented)
+    readonly id: string;
+    // (undocumented)
+    readonly idCompressor?: IIdCompressor;
+    // (undocumented)
+    readonly IFluidHandleContext: IFluidHandleContext;
+    // (undocumented)
+    readonly logger: ITelemetryLogger;
+    // (undocumented)
+    readonly objectsRoutingContext: IFluidHandleContext;
+    // (undocumented)
+    readonly options: ILoaderOptions;
+    // (undocumented)
+    readonly rootRoutingContext: IFluidHandleContext;
+    submitSignal(type: string, content: any, targetClientId?: string): void;
+    uploadBlob(blob: ArrayBufferLike, signal?: AbortSignal): Promise<IFluidHandle<ArrayBufferLike>>;
+    waitAttached(): Promise<void>;
+}
+
+// @public
+export interface IFluidDataStoreRuntimeEvents extends IEvent {
+    // (undocumented)
+    (event: "disconnected" | "dispose" | "attaching" | "attached", listener: () => void): any;
+    // (undocumented)
+    (event: "op", listener: (message: ISequencedDocumentMessage) => void): any;
+    // (undocumented)
+    (event: "signal", listener: (message: IInboundSignalMessage, local: boolean) => void): any;
+    // (undocumented)
+    (event: "connected", listener: (clientId: string) => void): any;
+}
+
+// @alpha (undocumented)
+export interface Internal_InterfaceOfJsonableTypesWith<T> {
+    // (undocumented)
+    [index: string | number]: JsonableTypeWith<T>;
+}
+
+// @alpha
+export type Jsonable<T, TReplaced = never> = boolean extends (T extends never ? true : false) ? JsonableTypeWith<TReplaced> : unknown extends T ? JsonableTypeWith<TReplaced> : T extends undefined | null | boolean | number | string | TReplaced ? T : Extract<T, Function> extends never ? T extends object ? T extends (infer U)[] ? Jsonable<U, TReplaced>[] : {
+    [K in keyof T]: Extract<K, symbol> extends never ? Jsonable<T[K], TReplaced> : never;
+} : never : never;
+
+// @alpha
+export type JsonableTypeWith<T> = undefined | null | boolean | number | string | T | Internal_InterfaceOfJsonableTypesWith<T> | ArrayLike<JsonableTypeWith<T>>;
+
+// @alpha
+export type Serializable<T> = Jsonable<T, IFluidHandle>;
+
+```

package/dist/channel.d.ts

@@ -4,45 +4,78 @@
  */
 import { IFluidHandle, IFluidLoadable } from "@fluidframework/core-interfaces";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
-import { IGarbageCollectionData, ISummaryTreeWithStats, ITelemetryContext } from "@fluidframework/runtime-definitions";
+import { IGarbageCollectionData, IExperimentalIncrementalSummaryContext, ISummaryTreeWithStats, ITelemetryContext } from "@fluidframework/runtime-definitions";
 import { IChannelAttributes } from "./storage";
 import { IFluidDataStoreRuntime } from "./dataStoreRuntime";
+/**
+ * @public
+ */
 export interface IChannel extends IFluidLoadable {
     /**
      * A readonly identifier for the channel
      */
     readonly id: string;
-    readonly owner?: string;
     readonly attributes: IChannelAttributes;
     /**
      * Generates summary of the channel synchronously. It is called when an `attach message`
      * for a local channel is generated. In other words, when the channel is being attached
      * to make it visible to other clients.
-     * Note: Since Attach Summary is generated for local channels when making them visible to
+     *
+     * @remarks
+     *
+     * Note: Since the Attach Summary is generated for local channels when making them visible to
      * remote clients, they don't have any previous summaries to compare against. For this reason,
-     * The attach summary cannot contain summary handles (paths to sub-trees or blobs).
-     * It can, however, contain ISummaryAttachment (handles to blobs uploaded async via the blob manager).
-     * @param fullTree - flag indicating whether the attempt should generate a full
+     * the attach summary cannot contain summary handles (paths to sub-trees or blobs).
+     * It can, however, contain {@link @fluidframework/protocol-definitions#ISummaryAttachment}
+     * (handles to blobs uploaded async via the blob manager).
+     *
+     * @param fullTree - A flag indicating whether the attempt should generate a full
      * summary tree without any handles for unchanged subtrees.
-     * @param trackState - optimization for tracking state of objects across summaries. If the state
-     * of an object did not change since last successful summary, an ISummaryHandle can be used
-     * instead of re-summarizing it. If this is false, the expectation is that you should never
-     * send an ISummaryHandle since you are not expected to track state.
+     *
+     * Default: `false`
+     *
+     * @param trackState - An optimization for tracking state of objects across summaries. If the state
+     * of an object did not change since last successful summary, an
+     * {@link @fluidframework/protocol-definitions#ISummaryHandle} can be used
+     * instead of re-summarizing it. If this is `false`, the expectation is that you should never
+     * send an `ISummaryHandle`, since you are not expected to track state.
+     *
      * Note: The goal is to remove the trackState and automatically decided whether the
-     * handles will be used or not: https://github.com/microsoft/FluidFramework/issues/10455
+     * handles will be used or not: {@link https://github.com/microsoft/FluidFramework/issues/10455}
+     *
+     * Default: `false`
+     *
+     * @param telemetryContext - See {@link @fluidframework/runtime-definitions#ITelemetryContext}.
+     *
      * @returns A summary capturing the current state of the channel.
      */
     getAttachSummary(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
     /**
      * Generates summary of the channel asynchronously.
      * This should not be called where the channel can be modified while summarization is in progress.
+     *
      * @param fullTree - flag indicating whether the attempt should generate a full
-     * summary tree without any handles for unchanged subtrees. It is only set to true when generating
+     * summary tree without any handles for unchanged subtrees. It should only be set to true when generating
      * a summary from the entire container.
-     * @param trackState - This tells whether we should track state from this summary.
+     *
+     * Default: `false`
+     *
+     * @param trackState - An optimization for tracking state of objects across summaries. If the state
+     * of an object did not change since last successful summary, an
+     * {@link @fluidframework/protocol-definitions#ISummaryHandle} can be used
+     * instead of re-summarizing it. If this is `false`, the expectation is that you should never
+     * send an `ISummaryHandle`, since you are not expected to track state.
+     *
+     * Default: `false`
+     *
+     * Note: The goal is to remove the trackState and automatically decided whether the
+     * handles will be used or not: {@link https://github.com/microsoft/FluidFramework/issues/10455}
+     *
+     * @param telemetryContext - See {@link @fluidframework/runtime-definitions#ITelemetryContext}.
+     *
      * @returns A summary capturing the current state of the channel.
      */
-    summarize(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): Promise<ISummaryTreeWithStats>;
+    summarize(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext, incrementalSummaryContext?: IExperimentalIncrementalSummaryContext): Promise<ISummaryTreeWithStats>;
     /**
      * Checks if the channel is attached to storage.
      * @returns True iff the channel is attached.
@@ -50,7 +83,7 @@ export interface IChannel extends IFluidLoadable {
     isAttached(): boolean;
     /**
      * Enables the channel to send and receive ops.
-     * @param services - Services to connect to
+     * @param services - The services to connect to.
      */
     connect(services: IChannelServices): void;
     /**
@@ -62,6 +95,7 @@ export interface IChannel extends IFluidLoadable {
 }
 /**
  * Handler provided by shared data structure to process requests from the runtime.
+ * @public
  */
 export interface IDeltaHandler {
     /**
@@ -104,6 +138,7 @@ export interface IDeltaHandler {
 }
 /**
  * Interface to represent a connection to a delta notification stream.
+ * @public
  */
 export interface IDeltaConnection {
     connected: boolean;
@@ -134,6 +169,7 @@ export interface IDeltaConnection {
 }
 /**
  * Storage services to read the objects at a given path.
+ * @public
  */
 export interface IChannelStorageService {
     /**
@@ -151,13 +187,32 @@ export interface IChannelStorageService {
 }
 /**
  * Storage services to read the objects at a given path using the given delta connection.
+ * @public
  */
 export interface IChannelServices {
     deltaConnection: IDeltaConnection;
     objectStorage: IChannelStorageService;
 }
 /**
- * Definitions of a channel factory. Factories follow a common model but enable custom behavior.
+ * Definitions of a channel factory.
+ *
+ * @remarks
+ *
+ * The runtime must be able to produce "channels" of the correct in-memory object type for the collaborative session.
+ * Here "channels" are typically distributed data structures (DDSs).
+ *
+ * The runtime will consult with a registry of such factories during
+ * {@link https://fluidframework.com/docs/build/containers/ | Container} load and when receiving "attach" operations
+ * (ops), which indicate a new instance of a channel being introduced to the collaboration session, to produce the
+ * appropriate in-memory object.
+ *
+ * Factories follow a common model but enable custom behavior.
+ *
+ * @example
+ *
+ * If a collaboration includes a {@link https://fluidframework.com/docs/data-structures/map/ | SharedMap},
+ * the collaborating clients will need to have access to a factory that can produce the `SharedMap` object.
+ * @public
  */
 export interface IChannelFactory {
     /**

package/dist/channel.d.ts.map

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