Fluid Framework Runtime Utils

The @fluidframework/runtime-utils package provides utilities for Fluid Framework runtime operations. Note: This package has a very limited public API surface with only two stable public functions. Most functionality is available through legacy/beta APIs that may change in future versions.

Package Information

• Package Name: @fluidframework/runtime-utils
• Package Type: npm
• Language: TypeScript
• Installation: npm install @fluidframework/runtime-utils

Core Imports

Public API (Stable):

import { 
  isFluidHandle, 
  compareFluidHandles
} from "@fluidframework/runtime-utils";

Legacy/Beta API (Unstable - May change in minor versions):

import {
  RequestParser,
  SummaryTreeBuilder,
  FluidHandleBase,
  RuntimeFactoryHelper,
  create404Response
} from "@fluidframework/runtime-utils/legacy";

Note: This package has a very limited public API surface. Most functionality is available only through legacy/beta APIs that may change or be removed in future versions.

Basic Usage

Public API Usage:

import { 
  isFluidHandle, 
  compareFluidHandles
} from "@fluidframework/runtime-utils";

// Handle management (Public API)
if (isFluidHandle(someValue)) {
  const isEqual = compareFluidHandles(handle1, handle2);
}

Legacy API Usage (Use with caution - may change):

import { 
  RequestParser,
  SummaryTreeBuilder 
} from "@fluidframework/runtime-utils/legacy";

// Request parsing (Legacy API)
const parser = RequestParser.create({ url: "/datastore/component" });
if (parser.isLeaf(1)) {
  // Handle terminal request
}

// Summary building (Legacy API)
const builder = new SummaryTreeBuilder();
builder.addBlob("config", JSON.stringify({ version: "1.0" }));
const summary = builder.getSummaryTree();

Architecture

The runtime-utils package is organized around several key functional areas:

• Handle Management: Serialization, comparison, and type-safe utilities for Fluid object handles
• Data Store Operations: Request/response handling, error management, and context path generation
• Storage Utilities: Blob handling, object storage partitions, and snapshot tree operations
• Summary Management: Building, converting, and tracking statistics for summary trees
• Runtime Factories: Base classes and helpers for creating container runtime instances
• Compatibility System: Version validation and configuration management for collaborative features
• Garbage Collection: Data building and route management for distributed state cleanup
• Delta Management: Type casting utilities for accessing internal delta manager APIs

Capabilities

Handle Management

Core utilities for working with Fluid object handles including serialization, comparison, and type guards. Essential for inter-component communication in Fluid applications.

Public API:

function isFluidHandle(value: unknown): value is IFluidHandle;
function compareFluidHandles(a: IFluidHandle, b: IFluidHandle): boolean;

Note: Additional handle management utilities like FluidHandleBase, encodeHandleForSerialization, and other serialization functions are available only through the legacy API import path and may change in future versions.

Handle Management

Data Store Operations ⚠️ Legacy API

Request parsing, response creation, and error handling utilities for data store interactions. These APIs are only available through the legacy import path and may change in future versions.

Legacy/Beta API (@fluidframework/runtime-utils/legacy):

function create404Response(request: IRequest): IResponse;

class RequestParser implements IRequest {
  static create(request: Readonly<IRequest>): RequestParser;
  static getPathParts(url: string): readonly string[];
  createSubRequest(startingPathIndex: number): IRequest;
  isLeaf(elements: number): boolean;
}

Note: Additional functions like createResponseError and generateHandleContextPath are not exported in the current API surface.

Data Store Operations

Storage Utilities ❌ Internal API

Utilities for working with object storage, blob handling, and snapshot tree operations. These APIs are not exported in the public or legacy API surfaces and are for internal use only.

Note: Functions like ObjectStoragePartition, getNormalizedObjectStoragePathParts, and listBlobsAtTreePath are not available for external consumption.

Storage Utilities

Summary Management ⚠️ Legacy API

Tools for building, converting, and managing summary trees with statistics tracking. These APIs are only available through the legacy import path and may change in future versions.

Legacy/Beta API (@fluidframework/runtime-utils/legacy):

class SummaryTreeBuilder implements ISummaryTreeWithStats {
  constructor(params?: { groupId?: string });
  addBlob(key: string, content: string | Uint8Array): void;
  addHandle(
    key: string, 
    handleType: SummaryType.Tree | SummaryType.Blob | SummaryType.Attachment, 
    handle: string
  ): void;
  addWithStats(key: string, summarizeResult: ISummarizeResult): void;
  getSummaryTree(): ISummaryTreeWithStats;
}

function convertToSummaryTreeWithStats(
  snapshot: ITree, 
  fullTree?: boolean
): ISummaryTreeWithStats;

Note: Additional functions like mergeStats, addBlobToSummary, etc. are not exported in the current API surface.

Summary Management

Runtime Factories ⚠️ Legacy API

Abstract base classes and helpers for implementing container runtime factories with standardized lifecycle management. These APIs are only available through the legacy import path and may change in future versions.

Legacy/Beta API (@fluidframework/runtime-utils/legacy):

abstract class RuntimeFactoryHelper<T = IContainerRuntime> implements IRuntimeFactory {
  abstract preInitialize(
    context: IContainerContext, 
    existing: boolean
  ): Promise<IRuntime & T>;
  instantiateRuntime(context: IContainerContext, existing: boolean): Promise<IRuntime>;
  instantiateFirstTime(runtime: T): Promise<void>;
  instantiateFromExisting(runtime: T): Promise<void>;
  hasInitialized(runtime: T): Promise<void>;
}

Runtime Factories

Compatibility Management ❌ Internal API

Version validation and configuration utilities for ensuring proper collaboration across different client versions. These APIs are not exported in the public or legacy API surfaces and are for internal use only.

Note: Functions like isValidMinVersionForCollab, getConfigsForMinVersionForCollab, and related types are not available for external consumption.

Compatibility Management

Garbage Collection ❌ Internal API

Tools for building and managing garbage collection data structures to track object references in distributed Fluid applications. These APIs are not exported in the public or legacy API surfaces and are for internal use only.

Note: Classes like GCDataBuilder and functions like processAttachMessageGCData, unpackChildNodesUsedRoutes are not available for external consumption.

Garbage Collection

Telemetry and Utilities ❌ Internal API

Telemetry context management and general utilities for runtime operations including ID encoding and sequence number extraction. These APIs are not exported in the public or legacy API surfaces and are for internal use only.

Note: Classes like TelemetryContext, enums like RuntimeHeaders, and utility functions like encodeCompactIdToString, seqFromTree are not available for external consumption.

Telemetry and Utilities