Skip to main content

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
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.
isAttached Beta readonly boolean
isReadOnly Beta readonly () => boolean Get the current readonly state.
logger Beta readonly ITelemetryLoggerExt
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:

  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.
getQuorum() Beta IQuorumClients
makeVisibleAndAttachGraph() Beta void

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.
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
submitMessage(type, content, localOpMetadata) 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

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.

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

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

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 Modifiers Type Description
type DataStoreMessageType
content any The content of the original message.
localOpMetadata unknown The local metadata associated with the original message.
squash optional 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

submitMessage

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
submitMessage(type: DataStoreMessageType, content: any, localOpMetadata: unknown): void;

Parameters

Parameter Type Description
type DataStoreMessageType
content any
localOpMetadata unknown

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>