@fluidframework/runtime-definitions 2.93.0 → 2.101.0

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
  */

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.