@fluid-internal/client-utils 2.0.0-dev.6.4.0.191258

package/src/bufferBrowser.ts

@@ -0,0 +1,198 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import * as base64js from "base64-js";
+
+/**
+ * Converts a Uint8Array to a string of the provided encoding
+ * Useful when the array might be an {@link IsoBuffer}.
+ *
+ * @param arr - The array to convert.
+ * @param encoding - Optional target encoding; only "utf8" and "base64" are
+ * supported, with "utf8" being default.
+ * @returns The converted string.
+ *
+ * @internal
+ */
+export function Uint8ArrayToString(arr: Uint8Array, encoding?: string): string {
+	switch (encoding) {
+		case "base64": {
+			return base64js.fromByteArray(arr);
+		}
+		case "utf8":
+		case "utf-8":
+		case undefined: {
+			return new TextDecoder().decode(arr);
+		}
+		default: {
+			throw new Error("invalid/unsupported encoding");
+		}
+	}
+}
+
+/**
+ * Converts a {@link https://en.wikipedia.org/wiki/Base64 | base64} or
+ * {@link https://en.wikipedia.org/wiki/UTF-8 | utf-8} string to array buffer.
+ *
+ * @param encoding - The input string's encoding.
+ *
+ * @internal
+ */
+export const stringToBuffer = (input: string, encoding: string): ArrayBufferLike =>
+	IsoBuffer.from(input, encoding).buffer;
+
+/**
+ * Convert binary blob to string format
+ *
+ * @param blob - the binary blob
+ * @param encoding - output string's encoding
+ * @returns the blob in string format
+ *
+ * @internal
+ */
+export const bufferToString = (blob: ArrayBufferLike, encoding: string): string =>
+	IsoBuffer.from(blob).toString(encoding);
+
+/**
+ * Determines if an object is an array buffer.
+ *
+ * @remarks Will detect and reject TypedArrays, like Uint8Array.
+ * Reason - they can be viewport into Array, they can be accepted, but caller has to deal with
+ * math properly (i.e. Take into account byteOffset at minimum).
+ * For example, construction of new TypedArray can be in the form of new TypedArray(typedArray) or
+ * new TypedArray(buffer, byteOffset, length), but passing TypedArray will result in fist path (and
+ * ignoring byteOffice, length).
+ *
+ * @param obj - The object to determine if it is an ArrayBuffer.
+ *
+ * @internal
+ */
+export function isArrayBuffer(obj: unknown): obj is ArrayBuffer {
+	const maybe = obj as (Partial<ArrayBuffer> & Partial<Uint8Array>) | undefined;
+	return (
+		obj instanceof ArrayBuffer ||
+		(typeof maybe === "object" &&
+			maybe !== null &&
+			typeof maybe.byteLength === "number" &&
+			typeof maybe.slice === "function" &&
+			maybe.byteOffset === undefined &&
+			maybe.buffer === undefined)
+	);
+}
+
+/**
+ * Minimal implementation of Buffer for our usages in the browser environment.
+ *
+ * @internal
+ */
+export class IsoBuffer extends Uint8Array {
+	/**
+	 * Convert the buffer to a string.
+	 * Only supports encoding the whole string (unlike the Node Buffer equivalent)
+	 * and only utf8 and base64 encodings.
+	 *
+	 * @param encoding - The encoding to use.
+	 */
+	public toString(encoding?: string): string {
+		return Uint8ArrayToString(this, encoding);
+	}
+
+	/**
+	 * Static constructor
+	 * @param value - (string | ArrayBuffer)
+	 * @param encodingOrOffset - (string | number)
+	 * @param length - (number)
+	 *
+	 * @privateRemarks TODO: Use actual types
+	 */
+	// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+	static from(value: any, encodingOrOffset?: any, length?: any): IsoBuffer {
+		if (typeof value === "string") {
+			return IsoBuffer.fromString(value, encodingOrOffset as string | undefined);
+			// Capture any typed arrays, including Uint8Array (and thus - IsoBuffer!)
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+		} else if (value !== null && typeof value === "object" && isArrayBuffer(value.buffer)) {
+			// The version of the from function for the node buffer, which takes a buffer or typed array
+			// as first parameter, does not have any offset or length parameters. Those are just silently
+			// ignored and not taken into account
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-member-access
+			return IsoBuffer.fromArrayBuffer(value.buffer, value.byteOffset, value.byteLength);
+		} else if (isArrayBuffer(value)) {
+			return IsoBuffer.fromArrayBuffer(
+				value,
+				encodingOrOffset as number | undefined,
+				length as number,
+			);
+		} else {
+			throw new TypeError("Input value was neither a string nor an ArrayBuffer.");
+		}
+	}
+
+	static fromArrayBuffer(
+		arrayBuffer: ArrayBuffer,
+		byteOffset?: number,
+		byteLength?: number,
+	): IsoBuffer {
+		const offset = byteOffset ?? 0;
+		const validLength = byteLength ?? arrayBuffer.byteLength - offset;
+		if (
+			offset < 0 ||
+			offset > arrayBuffer.byteLength ||
+			validLength < 0 ||
+			validLength + offset > arrayBuffer.byteLength
+		) {
+			throw new RangeError("Invalid range specified.");
+		}
+
+		return new IsoBuffer(arrayBuffer, offset, validLength);
+	}
+
+	static fromString(str: string, encoding?: string): IsoBuffer {
+		switch (encoding) {
+			case "base64": {
+				const sanitizedString = this.sanitizeBase64(str);
+				const encoded = base64js.toByteArray(sanitizedString);
+				return new IsoBuffer(encoded.buffer);
+			}
+			case "utf8":
+			case "utf-8":
+			case undefined: {
+				const encoded = new TextEncoder().encode(str);
+				return new IsoBuffer(encoded.buffer);
+			}
+			default: {
+				throw new Error("invalid/unsupported encoding");
+			}
+		}
+	}
+
+	static isBuffer(obj: unknown): boolean {
+		throw new Error("unimplemented");
+	}
+
+	/**
+	 * Sanitize a base64 string to provide to base64-js library.
+	 * {@link https://www.npmjs.com/package/base64-js} is not as tolerant of the same malformed base64 as Node'
+	 * Buffer is.
+	 */
+	private static sanitizeBase64(str: string): string {
+		let sanitizedStr = str;
+		// Remove everything after padding - Node buffer ignores everything
+		// after any padding whereas base64-js does not
+		sanitizedStr = sanitizedStr.split("=")[0];
+
+		// Remove invalid characters - Node buffer strips invalid characters
+		// whereas base64-js replaces them with "A"
+		sanitizedStr = sanitizedStr.replace(/[^\w+-/]/g, "");
+
+		// Check for missing padding - Node buffer tolerates missing padding
+		// whereas base64-js does not
+		if (sanitizedStr.length % 4 !== 0) {
+			const paddingArray = ["", "===", "==", "="];
+			sanitizedStr += paddingArray[sanitizedStr.length % 4];
+		}
+		return sanitizedStr;
+	}
+}

package/src/bufferNode.ts

@@ -0,0 +1,80 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Declare the subset of Buffer functionality we want to make available instead of
+ * exposing the entirely of Node's typings.  This should match the public interface
+ * of the browser implementation, so any changes made in one should be made in both.
+ *
+ * @public
+ */
+export declare class Buffer extends Uint8Array {
+	toString(encoding?: string): string;
+
+	/**
+	 * Static constructor
+	 *
+	 * @param value - (string | ArrayBuffer).
+	 * @param encodingOrOffset - (string | number).
+	 * @param length - (number).
+	 *
+	 * @privateRemarks TODO: Use actual types
+	 */
+	static from(value: unknown, encodingOrOffset?: unknown, length?: unknown): IsoBuffer;
+	static isBuffer(obj: unknown): obj is Buffer;
+}
+
+/**
+ * @public
+ */
+export const IsoBuffer = Buffer;
+
+/**
+ * @public
+ */
+export type IsoBuffer = Buffer;
+
+/**
+ * Converts a Uint8Array to a string of the provided encoding.
+ * @remarks Useful when the array might be an IsoBuffer.
+ * @param arr - The array to convert.
+ * @param encoding - Optional target encoding; only "utf8" and "base64" are
+ * supported, with "utf8" being default.
+ * @returns The converted string.
+ *
+ * @internal
+ */
+export function Uint8ArrayToString(arr: Uint8Array, encoding?: string): string {
+	// Make this check because Buffer.from(arr) will always do a buffer copy
+	return Buffer.isBuffer(arr) ? arr.toString(encoding) : Buffer.from(arr).toString(encoding);
+}
+
+/**
+ * Convert base64 or utf8 string to array buffer.
+ * @param encoding - The input string's encoding.
+ *
+ * @internal
+ */
+export function stringToBuffer(input: string, encoding: string): ArrayBufferLike {
+	const iso = IsoBuffer.from(input, encoding);
+	// In a Node environment, IsoBuffer may be a Node.js Buffer.  Node.js will
+	// pool multiple small Buffer instances into a single ArrayBuffer, in which
+	// case we need to slice the appropriate span of bytes.
+	return iso.byteLength === iso.buffer.byteLength
+		? iso.buffer
+		: iso.buffer.slice(iso.byteOffset, iso.byteOffset + iso.byteLength);
+}
+
+/**
+ * Convert binary blob to string format
+ *
+ * @param blob - The binary blob
+ * @param encoding - Output string's encoding
+ * @returns The blob in string format
+ *
+ * @internal
+ */
+export const bufferToString = (blob: ArrayBufferLike, encoding: string): string =>
+	IsoBuffer.from(blob).toString(encoding);

package/src/bufferShared.ts

@@ -0,0 +1,17 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Converts a Uint8Array array to an ArrayBuffer.
+ * @param array - Array to convert to ArrayBuffer.
+ *
+ * @internal
+ */
+export function Uint8ArrayToArrayBuffer(array: Uint8Array): ArrayBuffer {
+	if (array.byteOffset === 0 && array.byteLength === array.buffer.byteLength) {
+		return array.buffer;
+	}
+	return array.buffer.slice(array.byteOffset, array.byteOffset + array.byteLength);
+}

package/src/eventForwarder.ts

@@ -0,0 +1,120 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { EventEmitter } from "events";
+import { IDisposable, IEvent, IEventProvider } from "@fluidframework/core-interfaces";
+import { TypedEventEmitter } from "./typedEventEmitter";
+
+/**
+ * Base class used for forwarding events from a source EventEmitter.
+ * This can be useful when all arbitrary listeners need to be removed,
+ * but the primary source needs to stay intact.
+ *
+ * @internal
+ */
+export class EventForwarder<TEvent = IEvent>
+	extends TypedEventEmitter<TEvent>
+	implements IDisposable
+{
+	protected static isEmitterEvent(event: string): boolean {
+		return (
+			event === EventForwarder.newListenerEvent ||
+			event === EventForwarder.removeListenerEvent
+		);
+	}
+
+	private static readonly newListenerEvent = "newListener";
+	private static readonly removeListenerEvent = "removeListener";
+
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#IDisposable.disposed}
+	 */
+	public get disposed(): boolean {
+		return this.isDisposed;
+	}
+	private isDisposed: boolean = false;
+
+	private readonly forwardingEvents = new Map<
+		string,
+		Map<EventEmitter | IEventProvider<TEvent & IEvent>, () => void>
+	>();
+
+	constructor(source?: EventEmitter | IEventProvider<TEvent & IEvent>) {
+		super();
+		if (source !== undefined) {
+			// NewListener event is raised whenever someone starts listening to this events, so
+			// we keep track of events being listened to, and start forwarding from the source
+			// event emitter per event listened to on this
+			const removeListenerHandler = (event: string): void =>
+				this.unforwardEvent(source, event);
+			const newListenerHandler = (event: string): void => this.forwardEvent(source, event);
+			this.on(EventForwarder.removeListenerEvent, removeListenerHandler);
+			this.on(EventForwarder.newListenerEvent, newListenerHandler);
+		}
+	}
+
+	/**
+	 * {@inheritDoc @fluidframework/core-interfaces#IDisposable.dispose}
+	 */
+	public dispose(): void {
+		this.isDisposed = true;
+		for (const listenerRemovers of this.forwardingEvents.values()) {
+			for (const listenerRemover of listenerRemovers.values()) {
+				try {
+					listenerRemover();
+				} catch {
+					// Should be fine because of removeAllListeners below
+				}
+			}
+		}
+		this.removeAllListeners();
+		this.forwardingEvents.clear();
+	}
+
+	protected forwardEvent(
+		source: EventEmitter | IEventProvider<TEvent & IEvent>,
+		...events: string[]
+	): void {
+		for (const event of events) {
+			if (
+				source !== undefined &&
+				event !== undefined &&
+				!EventForwarder.isEmitterEvent(event)
+			) {
+				let sources = this.forwardingEvents.get(event);
+				if (sources === undefined) {
+					sources = new Map();
+					this.forwardingEvents.set(event, sources);
+				}
+				if (!sources.has(source)) {
+					const listener = (...args: unknown[]): boolean => this.emit(event, ...args);
+					sources.set(source, () => source.off(event, listener));
+					source.on(event, listener);
+				}
+			}
+		}
+	}
+
+	protected unforwardEvent(
+		source: EventEmitter | IEventProvider<TEvent & IEvent>,
+		...events: string[]
+	): void {
+		for (const event of events) {
+			if (event !== undefined && !EventForwarder.isEmitterEvent(event)) {
+				const sources = this.forwardingEvents.get(event);
+				if (sources?.has(source) === true && this.listenerCount(event) === 0) {
+					const listenerRemover = sources.get(source);
+					if (listenerRemover !== undefined) {
+						listenerRemover();
+					}
+					sources.delete(source);
+					if (sources.size === 0) {
+						this.forwardingEvents.delete(event);
+					}
+				}
+			}
+		}
+	}
+}

package/src/hashFileBrowser.ts

@@ -0,0 +1,84 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import * as base64js from "base64-js";
+import { IsoBuffer } from "./bufferBrowser";
+
+async function digestBuffer(file: IsoBuffer, algorithm: "SHA-1" | "SHA-256"): Promise<Uint8Array> {
+	const hash = await crypto.subtle.digest(algorithm, file);
+	return new Uint8Array(hash);
+}
+
+function encodeDigest(hashArray: Uint8Array, encoding: "hex" | "base64"): string {
+	// eslint-disable-next-line default-case
+	switch (encoding) {
+		case "hex": {
+			const hashHex = Array.prototype.map
+				.call(hashArray, (byte) => {
+					// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+					return byte.toString(16).padStart(2, "0") as string;
+				})
+				.join("");
+			return hashHex;
+		}
+		case "base64": {
+			return base64js.fromByteArray(hashArray);
+		}
+	}
+}
+
+/**
+ * Hash a file. Consistent within a session, but should not be persisted and
+ * is not consistent with git.
+ * If called under an insecure context for a browser, this will fallback to
+ * using the node implementation.
+ *
+ * @param file - The contents of the file in a buffer.
+ * @param algorithm - The hash algorithm to use, artificially constrained by what is used internally.
+ * @param hashEncoding - The encoding of the returned hash, also artificially constrained.
+ * @returns The hash of the content of the buffer.
+ *
+ * @internal
+ */
+export async function hashFile(
+	file: IsoBuffer,
+	algorithm: "SHA-1" | "SHA-256" = "SHA-1",
+	hashEncoding: "hex" | "base64" = "hex",
+): Promise<string> {
+	// Handle insecure contexts (e.g. running with local services)
+	// by deferring to Node version, which uses a hash polyfill
+	// When packed, this chunk will show as "FluidFramework-HashFallback" separately
+	// from the main chunk and will be of non-trivial size.  It will not be served
+	// under normal circumstances.
+	if (crypto.subtle === undefined) {
+		return import(
+			/* webpackChunkName: "FluidFramework-HashFallback" */
+			"./hashFileNode"
+		).then(async (m) => m.hashFile(file, algorithm, hashEncoding));
+	}
+
+	// This is split up this way to facilitate testing (see the test for more info)
+	const hashArray = await digestBuffer(file, algorithm);
+	return encodeDigest(hashArray, hashEncoding);
+}
+
+/**
+ * Create a github hash (Github hashes the string with blob and size)
+ * Must be called under secure context for browsers
+ *
+ * @param file - The contents of the file in a buffer
+ * @returns The sha1 hash of the content of the buffer with the `blob` prefix and size
+ *
+ * @internal
+ */
+export async function gitHashFile(file: IsoBuffer): Promise<string> {
+	const size = file.byteLength;
+	// eslint-disable-next-line unicorn/prefer-code-point
+	const filePrefix = `blob ${size.toString()}${String.fromCharCode(0)}`;
+	const hashBuffer = IsoBuffer.from(filePrefix + file.toString());
+
+	// hashFile uses sha1; if that changes this will need to change too
+	return hashFile(hashBuffer);
+}

package/src/hashFileNode.ts

@@ -0,0 +1,66 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// eslint-disable-next-line import/no-internal-modules
+import sha1 from "sha.js/sha1";
+// eslint-disable-next-line import/no-internal-modules
+import sha256 from "sha.js/sha256";
+
+import type { IsoBuffer } from "./bufferNode";
+
+/**
+ * Hash a file. Consistent within a session, but should not be persisted and
+ * is not consistent with git.
+ * If called under an insecure context for a browser, this will fallback to
+ * using the node implementation.
+ *
+ * @param file - The contents of the file in a buffer.
+ * @param algorithm - The hash algorithm to use, artificially constrained by what is used internally.
+ * @param hashEncoding - The encoding of the returned hash, also artificially constrained.
+ * @returns The hash of the content of the buffer.
+ *
+ * @internal
+ */
+export async function hashFile(
+	file: IsoBuffer,
+	algorithm: "SHA-1" | "SHA-256" = "SHA-1",
+	hashEncoding: "hex" | "base64" = "hex",
+): Promise<string> {
+	let engine;
+	// eslint-disable-next-line default-case
+	switch (algorithm) {
+		case "SHA-1": {
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
+			engine = new sha1();
+			break;
+		}
+		case "SHA-256": {
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
+			engine = new sha256();
+			break;
+		}
+	}
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+	return engine.update(file).digest(hashEncoding) as string;
+}
+
+/**
+ * Create a github hash (Github hashes the string with blob and size)
+ * Must be called under secure context for browsers
+ *
+ * @param file - The contents of the file in a buffer
+ * @returns The sha1 hash of the content of the buffer with the `blob` prefix and size
+ *
+ * @internal
+ */
+export async function gitHashFile(file: IsoBuffer): Promise<string> {
+	const size = file.byteLength;
+	// eslint-disable-next-line unicorn/prefer-code-point
+	const filePrefix = `blob ${size.toString()}${String.fromCharCode(0)}`;
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
+	const engine = new sha1();
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
+	return engine.update(filePrefix).update(file).digest("hex") as string;
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { fromBase64ToUtf8, fromUtf8ToBase64, toUtf8 } from "./base64Encoding";
+export { Uint8ArrayToArrayBuffer } from "./bufferShared";
+export { EventForwarder } from "./eventForwarder";
+/**
+ * NOTE: This export is remapped to export from "./indexBrowser" in browser environments via package.json.
+ * Because the two files don't have fully isomorphic exports, using named exports for the full API surface
+ * is problematic if that named export includes values not in their intersection.
+ *
+ * In a future breaking change of client-utils, we could use a named export for their intersection if we
+ * desired.
+ */
+// eslint-disable-next-line no-restricted-syntax
+export * from "./indexNode";
+export { IsomorphicPerformance } from "./performanceIsomorphic";
+// export { IRange, IRangeTrackerSnapshot, RangeTracker } from "./rangeTracker";
+export { ITraceEvent, Trace } from "./trace";
+export { EventEmitterEventType, TypedEventEmitter, TypedEventTransform } from "./typedEventEmitter";

package/src/indexBrowser.ts

@@ -0,0 +1,14 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	bufferToString,
+	isArrayBuffer,
+	IsoBuffer,
+	stringToBuffer,
+	Uint8ArrayToString,
+} from "./bufferBrowser";
+export { gitHashFile, hashFile } from "./hashFileBrowser";
+export { performance } from "./performanceBrowser";

package/src/indexNode.ts

@@ -0,0 +1,14 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export {
+	Buffer,
+	bufferToString,
+	IsoBuffer,
+	stringToBuffer,
+	Uint8ArrayToString,
+} from "./bufferNode";
+export { gitHashFile, hashFile } from "./hashFileNode";
+export { performance } from "./performanceNode";

package/src/performanceBrowser.ts

@@ -0,0 +1,11 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IsomorphicPerformance } from "./performanceIsomorphic";
+
+/**
+ * @internal
+ */
+export const performance: IsomorphicPerformance = globalThis.performance;

package/src/performanceIsomorphic.ts

@@ -0,0 +1,13 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * This type contains all browser performance properties as optional, and some
+ * of the intersecting properties of node and browser performance as required.
+ *
+ * @internal
+ */
+export type IsomorphicPerformance = Partial<Performance> &
+	Pick<Performance, "clearMarks" | "mark" | "measure" | "now">;

package/src/performanceNode.ts

@@ -0,0 +1,13 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// eslint-disable-next-line import/no-nodejs-modules
+import { performance as nodePerformance } from "perf_hooks";
+import { IsomorphicPerformance } from "./performanceIsomorphic";
+
+/**
+ * @internal
+ */
+export const performance: IsomorphicPerformance = nodePerformance;