@keeex/utils 7.0.1

package/lib/base58.js

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * 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.
+ * 
+ */
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+// Source was tracked back to:
+// https://gist.github.com/diafygi/90a3e80ca1c2793220e5/
+// License at the time of writing is "DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE"
+// which I think allows cleaning and reusing.
+const MAP = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const toB58 = (input, mapping) => {
+    const b58Digits = [];
+    let result = "";
+    let b58DigitsIndex = 0;
+    const len = input.byteLength;
+    for (let inputIndex = 0; inputIndex < len; ++inputIndex) {
+        let carryAmount = input[inputIndex];
+        b58DigitsIndex = 0;
+        if (!(carryAmount || result.length ^ inputIndex))
+            result += "1";
+        while (b58DigitsIndex in b58Digits || carryAmount) {
+            let pushedValue = b58Digits[b58DigitsIndex];
+            pushedValue = pushedValue ? pushedValue * 256 + carryAmount : carryAmount;
+            carryAmount = (pushedValue / 58) | 0;
+            b58Digits[b58DigitsIndex] = pushedValue % 58;
+            b58DigitsIndex++;
+        }
+    }
+    while (b58DigitsIndex--)
+        result += mapping[b58Digits[b58DigitsIndex]];
+    return result;
+};
+const fromB58 = (base58, mapping) => {
+    const remainder = [];
+    const resultBytes = [];
+    let remainderIndex = 0;
+    const len = base58.length;
+    for (let inputIndex = 0; inputIndex < len; ++inputIndex) {
+        let currentInput = mapping.indexOf(base58[inputIndex]);
+        remainderIndex = 0;
+        if (currentInput < 0)
+            throw new Error("Unexpected state");
+        if (!(currentInput || resultBytes.length ^ inputIndex))
+            resultBytes.push(0);
+        while (remainderIndex in remainder || currentInput) {
+            let currentValue = remainder[remainderIndex];
+            currentValue = currentValue ? currentValue * 58 + currentInput : currentInput;
+            currentInput = currentValue >> 8;
+            remainder[remainderIndex] = currentValue % 256;
+            remainderIndex++;
+        }
+    }
+    while (remainderIndex--)
+        resultBytes.push(remainder[remainderIndex]);
+    return new Uint8Array(resultBytes);
+};
+/** @public */
+export const encode = (data) => toB58(data, MAP);
+/** @public */
+export const decode = (b58) => fromB58(b58, MAP);
+const BYTE_COUNT = 256;
+const B58_COUNT = 58;
+/** Compute the expected length of a base58 encoding */
+const getBase58LengthFromBuf8 = (dataLengthInBytes) => Math.ceil((dataLengthInBytes * Math.log(BYTE_COUNT)) / Math.log(B58_COUNT));
+/**
+ * Encode a buf8 with base58.
+ *
+ * The output is padded accordingly to always accomodate a buffer of the full length of the input.
+ *
+ * @public
+ */
+export const encodePad = (data) => encode(data).padStart(getBase58LengthFromBuf8(data.byteLength), "1");

package/lib/base64.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * 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.
+ * 
+ */
+/** @public */
+export declare const buf82B64: (buffer: ArrayBuffer | Uint8Array) => string;
+export interface ArmorB64Input {
+    buffer: ArrayBuffer | Uint8Array;
+    label: string;
+    bagAttributes?: string;
+}
+interface Buf2ArmorB64 {
+    (buffer: ArrayBuffer | Uint8Array, label?: string, lineWidth?: number, bagAttributes?: string): string;
+    (input: ArmorB64Input | Array<ArmorB64Input>, lineWidth?: number): string;
+}
+/** @public */
+export declare const buf82ArmorB64: Buf2ArmorB64;
+export interface ArmorBase64Data {
+    arrayBuffer: ArrayBuffer;
+    buf8: Uint8Array;
+    label: string;
+    bagAttributes?: string;
+}
+/** @public */
+export declare const armorB642Buf8: (armorB64: string) => ArmorBase64Data;
+/** @public */
+export declare const multipleArmorB642Buf8: (armorB64: string) => Array<ArmorBase64Data>;
+/**
+ * Return the length of the data in a b64 string.
+ *
+ * @public
+ */
+export declare const b64Len: (data: string, strict: boolean) => number;
+/**
+ * Return the length of the data in an armored b64 string.
+ *
+ * @public
+ */
+export declare const armorB64Len: (armorB64: string) => number;
+export {};

package/lib/base64.js

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * 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.
+ * 
+ */
+import { asArray } from "./array.js";
+import { ab2b64, b642ab } from "./bits/arraybuffer.js";
+import { b64Len as b64LenBits } from "./bits/base64.js";
+import { getUint8Array } from "./bits/uint8array.js";
+import { buf82b64 } from "./uint8array.js";
+/** @public */
+export const buf82B64 = (buffer) => buffer instanceof ArrayBuffer ? ab2b64(buffer) : buf82b64(buffer);
+const headerBegin = "-----BEGIN ";
+const headerEnd = "-----END ";
+const headerSuffix = "-----";
+const bagAttributesHeader = "Bag Attributes";
+const singleInput2ArmorB64 = ({ buffer, label, bagAttributes }, lineWidth) => {
+    const b64Data = buf82B64(buffer);
+    const splitB64Data = lineWidth >= b64Data.length
+        ? b64Data
+        : (b64Data.match(new RegExp(`(.{1,${lineWidth}})`, "gu"))?.join("\n") ?? "");
+    const header = `${headerBegin}${label}${headerSuffix}\n`;
+    const footer = `\n${headerEnd}${label}${headerSuffix}\n`;
+    const bag = bagAttributes ? `${bagAttributesHeader}\n${bagAttributes}\n` : "";
+    return `${bag}${header}${splitB64Data}${footer}`;
+};
+const DEFAULT_WIDTH = 64;
+/** @public */
+export const buf82ArmorB64 = (bufferOrInput, labelOrLineWidth, lineWidth, bagAttributes) => {
+    if (bufferOrInput instanceof ArrayBuffer || bufferOrInput instanceof Uint8Array) {
+        const label = labelOrLineWidth ?? "DATA";
+        return singleInput2ArmorB64({
+            bagAttributes: bagAttributes,
+            buffer: bufferOrInput,
+            label: label,
+        }, lineWidth ?? DEFAULT_WIDTH);
+    }
+    return asArray(bufferOrInput)
+        .map((input) => singleInput2ArmorB64(input, labelOrLineWidth ?? DEFAULT_WIDTH))
+        .join("");
+};
+const splitArmorB64 = (armorB64) => {
+    const res = [];
+    const lines = armorB64.split("\n");
+    const bagAttributesLines = [];
+    let inBagAttributes = false;
+    // eslint-disable-next-line @typescript-eslint/init-declarations
+    let base64Begin;
+    for (let i = 0; i < lines.length; ++i) {
+        const line = lines[i];
+        if (base64Begin === undefined) {
+            if (line.startsWith(headerBegin) && line.endsWith(headerSuffix)) {
+                inBagAttributes = false;
+                base64Begin = i;
+            }
+            else if (inBagAttributes) {
+                bagAttributesLines.push(line);
+            }
+            else if (line.startsWith(bagAttributesHeader)) {
+                inBagAttributes = true;
+            }
+        }
+        else if (line.startsWith(headerEnd) && line.endsWith(headerSuffix)) {
+            const bagAttributes = bagAttributesLines.length > 0 ? bagAttributesLines.join("\n") : undefined;
+            const headLine = lines[base64Begin];
+            const label = headLine.substring(headerBegin.length, headLine.length - headerSuffix.length);
+            const labelEnd = line.substring(headerEnd.length, line.length - headerSuffix.length);
+            if (label !== labelEnd)
+                throw new Error("Invalid end marker");
+            res.push({
+                b64: lines.slice(base64Begin + 1, i).join(""),
+                bagAttributes,
+                label: headLine.substring(headerBegin.length, headLine.length - headerSuffix.length),
+            });
+            base64Begin = undefined;
+            bagAttributesLines.length = 0;
+        }
+    }
+    if (res.length === 0)
+        throw new Error("Not an armored base64 input");
+    return res;
+};
+/** @public */
+export const armorB642Buf8 = (armorB64) => {
+    const [{ label, b64, bagAttributes }] = splitArmorB64(armorB64);
+    const arrayBuffer = b642ab(b64, false);
+    return {
+        arrayBuffer,
+        bagAttributes,
+        buf8: getUint8Array(arrayBuffer),
+        label,
+    };
+};
+/** @public */
+export const multipleArmorB642Buf8 = (armorB64) => {
+    const splitted = splitArmorB64(armorB64);
+    return splitted.map(({ b64, label, bagAttributes }) => {
+        const arrayBuffer = b642ab(b64, false);
+        return { arrayBuffer, bagAttributes, buf8: getUint8Array(arrayBuffer), label };
+    });
+};
+/**
+ * Return the length of the data in a b64 string.
+ *
+ * @public
+ */
+export const b64Len = (data, strict) => b64LenBits(data, strict);
+/**
+ * Return the length of the data in an armored b64 string.
+ *
+ * @public
+ */
+export const armorB64Len = (armorB64) => {
+    const [{ b64 }] = splitArmorB64(armorB64);
+    return b64Len(b64, false);
+};

package/lib/benchmark.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * 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.
+ * 
+ */
+import { Awaitable } from "./types/types.js";
+export type BenchmarkFunction = (() => Promise<void>) | (() => void);
+/**
+ * Run the provided function for given iterations and return the average runtime in ms.
+ *
+ * @public
+ */
+export declare const benchmarkTime: (func: BenchmarkFunction, iterations: number) => Promise<number>;
+interface DynamicBenchSettings {
+    /**
+     * Minimum number of run before we can stop.
+     *
+     * Defaults to 5.
+     */
+    minRun?: number;
+    /**
+     * Maximum number of run after which we stop trying to get a stable value.
+     *
+     * When either this value or maxDuration is exceeded, the benchmark gives up.
+     *
+     * Defaults to 10000.
+     */
+    maxRun?: number;
+    /**
+     * Maximum duration before the benchmark gives up on running new iterations.
+     *
+     * When either this value or maxDuration is exceeded, the benchmark gives up.
+     *
+     * Defaults to never.
+     */
+    maxDurationMs?: number;
+    /**
+     * Number of runs to keep to compute the average duration.
+     *
+     * Defaults to 5.
+     */
+    averageWindowSize?: number;
+    /**
+     * Number of consecutive run that must fit withing the margin of error.
+     *
+     * If the average of the last `stableRun` are closer than `maxDeltaMs` to the average duration,
+     * the benchmark completes.
+     *
+     * Defaults to 3.
+     */
+    stableRun?: number;
+    /**
+     * Maximum delta between the fastest and slowest iteration in the last `stableRun` runs to accept.
+     *
+     * If the average of the last `stableRun` are closer than `maxDeltaMs` to the average duration,
+     * the benchmark completes.
+     *
+     * Defaults to 10 (ms).
+     */
+    maxDeltaMs?: number;
+    /** Set to true to output debug on the console when running the benchmark */
+    debugLog?: boolean;
+}
+interface DynamicBenchSimple extends DynamicBenchSettings {
+    /**
+     * Function to benchmark.
+     *
+     * Make sure this function can be called multiple time without side effect and for roughly the
+     * same duration each time.
+     */
+    func: BenchmarkFunction;
+}
+interface DynamicBenchAdvanced extends DynamicBenchSettings {
+    /**
+     * Function that return the adjusted function to benchmark.
+     *
+     * This function receive a multiplier as its single parameter, starting at 1.
+     * This value is increased until either the function duration is above the given threshold or it
+     * reaches a set maximum.
+     */
+    getFunc: (multiplier: number) => Awaitable<BenchmarkFunction>;
+    /**
+     * Maximum value for the multiplier.
+     *
+     * Defaults to 1000.
+     */
+    maxMultiplier?: number;
+    /**
+     * Minimum value for the function duration.
+     *
+     * Defaults to 10.
+     */
+    minFuncDurationMs?: number;
+}
+/**
+ * Benchmark the duration of a function.
+ *
+ * This benchmark will run the function multiple time until it reaches a stable average.
+ *
+ * @public
+ */
+export declare const dynamicBenchmark: (dynamicBenchSetup: DynamicBenchSimple) => Promise<number>;
+interface AdvancedBenchmarkResult {
+    multiplier: number;
+    durationMs: number;
+}
+/**
+ * Advanced dynamic benchmark where the length of the benchmark function can be adjusted.
+ *
+ * The `multiplier` property/parameter can be increased as needed until the benchmark function reach
+ * a given minimum duration, after which it is effectively benchmarked.
+ *
+ * @public
+ */
+export declare const advancedDynamicBenchmark: (dynamicBenchSetup: DynamicBenchAdvanced) => Promise<AdvancedBenchmarkResult>;
+export {};

package/lib/benchmark.js

@@ -0,0 +1,177 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * 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.
+ * 
+ */
+import { createLogger } from "@keeex/log";
+/** Return now() up to the best precision available */
+const getNow = typeof performance.now === "function"
+    ? () => performance.now()
+    : () => Date.now();
+/**
+ * Run the provided function for given iterations and return the average runtime in ms.
+ *
+ * @public
+ */
+export const benchmarkTime = async (func, iterations) => {
+    const usePromises = func() instanceof Promise;
+    const start = getNow();
+    if (usePromises) {
+        // eslint-disable-next-line no-await-in-loop
+        for (let i = 0; i < iterations; ++i)
+            await func();
+    }
+    else {
+        // We checked that the function does not return a promise above
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        for (let i = 0; i < iterations; ++i)
+            func();
+    }
+    const end = getNow();
+    const delta = end - start;
+    return delta / iterations;
+};
+/** Benchmark the function once */
+const benchOneRun = async (usePromise, func) => {
+    if (usePromise) {
+        const before = getNow();
+        await func();
+        return getNow() - before;
+    }
+    const before = getNow();
+    func();
+    return getNow() - before;
+};
+const getBenchFuncInfo = async (func) => {
+    const before = getNow();
+    const testRun = func();
+    const isPromise = testRun instanceof Promise;
+    if (isPromise)
+        await testRun;
+    const firstRunDurationMs = getNow() - before;
+    return { isPromise, firstRunDurationMs };
+};
+/** Compute the average of an array, excluding the max and min value */
+const computeAverage = (values) => {
+    const maxValue = Math.max(...values);
+    const minValue = Math.min(...values);
+    const filtered = [...values];
+    filtered.splice(filtered.indexOf(maxValue), 1);
+    filtered.splice(filtered.indexOf(minValue), 1);
+    return filtered.reduce((acc, cur) => acc + cur) / filtered.length;
+};
+const addToAverageWindow = (value, window, len) => {
+    while (window.length >= len)
+        window.shift();
+    window.push(value);
+};
+let logger = null;
+const getLogger = () => {
+    logger ??= createLogger({ tag: "@keeex/js-utils:benchmark" });
+    return logger;
+};
+const getLog = (printDebug) => printDebug
+    ? (msg) => {
+        getLogger().info(msg);
+    }
+    : // eslint-disable-next-line @typescript-eslint/no-empty-function
+        () => { };
+const defaultBenchConfig = {
+    averageWindowSize: 5,
+    debugLog: false,
+    maxDeltaMs: 10,
+    maxRun: 10000,
+    minRun: 5,
+    stableRun: 3,
+};
+/**
+ * Benchmark the duration of a function.
+ *
+ * This benchmark will run the function multiple time until it reaches a stable average.
+ *
+ * @public
+ */
+export const dynamicBenchmark = async (dynamicBenchSetup) => {
+    const cfg = { ...defaultBenchConfig, ...dynamicBenchSetup };
+    const log = getLog(cfg.debugLog);
+    log("Getting benchmark function informations");
+    const funcInfo = await getBenchFuncInfo(cfg.func);
+    let runCounter = 1;
+    log(`First run: ${funcInfo.firstRunDurationMs}ms; use promises: ${funcInfo.isPromise ? "true" : "false"}`);
+    const averageWindow = [];
+    averageWindow.push(funcInfo.firstRunDurationMs);
+    log("Filling average window with initial runs");
+    while (averageWindow.length < cfg.averageWindowSize || runCounter < cfg.minRun) {
+        log(`Run ${runCounter + 1}`);
+        addToAverageWindow(
+        // eslint-disable-next-line no-await-in-loop
+        await benchOneRun(funcInfo.isPromise, cfg.func), averageWindow, cfg.averageWindowSize);
+        ++runCounter;
+    }
+    let consecutiveSuccess = 0;
+    while (runCounter < cfg.maxRun) {
+        const currentAverage = computeAverage(averageWindow);
+        log(`Doing new run ${runCounter + 1}`);
+        // eslint-disable-next-line no-await-in-loop
+        const nextRun = await benchOneRun(funcInfo.isPromise, cfg.func);
+        ++runCounter;
+        if (Math.abs(currentAverage - nextRun) <= cfg.maxDeltaMs) {
+            log(`Average run: ${currentAverage}ms, new run: ${nextRun}ms, under delta ${cfg.maxDeltaMs}`);
+            ++consecutiveSuccess;
+        }
+        else {
+            log(`Average run: ${currentAverage}ms, new run: ${nextRun}ms, over delta ${cfg.maxDeltaMs}`);
+            consecutiveSuccess = 0;
+        }
+        averageWindow.shift();
+        averageWindow.push(nextRun);
+        if (consecutiveSuccess >= cfg.stableRun) {
+            log(`Found ${consecutiveSuccess} successive run under delta, ending benchmark`);
+            break;
+        }
+    }
+    if (consecutiveSuccess < cfg.stableRun)
+        log("Benchmark was inconclusive");
+    return computeAverage(averageWindow);
+};
+const advancedDefaults = {
+    maxMultiplier: 1000,
+    minFuncDurationMs: 10,
+};
+/**
+ * Advanced dynamic benchmark where the length of the benchmark function can be adjusted.
+ *
+ * The `multiplier` property/parameter can be increased as needed until the benchmark function reach
+ * a given minimum duration, after which it is effectively benchmarked.
+ *
+ * @public
+ */
+export const advancedDynamicBenchmark = async (dynamicBenchSetup) => {
+    const cfg = { ...advancedDefaults, ...dynamicBenchSetup };
+    const log = getLog(cfg.debugLog);
+    // eslint-disable-next-line @typescript-eslint/init-declarations
+    let durationMs;
+    let multiplier = 0;
+    while (durationMs === undefined ||
+        (durationMs < cfg.minFuncDurationMs && multiplier <= cfg.maxMultiplier)) {
+        log(`Advanced benchmark, multiplier: ${multiplier}`);
+        ++multiplier;
+        // eslint-disable-next-line no-await-in-loop
+        const func = await cfg.getFunc(multiplier);
+        // eslint-disable-next-line no-await-in-loop
+        durationMs = await dynamicBenchmark({ ...cfg, func });
+        log(`Duration: ${durationMs}ms, target: ${cfg.minFuncDurationMs}`);
+    }
+    log(`Final results: ${durationMs}ms with multiplier ${multiplier}`);
+    return { multiplier, durationMs };
+};

package/lib/bits/arraybuffer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * 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.
+ * 
+ */
+/**
+ * Return an ArrayBuffer that match the provided Uint8Array
+ *
+ * @public
+ */
+export declare const getArrayBuffer: (typedArray: ArrayBuffer | Uint8Array) => ArrayBuffer;
+/**
+ * Convert an array buffer to a b64 string
+ *
+ * @public
+ */
+export declare const ab2b64: (data: ArrayBuffer) => string;
+/**
+ * Convert a b64 string to an array buffer
+ *
+ * @param strict - If enabled, prevent input from having extra data after the B64 string.
+ *
+ * @public
+ */
+export declare const b642ab: (data: string, strict?: boolean) => ArrayBuffer;

package/lib/bits/arraybuffer.js

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * @preserve
+ *
+ * MIT License
+ * 
+ * Copyright (c) 2023 KeeeX SAS
+ * 
+ * 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.
+ * 
+ */
+import { encode as encodeB64, decode as decodeB64 } from "base64-arraybuffer";
+import { b64EffectiveData, B64_PAD2, B64_PAD1, B64_PAD0, B64_CHARBLOCK } from "./base64.js";
+/**
+ * Return an ArrayBuffer that match the provided Uint8Array
+ *
+ * @public
+ */
+export const getArrayBuffer = (typedArray) => {
+    if (typedArray instanceof ArrayBuffer)
+        return typedArray;
+    const ab = typedArray.buffer;
+    if (typedArray.byteOffset === 0 && typedArray.byteLength === ab.byteLength)
+        return ab;
+    return ab.slice(typedArray.byteOffset, typedArray.byteOffset + typedArray.byteLength);
+};
+/**
+ * Convert an array buffer to a b64 string
+ *
+ * @public
+ */
+export const ab2b64 = (data) => encodeB64(data);
+/**
+ * Convert a b64 string to an array buffer
+ *
+ * @param strict - If enabled, prevent input from having extra data after the B64 string.
+ *
+ * @public
+ */
+export const b642ab = (data, strict = false) => {
+    const effectiveData = b64EffectiveData(data, strict);
+    const result = decodeB64(effectiveData);
+    if (strict && effectiveData.length > 0) {
+        // eslint-disable-next-line @typescript-eslint/init-declarations
+        let padding;
+        if (effectiveData.endsWith("==")) {
+            padding = B64_PAD2;
+        }
+        else if (effectiveData.endsWith("=")) {
+            padding = B64_PAD1;
+        }
+        else {
+            padding = B64_PAD0;
+        }
+        const outputLength = (effectiveData.length / B64_CHARBLOCK) * (B64_CHARBLOCK - 1) - padding;
+        if (result.byteLength !== outputLength)
+            throw new Error("Invalid output length");
+    }
+    return result;
+};