@fluidframework/runtime-utils 2.0.0-dev-rc.3.0.0.254866 → 2.0.0-dev-rc.5.0.0.263932

package/src/handles.ts

@@ -3,6 +3,12 @@
  * Licensed under the MIT License.
  */
 
+import type {
+	IFluidHandleErased,
+	IFluidHandleInternal,
+} from "@fluidframework/core-interfaces/internal";
+import { IFluidHandle, fluidHandleSymbol } from "@fluidframework/core-interfaces";
+
 /**
  * JSON serialized form of an IFluidHandle
  * @internal
@@ -21,3 +27,89 @@ export interface ISerializedHandle {
  */
 export const isSerializedHandle = (value: any): value is ISerializedHandle =>
 	value?.type === "__fluid_handle__";
+
+/**
+ * Setting to opt into compatibility with handles from before {@link fluidHandleSymbol} existed (Fluid Framework client 2.0.0-rc.3.0.0 and earlier).
+ *
+ * Some code which uses this library might dynamically load multiple versions of it,
+ * as well as old or duplicated versions of packages which produce or implement handles.
+ * To correctly interoperate with this old packages and object produced by them, the old in-memory format for handles, without the symbol, are explicitly supported.
+ *
+ * This setting mostly exists as a way to easily find any code that only exists to provide this compatibility and clarify how to remove that compatibility.
+ * At some point this might be removed or turned into an actual configuration option, but for now its really just documentation.
+ */
+const enableBackwardsCompatibility = true;
+
+/**
+ * Check if a value is an IFluidHandle.
+ * @remarks
+ * Objects which have a field named `IFluidHandle` can in some cases produce a false positive.
+ * @internal
+ */
+export function isFluidHandle(value: unknown): value is IFluidHandle {
+	// `in` gives a type error on non-objects and null, so filter them out
+	if (typeof value !== "object" || value === null) {
+		return false;
+	}
+	if (fluidHandleSymbol in value) {
+		return true;
+	}
+	// If enableBackwardsCompatibility, run check for FluidHandles predating use of fluidHandleSymbol.
+	if (enableBackwardsCompatibility && IFluidHandle in value) {
+		// Since this check can have false positives, make it a bit more robust by checking value[IFluidHandle][IFluidHandle]
+		const inner = value[IFluidHandle] as IFluidHandle;
+		if (typeof inner !== "object" || inner === null) {
+			return false;
+		}
+		return IFluidHandle in inner;
+	}
+	return false;
+}
+
+/**
+ * Downcast an IFluidHandle to an IFluidHandleInternal.
+ * @alpha
+ */
+export function toFluidHandleInternal<T>(handle: IFluidHandle<T>): IFluidHandleInternal<T> {
+	if (!(fluidHandleSymbol in handle) || !(fluidHandleSymbol in handle[fluidHandleSymbol])) {
+		if (enableBackwardsCompatibility && IFluidHandle in handle) {
+			return handle[IFluidHandle] as IFluidHandleInternal<T>;
+		}
+		throw new TypeError("Invalid IFluidHandle");
+	}
+
+	// This casts the IFluidHandleErased from the symbol instead of `handle` to ensure that if someone
+	// implements their own IFluidHandle in terms of an existing handle, it won't break anything.
+	return handle[fluidHandleSymbol] as unknown as IFluidHandleInternal<T>;
+}
+
+/**
+ * Type erase IFluidHandleInternal for use with {@link @fluidframework/core-interfaces#fluidHandleSymbol}.
+ * @alpha
+ */
+export function toFluidHandleErased<T>(handle: IFluidHandleInternal<T>): IFluidHandleErased<T> {
+	return handle as unknown as IFluidHandleErased<T>;
+}
+
+/**
+ * Base class which can be uses to assist implementing IFluidHandleInternal.
+ * @alpha
+ */
+export abstract class FluidHandleBase<T> implements IFluidHandleInternal<T> {
+	public abstract absolutePath: string;
+	public abstract attachGraph(): void;
+	public abstract bind(handle: IFluidHandleInternal): void;
+	public abstract readonly isAttached: boolean;
+	public abstract get(): Promise<T>;
+
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#IProvideFluidHandle.IFluidHandle}
+	 */
+	public get IFluidHandle(): IFluidHandleInternal {
+		return this;
+	}
+
+	public get [fluidHandleSymbol](): IFluidHandleErased<T> {
+		return toFluidHandleErased(this);
+	}
+}

package/src/index.ts

@@ -12,7 +12,14 @@ export {
 	Factory,
 	responseToException,
 } from "./dataStoreHelpers.js";
-export { ISerializedHandle, isSerializedHandle } from "./handles.js";
+export {
+	ISerializedHandle,
+	isSerializedHandle,
+	isFluidHandle,
+	toFluidHandleErased,
+	toFluidHandleInternal,
+	FluidHandleBase,
+} from "./handles.js";
 export { ObjectStoragePartition } from "./objectstoragepartition.js";
 export { getNormalizedObjectStoragePathParts, listBlobsAtTreePath } from "./objectstorageutils.js";
 export { RequestParser } from "./requestParser.js";
@@ -35,3 +42,5 @@ export {
 } from "./summaryUtils.js";
 export { unpackChildNodesUsedRoutes } from "./unpackUsedRoutes.js";
 export { ReadAndParseBlob, seqFromTree, encodeCompactIdToString } from "./utils.js";
+export { isSnapshotFetchRequiredForLoadingGroupId } from "./snapshotUtils.js";
+export { toDeltaManagerErased, toDeltaManagerInternal } from "./deltaManager.js";

package/src/snapshotUtils.ts

@@ -0,0 +1,38 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { ISnapshotTree } from "@fluidframework/protocol-definitions";
+
+/**
+ * Utility function to check if any blobs under a snapshot tree is missing and if so, then return
+ * true if that is the case.
+ * @internal
+ * @param snapshotTree - snapshotTree to be evaluated for missing blobs.
+ * @param blobContents - blobContents of the snapshot.
+ */
+export function isSnapshotFetchRequiredForLoadingGroupId(
+	snapshotTree: ISnapshotTree,
+	blobContents: Map<string, ArrayBuffer>,
+): boolean {
+	for (const [_, id] of Object.entries(snapshotTree.blobs)) {
+		if (!blobContents.has(id)) {
+			return true;
+		}
+	}
+	for (const [_, childTree] of Object.entries(snapshotTree.trees)) {
+		// Only evaluate childTree if it does not have a loading groupId because if the childTree has a loading
+		// groupId then it will be evaluated whether we want to fetch blobs for that childTree or not when
+		// that particular childTree is getting realized. Now we just want to check for blobs which belongs to
+		// tree with current loading groupId. Note: Child with no loading groupId, will fall under parent with
+		// a loading groupId as it does not have its own loading groupId.
+		if (childTree.groupId === undefined) {
+			const value = isSnapshotFetchRequiredForLoadingGroupId(childTree, blobContents);
+			if (value) {
+				return true;
+			}
+		}
+	}
+	return false;
+}