@fluidframework/container-loader Package

Interfaces

Interface	Alerts	Modifiers	Description
ContainerAlpha	Legacy	sealed	IContainer interface that includes experimental features still under development.
IBaseProtocolHandler	Legacy
ICaptureFullContainerStateProps	Legacy		Properties for captureFullContainerState({ urlResolver, documentServiceFactory, request, logger, }, input).
ICodeDetailsLoader	Deprecated, Legacy
ICreateAndLoadContainerProps	Legacy		Properties necessary for creating and loading a container.
ICreateDetachedContainerProps	Legacy		Props used to create a detached container.
IFluidModuleWithDetails	Deprecated, Legacy
ILoaderProps	Legacy		Services and properties necessary for creating a loader
ILoaderServices	Legacy		Services and properties used by and exposed by the loader
ILoadExistingContainerProps	Legacy		Props used to load a container.
ILoadFrozenContainerFromPendingStateProps	Legacy		Properties required to load a frozen container from pending state.
IParsedUrl	Legacy		Interface to represent the parsed parts of IResolvedUrl.url to help in getting info about different parts of the url. May not be compatible or relevant for any Url Resolver
IProtocolHandler	Legacy
IQuorumSnapshot	Legacy		Snapshot format for a Quorum
IRehydrateDetachedContainerProps	Legacy		Props used to rehydrate a detached container.
IScribeProtocolState	Legacy
OnDemandSummaryResults	Legacy		Results from an on-demand summary request.

Classes

Class	Alerts	Description
Loader	Legacy	Manages Fluid resource loading
PendingLocalStateStore	Legacy	A Map-like store for managing pending local container states from attached containers. Optimizes storage by deduplicating shared resources across stored states.

Enumerations

Enum	Description
ConnectionState	The state of the Container's connection to the service.

Types

TypeAlias	Alerts	Description
ILoadSummarizerContainerProps	Legacy	Props used to load summarizer container.
LoadSummarizerSummaryResult	Legacy	Outcome from loadSummarizerContainerAndMakeSummary(loadSummarizerContainerProps).
ProtocolHandlerBuilder	Legacy	Function to be used for creating a protocol handler.
QuorumClientsSnapshot	Legacy	Snapshot format for a QuorumClients
QuorumProposalsSnapshot	Legacy	Snapshot format for a QuorumProposals
SummaryStage	Legacy	Stages of summary process. Stages: "base" - stopped before the summary tree was even generated, and the result only contains the base data "generate" - the summary tree was generated, and the result will contain that tree + stats "upload" - the summary was uploaded to storage, and the result contains the server-provided handle "submit" - the summarize op was submitted, and the result contains the op client sequence number.

Functions

Function	Alerts	Return Type	Description
asLegacyAlpha(base)	Legacy	ContainerAlpha	Converts types to their alpha counterparts to expose alpha functionality.
captureFullContainerState({ urlResolver, documentServiceFactory, request, logger, }, input)	Legacy	Promise<string>	Captures the current state of an attached container using only driver-level services, without instantiating a runtime or loading a full container. The returned string is a serialized pending container state in the same wire format produced by a live container's pending-state serialization, and can be handed to loadExistingContainer(loadExistingContainerProps) as pendingLocalState. The output is a self-contained view of the container's referenced graph: the latest snapshot, inlined contents of every blob reachable through referenced subtrees, inlined contents of every referenced attachment blob keyed by storage id, and all ops with sequence numbers after the base snapshot's sequence number (as read from its attributes blob). Reachability respects GC. Snapshot subtrees flagged unreferenced: true are skipped (their contents are not inlined). Attachment blobs that GC has marked unreferenced, tombstoned, or deleted are skipped. When the snapshot has no GC tree (GC disabled or pre-GC document), no filtering is applied. Blob reads on load hit the ContainerStorageAdapter cache populated from the captured snapshotBlobs map, so a frozen loader can serve the full referenced graph without a live storage service. pendingRuntimeState is undefined — no runtime is instantiated — so the output cannot carry DDS-level in-flight changes. It is intended for state relay, inspection, and durable-state snapshot use cases. Containers that declare loading groups are not yet supported: the function throws UsageError if any referenced subtree carries a groupId. Group snapshots would need a separate prefetch + serialization path; until there is a known consumer and end-to-end coverage, the capture refuses rather than silently producing pending state that omits group data. Note: if a new snapshot lands between the snapshot fetch and the ops fetch, the returned state may not reflect the very latest snapshot, but remains internally consistent: ops are anchored to the snapshot that was captured. No mixinMonitoringContext / configProvider is wired here, deliberately diverging from the sibling entry points in this file. The function reads no feature flags and instantiates no runtime, so there is nothing for a monitoring context to gate or attribute. If a future change introduces config-gated behavior or runtime-attributed telemetry, add the wiring back together with that change.
createDetachedContainer(createDetachedContainerProps)	Legacy	Promise<IContainer>	Creates a new container using the specified code details but in an unattached state. While unattached, all updates will only be local until the user explicitly attaches the container to a service provider.
createFrozenDocumentServiceFactory(factory, readOnly)	Legacy	IDocumentServiceFactory	Creates an IDocumentServiceFactory that produces a "frozen" document service: one whose delta stream never sends or receives ops, and whose storage service only supports IDocumentStorageService.readBlob. Used to load a container from pending local state without re-establishing a live connection.
loadExistingContainer(loadExistingContainerProps)	Legacy	Promise<IContainer>	Loads a container with an existing snapshot from the service.
loadFrozenContainerFromPendingState(props)	Legacy	Promise<IContainer>	Loads a frozen container from pending local state.
loadSummarizerContainerAndMakeSummary(loadSummarizerContainerProps)	Legacy	Promise<LoadSummarizerSummaryResult>	Loads a summarizer container with the required headers, triggers an on-demand summary, and then closes it. Returns success/failure and an optional error for host-side handling.
rehydrateDetachedContainer(rehydrateDetachedContainerProps)	Legacy	Promise<IContainer>	Creates a new container using the specified snapshot but in an unattached state. While unattached, all updates will only be local until the user explicitly attaches the container to a service provider.
resolveWithLocationRedirectionHandling(api, request, urlResolver, logger)	Legacy	Promise<T>	Handles location redirection while fulfilling the loader request.
tryParseCompatibleResolvedUrl(url)	Legacy	IParsedUrl | undefined	Utility api to parse the IResolvedUrl.url into specific parts like querystring, path to get deep link info etc. Warning - This function may not be compatible with any Url Resolver's resolved url. It works with urls of type: protocol:///.../..?
waitContainerToCatchUp(container)	Legacy	Promise<boolean>	Waits until container connects to delta storage and gets up-to-date. Useful when resolving URIs and hitting 404, due to container being loaded from (stale) snapshot and not being up to date. Host may chose to wait in such case and retry resolving URI. Warning: Will wait infinitely for connection to establish if there is no connection. May result in deadlock if Container.disconnect() is called and never followed by a call to Container.connect().

Function Details

asLegacyAlpha

Converts types to their alpha counterparts to expose alpha functionality.

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function asLegacyAlpha(base: IContainer): ContainerAlpha;

Remarks

For getPendingLocalState, prefer calling IContainer.getPendingLocalState directly on the @legacy @beta surface. This helper is retained for callers that need the typed-required shape and will be removed in a future breaking release.

Parameters

Parameter	Type	Description
base	IContainer

Returns

Return type: ContainerAlpha

captureFullContainerState

Captures the current state of an attached container using only driver-level services, without instantiating a runtime or loading a full container. The returned string is a serialized pending container state in the same wire format produced by a live container's pending-state serialization, and can be handed to loadExistingContainer(loadExistingContainerProps) as pendingLocalState.

The output is a self-contained view of the container's referenced graph: the latest snapshot, inlined contents of every blob reachable through referenced subtrees, inlined contents of every referenced attachment blob keyed by storage id, and all ops with sequence numbers after the base snapshot's sequence number (as read from its attributes blob).

Reachability respects GC. Snapshot subtrees flagged unreferenced: true are skipped (their contents are not inlined). Attachment blobs that GC has marked unreferenced, tombstoned, or deleted are skipped. When the snapshot has no GC tree (GC disabled or pre-GC document), no filtering is applied.

Blob reads on load hit the ContainerStorageAdapter cache populated from the captured snapshotBlobs map, so a frozen loader can serve the full referenced graph without a live storage service.

pendingRuntimeState is undefined — no runtime is instantiated — so the output cannot carry DDS-level in-flight changes. It is intended for state relay, inspection, and durable-state snapshot use cases.

Containers that declare loading groups are not yet supported: the function throws UsageError if any referenced subtree carries a groupId. Group snapshots would need a separate prefetch + serialization path; until there is a known consumer and end-to-end coverage, the capture refuses rather than silently producing pending state that omits group data.

Note: if a new snapshot lands between the snapshot fetch and the ops fetch, the returned state may not reflect the very latest snapshot, but remains internally consistent: ops are anchored to the snapshot that was captured.

No mixinMonitoringContext / configProvider is wired here, deliberately diverging from the sibling entry points in this file. The function reads no feature flags and instantiates no runtime, so there is nothing for a monitoring context to gate or attribute. If a future change introduces config-gated behavior or runtime-attributed telemetry, add the wiring back together with that change.

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function captureFullContainerState(input: ICaptureFullContainerStateProps): Promise<string>;

Parameters

Parameter	Type	Description
{ urlResolver, documentServiceFactory, request, logger, }
input	ICaptureFullContainerStateProps

Returns

Return type: Promise<string>

createDetachedContainer

Creates a new container using the specified code details but in an unattached state. While unattached, all updates will only be local until the user explicitly attaches the container to a service provider.

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function createDetachedContainer(createDetachedContainerProps: ICreateDetachedContainerProps): Promise<IContainer>;

Parameters

Parameter	Type	Description
createDetachedContainerProps	ICreateDetachedContainerProps	Services and properties necessary for creating detached container.

Returns

Return type: Promise<IContainer>

createFrozenDocumentServiceFactory

Creates an IDocumentServiceFactory that produces a "frozen" document service: one whose delta stream never sends or receives ops, and whose storage service only supports IDocumentStorageService.readBlob. Used to load a container from pending local state without re-establishing a live connection.

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function createFrozenDocumentServiceFactory(factory?: IDocumentServiceFactory | Promise<IDocumentServiceFactory>, readOnly?: boolean): IDocumentServiceFactory;

Parameters

Parameter	Modifiers	Type	Description
factory	optional	IDocumentServiceFactory | Promise<IDocumentServiceFactory>	The underlying factory to wrap. Its storage backs blob reads; all other storage operations throw. May be omitted when blob fetches are not required.
readOnly	optional	boolean	When true (the default), the document service advertises the IDocumentServicePolicies.storageOnly policy, which causes the loader to surface the container as read-only (see IContainer.readOnlyInfo). When false, the container is loaded as writable so the runtime will accept DDS submissions. The connection itself stays Connected: ConnectionManager.sendMessages recognizes the WritableFrozenDeltaStream as the live connection and short-circuits — the message is dropped at the network layer rather than triggering a read→write reconnect. Local DDS state continues to update via optimistic apply, and submitted ops accumulate in the runtime's pending-state manager, which is exactly the state needed to capture pending local state. Use false when callers want to accrue and capture pending state without publishing it.

Returns

A factory that produces frozen document services.

Return type: IDocumentServiceFactory

loadExistingContainer

Loads a container with an existing snapshot from the service.

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function loadExistingContainer(loadExistingContainerProps: ILoadExistingContainerProps): Promise<IContainer>;

Parameters

Parameter	Type	Description
loadExistingContainerProps	ILoadExistingContainerProps	Services and properties necessary for loading an existing container.

Returns

Return type: Promise<IContainer>

loadFrozenContainerFromPendingState

Loads a frozen container from pending local state.

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function loadFrozenContainerFromPendingState(props: ILoadFrozenContainerFromPendingStateProps): Promise<IContainer>;

Parameters

Parameter	Type	Description
props	ILoadFrozenContainerFromPendingStateProps	Properties required to load a frozen container from pending state.

Returns

Return type: Promise<IContainer>

loadSummarizerContainerAndMakeSummary

Loads a summarizer container with the required headers, triggers an on-demand summary, and then closes it. Returns success/failure and an optional error for host-side handling.

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function loadSummarizerContainerAndMakeSummary(loadSummarizerContainerProps: ILoadSummarizerContainerProps): Promise<LoadSummarizerSummaryResult>;

Parameters

Parameter	Type	Description
loadSummarizerContainerProps	ILoadSummarizerContainerProps

Returns

Return type: Promise<LoadSummarizerSummaryResult>

rehydrateDetachedContainer

Creates a new container using the specified snapshot but in an unattached state. While unattached, all updates will only be local until the user explicitly attaches the container to a service provider.

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function rehydrateDetachedContainer(rehydrateDetachedContainerProps: IRehydrateDetachedContainerProps): Promise<IContainer>;

Parameters

Parameter	Type	Description
rehydrateDetachedContainerProps	IRehydrateDetachedContainerProps	Services and properties necessary for rehydrating detached container from a previously serialized container's state.

Returns

Return type: Promise<IContainer>

resolveWithLocationRedirectionHandling

Handles location redirection while fulfilling the loader request.

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function resolveWithLocationRedirectionHandling<T>(api: (request: IRequest) => Promise<T>, request: IRequest, urlResolver: IUrlResolver, logger?: ITelemetryBaseLogger): Promise<T>;

Type Parameters

Parameter	Description
T

Parameters

Parameter	Modifiers	Type	Description
api		(request: IRequest) => Promise<T>	Callback in which user can wrap the loader.resolve or loader.request call.
request		IRequest	request to be resolved.
urlResolver		IUrlResolver	resolver used to resolve the url.
logger	optional	ITelemetryBaseLogger	logger to send events.

Returns

Response from the API call.

Return type: Promise<T>

tryParseCompatibleResolvedUrl

Utility api to parse the IResolvedUrl.url into specific parts like querystring, path to get deep link info etc. Warning - This function may not be compatible with any Url Resolver's resolved url. It works with urls of type: protocol:///.../..?

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function tryParseCompatibleResolvedUrl(url: string): IParsedUrl | undefined;

Parameters

Parameter	Type	Description
url	string	This is the IResolvedUrl.url part of the resolved url.

Returns

The IParsedUrl representing the input URL, or undefined if the format was not supported

Return type: IParsedUrl | undefined

waitContainerToCatchUp

Waits until container connects to delta storage and gets up-to-date.

Useful when resolving URIs and hitting 404, due to container being loaded from (stale) snapshot and not being up to date. Host may chose to wait in such case and retry resolving URI.

Warning: Will wait infinitely for connection to establish if there is no connection. May result in deadlock if Container.disconnect() is called and never followed by a call to Container.connect().

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

To use, import via @fluidframework/container-loader/legacy.

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

Signature

export declare function waitContainerToCatchUp(container: IContainer): Promise<boolean>;

Parameters

Parameter	Type	Description
container	IContainer

Returns

true: container is up to date, it processed all the ops that were know at the time of first connection.

false: storage does not provide indication of how far the client is. Container processed all the ops known to it, but it maybe still behind.

Return type: Promise<boolean>

Error Handling

an error beginning with "Container closed" if the container is closed before it catches up.