@fluidframework/runtime-definitions 2.92.0 → 2.100.0

package/lib/stagingMode.js.map

@@ -1 +1 @@
-{"version":3,"file":"stagingMode.js","sourceRoot":"","sources":["../src/stagingMode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA6FH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAA2B;IACxD,OAAO,IAAiC,CAAC;AAC1C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IContainerRuntimeBase } from \"./dataStoreContext.js\";\n\n/**\n * Options for committing staged changes in experimental staging mode.\n * @internal\n */\nexport interface CommitStagedChangesOptionsInternal {\n\t/**\n\t * If true, intermediate states created by changes made while in staging mode will be \"squashed\" out of the\n\t * ops which were created during staging mode.\n\t * Defaults to false.\n\t * @remarks\n\t * The squash parameter is analogous to `git squash` but differs in a notable way: ops created by a client exiting staging mode\n\t * are not necessarily coalesced into a single op or something like it.\n\t * It still does have the desirable property that \"unnecessary changes\" (such as inserting some content then removing it) will\n\t * be removed from the set of submitted ops, which means it helps reduce network traffic and the chance of unwanted data being\n\t * persisted--even if only temporarily--in the document.\n\t *\n\t * By not attempting to reduce the set of changes to a single op a la `git squash`, we can better preserve the ordering of\n\t * changes that remote clients see such that they better align with the client which submitted the changes.\n\t */\n\tsquash?: boolean;\n}\n\n/**\n * Controls for managing staged changes in experimental staging mode.\n *\n * Provides methods to either commit or discard changes made while in staging mode.\n * @internal\n */\nexport interface StageControlsInternal extends StageControlsAlpha {\n\t/**\n\t * Exit staging mode and commit to any changes made while in staging mode.\n\t * This will cause them to be sent to the ordering service, and subsequent changes\n\t * made by this container will additionally flow freely to the ordering service.\n\t * @param options - Options when committing changes.\n\t */\n\treadonly commitChanges: (options?: Partial<CommitStagedChangesOptionsInternal>) => void;\n}\n\n/**\n * Controls for managing staged changes in alpha staging mode.\n *\n * Provides methods to either commit or discard changes made while in staging mode.\n *\n * @legacy @alpha\n * @sealed\n */\nexport interface StageControlsAlpha {\n\t/**\n\t * Exit staging mode and commit to any changes made while in staging mode.\n\t * This will cause them to be sent to the ordering service, and subsequent changes\n\t * made by this container will additionally flow freely to the ordering service.\n\t */\n\treadonly commitChanges: () => void;\n\t/**\n\t * Exit staging mode and discard any changes made while in staging mode.\n\t */\n\treadonly discardChanges: () => void;\n}\n\n/**\n * Experimental extension of {@link IContainerRuntimeBase} to support staging mode.\n * @internal\n */\nexport interface IContainerRuntimeBaseInternal extends ContainerRuntimeBaseAlpha {\n\t/**\n\t * Enters staging mode, allowing changes to be staged before being committed or discarded.\n\t * @returns Controls for committing or discarding staged changes.\n\t */\n\tenterStagingMode(): StageControlsInternal;\n}\n\n/**\n * Alpha interface for container runtime base supporting staging mode.\n *\n * @legacy @alpha\n * @sealed\n */\nexport interface ContainerRuntimeBaseAlpha extends IContainerRuntimeBase {\n\t/**\n\t * Enters staging mode, allowing changes to be staged before being committed or discarded.\n\t * @returns Controls for committing or discarding staged changes.\n\t */\n\tenterStagingMode(): StageControlsAlpha;\n\t/**\n\t * Indicates whether the container is currently in staging mode.\n\t */\n\treadonly inStagingMode: boolean;\n}\n\n/**\n * Converts types to their alpha counterparts to expose alpha functionality.\n * @legacy @alpha\n * @sealed\n */\nexport function asLegacyAlpha(base: IContainerRuntimeBase): ContainerRuntimeBaseAlpha {\n\treturn base as ContainerRuntimeBaseAlpha;\n}\n"]}
+{"version":3,"file":"stagingMode.js","sourceRoot":"","sources":["../src/stagingMode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4EH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAA2B;IACxD,OAAO,IAAiC,CAAC;AAC1C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IContainerRuntimeBase, StageControls } from \"./dataStoreContext.js\";\n\n/**\n * Options for committing staged changes in experimental staging mode.\n * @internal\n */\nexport interface CommitStagedChangesOptionsInternal {\n\t/**\n\t * If true, intermediate states created by changes made while in staging mode will be \"squashed\" out of the\n\t * ops which were created during staging mode.\n\t * Defaults to false.\n\t * @remarks\n\t * The squash parameter is analogous to `git squash` but differs in a notable way: ops created by a client exiting staging mode\n\t * are not necessarily coalesced into a single op or something like it.\n\t * It still does have the desirable property that \"unnecessary changes\" (such as inserting some content then removing it) will\n\t * be removed from the set of submitted ops, which means it helps reduce network traffic and the chance of unwanted data being\n\t * persisted--even if only temporarily--in the document.\n\t *\n\t * By not attempting to reduce the set of changes to a single op a la `git squash`, we can better preserve the ordering of\n\t * changes that remote clients see such that they better align with the client which submitted the changes.\n\t */\n\tsquash?: boolean;\n}\n\n/**\n * Controls for managing staged changes in experimental staging mode.\n *\n * Provides methods to either commit or discard changes made while in staging mode.\n * @internal\n */\nexport interface StageControlsInternal extends StageControls {\n\t/**\n\t * Exit staging mode and commit to any changes made while in staging mode.\n\t * This will cause them to be sent to the ordering service, and subsequent changes\n\t * made by this container will additionally flow freely to the ordering service.\n\t * @param options - Options when committing changes.\n\t */\n\treadonly commitChanges: (options?: Partial<CommitStagedChangesOptionsInternal>) => void;\n}\n\n/**\n * Internal extension of {@link IContainerRuntimeBase} whose {@link IContainerRuntimeBaseInternal.enterStagingMode}\n * returns {@link StageControlsInternal} (which exposes internal commit options such as squash)\n * @internal\n */\nexport interface IContainerRuntimeBaseInternal extends IContainerRuntimeBase {\n\t/**\n\t * Enters staging mode, allowing changes to be staged before being committed or discarded.\n\t * @returns Controls for committing or discarding staged changes.\n\t */\n\tenterStagingMode(): StageControlsInternal;\n}\n\n/**\n * Controls for managing staged changes in alpha staging mode.\n *\n * Provides methods to either commit or discard changes made while in staging mode.\n *\n * @deprecated Use {@link StageControls} (beta) instead.\n * @legacy @alpha\n * @sealed\n */\nexport interface StageControlsAlpha extends StageControls {}\n\n/**\n * Alpha extension of {@link IContainerRuntimeBase} that exposes alpha-level APIs.\n *\n * @remarks Use {@link asLegacyAlpha} to obtain an instance from an {@link IContainerRuntimeBase}.\n *\n * @legacy @alpha\n * @sealed\n */\nexport interface ContainerRuntimeBaseAlpha extends IContainerRuntimeBase {}\n\n/**\n * Converts types to their alpha counterparts to expose alpha functionality.\n * @legacy @alpha\n * @sealed\n */\nexport function asLegacyAlpha(base: IContainerRuntimeBase): ContainerRuntimeBaseAlpha {\n\treturn base as ContainerRuntimeBaseAlpha;\n}\n"]}

package/lib/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.52.11"
+      "packageVersion": "7.58.1"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/runtime-definitions",
-  "version": "2.92.0",
+  "version": "2.100.0",
   "description": "Fluid Runtime definitions",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -67,22 +67,22 @@
   "main": "lib/index.js",
   "types": "lib/public.d.ts",
   "dependencies": {
-    "@fluid-internal/client-utils": "~2.92.0",
-    "@fluidframework/container-definitions": "~2.92.0",
-    "@fluidframework/core-interfaces": "~2.92.0",
-    "@fluidframework/driver-definitions": "~2.92.0",
-    "@fluidframework/id-compressor": "~2.92.0",
-    "@fluidframework/telemetry-utils": "~2.92.0"
+    "@fluid-internal/client-utils": "~2.100.0",
+    "@fluidframework/container-definitions": "~2.100.0",
+    "@fluidframework/core-interfaces": "~2.100.0",
+    "@fluidframework/driver-definitions": "~2.100.0",
+    "@fluidframework/id-compressor": "~2.100.0",
+    "@fluidframework/telemetry-utils": "~2.100.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-tools/build-cli": "^0.64.0",
+    "@fluid-tools/build-cli": "^0.65.0",
     "@fluidframework/build-common": "^2.0.3",
-    "@fluidframework/build-tools": "^0.64.0",
+    "@fluidframework/build-tools": "^0.65.0",
     "@fluidframework/eslint-config-fluid": "^9.0.0",
-    "@fluidframework/runtime-definitions-previous": "npm:@fluidframework/runtime-definitions@2.91.0",
-    "@microsoft/api-extractor": "7.52.11",
+    "@fluidframework/runtime-definitions-previous": "npm:@fluidframework/runtime-definitions@2.92.0",
+    "@microsoft/api-extractor": "7.58.1",
     "concurrently": "^9.2.1",
     "copyfiles": "^2.4.1",
     "eslint": "~9.39.1",
@@ -133,7 +133,6 @@
     "lint": "fluid-build . --task lint",
     "lint:fix": "fluid-build . --task eslint:fix --task format",
     "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
-    "typetests:gen": "flub generate typetests --dir . -v",
-    "typetests:prepare": "flub typetests --dir . --reset --previous --normalize"
+    "typetests:gen": "flub generate typetests --dir . -v"
   }
 }

package/src/dataStoreContext.ts

@@ -132,6 +132,17 @@ export interface IContainerRuntimeBaseEvents extends IEvent {
 	(event: "op", listener: (op: ISequencedDocumentMessage, runtimeMessage?: boolean) => void);
 	(event: "signal", listener: (message: IInboundSignalMessage, local: boolean) => void);
 	(event: "dispose", listener: () => void);
+	/**
+	 * Fires when the container runtime enters or exits staging mode.
+	 * @param stagingModeInfo - An object describing the staging mode state.
+	 * If `inStagingMode` is true, the runtime has entered staging mode.
+	 * If false, it has exited staging mode, and `commit` indicates whether changes were committed or discarded.
+	 *
+	 * @remarks
+	 * This event is not emitted when the container is disposed while in staging mode.
+	 * If the container is disposed, staged changes are silently dropped.
+	 */
+	(event: "stagingModeChanged", listener: (stagingModeInfo: StagingModeChangedEvent) => void);
 }
 
 /**
@@ -180,6 +191,35 @@ export interface IDataStore {
 	readonly entryPoint: IFluidHandleInternal<FluidObject>;
 }
 
+/**
+ * Controls for managing staged changes in staging mode.
+ *
+ * Provides methods to either commit or discard changes made while in staging mode.
+ *
+ * @see {@link IContainerRuntimeBase.enterStagingMode}
+ *
+ * @legacy @beta
+ * @sealed
+ */
+export interface StageControls {
+	/**
+	 * Exit staging mode and commit to any changes made while in staging mode.
+	 * This will cause them to be sent to the ordering service, and subsequent changes
+	 * made by this container will additionally flow freely to the ordering service.
+	 *
+	 * @remarks
+	 * Squash-rebase semantics during commit are not yet fully specified.
+	 */
+	readonly commitChanges: () => void;
+	/**
+	 * Exit staging mode and discard any changes made while in staging mode.
+	 *
+	 * @remarks
+	 * DDS rollback support may be incomplete — this may throw for some DDS implementations.
+	 */
+	readonly discardChanges: () => void;
+}
+
 /**
  * A reduced set of functionality of {@link @fluidframework/container-runtime-definitions#IContainerRuntime} that a data store context/data store runtime will need.
  * @privateRemarks
@@ -290,6 +330,27 @@ export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeB
 		loadingGroupIds: string[],
 		pathParts: string[],
 	): Promise<{ snapshotTree: ISnapshotTree; sequenceNumber: number }>;
+
+	/**
+	 * Enter Staging Mode, such that ops submitted to the ContainerRuntime will not be sent to the ordering service.
+	 * To exit Staging Mode, call either discardChanges or commitChanges on the Stage Controls returned from this method.
+	 *
+	 * @remarks
+	 * Known limitations:
+	 * - DDS rollback support may be incomplete — {@link StageControls.discardChanges} may throw for some DDS implementations.
+	 * - Squash-rebase semantics during {@link StageControls.commitChanges} are not yet fully specified.
+	 *
+	 * @returns Controls for committing or discarding staged changes.
+	 */
+	enterStagingMode(): StageControls;
+
+	/**
+	 * If true, the ContainerRuntime is not submitting any new ops to the ordering service.
+	 * Ops submitted to the ContainerRuntime while in Staging Mode will be queued in the PendingStateManager,
+	 * either to be discarded or committed later (via the Stage Controls returned from enterStagingMode).
+	 * @see {@link IContainerRuntimeBase.enterStagingMode}
+	 */
+	readonly inStagingMode: boolean;
 }
 
 /**
@@ -310,6 +371,10 @@ export interface IFluidDataStorePolicies {
 	 * (e.g., `ConsensusRegisterCollection`, `ConsensusQueue`, `TaskManager`) won't resolve their promises until
 	 * staging mode exits. Set this to `true` for data stores that depend on consensus acknowledgments
 	 * to prevent modifications that would leave the data store in an unresponsive state.
+	 *
+	 * This provides a best-effort readonly appearance, but no strict enforcement.
+	 *
+	 * @see {@link IContainerRuntimeBase.enterStagingMode}
 	 */
 	readonly readonlyInStagingMode: boolean;
 }
@@ -438,6 +503,19 @@ export interface IFluidDataStoreChannel extends IDisposable {
 	setAttachState(attachState: AttachState.Attaching | AttachState.Attached): void;
 }
 
+/**
+ * Describes a staging mode transition on the container runtime.
+ * - `{ inStagingMode: true }` — the runtime has entered staging mode.
+ *
+ * - `{ inStagingMode: false, commit: boolean }` — the runtime has exited staging mode.
+ * `commit` is `true` when staged changes were committed (not discarded), or `false` when they were discarded.
+ *
+ * @legacy @beta
+ */
+export type StagingModeChangedEvent =
+	| { readonly inStagingMode: true }
+	| { readonly inStagingMode: false; readonly commit: boolean };
+
 /**
  * @legacy @beta
  */
@@ -492,7 +570,7 @@ export interface IFluidParentContext
 	 * Consumed by {@link @fluidframework/container-runtime#FluidDataStoreContext}.
 	 * See {@link @fluidframework/container-runtime#LoadContainerRuntimeParams.minVersionForCollab} for more details.
 	 */
-	readonly minVersionForCollab?: MinimumVersionForCollab;
+	readonly minVersionForCollab: MinimumVersionForCollab;
 	readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
 	readonly storage: IRuntimeStorageService;
 	readonly baseLogger: ITelemetryBaseLogger;

package/src/index.ts

@@ -31,6 +31,8 @@ export type {
 	IFluidDataStoreContextDetached,
 	IPendingMessagesState,
 	PackagePath,
+	StageControls,
+	StagingModeChangedEvent,
 } from "./dataStoreContext.js";
 export { FlushMode, VisibilityState } from "./dataStoreContext.js";
 export type { IProvideFluidDataStoreFactory } from "./dataStoreFactory.js";

package/src/stagingMode.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { IContainerRuntimeBase } from "./dataStoreContext.js";
+import type { IContainerRuntimeBase, StageControls } from "./dataStoreContext.js";
 
 /**
  * Options for committing staged changes in experimental staging mode.
@@ -33,7 +33,7 @@ export interface CommitStagedChangesOptionsInternal {
  * Provides methods to either commit or discard changes made while in staging mode.
  * @internal
  */
-export interface StageControlsInternal extends StageControlsAlpha {
+export interface StageControlsInternal extends StageControls {
 	/**
 	 * Exit staging mode and commit to any changes made while in staging mode.
 	 * This will cause them to be sent to the ordering service, and subsequent changes
@@ -44,31 +44,11 @@ export interface StageControlsInternal extends StageControlsAlpha {
 }
 
 /**
- * Controls for managing staged changes in alpha staging mode.
- *
- * Provides methods to either commit or discard changes made while in staging mode.
- *
- * @legacy @alpha
- * @sealed
- */
-export interface StageControlsAlpha {
-	/**
-	 * Exit staging mode and commit to any changes made while in staging mode.
-	 * This will cause them to be sent to the ordering service, and subsequent changes
-	 * made by this container will additionally flow freely to the ordering service.
-	 */
-	readonly commitChanges: () => void;
-	/**
-	 * Exit staging mode and discard any changes made while in staging mode.
-	 */
-	readonly discardChanges: () => void;
-}
-
-/**
- * Experimental extension of {@link IContainerRuntimeBase} to support staging mode.
+ * Internal extension of {@link IContainerRuntimeBase} whose {@link IContainerRuntimeBaseInternal.enterStagingMode}
+ * returns {@link StageControlsInternal} (which exposes internal commit options such as squash)
  * @internal
  */
-export interface IContainerRuntimeBaseInternal extends ContainerRuntimeBaseAlpha {
+export interface IContainerRuntimeBaseInternal extends IContainerRuntimeBase {
 	/**
 	 * Enters staging mode, allowing changes to be staged before being committed or discarded.
 	 * @returns Controls for committing or discarding staged changes.
@@ -77,22 +57,25 @@ export interface IContainerRuntimeBaseInternal extends ContainerRuntimeBaseAlpha
 }
 
 /**
- * Alpha interface for container runtime base supporting staging mode.
+ * Controls for managing staged changes in alpha staging mode.
+ *
+ * Provides methods to either commit or discard changes made while in staging mode.
  *
+ * @deprecated Use {@link StageControls} (beta) instead.
  * @legacy @alpha
  * @sealed
  */
-export interface ContainerRuntimeBaseAlpha extends IContainerRuntimeBase {
-	/**
-	 * Enters staging mode, allowing changes to be staged before being committed or discarded.
-	 * @returns Controls for committing or discarding staged changes.
-	 */
-	enterStagingMode(): StageControlsAlpha;
-	/**
-	 * Indicates whether the container is currently in staging mode.
-	 */
-	readonly inStagingMode: boolean;
-}
+export interface StageControlsAlpha extends StageControls {}
+
+/**
+ * Alpha extension of {@link IContainerRuntimeBase} that exposes alpha-level APIs.
+ *
+ * @remarks Use {@link asLegacyAlpha} to obtain an instance from an {@link IContainerRuntimeBase}.
+ *
+ * @legacy @alpha
+ * @sealed
+ */
+export interface ContainerRuntimeBaseAlpha extends IContainerRuntimeBase {}
 
 /**
  * Converts types to their alpha counterparts to expose alpha functionality.