FluidDataStoreRuntime Class

Base data store class

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/datastore/legacy.

For more information about our API support guarantees, see here.

Signature

export declare class FluidDataStoreRuntime extends TypedEventEmitter<IFluidDataStoreRuntimeEvents> implements IFluidDataStoreChannel, IFluidDataStoreRuntime, IFluidHandleContext

Extends: TypedEventEmitter<IFluidDataStoreRuntimeEvents>

Implements: IFluidDataStoreChannel, IFluidDataStoreRuntime, IFluidHandleContext

Constructors

Constructor	Alerts	Description
(constructor)(dataStoreContext, sharedObjectRegistry, existing, provideEntryPoint, policies)	Beta	Create an instance of a DataStore runtime.

Properties

Property	Alerts	Modifiers	Type	Description
absolutePath	Beta	readonly	string
activeLocalOperationActivity	Beta	readonly	"applyStashed" | "rollback" | undefined
attachState	Beta	readonly	AttachState
channelsRoutingContext	Beta	readonly	this
clientDetails	Beta	readonly	IClientDetails
clientId	Beta	readonly	string | undefined
connected	Beta	readonly	boolean
deltaManager	Beta	readonly	IDeltaManagerErased
deltaManagerInternal	Beta	readonly	IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>
disposed	Beta	readonly	boolean
entryPoint	Beta	readonly	IFluidHandleInternal<FluidObject>	Exposes a handle to the root object / entryPoint of the data store. Use this as the primary way of interacting with it.
id	Beta	readonly	string
idCompressor	Beta	readonly	IIdCompressor | undefined
IFluidHandleContext	Beta	readonly	this
ILayerCompatDetails	Beta	optional, readonly	unknown	The compatibility details of the DataStore layer that is exposed to the Runtime layer for validating Runtime-DataStore compatibility.
inStagingMode	Beta	readonly	boolean	Indicates whether the container is currently in staging mode.
isAttached	Beta	readonly	boolean
isDirty	Beta	readonly	boolean	Indicates whether the data store has uncommitted local changes.
isReadOnly	Beta	readonly	() => boolean	Get the current readonly state.
logger	Beta	readonly	ITelemetryLoggerExt
minVersionForCollab	Beta	readonly	OldestSupportedClientVersion	See IFluidDataStoreRuntimeInternalConfig.minVersionForCollab Note: this class doesn't declare that it implements IFluidDataStoreRuntimeInternalConfig, and we keep this property as private, but consumers may optimistically cast to the internal interface to access this property.
objectsRoutingContext	Beta	readonly	this
options	Beta	readonly	Record<string | number, any>
policies	Beta	readonly	IFluidDataStorePolicies
rootRoutingContext	Beta	readonly	this
routeContext	Beta	readonly	IFluidHandleContext
visibilityState	Beta		VisibilityState

Methods

Method	Alerts	Modifiers	Return Type	Description
addChannel(channel)	Beta		void	Api which allows caller to create the channel first and then add it to the runtime. The channel type should be present in the registry, otherwise the runtime would reject the channel. Also the runtime used to create the channel object should be same to which it is added.
applyStashedOp(content)	Beta		Promise<unknown>
attachGraph()	Beta		void	This function is called when a handle to this data store is added to a visible DDS.
bind(handle)	Beta		void
bindChannel(channel)	Beta		void	Binds a channel with the runtime. If the runtime is attached we will attach the channel right away. If the runtime is not attached we will defer the attach until the runtime attaches.
createChannel(idArg, type)	Beta		IChannel
dispose()	Beta		void
getAttachGCData(telemetryContext)	Beta		IGarbageCollectionData	Get the GC Data for the initial state being attached so remote clients can learn of this DataStore's outbound routes
getAttachSummary(telemetryContext)	Beta		ISummaryTreeWithStats
getAudience()	Beta		IAudience
getChannel(id)	Beta		Promise<IChannel>
getGCData(fullGC)	Beta		Promise<IGarbageCollectionData>	Generates data used for garbage collection. This includes a list of GC nodes that represent this channel including any of its child channel contexts. Each node has a set of outbound routes to other GC nodes in the document. It does the following: Calls into each child context to get its GC data. Prefixes the child context's id to the GC nodes in the child's GC data. This makes sure that the node can be identified as belonging to the child. Adds a GC node for this channel to the nodes received from the children. All these nodes together represent the GC data of this channel.
getQuorum()	Beta		IQuorumClients
makeVisibleAndAttachGraph()	Beta		void	This function is called when a data store becomes root. It does the following: Marks the data store locally visible in the container. Attaches the graph of all the handles bound to it. Calls into the data store context to mark it visible in the container too. If the container is globally visible, it will mark us globally visible. Otherwise, it will mark us globally visible when it becomes globally visible.
notifyReadOnlyState(readonly)	Beta		void	This function is used by the datastore context to configure the readonly state of this object. It should not be invoked by any other callers.
processMessages(messageCollection)	Beta		void	Process messages for this data store. The messages here are contiguous messages in a batch.
processSignal(message, local)	Beta		void
request(request)	Beta		Promise<IResponse>
resolveHandle(request)	Beta		Promise<IResponse>
reSubmit(type, content, localOpMetadata, squash)	Beta		void	For messages of type MessageType.Operation, finds the right channel and asks it to resubmit the message. For all other messages, just submit it again. This typically happens when we reconnect and there are unacked messages.
rollback(type, content, localOpMetadata)	Beta	optional	void	Revert a local op.
setAttachState(attachState)	Beta		void
setConnectionState(connected, clientId)	Beta		void
submitSignal(type, content, targetClientId)	Beta		void	Submits the signal to be sent to other clients.
summarize(fullTree, trackState, telemetryContext)	Beta		Promise<ISummaryTreeWithStats>	Returns a summary at the current sequence number.
updateUsedRoutes(usedRoutes)	Beta		void	After GC has run, called to notify this channel of routes that are used in it. It calls the child contexts to update their used routes.
uploadBlob(blob, signal)	Beta		Promise<IFluidHandle<ArrayBufferLike>>
validateChannelId(id)	Beta		void	Validate user provided channel ID Channel ID has limitations. "/" is not allowed as IDs in storage can not have slashes - we parse tree paths and use "/" as separator. IDs cannot start with "_" as it could result in collision of IDs with auto-assigned (by FF) short IDs.
waitAttached()	Beta		Promise<void>	Will return when the data store is attached.

Constructor Details

(constructor)

Create an instance of a DataStore runtime.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

constructor(dataStoreContext: IFluidDataStoreContext, sharedObjectRegistry: ISharedObjectRegistry, existing: boolean, provideEntryPoint: (runtime: IFluidDataStoreRuntime) => Promise<FluidObject>, policies?: Partial<IFluidDataStorePolicies>);

Parameters

Parameter	Modifiers	Type	Description
dataStoreContext		IFluidDataStoreContext	Context object for the runtime.
sharedObjectRegistry		ISharedObjectRegistry	The registry of shared objects that this data store will be able to instantiate.
existing		boolean	Pass 'true' if loading this datastore from an existing file; pass 'false' otherwise.
provideEntryPoint		(runtime: IFluidDataStoreRuntime) => Promise<FluidObject>	Function to initialize the entryPoint object for the data store runtime. The handle to this data store runtime will point to the object returned by this function. If this function is not provided, the handle will be left undefined. This is here so we can start making handles a first-class citizen and the primary way of interacting with some Fluid objects, and should be used if possible.
policies	optional	Partial<IFluidDataStorePolicies>

Property Details

absolutePath

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get absolutePath(): string;

Type: string

activeLocalOperationActivity

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get activeLocalOperationActivity(): "applyStashed" | "rollback" | undefined;

Type: "applyStashed" | "rollback" | undefined

attachState

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get attachState(): AttachState;

Type: AttachState

channelsRoutingContext

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get channelsRoutingContext(): this;

Type: this

clientDetails

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get clientDetails(): IClientDetails;

Type: IClientDetails

clientId

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get clientId(): string | undefined;

Type: string | undefined

connected

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get connected(): boolean;

Type: boolean

deltaManager

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get deltaManager(): IDeltaManagerErased;

Type: IDeltaManagerErased

deltaManagerInternal

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly deltaManagerInternal: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;

Type: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>

disposed

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get disposed(): boolean;

Type: boolean

entryPoint

Exposes a handle to the root object / entryPoint of the data store. Use this as the primary way of interacting with it.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly entryPoint: IFluidHandleInternal<FluidObject>;

Type: IFluidHandleInternal<FluidObject>

id

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly id: string;

Type: string

idCompressor

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get idCompressor(): IIdCompressor | undefined;

Type: IIdCompressor | undefined

IFluidHandleContext

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get IFluidHandleContext(): this;

Type: this

ILayerCompatDetails

The compatibility details of the DataStore layer that is exposed to the Runtime layer for validating Runtime-DataStore compatibility.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly ILayerCompatDetails?: unknown;

Type: unknown

Remarks

This is for internal use only. The type of this should be ILayerCompatDetails. However, ILayerCompatDetails is internal and this class is currently marked as legacy alpha. So, using unknown here.

inStagingMode

Indicates whether the container is currently in staging mode.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get inStagingMode(): boolean;

Type: boolean

Remarks

See enterStagingMode() for known limitations.

isAttached

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get isAttached(): boolean;

Type: boolean

isDirty

Indicates whether the data store has uncommitted local changes.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get isDirty(): boolean;

Type: boolean

isReadOnly

Get the current readonly state.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly isReadOnly: () => boolean;

Type: () => boolean

logger

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get logger(): ITelemetryLoggerExt;

Type: ITelemetryLoggerExt

minVersionForCollab

See IFluidDataStoreRuntimeInternalConfig.minVersionForCollab

Note: this class doesn't declare that it implements IFluidDataStoreRuntimeInternalConfig, and we keep this property as private, but consumers may optimistically cast to the internal interface to access this property.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly minVersionForCollab: OldestSupportedClientVersion;

Type: OldestSupportedClientVersion

objectsRoutingContext

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get objectsRoutingContext(): this;

Type: this

options

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly options: Record<string | number, any>;

Type: Record<string | number, any>

policies

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly policies: IFluidDataStorePolicies;

Type: IFluidDataStorePolicies

rootRoutingContext

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get rootRoutingContext(): this;

Type: this

routeContext

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get routeContext(): IFluidHandleContext;

Type: IFluidHandleContext

visibilityState

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

visibilityState: VisibilityState;

Type: VisibilityState

Method Details

addChannel

Api which allows caller to create the channel first and then add it to the runtime. The channel type should be present in the registry, otherwise the runtime would reject the channel. Also the runtime used to create the channel object should be same to which it is added.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

addChannel(channel: IChannel): void;

Parameters

Parameter	Type	Description
channel	IChannel	channel which needs to be added to the runtime.

applyStashedOp

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

applyStashedOp(content: any): Promise<unknown>;

Parameters

Parameter	Type	Description
content	any

Returns

Return type: Promise<unknown>

attachGraph

This function is called when a handle to this data store is added to a visible DDS.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

attachGraph(): void;

bind

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

bind(handle: IFluidHandle): void;

Parameters

Parameter	Type	Description
handle	IFluidHandle

bindChannel

Binds a channel with the runtime. If the runtime is attached we will attach the channel right away. If the runtime is not attached we will defer the attach until the runtime attaches.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

bindChannel(channel: IChannel): void;

Parameters

Parameter	Type	Description
channel	IChannel	channel to be registered.

createChannel

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

createChannel(idArg: string | undefined, type: string): IChannel;

Parameters

Parameter	Type	Description
idArg	string | undefined
type	string

Returns

Return type: IChannel

dispose

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

dispose(): void;

getAttachGCData

Get the GC Data for the initial state being attached so remote clients can learn of this DataStore's outbound routes

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getAttachGCData(telemetryContext?: ITelemetryContext): IGarbageCollectionData;

Parameters

Parameter	Modifiers	Type	Description
telemetryContext	optional	ITelemetryContext

Returns

Return type: IGarbageCollectionData

getAttachSummary

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getAttachSummary(telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;

Parameters

Parameter	Modifiers	Type	Description
telemetryContext	optional	ITelemetryContext

Returns

Return type: ISummaryTreeWithStats

getAudience

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getAudience(): IAudience;

Returns

Return type: IAudience

getChannel

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getChannel(id: string): Promise<IChannel>;

Parameters

Parameter	Type	Description
id	string

Returns

Return type: Promise<IChannel>

getGCData

Generates data used for garbage collection. This includes a list of GC nodes that represent this channel including any of its child channel contexts. Each node has a set of outbound routes to other GC nodes in the document. It does the following:

1. Calls into each child context to get its GC data.

1. Prefixes the child context's id to the GC nodes in the child's GC data. This makes sure that the node can be identified as belonging to the child.

1. Adds a GC node for this channel to the nodes received from the children. All these nodes together represent the GC data of this channel.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getGCData(fullGC?: boolean): Promise<IGarbageCollectionData>;

Parameters

Parameter	Modifiers	Type	Description
fullGC	optional	boolean	true to bypass optimizations and force full generation of GC data.

Returns

Return type: Promise<IGarbageCollectionData>

getQuorum

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

getQuorum(): IQuorumClients;

Returns

Return type: IQuorumClients

makeVisibleAndAttachGraph

This function is called when a data store becomes root. It does the following:

1. Marks the data store locally visible in the container.

1. Attaches the graph of all the handles bound to it.

1. Calls into the data store context to mark it visible in the container too. If the container is globally visible, it will mark us globally visible. Otherwise, it will mark us globally visible when it becomes globally visible.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

makeVisibleAndAttachGraph(): void;

notifyReadOnlyState

This function is used by the datastore context to configure the readonly state of this object. It should not be invoked by any other callers.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

notifyReadOnlyState(readonly: boolean): void;

Parameters

Parameter	Type	Description
readonly	boolean

processMessages

Process messages for this data store. The messages here are contiguous messages in a batch.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

processMessages(messageCollection: IRuntimeMessageCollection): void;

Parameters

Parameter	Type	Description
messageCollection	IRuntimeMessageCollection	The collection of messages to process.

processSignal

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

processSignal(message: IInboundSignalMessage, local: boolean): void;

Parameters

Parameter	Type	Description
message	IInboundSignalMessage
local	boolean

request

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

request(request: IRequest): Promise<IResponse>;

Parameters

Parameter	Type	Description
request	IRequest

Returns

Return type: Promise<IResponse>

resolveHandle

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

resolveHandle(request: IRequest): Promise<IResponse>;

Parameters

Parameter	Type	Description
request	IRequest

Returns

Return type: Promise<IResponse>

reSubmit

For messages of type MessageType.Operation, finds the right channel and asks it to resubmit the message. For all other messages, just submit it again. This typically happens when we reconnect and there are unacked messages.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

reSubmit(type: DataStoreMessageType, content: any, localOpMetadata: unknown, squash: boolean): void;

Parameters

Parameter	Type	Description
type	DataStoreMessageType
content	any	The content of the original message.
localOpMetadata	unknown	The local metadata associated with the original message.
squash	boolean

rollback

Revert a local op.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

rollback?(type: DataStoreMessageType, content: any, localOpMetadata: unknown): void;

Parameters

Parameter	Type	Description
type	DataStoreMessageType
content	any	The content of the original message.
localOpMetadata	unknown	The local metadata associated with the original message.

setAttachState

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

setAttachState(attachState: AttachState.Attaching | AttachState.Attached): void;

Parameters

Parameter	Type	Description
attachState	AttachState.Attaching | AttachState.Attached

setConnectionState

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

setConnectionState(connected: boolean, clientId?: string): void;

Parameters

Parameter	Modifiers	Type	Description
connected		boolean
clientId	optional	string

submitSignal

Submits the signal to be sent to other clients.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

submitSignal(type: string, content: unknown, targetClientId?: string): void;

Parameters

Parameter	Modifiers	Type	Description
type		string	Type of the signal.
content		unknown	Content of the signal. Should be a JSON serializable object or primitive.
targetClientId	optional	string	When specified, the signal is only sent to the provided client id.

summarize

Returns a summary at the current sequence number.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

summarize(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): Promise<ISummaryTreeWithStats>;

Parameters

Parameter	Modifiers	Type	Description
fullTree	optional	boolean	true to bypass optimizations and force a full summary tree
trackState	optional	boolean	This tells whether we should track state from this summary.
telemetryContext	optional	ITelemetryContext	summary data passed through the layers for telemetry purposes

Returns

Return type: Promise<ISummaryTreeWithStats>

updateUsedRoutes

After GC has run, called to notify this channel of routes that are used in it. It calls the child contexts to update their used routes.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

updateUsedRoutes(usedRoutes: string[]): void;

Parameters

Parameter	Type	Description
usedRoutes	string[]	The routes that are used in all contexts in this channel.

uploadBlob

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

uploadBlob(blob: ArrayBufferLike, signal?: AbortSignal): Promise<IFluidHandle<ArrayBufferLike>>;

Parameters

Parameter	Modifiers	Type	Description
blob		ArrayBufferLike
signal	optional	AbortSignal

Returns

Return type: Promise<IFluidHandle<ArrayBufferLike>>

validateChannelId

Validate user provided channel ID Channel ID has limitations. "/" is not allowed as IDs in storage can not have slashes - we parse tree paths and use "/" as separator. IDs cannot start with "_" as it could result in collision of IDs with auto-assigned (by FF) short IDs.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected validateChannelId(id: string): void;

Parameters

Parameter	Type	Description
id	string	channel ID.

waitAttached

Will return when the data store is attached.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

waitAttached(): Promise<void>;

Returns

Return type: Promise<void>