@fluidframework/runtime-utils 2.53.1 → 2.61.0-355054

package/src/dataStoreHelpers.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { IRequest, IResponse } from "@fluidframework/core-interfaces";
+import type { IRequest, IResponse } from "@fluidframework/core-interfaces";
 import { assert } from "@fluidframework/core-utils/internal";
 import { generateErrorWithStack } from "@fluidframework/telemetry-utils/internal";
 
@@ -12,53 +12,76 @@ interface IResponseException extends Error {
 	message: string;
 	code: number;
 	stack?: string;
-	underlyingResponseHeaders?: { [key: string]: any };
+	underlyingResponseHeaders?: Record<string, unknown>;
 }
 
 /**
+ * Type guard for determining if an error is an {@link IResponseException}.
  * @internal
  */
-export function exceptionToResponse(err: any): IResponse {
+function isResponseException(err: unknown): err is IResponseException {
+	return (
+		err !== null &&
+		typeof err === "object" &&
+		"errorFromRequestFluidObject" in err &&
+		(err as { errorFromRequestFluidObject: unknown }).errorFromRequestFluidObject === true
+	);
+}
+
+/**
+ * Converts an error object into an {@link @fluidframework/core-interfaces#IResponse}.
+ * @internal
+ */
+export function exceptionToResponse(error: unknown): IResponse {
 	const status = 500;
-	if (err !== null && typeof err === "object" && err.errorFromRequestFluidObject === true) {
-		const responseErr: IResponseException = err;
+	if (isResponseException(error)) {
 		return {
 			mimeType: "text/plain",
-			status: responseErr.code,
-			value: responseErr.message,
+			status: error.code,
+			value: error.message,
 			get stack() {
-				return responseErr.stack;
+				return error.stack;
 			},
-			headers: responseErr.underlyingResponseHeaders,
+			headers: error.underlyingResponseHeaders,
 		};
 	}
 
-	// Capture error objects, not stack itself, as stack retrieval is very expensive operation, so we delay it
-	const errWithStack = generateErrorWithStack();
+	// Both error generation, and accessing the stack value are expensive operations, so we only create an error if necessary, and then defer accessing the stack value until it is needed.
+	const errWithStack =
+		typeof error === "object" && error !== null && "stack" in error
+			? (error as { stack: string })
+			: generateErrorWithStack();
 
 	return {
 		mimeType: "text/plain",
 		status,
-		value: `${err}`,
+		value: `${error}`,
 		get stack() {
-			return (err?.stack as string | undefined) ?? errWithStack.stack;
+			return errWithStack.stack;
 		},
 	};
 }
 
 /**
+ * Converts an {@link @fluidframework/core-interfaces#IResponse} back into an Error object that can be thrown.
+ * @param response - The {@link @fluidframework/core-interfaces#IResponse} to convert.
+ * @param request - The original {@link @fluidframework/core-interfaces#IRequest}.
+ * @returns An Error object with additional properties from the response
  * @internal
  */
 export function responseToException(response: IResponse, request: IRequest): Error {
-	const message = response.value;
-	const errWithStack = generateErrorWithStack();
+	// As of 2025-08-20 the code seems to assume `response.value` is always a string.
+	// This type assertion just encodes that assumption as we move to stricter linting rules, but it might need to be revisited.
+	const message = response.value as string;
+	// Both error generation, and accessing the stack value are expensive operations, so we only create an error if necessary, and then defer accessing the stack value until it is needed.
+	const errWithStack = "stack" in response ? response : generateErrorWithStack();
 	const responseErr: Error & IResponseException = {
 		errorFromRequestFluidObject: true,
 		message,
 		name: "Error",
 		code: response.status,
 		get stack() {
-			return response.stack ?? errWithStack.stack;
+			return errWithStack.stack;
 		},
 		underlyingResponseHeaders: response.headers,
 	};
@@ -67,26 +90,35 @@ export function responseToException(response: IResponse, request: IRequest): Err
 }
 
 /**
+ * Creates a 404 "not found" response for the given request
+ * @param request - The request that resulted in the 404 response
+ * @returns An {@link @fluidframework/core-interfaces#IResponse} with 404 status code.
  * @legacy
- * @alpha
+ * @beta
  */
-export const create404Response = (request: IRequest) =>
+export const create404Response = (request: IRequest): IResponse =>
 	createResponseError(404, "not found", request);
 
 /**
+ * Creates an error response with the specified status code and message
+ * @param status - HTTP status code for the error (must not be 200)
+ * @param value - Error message or description
+ * @param request - The request that resulted in this error
+ * @param headers - Optional headers to include in the response
+ * @returns An {@link @fluidframework/core-interfaces#IResponse} representing the error
  * @internal
  */
 export function createResponseError(
 	status: number,
 	value: string,
 	request: IRequest,
-	headers?: { [key: string]: any },
+	headers?: Record<string, unknown>,
 ): IResponse {
 	assert(status !== 200, 0x19b /* "Cannot not create response error on 200 status" */);
 	// Omit query string which could contain personal data unfit for logging
 	const urlNoQuery = request.url?.split("?")[0];
 
-	// Capture error objects, not stack itself, as stack retrieval is very expensive operation, so we delay it
+	// Both error generation, and accessing the stack value are expensive operations, so we only create an error if necessary, and then defer accessing the stack value until it is needed.
 	const errWithStack = generateErrorWithStack();
 
 	return {

package/src/deltaManager.ts

@@ -13,12 +13,12 @@ import type {
 /**
  * Casts the public API for delta manager into the internal one,
  * exposing access to APIs needed by the implementation of Fluid Framework but not its users.
- * @legacy
- * @alpha
+ * @legacy @beta
  */
 export function toDeltaManagerInternal(
 	deltaManager: IDeltaManagerErased,
 ): IDeltaManager<ISequencedDocumentMessage, IDocumentMessage> {
+	// Type assertion is safe as IDeltaManagerErased is specifically designed to be a type-erased version of IDeltaManager
 	return deltaManager as unknown as IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
 }
 
@@ -29,5 +29,6 @@ export function toDeltaManagerInternal(
 export function toDeltaManagerErased(
 	deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>,
 ): IDeltaManagerErased {
+	// Type assertion is safe as we're intentionally erasing the type information for public API safety
 	return deltaManager as unknown as IDeltaManagerErased;
 }

package/src/handles.ts

@@ -36,13 +36,15 @@ export interface ISerializedHandle {
 }
 
 /**
- * Is the input object a @see ISerializedHandle?
+ * Narrow a value to {@link ISerializedHandle} by checking its type property.
  * @internal
  */
-export const isSerializedHandle = (value: any): value is ISerializedHandle =>
-	value?.type === "__fluid_handle__";
+export const isSerializedHandle = (value: unknown): value is ISerializedHandle =>
+	// Type assertion is safe as we're only checking for the existence of the type property
+	(value as { type?: string } | undefined)?.type === "__fluid_handle__";
 
 /**
+ * Checks if a Fluid handle's internal payload is pending.
  * @internal
  */
 export const isFluidHandleInternalPayloadPending = (
@@ -55,8 +57,7 @@ export const isFluidHandleInternalPayloadPending = (
  * @privateRemarks
  * This should be true for locally-created BlobHandles currently. When IFluidHandlePayloadPending is merged
  * to IFluidHandle, this type guard will no longer be necessary.
- * @legacy
- * @alpha
+ * @legacy @beta
  */
 export const isFluidHandlePayloadPending = <T>(
 	handle: IFluidHandle<T>,
@@ -66,8 +67,7 @@ export const isFluidHandlePayloadPending = <T>(
 
 /**
  * Check if the handle is an ILocalFluidHandle.
- * @legacy
- * @alpha
+ * @legacy @beta
  */
 export const isLocalFluidHandle = <T>(
 	handle: IFluidHandle<T>,
@@ -122,6 +122,7 @@ export function isFluidHandle(value: unknown): value is IFluidHandle {
 	// 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]
+		// Type assertion is needed for backward compatibility with old FluidHandle format
 		const inner = value[IFluidHandle] as IFluidHandle;
 		if (typeof inner !== "object" || inner === null) {
 			return false;
@@ -145,12 +146,12 @@ export function compareFluidHandles(a: IFluidHandle, b: IFluidHandle): boolean {
 
 /**
  * Downcast an IFluidHandle to an IFluidHandleInternal.
- * @legacy
- * @alpha
+ * @legacy @beta
  */
 export function toFluidHandleInternal<T>(handle: IFluidHandle<T>): IFluidHandleInternal<T> {
 	if (!(fluidHandleSymbol in handle) || !(fluidHandleSymbol in handle[fluidHandleSymbol])) {
 		if (enableBackwardsCompatibility && IFluidHandle in handle) {
+			// Type assertion needed for backward compatibility with old handle format
 			return handle[IFluidHandle] as IFluidHandleInternal<T>;
 		}
 		throw new TypeError("Invalid IFluidHandle");
@@ -158,24 +159,24 @@ export function toFluidHandleInternal<T>(handle: IFluidHandle<T>): IFluidHandleI
 
 	// 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.
+	// Type assertion is safe as fluidHandleSymbol is guaranteed to contain an IFluidHandleInternal
 	return handle[fluidHandleSymbol] as unknown as IFluidHandleInternal<T>;
 }
 
 /**
  * Type erase IFluidHandleInternal for use with {@link @fluidframework/core-interfaces#fluidHandleSymbol}.
- * @legacy
- * @alpha
+ * @legacy @beta
  */
 export function toFluidHandleErased<T>(
 	handle: IFluidHandleInternal<T>,
 ): IFluidHandleErased<T> {
+	// Type assertion is safe as we're intentionally erasing internal type information
 	return handle as unknown as IFluidHandleErased<T>;
 }
 
 /**
  * Base class which can be uses to assist implementing IFluidHandleInternal.
- * @legacy
- * @alpha
+ * @legacy @beta
  */
 export abstract class FluidHandleBase<T> implements IFluidHandleInternal<T> {
 	public abstract absolutePath: string;

package/src/index.ts

@@ -14,7 +14,6 @@ export {
 	compareFluidHandles,
 	encodeHandleForSerialization,
 	FluidHandleBase,
-	ISerializedHandle,
 	isFluidHandle,
 	isFluidHandleInternalPayloadPending,
 	isFluidHandlePayloadPending,
@@ -23,6 +22,7 @@ export {
 	toFluidHandleErased,
 	toFluidHandleInternal,
 } from "./handles.js";
+export type { ISerializedHandle } from "./handles.js";
 export { ObjectStoragePartition } from "./objectstoragepartition.js";
 export {
 	getNormalizedObjectStoragePathParts,
@@ -49,24 +49,26 @@ export {
 } from "./summaryUtils.js";
 export { unpackChildNodesUsedRoutes } from "./unpackUsedRoutes.js";
 export {
-	ReadAndParseBlob,
 	RuntimeHeaders,
 	seqFromTree,
 	encodeCompactIdToString,
 } from "./utils.js";
+export type { ReadAndParseBlob } from "./utils.js";
 export { isSnapshotFetchRequiredForLoadingGroupId } from "./snapshotUtils.js";
 export {
 	toDeltaManagerErased,
 	toDeltaManagerInternal,
 } from "./deltaManager.js";
 export {
-	ConfigMap,
 	configValueToMinVersionForCollab,
-	ConfigValidationMap,
 	defaultMinVersionForCollab,
 	getValidationForRuntimeOptions,
 	getConfigsForMinVersionForCollab,
 	isValidMinVersionForCollab,
+} from "./compatibilityBase.js";
+export type {
+	ConfigMap,
+	ConfigValidationMap,
 	MinimumMinorSemanticVersion,
 	SemanticVersion,
 } from "./compatibilityBase.js";

package/src/objectstoragepartition.ts

@@ -4,14 +4,14 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
+import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 
 /**
  * Returns a new IChannelStorageService that resolves the given `path` as root.
  * @internal
  */
 export class ObjectStoragePartition implements IChannelStorageService {
-	constructor(
+	public constructor(
 		private readonly storage: IChannelStorageService,
 		private readonly path: string,
 	) {

package/src/objectstorageutils.ts

@@ -3,18 +3,22 @@
  * Licensed under the MIT License.
  */
 
-import { ITree } from "@fluidframework/driver-definitions/internal";
+import type { ITree } from "@fluidframework/driver-definitions/internal";
+import { TreeEntry } from "@fluidframework/driver-definitions/internal";
 
 /**
+ * Normalizes a storage path by removing leading and trailing slashes and splitting into parts
+ * @param path - The storage path to normalize (e.g. "/foo/bar/")
+ * @returns Array of path segments (e.g. ["foo", "bar"])
  * @internal
  */
-export function getNormalizedObjectStoragePathParts(path: string) {
+export function getNormalizedObjectStoragePathParts(path: string): string[] {
 	let normalizePath = path;
 	if (normalizePath.startsWith("/")) {
-		normalizePath = normalizePath.substr(1);
+		normalizePath = normalizePath.slice(1);
 	}
 	if (normalizePath.endsWith("/")) {
-		normalizePath = normalizePath.substr(0, normalizePath.length - 1);
+		normalizePath = normalizePath.slice(0, -1);
 	}
 	if (normalizePath.length > 0) {
 		return normalizePath.split("/");
@@ -23,6 +27,11 @@ export function getNormalizedObjectStoragePathParts(path: string) {
 }
 
 /**
+ * Lists all blobs at the specified path in the given tree
+ * @param inputTree - The tree to search within
+ * @param path - The path to search at (e.g. "foo/bar")
+ * @returns Promise that resolves to an array of blob names at that path
+ * @throws Error if the path does not exist in the tree
  * @internal
  */
 export async function listBlobsAtTreePath(
@@ -34,16 +43,16 @@ export async function listBlobsAtTreePath(
 	while (tree?.entries !== undefined && pathParts.length > 0) {
 		const part = pathParts.shift();
 		const treeEntry = tree.entries.find((value) => {
-			return value.type === "Tree" && value.path === part ? true : false;
+			return value.type === TreeEntry.Tree && value.path === part ? true : false;
 		});
 
 		// this check is largely superfluous due to the same check being done
 		// immediately above. the type system, however, is not aware of this.
 		// so we must redundantly determine that the entry's type is "Tree"
-		tree = treeEntry?.type === "Tree" ? treeEntry.value : undefined;
+		tree = treeEntry?.type === TreeEntry.Tree ? treeEntry.value : undefined;
 	}
-	if (tree?.entries === undefined || pathParts.length !== 0) {
+	if (tree?.entries === undefined || pathParts.length > 0) {
 		throw new Error("path does not exist");
 	}
-	return tree.entries.filter((e) => e.type === "Blob").map((e) => e.path);
+	return tree.entries.filter((e) => e.type === TreeEntry.Blob).map((e) => e.path);
 }

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/runtime-utils";
-export const pkgVersion = "2.53.1";
+export const pkgVersion = "2.61.0-355054";

package/src/remoteFluidObjectHandle.ts

@@ -3,8 +3,8 @@
  * Licensed under the MIT License.
  */
 
-import { FluidObject, IRequest } from "@fluidframework/core-interfaces";
-import { IFluidHandleContext } from "@fluidframework/core-interfaces/internal";
+import type { FluidObject, IRequest } from "@fluidframework/core-interfaces";
+import type { IFluidHandleContext } from "@fluidframework/core-interfaces/internal";
 import { assert } from "@fluidframework/core-utils/internal";
 
 import { responseToException } from "./dataStoreHelpers.js";
@@ -30,7 +30,7 @@ export class RemoteFluidObjectHandle extends FluidHandleBase<FluidObject> {
 	 * @param routeContext - The root IFluidHandleContext that has a route to this handle.
 	 * @param payloadPending - Whether the handle may have a pending payload that is not yet available.
 	 */
-	constructor(
+	public constructor(
 		public readonly absolutePath: string,
 		public readonly routeContext: IFluidHandleContext,
 		public readonly payloadPending: boolean,
@@ -54,6 +54,7 @@ export class RemoteFluidObjectHandle extends FluidHandleBase<FluidObject> {
 			};
 			this.objectP = this.routeContext.resolveHandle(request).then<FluidObject>((response) => {
 				if (response.mimeType === "fluid/object") {
+					// Responses with mimeType == "fluid/object" are produced by Fluid, and thus they can reasonably be expected to always be a FluidObject
 					const fluidObject: FluidObject = response.value as FluidObject;
 					return fluidObject;
 				}

package/src/requestParser.ts

@@ -3,12 +3,11 @@
  * Licensed under the MIT License.
  */
 
-import { IRequest, IRequestHeader } from "@fluidframework/core-interfaces";
+import type { IRequest, IRequestHeader } from "@fluidframework/core-interfaces";
 
 /**
  * The Request Parser takes an IRequest provides parsing and sub request creation
- * @legacy
- * @alpha
+ * @legacy @beta
  */
 export class RequestParser implements IRequest {
 	/**
@@ -17,21 +16,22 @@ export class RequestParser implements IRequest {
 	 */
 	public static getPathParts(url: string): readonly string[] {
 		const queryStartIndex = url.indexOf("?");
-		return url
-			.substring(0, queryStartIndex < 0 ? url.length : queryStartIndex)
-			.split("/")
-			.reduce<string[]>((pv, cv) => {
-				if (cv !== undefined && cv.length > 0) {
-					pv.push(decodeURIComponent(cv));
-				}
-				return pv;
-			}, []);
+		const pathParts: string[] = [];
+		const urlPath = url.slice(0, queryStartIndex < 0 ? url.length : queryStartIndex);
+
+		for (const part of urlPath.split("/")) {
+			if (part !== undefined && part.length > 0) {
+				pathParts.push(decodeURIComponent(part));
+			}
+		}
+
+		return pathParts;
 	}
 
 	private requestPathParts: readonly string[] | undefined;
 	public readonly query: string;
 
-	public static create(request: Readonly<IRequest>) {
+	public static create(request: Readonly<IRequest>): RequestParser {
 		// Perf optimizations.
 		if (request instanceof RequestParser) {
 			return request;
@@ -41,7 +41,7 @@ export class RequestParser implements IRequest {
 
 	protected constructor(private readonly request: Readonly<IRequest>) {
 		const queryStartIndex = this.request.url.indexOf("?");
-		this.query = queryStartIndex >= 0 ? this.request.url.substring(queryStartIndex) : "";
+		this.query = queryStartIndex >= 0 ? this.request.url.slice(queryStartIndex) : "";
 		if (request.headers !== undefined) {
 			this.headers = request.headers;
 		}
@@ -67,7 +67,7 @@ export class RequestParser implements IRequest {
 	 * Returns true if it's a terminating path, i.e. no more elements after `elements` entries and empty query.
 	 * @param elements - number of elements in path
 	 */
-	public isLeaf(elements: number) {
+	public isLeaf(elements: number): boolean {
 		return this.query === "" && this.pathParts.length === elements;
 	}
 

package/src/runtimeFactoryHelper.ts

@@ -3,19 +3,18 @@
  * Licensed under the MIT License.
  */
 
-import {
+import type {
 	IContainerContext,
 	IRuntime,
 	IRuntimeFactory,
 } from "@fluidframework/container-definitions/internal";
-import { IContainerRuntime } from "@fluidframework/container-runtime-definitions/internal";
+import type { IContainerRuntime } from "@fluidframework/container-runtime-definitions/internal";
 
 /**
- * @legacy
- * @alpha
+ * @legacy @beta
  */
 export abstract class RuntimeFactoryHelper<T = IContainerRuntime> implements IRuntimeFactory {
-	public get IRuntimeFactory() {
+	public get IRuntimeFactory(): this {
 		return this;
 	}