@fluidframework/driver-utils 2.0.0-internal.7.0.0 → 2.0.0-internal.7.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/driver-utils",
-  "version": "2.0.0-internal.7.0.0",
+  "version": "2.0.0-internal.7.2.0",
   "description": "Collection of utility functions for Fluid drivers",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -35,39 +35,38 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": ">=2.0.0-internal.7.0.0 <2.0.0-internal.7.1.0",
-    "@fluidframework/core-interfaces": ">=2.0.0-internal.7.0.0 <2.0.0-internal.7.1.0",
-    "@fluidframework/core-utils": ">=2.0.0-internal.7.0.0 <2.0.0-internal.7.1.0",
-    "@fluidframework/driver-definitions": ">=2.0.0-internal.7.0.0 <2.0.0-internal.7.1.0",
+    "@fluid-internal/client-utils": ">=2.0.0-internal.7.2.0 <2.0.0-internal.7.3.0",
+    "@fluidframework/core-interfaces": ">=2.0.0-internal.7.2.0 <2.0.0-internal.7.3.0",
+    "@fluidframework/core-utils": ">=2.0.0-internal.7.2.0 <2.0.0-internal.7.3.0",
+    "@fluidframework/driver-definitions": ">=2.0.0-internal.7.2.0 <2.0.0-internal.7.3.0",
     "@fluidframework/gitresources": "^2.0.1",
     "@fluidframework/protocol-base": "^2.0.1",
     "@fluidframework/protocol-definitions": "^3.0.0",
-    "@fluidframework/telemetry-utils": ">=2.0.0-internal.7.0.0 <2.0.0-internal.7.1.0",
+    "@fluidframework/telemetry-utils": ">=2.0.0-internal.7.2.0 <2.0.0-internal.7.3.0",
     "axios": "^0.26.0",
     "lz4js": "^0.2.0",
     "url": "^0.11.0",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@fluid-tools/build-cli": "^0.24.0",
-    "@fluidframework/build-common": "^2.0.0",
-    "@fluidframework/build-tools": "^0.24.0",
-    "@fluidframework/driver-utils-previous": "npm:@fluidframework/driver-utils@2.0.0-internal.6.3.0",
-    "@fluidframework/eslint-config-fluid": "^2.1.0",
-    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.7.0.0 <2.0.0-internal.7.1.0",
+    "@fluid-tools/build-cli": "^0.26.1",
+    "@fluidframework/build-common": "^2.0.3",
+    "@fluidframework/build-tools": "^0.26.1",
+    "@fluidframework/driver-utils-previous": "npm:@fluidframework/driver-utils@2.0.0-internal.7.1.0",
+    "@fluidframework/eslint-config-fluid": "^3.0.0",
+    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.7.2.0 <2.0.0-internal.7.3.0",
     "@microsoft/api-extractor": "^7.37.0",
     "@types/mocha": "^9.1.1",
     "@types/node": "^16.18.38",
     "@types/sinon": "^7.0.13",
     "c8": "^7.7.1",
-    "copyfiles": "^2.4.1",
     "cross-env": "^7.0.3",
-    "eslint": "~8.6.0",
+    "eslint": "~8.50.0",
     "mocha": "^10.2.0",
     "mocha-json-output-reporter": "^2.0.1",
     "mocha-multi-reporters": "^1.5.1",
     "moment": "^2.21.0",
-    "prettier": "~2.6.2",
+    "prettier": "~3.0.3",
     "rimraf": "^4.4.0",
     "sinon": "^7.4.2",
     "typescript": "~5.1.6"
@@ -79,12 +78,12 @@
     "build": "fluid-build . --task build",
     "build:commonjs": "fluid-build . --task commonjs",
     "build:compile": "fluid-build . --task compile",
-    "build:docs": "api-extractor run --local --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/doc-models/* ../../../_api-extractor-temp/",
+    "build:docs": "api-extractor run --local",
     "build:esnext": "tsc --project ./tsconfig.esnext.json",
     "build:genver": "gen-version",
     "build:test": "tsc --project ./src/test/tsconfig.json",
-    "ci:build:docs": "api-extractor run --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/* ../../../_api-extractor-temp/",
-    "clean": "rimraf --glob 'dist' 'lib' '*.tsbuildinfo' '*.build.log' '_api-extractor-temp' 'nyc'",
+    "ci:build:docs": "api-extractor run",
+    "clean": "rimraf --glob dist lib \"*.tsbuildinfo\" \"*.build.log\" _api-extractor-temp nyc",
     "eslint": "eslint --format stylish src",
     "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
     "format": "npm run prettier:fix",

package/src/adapters/compression/compressionTypes.ts

@@ -3,11 +3,17 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * @public
+ */
 export enum SummaryCompressionAlgorithm {
 	None = 0,
 	LZ4 = 1,
 }
 
+/**
+ * @public
+ */
 export interface ICompressionStorageConfig {
 	algorithm: SummaryCompressionAlgorithm;
 	minSizeToCompress: number;

package/src/adapters/compression/documentServiceCompressionAdapter.ts

@@ -9,7 +9,10 @@ import { DocumentStorageServiceCompressionAdapter as DocumentStorageServiceSumma
 import { ICompressionStorageConfig } from "./compressionTypes";
 
 export class DocumentServiceCompressionAdapter extends DocumentServiceProxy {
-	constructor(service: IDocumentService, private readonly _config: ICompressionStorageConfig) {
+	constructor(
+		service: IDocumentService,
+		private readonly _config: ICompressionStorageConfig,
+	) {
 		super(service);
 	}
 

package/src/adapters/compression/summaryblob/documentStorageServiceSummaryBlobCompressionAdapter.ts

@@ -19,6 +19,9 @@ import { compress, decompress } from "lz4js";
 import { DocumentStorageServiceProxy } from "../../../documentStorageServiceProxy";
 import { ICompressionStorageConfig, SummaryCompressionAlgorithm } from "../";
 
+/**
+ * @public
+ */
 export const blobHeadersBlobName = ".metadata.blobHeaders";
 const metadataBlobName = ".metadata";
 
@@ -32,6 +35,7 @@ const metadataBlobName = ".metadata";
  * In case, the markup blob is present, it is expected that the first byte of the markup blob
  * will contain the info about the compression. If the first byte is not present, it is assumed
  * that the compression is not enabled and no first prefix byte is present in the blobs.
+ * @public
  */
 export class DocumentStorageServiceCompressionAdapter extends DocumentStorageServiceProxy {
 	private _isCompressionEnabled: boolean = false;

package/src/adapters/predefinedAdapters.ts

@@ -17,6 +17,7 @@ import {
  * @param documentServiceFactory - The document service factory to apply compression to.
  * @param config - The compression configuration.
  * @returns The document service factory possibly with compression applied.
+ * @public
  */
 export function applyStorageCompression(
 	documentServiceFactory: IDocumentServiceFactory,

package/src/blob.ts

@@ -13,6 +13,7 @@ import {
 
 /**
  * Basic implementation of a blob ITreeEntry
+ * @public
  */
 export class BlobTreeEntry {
 	public readonly mode = FileMode.File;
@@ -36,6 +37,7 @@ export class BlobTreeEntry {
 
 /**
  * Basic implementation of a tree ITreeEntry
+ * @public
  */
 export class TreeTreeEntry {
 	public readonly mode = FileMode.Directory;
@@ -46,11 +48,15 @@ export class TreeTreeEntry {
 	 * @param path - path of entry
 	 * @param value - subtree
 	 */
-	constructor(public readonly path: string, public readonly value: ITree) {}
+	constructor(
+		public readonly path: string,
+		public readonly value: ITree,
+	) {}
 }
 
 /**
  * Basic implementation of an attachment ITreeEntry
+ * @public
  */
 export class AttachmentTreeEntry {
 	public readonly mode = FileMode.File;
@@ -62,7 +68,10 @@ export class AttachmentTreeEntry {
 	 * @param path - path of entry
 	 * @param id - id of external blob attachment
 	 */
-	constructor(public readonly path: string, public readonly id: string) {
+	constructor(
+		public readonly path: string,
+		public readonly id: string,
+	) {
 		this.value = { id };
 	}
 }

package/src/buildSnapshotTree.ts

@@ -86,6 +86,7 @@ function flatten(tree: ITreeEntry[], blobMap: Map<string, ArrayBufferLike>): git
  * @param blobMap - a map of blob's sha1 to content that gets filled with content from entries
  * NOTE: blobMap's validity is contingent on the returned promise's resolution
  * @returns the hierarchical tree
+ * @public
  */
 export function buildSnapshotTree(
 	entries: ITreeEntry[],

package/src/documentStorageServiceProxy.ts

@@ -17,6 +17,9 @@ import {
 	IVersion,
 } from "@fluidframework/protocol-definitions";
 
+/**
+ * @public
+ */
 export class DocumentStorageServiceProxy implements IDocumentStorageService {
 	private _policies: IDocumentStorageServicePolicies | undefined;
 

package/src/error.ts

@@ -7,7 +7,10 @@
 import { DriverErrorType, IDriverErrorBase } from "@fluidframework/driver-definitions";
 import { IFluidErrorBase, LoggingError } from "@fluidframework/telemetry-utils";
 
-/** Error indicating an API is being used improperly resulting in an invalid operation. */
+/**
+ * Error indicating an API is being used improperly resulting in an invalid operation.
+ * @public
+ */
 export class UsageError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
 	// eslint-disable-next-line import/no-deprecated
 	readonly errorType = DriverErrorType.usageError;

package/src/index.ts

@@ -51,5 +51,6 @@ export { convertSummaryTreeToSnapshotITree } from "./treeConversions";
 export {
 	applyStorageCompression,
 	ICompressionStorageConfig,
+	SummaryCompressionAlgorithm,
 	blobHeadersBlobName,
 } from "./adapters";

package/src/insecureUrlResolver.ts

@@ -22,6 +22,7 @@ import Axios from "axios";
  * The tenantId/documentId pair defines the 'full' document ID the service makes use of. The path is then an optional
  * part of the URL that the document interprets and maps to a data store. It's exactly similar to how a web service
  * works or a router inside of a single page app framework.
+ * @public
  */
 export class InsecureUrlResolver implements IUrlResolver {
 	private readonly cache = new Map<string, Promise<IResolvedUrl>>();

package/src/messageRecognition.ts

@@ -12,18 +12,25 @@ import {
  * Tells if message was sent by container runtime
  * @privateRemarks ADO #1385: To be moved to container-definitions
  * @returns whether the message is a runtime message
+ * @public
  */
 export function isRuntimeMessage(message: { type: string }): boolean {
 	return message.type === MessageType.Operation;
 }
 
-// ADO #1385: staging code changes across layers.
-// Eventually to be replaced by MessageType.accept
+/**
+ * @privateRemarks ADO #1385: staging code changes across layers.
+ * Eventually to be replaced by MessageType.accept
+ * @public
+ */
 export enum MessageType2 {
 	Accept = "accept",
 }
 
-// ADO #1385: To be moved to packages/protocol-base/src/protocol.ts
+/**
+ * @privateRemarks ADO #1385: To be moved to packages/protocol-base/src/protocol.ts
+ * @public
+ */
 export function canBeCoalescedByService(
 	message: ISequencedDocumentMessage | IDocumentMessage,
 ): boolean {

package/src/network.ts

@@ -16,15 +16,21 @@ import {
 import { ITelemetryProperties } from "@fluidframework/core-interfaces";
 import { IFluidErrorBase, LoggingError } from "@fluidframework/telemetry-utils";
 
+/**
+ * @public
+ */
 export enum OnlineStatus {
 	Offline,
 	Online,
 	Unknown,
 }
 
-// It tells if we have local connection only - we might not have connection to web.
-// No solution for node.js (other than resolve dns names / ping specific sites)
-// Can also use window.addEventListener("online" / "offline")
+/**
+ * It tells if we have local connection only - we might not have connection to web.
+ * No solution for node.js (other than resolve dns names / ping specific sites)
+ * Can also use window.addEventListener("online" / "offline")
+ * @public
+ */
 export function isOnline(): OnlineStatus {
 	if (
 		typeof navigator === "object" &&
@@ -36,25 +42,34 @@ export function isOnline(): OnlineStatus {
 	return OnlineStatus.Unknown;
 }
 
-/** Telemetry props with driver-specific required properties */
+/**
+ * Telemetry props with driver-specific required properties
+ * @public
+ */
 export type DriverErrorTelemetryProps = ITelemetryProperties & {
 	driverVersion: string | undefined;
 };
 
 /**
  * Generic network error class.
+ * @public
  */
 export class GenericNetworkError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
 	// eslint-disable-next-line import/no-deprecated
 	readonly errorType = DriverErrorType.genericNetworkError;
 
-	constructor(message: string, readonly canRetry: boolean, props: DriverErrorTelemetryProps) {
+	constructor(
+		message: string,
+		readonly canRetry: boolean,
+		props: DriverErrorTelemetryProps,
+	) {
 		super(message, props);
 	}
 }
 
 /**
  * FluidInvalidSchema error class.
+ * @public
  */
 export class FluidInvalidSchemaError
 	extends LoggingError
@@ -69,6 +84,9 @@ export class FluidInvalidSchemaError
 	}
 }
 
+/**
+ * @public
+ */
 export class DeltaStreamConnectionForbiddenError
 	extends LoggingError
 	implements IDriverErrorBase, IFluidErrorBase
@@ -85,6 +103,9 @@ export class DeltaStreamConnectionForbiddenError
 	}
 }
 
+/**
+ * @public
+ */
 export class AuthorizationError
 	extends LoggingError
 	implements IAuthorizationError, IFluidErrorBase
@@ -104,6 +125,9 @@ export class AuthorizationError
 	}
 }
 
+/**
+ * @public
+ */
 export class LocationRedirectionError
 	extends LoggingError
 	implements ILocationRedirectionError, IFluidErrorBase
@@ -122,6 +146,9 @@ export class LocationRedirectionError
 	}
 }
 
+/**
+ * @public
+ */
 export class NetworkErrorBasic<T extends string> extends LoggingError implements IFluidErrorBase {
 	constructor(
 		message: string,
@@ -133,20 +160,35 @@ export class NetworkErrorBasic<T extends string> extends LoggingError implements
 	}
 }
 
+/**
+ * @public
+ */
 export class NonRetryableError<T extends string> extends NetworkErrorBasic<T> {
-	constructor(message: string, readonly errorType: T, props: DriverErrorTelemetryProps) {
+	constructor(
+		message: string,
+		readonly errorType: T,
+		props: DriverErrorTelemetryProps,
+	) {
 		super(message, errorType, false, props);
 	}
 }
 
+/**
+ * @public
+ */
 export class RetryableError<T extends string> extends NetworkErrorBasic<T> {
-	constructor(message: string, readonly errorType: T, props: DriverErrorTelemetryProps) {
+	constructor(
+		message: string,
+		readonly errorType: T,
+		props: DriverErrorTelemetryProps,
+	) {
 		super(message, errorType, true, props);
 	}
 }
 
 /**
  * Throttling error class - used to communicate all throttling errors
+ * @public
  */
 export class ThrottlingError extends LoggingError implements IThrottlingWarning, IFluidErrorBase {
 	// eslint-disable-next-line import/no-deprecated
@@ -162,9 +204,15 @@ export class ThrottlingError extends LoggingError implements IThrottlingWarning,
 	}
 }
 
+/**
+ * @public
+ */
 export const createWriteError = (message: string, props: DriverErrorTelemetryProps) =>
 	new NonRetryableError(message, DriverErrorTypes.writeError, props);
 
+/**
+ * @public
+ */
 export function createGenericNetworkError(
 	message: string,
 	retryInfo: { canRetry: boolean; retryAfterMs?: number },
@@ -180,13 +228,20 @@ export function createGenericNetworkError(
  * Check if a connection error can be retried.  Unless explicitly allowed, retry is disallowed.
  * I.e. asserts or unexpected exceptions in our code result in container failure.
  * @param error - The error to inspect for ability to retry
+ * @public
  */
 export const canRetryOnError = (error: any): boolean => error?.canRetry === true;
 
-/** Check retryAfterSeconds property on error */
+/**
+ * Check retryAfterSeconds property on error
+ * @public
+ * */
 export const getRetryDelaySecondsFromError = (error: any): number | undefined =>
 	error?.retryAfterSeconds as number | undefined;
 
-/** Check retryAfterSeconds property on error and convert to ms */
+/**
+ * Check retryAfterSeconds property on error and convert to ms
+ * @public
+ * */
 export const getRetryDelayFromError = (error: any): number | undefined =>
 	error?.retryAfterSeconds !== undefined ? error.retryAfterSeconds * 1000 : undefined;

package/src/networkUtils.ts

@@ -7,6 +7,9 @@ import { ITelemetryErrorEvent } from "@fluidframework/core-interfaces";
 import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
 import { isOnline, OnlineStatus, canRetryOnError } from "./network";
 
+/**
+ * @public
+ */
 export function logNetworkFailure(
 	logger: ITelemetryLoggerExt,
 	event: ITelemetryErrorEvent,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/driver-utils";
-export const pkgVersion = "2.0.0-internal.7.0.0";
+export const pkgVersion = "2.0.0-internal.7.2.0";

package/src/parallelRequests.ts

@@ -29,6 +29,7 @@ type WorkingState = "working" | "done" | "canceled";
  * @param logger - logger to use
  * @param requestCallback - callback to request batches
  * @returns Queue that can be used to retrieve data
+ * @public
  */
 export class ParallelRequests<T> {
 	private latestRequested: number;
@@ -338,6 +339,7 @@ export class ParallelRequests<T> {
 /**
  * Helper queue class to allow async push / pull
  * It's essentially a pipe allowing multiple writers, and single reader
+ * @public
  */
 export class Queue<T> implements IStream<T> {
 	private readonly queue: Promise<IStreamResult<T>>[] = [];
@@ -531,6 +533,7 @@ async function getSingleOpBatch(
  * @param signal - Cancelation signal
  * @param scenarioName - Reason for fetching ops
  * @returns Messages fetched
+ * @public
  */
 export function requestOps(
 	get: (
@@ -651,12 +654,18 @@ export function requestOps(
 	return queue;
 }
 
+/**
+ * @public
+ */
 export const emptyMessageStream: IStream<ISequencedDocumentMessage[]> = {
 	read: async () => {
 		return { done: true };
 	},
 };
 
+/**
+ * @public
+ */
 export function streamFromMessages(
 	messagesArg: Promise<ISequencedDocumentMessage[]>,
 ): IStream<ISequencedDocumentMessage[]> {
@@ -673,6 +682,9 @@ export function streamFromMessages(
 	};
 }
 
+/**
+ * @public
+ */
 export function streamObserver<T>(
 	stream: IStream<T>,
 	handler: (value: IStreamResult<T>) => void,

package/src/prefetchDocumentStorageService.ts

@@ -7,6 +7,9 @@ import { ISnapshotTree, IVersion } from "@fluidframework/protocol-definitions";
 import { DocumentStorageServiceProxy } from "./documentStorageServiceProxy";
 import { canRetryOnError } from "./network";
 
+/**
+ * @public
+ */
 export class PrefetchDocumentStorageService extends DocumentStorageServiceProxy {
 	// BlobId -> blob prefetchCache cache
 	private readonly prefetchCache = new Map<string, Promise<ArrayBufferLike>>();

package/src/rateLimiter.ts

@@ -5,6 +5,9 @@
 
 import { assert } from "@fluidframework/core-utils";
 
+/**
+ * @public
+ */
 export class RateLimiter {
 	private readonly tasks: (() => void)[] = [];
 	constructor(private maxRequests: number) {

package/src/readAndParse.ts

@@ -17,6 +17,7 @@ import { IDocumentStorageService } from "@fluidframework/driver-definitions";
  * @typeParam T - Output type matching JSON format of inpyt blob data.
  *
  * @returns The object that we decoded and parsed via `JSON.parse`.
+ * @public
  */
 export async function readAndParse<T>(
 	storage: Pick<IDocumentStorageService, "readBlob">,

package/src/runWithRetry.ts

@@ -14,6 +14,7 @@ import { NonRetryableError } from ".";
 /**
  * Interface describing an object passed to various network APIs.
  * It allows caller to control cancellation, as well as learn about any delays.
+ * @public
  */
 export interface IProgress {
 	/**
@@ -43,6 +44,9 @@ export interface IProgress {
 	onRetry?(delayInMs: number, error: any): void;
 }
 
+/**
+ * @public
+ */
 export async function runWithRetry<T>(
 	api: (cancel?: AbortSignal) => Promise<T>,
 	fetchCallName: string,
@@ -81,8 +85,7 @@ export async function runWithRetry<T>(
 						retry: numRetries,
 						duration: performance.now() - startTime,
 						fetchCallName,
-						// TODO: Remove when typescript version of the repo contains the AbortSignal.reason property (AB#5045)
-						reason: (progress.cancel as AbortSignal & { reason: any }).reason,
+						reason: progress.cancel.reason,
 					},
 					err,
 				);
@@ -92,8 +95,7 @@ export async function runWithRetry<T>(
 					{
 						driverVersion: pkgVersion,
 						fetchCallName,
-						// TODO: Remove when typescript version of the repo contains the AbortSignal.reason property (AB#5045)
-						reason: (progress.cancel as AbortSignal & { reason: any }).reason,
+						reason: progress.cancel.reason,
 					},
 				);
 			}
@@ -148,6 +150,7 @@ const MaxReconnectDelayInMsWhenEndpointIsNotReachable = 8000;
  * to when endpoint is reachable in which case it is 30s.
  * @param error - error based on which we decide max wait time.
  * @returns Max wait time.
+ * @public
  */
 export function calculateMaxWaitTime(error: unknown): number {
 	return isFluidError(error) && error.getTelemetryProperties().endpointReached === true

package/src/summaryForCreateNew.ts

@@ -30,6 +30,7 @@ export interface CombinedAppAndProtocolSummary extends ISummaryTree {
  */
 export function isCombinedAppAndProtocolSummary(
 	summary: ISummaryTree | undefined,
+	...optionalRootTrees: string[]
 ): summary is CombinedAppAndProtocolSummary {
 	if (
 		summary?.tree === undefined ||
@@ -38,7 +39,7 @@ export function isCombinedAppAndProtocolSummary(
 	) {
 		return false;
 	}
-	const treeKeys = Object.keys(summary.tree);
+	const treeKeys = Object.keys(summary.tree).filter((t) => !optionalRootTrees.includes(t));
 	if (treeKeys.length !== 2) {
 		return false;
 	}
@@ -48,6 +49,7 @@ export function isCombinedAppAndProtocolSummary(
 /**
  * Extract the attributes from the protocol summary.
  * @param protocolSummary - protocol summary from which the values are to be extracted.
+ * @public
  */
 export function getDocAttributesFromProtocolSummary(
 	protocolSummary: ISummaryTree,
@@ -59,6 +61,7 @@ export function getDocAttributesFromProtocolSummary(
 /**
  * Extract quorum values from the protocol summary.
  * @param protocolSummary - protocol summary from which the values are to be extracted.
+ * @public
  */
 export function getQuorumValuesFromProtocolSummary(
 	protocolSummary: ISummaryTree,

package/src/treeConversions.ts

@@ -12,6 +12,7 @@ import { isCombinedAppAndProtocolSummary } from "./summaryForCreateNew";
 /**
  * Converts ISummaryTree to ITree format.
  * @param summaryTree - summary tree in ISummaryTree format
+ * @public
  */
 export function convertSummaryTreeToSnapshotITree(summaryTree: ISummaryTree): ITree {
 	const entries: ITreeEntry[] = [];