Core utilities for working with Fluid object handles including comparison and type guards. These utilities are essential for inter-component communication in Fluid applications.
⚠️ Important: This package has a very limited public API surface for handle management. Most handle utilities are available only through legacy APIs that may change in future versions.
The stable public API provides only basic handle identification and comparison functionality.
/**
* Check if a value is an IFluidHandle with backward compatibility support
* @param value - The value to check
* @returns True if the value is a valid IFluidHandle
*/
function isFluidHandle(value: unknown): value is IFluidHandle;
/**
* Compare two IFluidHandles by their internal absolutePath
* @param a - First handle to compare
* @param b - Second handle to compare
* @returns True if both handles have the same internal absolutePath
*/
function compareFluidHandles(a: IFluidHandle, b: IFluidHandle): boolean;Usage Example:
import { isFluidHandle, compareFluidHandles } from "@fluidframework/runtime-utils";
// Type checking
if (isFluidHandle(someValue)) {
console.log("Found a Fluid handle");
}
// Handle comparison
const areEqual = compareFluidHandles(handle1, handle2);Warning: The following APIs are available through @fluidframework/runtime-utils/legacy but are marked as legacy/beta and may change or be removed in future versions.
/**
* Check if the handle is an IFluidHandlePayloadPending
*/
function isFluidHandlePayloadPending<T>(
handle: IFluidHandle<T>
): handle is IFluidHandlePayloadPending<T>;
/**
* Check if the handle is an ILocalFluidHandle
*/
function isLocalFluidHandle<T>(
handle: IFluidHandle<T>
): handle is ILocalFluidHandle<T>;/**
* Downcast an IFluidHandle to an IFluidHandleInternal
*/
function toFluidHandleInternal<T>(handle: IFluidHandle<T>): IFluidHandleInternal<T>;
/**
* Type erase IFluidHandleInternal for use with fluidHandleSymbol
*/
function toFluidHandleErased<T>(
handle: IFluidHandleInternal<T>
): IFluidHandleErased<T>;/**
* Base class which can be used to assist implementing IFluidHandleInternal
*/
abstract class FluidHandleBase<T> implements IFluidHandleInternal<T> {
abstract absolutePath: string;
abstract readonly isAttached: boolean;
abstract attachGraph(): void;
abstract get(): Promise<T>;
get IFluidHandle(): IFluidHandleInternal;
get [fluidHandleSymbol](): IFluidHandleErased<T>;
}Legacy API Usage Example:
import {
isFluidHandlePayloadPending,
toFluidHandleInternal,
FluidHandleBase
} from "@fluidframework/runtime-utils/legacy";
// Using legacy type guards
if (isFluidHandlePayloadPending(handle)) {
console.log("Handle has pending payload");
}
// Using legacy type conversion
const internalHandle = toFluidHandleInternal(handle);Note: The following APIs are mentioned in the source code but are not exported and not available for external use:
encodeHandleForSerialization - Internal serialization utilityisSerializedHandle - Internal serialization type guardRemoteFluidObjectHandle - Internal remote handle implementationisFluidHandleInternalPayloadPending - Internal type guardThese APIs are for internal framework use only and should not be relied upon by external applications.
If you're using handle management utilities:
The limited public API surface suggests that most handle management should be done through other Fluid Framework packages rather than directly using runtime-utils.