@fluid-internal/client-utils 2.118.0 → 3.0.0

package/src/buffer.ts

@@ -0,0 +1,112 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Declare the subset of node:Buffer functionality we want to make available instead of
+ * exposing the entirely of Node's typings.  These serve as the public interface
+ * of the browser and node implementation.
+ */
+
+/**
+ * Set of supported encodings for string to buffer conversion.
+ *
+ * @internal
+ */
+export type IsoBufferEncoding =
+	| "utf8"
+	// eslint-disable-next-line unicorn/text-encoding-identifier-case -- "utf-8" value is supported, just discouraged
+	| "utf-8"
+	| "base64";
+
+/**
+ * Minimal Buffer interface for our usages in the browser or Node environments.
+ *
+ * @internal
+ */
+export interface IsoBuffer<TArrayBuffer extends ArrayBufferLike>
+	extends Uint8Array<TArrayBuffer> {
+	/**
+	 * 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.
+	 */
+	toString(encoding?: IsoBufferEncoding): string;
+}
+
+/**
+ * Constructor for {@link (IsoBuffer:type)}.
+ *
+ * @internal
+ */
+export interface IsoBufferConstructor {
+	readonly prototype: IsoBuffer<ArrayBufferLike>;
+
+	new (length: number): IsoBuffer<ArrayBuffer>;
+	new (array: ArrayLike<number>): IsoBuffer<ArrayBuffer>;
+	new <TArrayBuffer extends ArrayBufferLike = ArrayBuffer>(
+		buffer: TArrayBuffer,
+		byteOffset?: number,
+		length?: number,
+	): IsoBuffer<TArrayBuffer>;
+
+	/**
+	 * Creates a new `IsoBuffer` containing `string`. The `encoding` parameter identifies
+	 * the character encoding to be used when converting `string` into bytes.
+	 *
+	 * @param string - A string to encode.
+	 * @param encoding - The encoding of `string`. **Default:** `'utf8'`.
+	 *
+	 * @privateRemarks
+	 * Node buffer.buffer.d.ts declaration:
+	 * `from(string: WithImplicitCoercion<string>, encoding?: IsoBufferEncoding): Buffer<ArrayBuffer>;`
+	 */
+	from(string: string, encoding?: IsoBufferEncoding): IsoBuffer<ArrayBuffer>;
+	/**
+	 * Allocates a new `IsoBuffer` using an `array` of bytes in the range `0` – `255`.
+	 * Array entries outside that range will be truncated to fit into it.
+	 *
+	 * @param value - `Uint8Array`.
+	 *
+	 * @remarks
+	 * This is limited to `Uint8Array` input to match Node implementation that
+	 * takes `ArrayLike<number>` and returns `IsoBuffer<ArrayBuffer>`.
+	 *
+	 * @privateRemarks
+	 * Node buffer.buffer.d.ts declaration:
+	 * `from(array: WithImplicitCoercion<ArrayLike<number>>): IsoBuffer<ArrayBuffer>;`
+	 */
+	from(array: Uint8Array): IsoBuffer<ArrayBuffer>;
+	/**
+	 * This creates a view of the `ArrayBuffer` without copying the underlying
+	 * memory. For example, when passed a reference to the `.buffer` property of a
+	 * `TypedArray` instance, the newly created `Buffer` will share the same
+	 * allocated memory as the `TypedArray`'s underlying `ArrayBuffer`.
+	 *
+	 * @param arrayBuffer - An `ArrayBuffer`, `SharedArrayBuffer`, for example the
+	 * `.buffer` property of a `TypedArray`.
+	 * @param byteOffset - Index of first byte to expose. **Default:** `0`.
+	 * @param length - Number of bytes to expose. **Default:**
+	 * `arrayBuffer.byteLength - byteOffset`.
+	 *
+	 * @privateRemarks
+	 * Node buffer.buffer.d.ts declaration:
+	 * ```
+	 * public static from<TArrayBuffer extends WithImplicitCoercion<ArrayBufferLike>>(
+	 * 		arrayBuffer: TArrayBuffer,
+	 * 		byteOffset?: number,
+	 * 		length?: number,
+	 * ): Buffer<ImplicitArrayBuffer<TArrayBuffer>>;
+	 * ```
+	 */
+	from<TArrayBuffer extends ArrayBufferLike>(
+		arrayBuffer: TArrayBuffer,
+		byteOffset?: number,
+		length?: number,
+	): IsoBuffer<TArrayBuffer>;
+
+	isBuffer(obj: unknown): obj is IsoBuffer<ArrayBufferLike>;
+}

package/src/bufferBrowser.ts

@@ -5,9 +5,30 @@
 
 import * as base64js from "base64-js";
 
+import type {
+	IsoBufferConstructor,
+	IsoBufferEncoding,
+	IsoBuffer as IsoBufferInterface,
+} from "./buffer.js";
+
+export type {
+	IsoBufferConstructor,
+	IsoBufferEncoding,
+} from "./buffer.js";
 /**
- * Converts a Uint8Array to a string of the provided encoding
- * Useful when the array might be an {@link IsoBuffer}.
+ * Minimal `Buffer` interface for our usages in the browser or Node.js environments.
+ *
+ * @internal
+ *
+ * @privateRemarks
+ * This type is exported specifically from here to respect combo type+value of same name rules.
+ */
+export type IsoBuffer<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike> =
+	IsoBufferInterface<TArrayBuffer>;
+
+/**
+ * Converts a `Uint8Array` to a string of the provided encoding
+ * Useful when the array might be an {@link (IsoBuffer:type)}.
  *
  * @param arr - The array to convert.
  * @param encoding - Optional target encoding; only "utf8" and "base64" are
@@ -16,11 +37,7 @@ import * as base64js from "base64-js";
  *
  * @internal
  */
-export function Uint8ArrayToString(
-	arr: Uint8Array,
-	// eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
-	encoding?: "utf8" | "utf-8" | "base64",
-): string {
+export function Uint8ArrayToString(arr: Uint8Array, encoding?: IsoBufferEncoding): string {
 	switch (encoding) {
 		case "base64": {
 			return base64js.fromByteArray(arr);
@@ -45,7 +62,7 @@ export function Uint8ArrayToString(
  *
  * @internal
  */
-export const stringToBuffer = (input: string, encoding: string): ArrayBuffer =>
+export const stringToBuffer = (input: string, encoding: IsoBufferEncoding): ArrayBuffer =>
 	IsoBuffer.from(input, encoding).buffer;
 
 /**
@@ -58,10 +75,10 @@ export const stringToBuffer = (input: string, encoding: string): ArrayBuffer =>
  * @internal
  */
 export const bufferToString = (
-	blob: ArrayBufferLike,
-	// eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
-	encoding: "utf8" | "utf-8" | "base64",
-): string => IsoBuffer.from(blob).toString(encoding);
+	blob: ArrayBufferLike | Uint8Array,
+	encoding: IsoBufferEncoding,
+): string =>
+	Uint8ArrayToString(blob instanceof Uint8Array ? blob : IsoBuffer.from(blob), encoding);
 
 /**
  * Determines if an object is an array buffer.
@@ -73,12 +90,16 @@ export const bufferToString = (
  * 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.
+ * @param obj - The object to determine if it is `ArrayBufferLike`.
  *
- * @internal
+ * @privateRemarks
+ * This function preserves runtime functionality as it has been in the past.
+ * Typing has been adjusted to reflect the only use that remains and (assuming
+ * is called as expected) will always return true as the input is already
+ * expected to be `ArrayBufferLike`.
  */
-export function isArrayBuffer(obj: unknown): obj is ArrayBuffer {
-	const maybe = obj as (Partial<ArrayBuffer> & Partial<Uint8Array>) | undefined;
+function isArrayBufferLike(obj: ArrayBufferLike): obj is ArrayBufferLike {
+	const maybe = obj as (Partial<ArrayBufferLike> & Partial<Uint8Array>) | undefined;
 	return (
 		obj instanceof ArrayBuffer ||
 		(typeof maybe === "object" &&
@@ -91,59 +112,71 @@ export function isArrayBuffer(obj: unknown): obj is ArrayBuffer {
 }
 
 /**
- * Minimal implementation of Buffer for our usages in the browser environment.
+ * 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.
-	 */
-	// eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
-	public toString(encoding?: "utf8" | "utf-8" | "base64"): string {
+// eslint-disable-next-line @typescript-eslint/no-shadow -- Preserve the public constructor name at runtime.
+export const IsoBuffer: IsoBufferConstructor = class IsoBuffer<
+		TArrayBuffer extends ArrayBufferLike = ArrayBufferLike,
+	>
+	extends Uint8Array<TArrayBuffer>
+	implements IsoBufferInterface<TArrayBuffer>
+{
+	public constructor(
+		value: number | ArrayLike<number> | TArrayBuffer,
+		byteOffset?: number,
+		length?: number,
+	) {
+		super(value as TArrayBuffer, byteOffset, length);
+	}
+
+	public toString(encoding?: IsoBufferEncoding): 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
-	public static from(value: any, encodingOrOffset?: any, length?: any): IsoBuffer {
+	public static from(
+		value: string,
+		encoding?: IsoBufferEncoding,
+	): IsoBufferInterface<ArrayBuffer>;
+	public static from(value: Uint8Array): IsoBufferInterface<ArrayBuffer>;
+	public static from<TFArrayBuffer extends ArrayBufferLike>(
+		value: TFArrayBuffer,
+		byteOffset?: number,
+		length?: number,
+	): IsoBufferInterface<TFArrayBuffer>;
+	public static from<TFArrayBuffer extends ArrayBufferLike>(
+		value: string | Uint8Array | TFArrayBuffer,
+		encodingOrOffset?: IsoBufferEncoding | number,
+		length?: number,
+	): IsoBufferInterface<ArrayBufferLike> {
 		if (typeof value === "string") {
-			return IsoBuffer.fromString(value, encodingOrOffset as string | undefined);
+			return IsoBuffer.fromString(
+				value,
+				encodingOrOffset as IsoBufferEncoding | undefined,
+			) satisfies IsoBufferInterface<ArrayBuffer>;
 			// 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)) {
+		} else if (value instanceof Uint8Array) {
 			// 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,
-			);
+			const copy = new Uint8Array(value.byteLength);
+			copy.set(value);
+			return new IsoBuffer<ArrayBuffer>(copy.buffer) satisfies IsoBufferInterface<ArrayBuffer>;
+		} else if (isArrayBufferLike(value)) {
+			return IsoBuffer.fromArrayBuffer(value, encodingOrOffset as number | undefined, length);
 		} else {
-			throw new TypeError("Input value was neither a string nor an ArrayBuffer.");
+			throw new TypeError(
+				"Input value was neither a string, a Uint8Array, nor an ArrayBuffer.",
+			);
 		}
 	}
 
-	public static fromArrayBuffer(
-		arrayBuffer: ArrayBuffer,
+	public static fromArrayBuffer<TFArrayBuffer extends ArrayBufferLike>(
+		arrayBuffer: TFArrayBuffer,
 		byteOffset?: number,
 		byteLength?: number,
-	): IsoBuffer {
+	): IsoBufferInterface<TFArrayBuffer> {
 		const offset = byteOffset ?? 0;
 		const validLength = byteLength ?? arrayBuffer.byteLength - offset;
 		if (
@@ -155,22 +188,27 @@ export class IsoBuffer extends Uint8Array {
 			throw new RangeError("Invalid range specified.");
 		}
 
-		return new IsoBuffer(arrayBuffer, offset, validLength);
+		return new IsoBuffer<TFArrayBuffer>(arrayBuffer, offset, validLength);
 	}
 
-	public static fromString(str: string, encoding?: string): IsoBuffer {
+	public static fromString(
+		str: string,
+		encoding?: IsoBufferEncoding,
+	): IsoBufferInterface<ArrayBuffer> {
 		switch (encoding) {
 			case "base64": {
 				const sanitizedString = this.sanitizeBase64(str);
-				const encoded = base64js.toByteArray(sanitizedString);
-				return new IsoBuffer(encoded.buffer);
+				// base64-js will always return a Uint8Array<ArrayBuffer>, but typing has not
+				// been updated to reflect that yet.  Cast to the correct type here.
+				const encoded = base64js.toByteArray(sanitizedString) as Uint8Array<ArrayBuffer>;
+				return new IsoBuffer(encoded.buffer, encoded.byteOffset, encoded.byteLength);
 			}
 			case "utf8":
 			// eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
 			case "utf-8":
 			case undefined: {
 				const encoded = new TextEncoder().encode(str);
-				return new IsoBuffer(encoded.buffer);
+				return new IsoBuffer(encoded.buffer, encoded.byteOffset, encoded.byteLength);
 			}
 			default: {
 				throw new Error("invalid/unsupported encoding");
@@ -178,8 +216,8 @@ export class IsoBuffer extends Uint8Array {
 		}
 	}
 
-	public static isBuffer(obj: unknown): boolean {
-		throw new Error("unimplemented");
+	public static isBuffer(obj: unknown): obj is IsoBuffer {
+		return obj instanceof IsoBuffer;
 	}
 
 	/**
@@ -205,4 +243,4 @@ export class IsoBuffer extends Uint8Array {
 		}
 		return sanitizedStr;
 	}
-}
+} satisfies IsoBufferConstructor;

package/src/bufferNode.ts

@@ -3,43 +3,103 @@
  * Licensed under the MIT License.
  */
 
+import type {
+	IsoBufferConstructor,
+	IsoBufferEncoding,
+	IsoBuffer as IsoBufferInterface,
+} from "./buffer.js";
+
+export type { IsoBufferConstructor, IsoBufferEncoding } from "./buffer.js";
+/**
+ * Minimal `Buffer` interface for our usages in the browser or Node.js environments.
+ *
+ * @internal
+ *
+ * @privateRemarks
+ * This type is exported specifically from here to respect combo type+value of same name rules.
+ */
+export type IsoBuffer<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike> =
+	IsoBufferInterface<TArrayBuffer>;
+
 /**
  * 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.
+ * of the browser implementation -- see {@link (IsoBuffer:type)} and {@link IsoBufferConstructor}.
  *
  * @internal
  */
-export declare class Buffer extends Uint8Array {
-	// eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
-	public toString(encoding?: "utf8" | "utf-8" | "base64"): string;
-
+export declare class Buffer<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike>
+	extends Uint8Array<TArrayBuffer>
+	implements IsoBuffer<TArrayBuffer>
+{
 	/**
-	 * Static constructor
+	 * Creates a new `IsoBuffer` containing `string`. The `encoding` parameter identifies
+	 * the character encoding to be used when converting `string` into bytes.
 	 *
-	 * @param value - (string | ArrayBuffer).
-	 * @param encodingOrOffset - (string | number).
-	 * @param length - (number).
+	 * @param string - A string to encode.
+	 * @param encoding - The encoding of `string`. **Default:** `'utf8'`.
 	 *
-	 * @privateRemarks TODO: Use actual types
+	 * @privateRemarks
+	 * Node buffer.buffer.d.ts declaration:
+	 * `from(string: WithImplicitCoercion<string>, encoding?: IsoBufferEncoding): Buffer<ArrayBuffer>;`
 	 */
-	public static from(value: unknown, encodingOrOffset?: unknown, length?: unknown): IsoBuffer;
+	public static from(string: string, encoding?: IsoBufferEncoding): IsoBuffer<ArrayBuffer>;
+	/**
+	 * Allocates a new `IsoBuffer` using an `array` of bytes in the range `0` – `255`.
+	 * Array entries outside that range will be truncated to fit into it.
+	 *
+	 * @param value - `Uint8Array`.
+	 *
+	 * @remarks
+	 * This is limited to `Uint8Array` input to match Node implementation that
+	 * takes `ArrayLike<number>` and returns `IsoBuffer<ArrayBuffer>`.
+	 *
+	 * @privateRemarks
+	 * Node buffer.buffer.d.ts declaration:
+	 * `from(array: WithImplicitCoercion<ArrayLike<number>>): IsoBuffer<ArrayBuffer>;`
+	 */
+	public static from(array: Uint8Array): IsoBuffer<ArrayBuffer>;
+	/**
+	 * This creates a view of the `ArrayBuffer` without copying the underlying
+	 * memory. For example, when passed a reference to the `.buffer` property of a
+	 * `TypedArray` instance, the newly created `Buffer` will share the same
+	 * allocated memory as the `TypedArray`'s underlying `ArrayBuffer`.
+	 *
+	 * @param arrayBuffer - An `ArrayBuffer`, `SharedArrayBuffer`, for example the
+	 * `.buffer` property of a `TypedArray`.
+	 * @param byteOffset - Index of first byte to expose. **Default:** `0`.
+	 * @param length - Number of bytes to expose. **Default:**
+	 * `arrayBuffer.byteLength - byteOffset`.
+	 *
+	 * @privateRemarks
+	 * Node buffer.buffer.d.ts declaration:
+	 * ```
+	 * public static from<TArrayBuffer extends WithImplicitCoercion<ArrayBufferLike>>(
+	 * 		arrayBuffer: TArrayBuffer,
+	 * 		byteOffset?: number,
+	 * 		length?: number,
+	 * ): Buffer<ImplicitArrayBuffer<TArrayBuffer>>;
+	 * ```
+	 */
+	public static from<TArrayBuffer extends ArrayBufferLike>(
+		arrayBuffer: TArrayBuffer,
+		byteOffset?: number,
+		length?: number,
+	): IsoBuffer<TArrayBuffer>;
+
 	public static isBuffer(obj: unknown): obj is Buffer;
 }
 
 /**
+ * The native Node.js Buffer implementation.
+ *
  * @internal
  */
-export const IsoBuffer = Buffer;
-
-/**
- * @internal
- */
-export type IsoBuffer = Buffer;
+export const IsoBuffer: IsoBufferConstructor = Buffer;
 
 /**
- * Converts a Uint8Array to a string of the provided encoding.
- * @remarks Useful when the array might be an IsoBuffer.
+ * 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.
@@ -47,14 +107,10 @@ export type IsoBuffer = Buffer;
  *
  * @internal
  */
-export function Uint8ArrayToString(
-	arr: Uint8Array,
-	// eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
-	encoding?: "utf8" | "utf-8" | "base64",
-): string {
+export function Uint8ArrayToString(arr: Uint8Array, encoding?: IsoBufferEncoding): string {
 	// Buffer extends Uint8Array.  Therefore, 'arr' may already be a Buffer, in
 	// which case we can avoid copying the Uint8Array into a new Buffer instance.
-	return (Buffer.isBuffer(arr) ? arr : Buffer.from(arr)).toString(encoding);
+	return (IsoBuffer.isBuffer(arr) ? arr : IsoBuffer.from(arr)).toString(encoding);
 }
 
 /**
@@ -63,7 +119,7 @@ export function Uint8ArrayToString(
  *
  * @internal
  */
-export function stringToBuffer(input: string, encoding: string): ArrayBuffer {
+export function stringToBuffer(input: string, encoding: IsoBufferEncoding): ArrayBuffer {
 	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
@@ -83,7 +139,7 @@ export function stringToBuffer(input: string, encoding: string): ArrayBuffer {
  * @internal
  */
 export const bufferToString = (
-	blob: ArrayBufferLike,
-	// eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
-	encoding: "utf8" | "utf-8" | "base64",
-): string => IsoBuffer.from(blob).toString(encoding);
+	blob: ArrayBufferLike | Uint8Array,
+	encoding: IsoBufferEncoding,
+): string =>
+	Uint8ArrayToString(blob instanceof Uint8Array ? blob : IsoBuffer.from(blob), encoding);

package/src/bufferShared.ts

@@ -4,14 +4,84 @@
  */
 
 /**
- * Converts a Uint8Array array to an ArrayBuffer.
- * @param array - Array to convert to ArrayBuffer.
+ * Distills an `ArrayBuffer` from an `ArrayBufferLike` or creates one from `SharedArrayBuffer` if needed.
+ *
+ * @param buffer - `ArrayBuffer` or any `ArrayBufferLike` to convert to `ArrayBuffer`.
+ *
+ * @remarks The returned buffer may be the input array's backing buffer or a copy of its bytes.
+ * Callers should not mutate the returned buffer unless they own the input array and its backing
+ * storage, and should not rely on mutations being reflected in the input array.
+ *
+ * @internal
+ */
+export function ArrayBufferLikeToArrayBuffer(buffer: ArrayBufferLike): ArrayBuffer {
+	if (buffer instanceof ArrayBuffer) {
+		return buffer;
+	}
+	// Use .slice to get `ArrayBuffer` backing that `Blob` requires.
+	// Note that `buffer.slice` preserves the underlying buffer type, so we
+	// need to use .slice on a `Uint8Array` to ensure we get an `ArrayBuffer`.
+	// eslint-disable-next-line unicorn/prefer-spread -- spread is not the same as slice for `Uint8Array`
+	return new Uint8Array(buffer).slice().buffer;
+}
+
+/**
+ * Distills a `Uint8Array` array to an `ArrayBuffer | SharedArrayBuffer` copying
+ * data as needed per the array's `byteOffset` and `byteLength` to have a full
+ * buffer (no offset and entire length).
+ *
+ * @param array - Array to extract buffer from.
+ *
+ * @remarks The returned buffer may be the input array's backing buffer or a copy of its bytes.
+ * Callers should not mutate the returned buffer unless they own the input array and its backing
+ * storage, and should not rely on mutations being reflected in the input array.
  *
  * @internal
  */
-export function Uint8ArrayToArrayBuffer(array: Uint8Array): ArrayBuffer {
+export function Uint8ArrayToArrayBufferLike<TArrayBuffer extends ArrayBufferLike>(
+	array: Uint8Array<TArrayBuffer>,
+): TArrayBuffer {
 	if (array.byteOffset === 0 && array.byteLength === array.buffer.byteLength) {
 		return array.buffer;
 	}
-	return array.buffer.slice(array.byteOffset, array.byteOffset + array.byteLength);
+	// Both ArrayBuffer and SharedArrayBuffer have a slice method and will return
+	// their same type, but TypeScript does not correctly determine that will
+	// satisfy TArrayBuffer. Cast to TArrayBuffer to indicate that.
+	return array.buffer.slice(
+		array.byteOffset,
+		array.byteOffset + array.byteLength,
+	) as TArrayBuffer;
+}
+
+/**
+ * Distills a `Uint8Array` array to an `ArrayBuffer` copying data as needed per the array's
+ * `byteOffset` and `byteLength` or if underlying buffer is not `ArrayBuffer`.
+ *
+ * @param array - Array to convert to `ArrayBuffer`.
+ *
+ * @remarks The returned buffer may be the input array's backing buffer or a copy of its bytes.
+ * Callers should not mutate the returned buffer unless they own the input array and its backing
+ * storage, and should not rely on mutations being reflected in the input array.
+ *
+ * Prefer to use {@link Uint8ArrayToArrayBufferLike} if the call site doesn't require
+ * an explicit `ArrayBuffer` (can also handle `SharedArrayBuffer`).
+ *
+ * @internal
+ */
+export function AnyUint8ArrayToArrayBuffer(array: Uint8Array): ArrayBuffer {
+	// Shortcut to provider underlying buffer as-is when possible.
+	if (
+		array.byteOffset === 0 &&
+		array.byteLength === array.buffer.byteLength &&
+		array.buffer instanceof ArrayBuffer
+	) {
+		return array.buffer;
+	}
+	// .slice is used to ensure underlying buffer is:
+	//  1. ArrayBuffer
+	//  2. the complete data (no offset, full length)
+	// Cloning specified per https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/slice
+	// and ECMAScript https://tc39.es/ecma262/multipage/indexed-collections.html#sec-%typedarray%.prototype.slice.
+	// eslint-disable-next-line unicorn/prefer-spread -- spread is not the same as slice for `Uint8Array`
+	return array.slice().buffer;
 }

package/src/hashFileBrowser.ts

@@ -9,7 +9,7 @@ import * as base64js from "base64-js";
 import { IsoBuffer } from "./bufferBrowser.js";
 
 async function digestBuffer(
-	file: IsoBuffer,
+	file: IsoBuffer<ArrayBuffer>,
 	algorithm: "SHA-1" | "SHA-256",
 ): Promise<Uint8Array> {
 	const hash = await crypto.subtle.digest(algorithm, file);
@@ -48,7 +48,7 @@ function encodeDigest(hashArray: Uint8Array, encoding: "hex" | "base64"): string
  * @internal
  */
 export async function hashFile(
-	file: IsoBuffer,
+	file: IsoBuffer<ArrayBuffer>,
 	algorithm: "SHA-1" | "SHA-256" = "SHA-1",
 	hashEncoding: "hex" | "base64" = "hex",
 ): Promise<string> {
@@ -82,7 +82,10 @@ 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());
+	const prefixBuffer = IsoBuffer.from(filePrefix);
+	const hashBuffer = new IsoBuffer(prefixBuffer.byteLength + file.byteLength);
+	hashBuffer.set(prefixBuffer);
+	hashBuffer.set(file, prefixBuffer.byteLength);
 
 	// hashFile uses sha1; if that changes this will need to change too
 	return hashFile(hashBuffer);

package/src/hashFileNode.ts

@@ -20,9 +20,13 @@ import type { IsoBuffer } from "./bufferNode.js";
  * @returns The hash of the content of the buffer.
  *
  * @internal
+ *
+ * @privateRemarks
+ * This function does not strictly require `<ArrayBuffer>` backing, but it is typed
+ * that way to match the browser implementation, which does require `<ArrayBuffer>` backing.
  */
 export async function hashFile(
-	file: IsoBuffer,
+	file: IsoBuffer<ArrayBuffer>,
 	algorithm: "SHA-1" | "SHA-256" = "SHA-1",
 	hashEncoding: "hex" | "base64" = "hex",
 ): Promise<string> {
@@ -50,8 +54,12 @@ export async function hashFile(
  * @returns The sha1 hash of the content of the buffer with the `blob` prefix and size
  *
  * @internal
+ *
+ * @privateRemarks
+ * This function does not strictly require `<ArrayBuffer>` backing, but it is typed
+ * that way to match the browser implementation, which does require `<ArrayBuffer>` backing.
  */
-export async function gitHashFile(file: IsoBuffer): Promise<string> {
+export async function gitHashFile(file: IsoBuffer<ArrayBuffer>): Promise<string> {
 	const size = file.byteLength;
 	// eslint-disable-next-line unicorn/prefer-code-point
 	const filePrefix = `blob ${size.toString()}${String.fromCharCode(0)}`;