@fluid-internal/client-utils 2.0.0-dev-rc.1.0.0.224419

package/.eslintrc.js

@@ -0,0 +1,16 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+module.exports = {
+	extends: [require.resolve("@fluidframework/eslint-config-fluid"), "prettier"],
+	parserOptions: {
+		project: [
+			"./tsconfig.json",
+			"./src/test/mocha/tsconfig.json",
+			"./src/test/jest/tsconfig.json",
+			"./src/test/types/tsconfig.json",
+		],
+	},
+};

package/.mocharc.js

@@ -0,0 +1,12 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+"use strict";
+
+const getFluidTestMochaConfig = require("@fluidframework/mocha-test-setup/mocharc-common");
+
+const packageDir = __dirname;
+const config = getFluidTestMochaConfig(packageDir);
+module.exports = config;

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @fluid-internal/client-utils
+
+## 2.0.0-internal.8.0.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.4.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.3.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.2.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.1.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.0.0
+
+### Minor Changes
+
+-   client-utils: Internal buffer encoding helpers now require 'utf8', 'utf-8', or 'base64' [871b3493dd](https://github.com/microsoft/FluidFramework/commits/871b3493dd0d7ea3a89be64998ceb6cb9021a04e)
+
+    Previously, the buffer encoding helpers 'Uint8ArrayToString', 'bufferToString', and 'IsoBuffer.toString' would accept a string argument, which was overly permissive.
+
+    The type of the 'encoding' argument has been narrow to just the supported values 'utf8', 'utf-8', or 'base64'.
+
+## 2.0.0-internal.6.4.0
+
+Dependency updates only.
+
+## 2.0.0-internal.6.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @fluid-internal/client-utils
+
+This package is intended for sharing and promoting utility functions across packages in the Fluid Framework repo,
+primarily within the client release group.
+
+<!-- AUTO-GENERATED-CONTENT:START (README_PACKAGE_SCOPE_NOTICE) -->
+
+**IMPORTANT: This package is intended strictly as an implementation detail of the Fluid Framework and is not intended for public consumption.**
+**We make no stability guarantees regarding its APIs.**
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+## Adding code to this package
+
+As a utility package, this package does not have a strong identity. This means that it's easy to become a "dumping
+ground" for code that we think we should share but doesn't have an obvious home. We try to avoid dumping things into
+utility packages, and this one is no exception.
+
+New code should only be added to this package in rare circumstances. In most cases, the code would be better placed in a
+package with a clear identity (e.g. an "events" package for shared event infrastructure) or not shared at all.
+
+## Requirements
+
+This package has important requirements for the code within it.
+
+1. Code within this package should require some external dependencies. If it does not, then the **core-utils** package
+   is a better location.
+1. **All exports must be designated `@internal`.** This code is intended for use within the Fluid Framework only.
+1. This package should **only contain 'implementation' code, not type definitions.** This is the most flexible rule, and
+   there are some exceptions. If the type is _only_ necessary when using this package, then it is probably OK. However,
+   usually such types would be better placed in core-interfaces or in a package that corresponds to the purpose.
+
+If you want to add code that does not meet these requirements, these other packages may be a better choice:
+
+-   **Types and interfaces** that are intended to be broadly shared across the client release group should be put in the
+    **core-interfaces** package.
+-   **Zero-dependency shared code** should be put in the **core-utils** package.
+
+<!-- AUTO-GENERATED-CONTENT:START (README_DEPENDENCY_GUIDELINES_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Using Fluid Framework libraries
+
+When taking a dependency on a Fluid Framework library, we recommend using a `^` (caret) version range, such as `^1.3.4`.
+While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries,
+library consumers should always prefer `^`.
+
+Note that when depending on a library version of the form `2.0.0-internal.x.y.z`, called the Fluid internal version scheme,
+you must use a `>= <` dependency range (such as `>=2.0.0-internal.x.y.z <2.0.0-internal.w.0.0` where `w` is `x+1`).
+Standard `^` and `~` ranges will not work as expected.
+See the [@fluid-tools/version-tools](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/version-tools/README.md)
+package for more information including tools to convert between version schemes.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+<!-- AUTO-GENERATED-CONTENT:START (README_TRADEMARK_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Trademark
+
+This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
+
+Use of these trademarks or logos must follow Microsoft's [Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->

package/api-extractor-lint.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-lint.json"
+}

package/api-extractor.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-base.json"
+}

package/api-report/client-utils.api.md

@@ -0,0 +1,130 @@
+## API Report File for "@fluid-internal/client-utils"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+/// <reference types="node" />
+
+import { EventEmitter } from 'events';
+import { IDisposable } from '@fluidframework/core-interfaces';
+import { IEvent } from '@fluidframework/core-interfaces';
+import { IEventProvider } from '@fluidframework/core-interfaces';
+import { IEventTransformer } from '@fluidframework/core-interfaces';
+import { TransformedEvent } from '@fluidframework/core-interfaces';
+
+// @internal
+class Buffer_2 extends Uint8Array {
+    static from(value: unknown, encodingOrOffset?: unknown, length?: unknown): IsoBuffer;
+    // (undocumented)
+    static isBuffer(obj: unknown): obj is Buffer_2;
+    // (undocumented)
+    toString(encoding?: "utf8" | "utf-8" | "base64"): string;
+}
+export { Buffer_2 as Buffer }
+
+// @alpha
+export const bufferToString: (blob: ArrayBufferLike, encoding: "utf8" | "utf-8" | "base64") => string;
+
+// @public
+export type EventEmitterEventType = EventEmitter extends {
+    on(event: infer E, listener: any): any;
+} ? E : never;
+
+// @internal
+export class EventForwarder<TEvent = IEvent> extends TypedEventEmitter<TEvent> implements IDisposable {
+    constructor(source?: EventEmitter | IEventProvider<TEvent & IEvent>);
+    // (undocumented)
+    dispose(): void;
+    // (undocumented)
+    get disposed(): boolean;
+    // (undocumented)
+    protected forwardEvent(source: EventEmitter | IEventProvider<TEvent & IEvent>, ...events: string[]): void;
+    // (undocumented)
+    protected static isEmitterEvent(event: string): boolean;
+    // (undocumented)
+    protected unforwardEvent(source: EventEmitter | IEventProvider<TEvent & IEvent>, ...events: string[]): void;
+}
+
+// @internal
+export const fromBase64ToUtf8: (input: string) => string;
+
+// @internal
+export const fromUtf8ToBase64: (input: string) => string;
+
+// @internal
+export function gitHashFile(file: IsoBuffer): Promise<string>;
+
+// @internal
+export function hashFile(file: IsoBuffer, algorithm?: "SHA-1" | "SHA-256", hashEncoding?: "hex" | "base64"): Promise<string>;
+
+// @internal (undocumented)
+export const IsoBuffer: typeof Buffer_2;
+
+// @internal (undocumented)
+export type IsoBuffer = Buffer_2;
+
+// @internal
+export type IsomorphicPerformance = Partial<Performance> & Pick<Performance, "clearMarks" | "mark" | "measure" | "now">;
+
+// @internal
+export interface ITraceEvent {
+    readonly duration: number;
+    readonly tick: number;
+    readonly totalTimeElapsed: number;
+}
+
+// @internal
+const performance_2: IsomorphicPerformance;
+export { performance_2 as performance }
+
+// @internal
+export function stringToBuffer(input: string, encoding: string): ArrayBufferLike;
+
+// @internal
+export const toUtf8: (input: string, encoding: string) => string;
+
+// @internal
+export class Trace {
+    protected constructor(startTick: number);
+    // (undocumented)
+    protected lastTick: number;
+    // (undocumented)
+    static start(): Trace;
+    // (undocumented)
+    readonly startTick: number;
+    // (undocumented)
+    trace(): ITraceEvent;
+}
+
+// @public
+export class TypedEventEmitter<TEvent> extends EventEmitter implements IEventProvider<TEvent & IEvent> {
+    constructor();
+    // (undocumented)
+    readonly addListener: TypedEventTransform<this, TEvent>;
+    // (undocumented)
+    readonly off: TypedEventTransform<this, TEvent>;
+    // (undocumented)
+    readonly on: TypedEventTransform<this, TEvent>;
+    // (undocumented)
+    readonly once: TypedEventTransform<this, TEvent>;
+    // (undocumented)
+    readonly prependListener: TypedEventTransform<this, TEvent>;
+    // (undocumented)
+    readonly prependOnceListener: TypedEventTransform<this, TEvent>;
+    // (undocumented)
+    readonly removeListener: TypedEventTransform<this, TEvent>;
+}
+
+// @public (undocumented)
+export type TypedEventTransform<TThis, TEvent> = TransformedEvent<TThis, "newListener" | "removeListener", Parameters<(event: string, listener: (...args: any[]) => void) => void>> & IEventTransformer<TThis, TEvent & IEvent> & TransformedEvent<TThis, EventEmitterEventType, any[]>;
+
+// @internal
+export function Uint8ArrayToArrayBuffer(array: Uint8Array): ArrayBuffer;
+
+// @internal
+export function Uint8ArrayToString(arr: Uint8Array, encoding?: "utf8" | "utf-8" | "base64"): string;
+
+// (No @packageDocumentation comment for this package)
+
+```

package/dist/base64Encoding.cjs

@@ -0,0 +1,46 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toUtf8 = exports.fromUtf8ToBase64 = exports.fromBase64ToUtf8 = void 0;
+const indexNode_1 = require("./indexNode.cjs");
+/**
+ * Converts the provided {@link https://en.wikipedia.org/wiki/Base64 | base64}-encoded string
+ * to {@link https://en.wikipedia.org/wiki/UTF-8 | utf-8}.
+ *
+ * @internal
+ */
+const fromBase64ToUtf8 = (input) => indexNode_1.IsoBuffer.from(input, "base64").toString("utf8");
+exports.fromBase64ToUtf8 = fromBase64ToUtf8;
+/**
+ * Converts the provided {@link https://en.wikipedia.org/wiki/UTF-8 | utf-8}-encoded string
+ * to {@link https://en.wikipedia.org/wiki/Base64 | base64}.
+ *
+ * @internal
+ */
+const fromUtf8ToBase64 = (input) => indexNode_1.IsoBuffer.from(input, "utf8").toString("base64");
+exports.fromUtf8ToBase64 = fromUtf8ToBase64;
+/**
+ * Convenience function to convert unknown encoding to utf8 that avoids
+ * buffer copies/encode ops when no conversion is needed.
+ * @param input - The source string to convert.
+ * @param encoding - The source string's encoding.
+ *
+ * @internal
+ */
+const toUtf8 = (input, encoding) => {
+    switch (encoding) {
+        case "utf8":
+        // eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
+        case "utf-8": {
+            return input;
+        }
+        default: {
+            return indexNode_1.IsoBuffer.from(input, encoding).toString();
+        }
+    }
+};
+exports.toUtf8 = toUtf8;
+//# sourceMappingURL=base64Encoding.cjs.map

package/dist/base64Encoding.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64Encoding.cjs","sourceRoot":"","sources":["../src/base64Encoding.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,+CAAwC;AAExC;;;;;GAKG;AACI,MAAM,gBAAgB,GAAG,CAAC,KAAa,EAAU,EAAE,CACzD,qBAAS,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AADrC,QAAA,gBAAgB,oBACqB;AAElD;;;;;GAKG;AACI,MAAM,gBAAgB,GAAG,CAAC,KAAa,EAAU,EAAE,CACzD,qBAAS,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AADrC,QAAA,gBAAgB,oBACqB;AAElD;;;;;;;GAOG;AACI,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,QAAgB,EAAU,EAAE;IACjE,QAAQ,QAAQ,EAAE;QACjB,KAAK,MAAM,CAAC;QACZ,8GAA8G;QAC9G,KAAK,OAAO,CAAC,CAAC;YACb,OAAO,KAAK,CAAC;SACb;QACD,OAAO,CAAC,CAAC;YACR,OAAO,qBAAS,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;SAClD;KACD;AACF,CAAC,CAAC;AAXW,QAAA,MAAM,UAWjB","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IsoBuffer } from \"./indexNode\";\n\n/**\n * Converts the provided {@link https://en.wikipedia.org/wiki/Base64 | base64}-encoded string\n * to {@link https://en.wikipedia.org/wiki/UTF-8 | utf-8}.\n *\n * @internal\n */\nexport const fromBase64ToUtf8 = (input: string): string =>\n\tIsoBuffer.from(input, \"base64\").toString(\"utf8\");\n\n/**\n * Converts the provided {@link https://en.wikipedia.org/wiki/UTF-8 | utf-8}-encoded string\n * to {@link https://en.wikipedia.org/wiki/Base64 | base64}.\n *\n * @internal\n */\nexport const fromUtf8ToBase64 = (input: string): string =>\n\tIsoBuffer.from(input, \"utf8\").toString(\"base64\");\n\n/**\n * Convenience function to convert unknown encoding to utf8 that avoids\n * buffer copies/encode ops when no conversion is needed.\n * @param input - The source string to convert.\n * @param encoding - The source string's encoding.\n *\n * @internal\n */\nexport const toUtf8 = (input: string, encoding: string): string => {\n\tswitch (encoding) {\n\t\tcase \"utf8\":\n\t\t// eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged\n\t\tcase \"utf-8\": {\n\t\t\treturn input;\n\t\t}\n\t\tdefault: {\n\t\t\treturn IsoBuffer.from(input, encoding).toString();\n\t\t}\n\t}\n};\n"]}

package/dist/base64Encoding.d.ts

@@ -0,0 +1,28 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Converts the provided {@link https://en.wikipedia.org/wiki/Base64 | base64}-encoded string
+ * to {@link https://en.wikipedia.org/wiki/UTF-8 | utf-8}.
+ *
+ * @internal
+ */
+export declare const fromBase64ToUtf8: (input: string) => string;
+/**
+ * Converts the provided {@link https://en.wikipedia.org/wiki/UTF-8 | utf-8}-encoded string
+ * to {@link https://en.wikipedia.org/wiki/Base64 | base64}.
+ *
+ * @internal
+ */
+export declare const fromUtf8ToBase64: (input: string) => string;
+/**
+ * Convenience function to convert unknown encoding to utf8 that avoids
+ * buffer copies/encode ops when no conversion is needed.
+ * @param input - The source string to convert.
+ * @param encoding - The source string's encoding.
+ *
+ * @internal
+ */
+export declare const toUtf8: (input: string, encoding: string) => string;
+//# sourceMappingURL=base64Encoding.d.ts.map

package/dist/base64Encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64Encoding.d.ts","sourceRoot":"","sources":["../src/base64Encoding.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,UAAW,MAAM,KAAG,MACA,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,UAAW,MAAM,KAAG,MACA,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,UAAW,MAAM,YAAY,MAAM,KAAG,MAWxD,CAAC"}

package/dist/bufferBrowser.cjs

@@ -0,0 +1,212 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IsoBuffer = exports.isArrayBuffer = exports.bufferToString = exports.stringToBuffer = exports.Uint8ArrayToString = void 0;
+const base64js = __importStar(require("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
+ */
+function Uint8ArrayToString(arr, 
+// eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
+encoding) {
+    switch (encoding) {
+        case "base64": {
+            return base64js.fromByteArray(arr);
+        }
+        case "utf8":
+        // eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
+        case "utf-8":
+        case undefined: {
+            return new TextDecoder().decode(arr);
+        }
+        default: {
+            throw new Error("invalid/unsupported encoding");
+        }
+    }
+}
+exports.Uint8ArrayToString = Uint8ArrayToString;
+/**
+ * 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
+ */
+const stringToBuffer = (input, encoding) => IsoBuffer.from(input, encoding).buffer;
+exports.stringToBuffer = stringToBuffer;
+/**
+ * Convert binary blob to string format
+ *
+ * @param blob - the binary blob
+ * @param encoding - output string's encoding
+ * @returns the blob in string format
+ *
+ * @alpha
+ */
+const bufferToString = (blob, 
+// eslint-disable-next-line unicorn/text-encoding-identifier-case -- this value is supported, just discouraged
+encoding) => IsoBuffer.from(blob).toString(encoding);
+exports.bufferToString = bufferToString;
+/**
+ * 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
+ */
+function isArrayBuffer(obj) {
+    const maybe = obj;
+    return (obj instanceof ArrayBuffer ||
+        (typeof maybe === "object" &&
+            maybe !== null &&
+            typeof maybe.byteLength === "number" &&
+            typeof maybe.slice === "function" &&
+            maybe.byteOffset === undefined &&
+            maybe.buffer === undefined));
+}
+exports.isArrayBuffer = isArrayBuffer;
+/**
+ * Minimal implementation of Buffer for our usages in the browser environment.
+ *
+ * @internal
+ */
+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
+    toString(encoding) {
+        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, encodingOrOffset, length) {
+        if (typeof value === "string") {
+            return IsoBuffer.fromString(value, encodingOrOffset);
+            // 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, length);
+        }
+        else {
+            throw new TypeError("Input value was neither a string nor an ArrayBuffer.");
+        }
+    }
+    static fromArrayBuffer(arrayBuffer, byteOffset, byteLength) {
+        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, encoding) {
+        switch (encoding) {
+            case "base64": {
+                const sanitizedString = this.sanitizeBase64(str);
+                const encoded = base64js.toByteArray(sanitizedString);
+                return new IsoBuffer(encoded.buffer);
+            }
+            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);
+            }
+            default: {
+                throw new Error("invalid/unsupported encoding");
+            }
+        }
+    }
+    static isBuffer(obj) {
+        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.
+     */
+    static sanitizeBase64(str) {
+        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;
+    }
+}
+exports.IsoBuffer = IsoBuffer;
+//# sourceMappingURL=bufferBrowser.cjs.map

package/dist/bufferBrowser.cjs.map

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