@keeex/utils 7.0.1

package/web/units.js

@@ -0,0 +1,312 @@
+/**
+ * @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 ms from "ms";
+import { roundDecimals } from "./number.js";
+/** Coerce a delay value to milliseconds using `ms` if a string is provided */
+export const delayInMs = delayInMsValue => {
+  if (typeof delayInMsValue === "number") return delayInMsValue;
+  return ms(delayInMsValue);
+};
+/**
+ * Convert description for byte based values
+ *
+ * @public
+ */
+export const byteUnit = {
+  basename: "B",
+  levels: [{
+    multiplierFromPrevious: 1
+  },
+  // Base level
+  {
+    prefix: "k",
+    multiplierFromPrevious: 1000
+  }, {
+    prefix: "M",
+    multiplierFromPrevious: 1000
+  }, {
+    prefix: "G",
+    multiplierFromPrevious: 1000
+  }, {
+    prefix: "T",
+    multiplierFromPrevious: 1000
+  }, {
+    prefix: "P",
+    multiplierFromPrevious: 1000
+  }, {
+    prefix: "E",
+    multiplierFromPrevious: 1000
+  }, {
+    prefix: "Z",
+    multiplierFromPrevious: 1000
+  }, {
+    prefix: "Y",
+    multiplierFromPrevious: 1000
+  }, {
+    prefix: "R",
+    multiplierFromPrevious: 1000
+  }, {
+    prefix: "Q",
+    multiplierFromPrevious: 1000
+  }]
+};
+/**
+ * Convert description for small time based values
+ *
+ * Handles `ms`, `s`, `m` (minutes), `h`, `d`, `w` (weeks)
+ *
+ * @public
+ */
+export const timeUnit = {
+  basename: "s",
+  levels: [{
+    unitName: "ms",
+    multiplierFromPrevious: 1
+  }, {
+    multiplierFromPrevious: 1000
+  },
+  // Base level
+  {
+    unitName: "m",
+    multiplierFromPrevious: 60
+  }, {
+    unitName: "h",
+    multiplierFromPrevious: 60
+  }, {
+    unitName: "d",
+    multiplierFromPrevious: 24
+  }, {
+    unitName: "w",
+    multiplierFromPrevious: 7
+  }]
+};
+/** Return the full name of a level unit */
+const getUnitLevel = (unitDescription, level) => {
+  const lvl = unitDescription.levels[level];
+  return `${lvl.prefix ?? ""}${lvl.unitName ?? unitDescription.basename}${lvl.suffix ?? ""}`;
+};
+/** Prefix/suffix the numeric value with the requested unit level */
+const addUnitName = (unitDescription, numericValue, levelOrUnit) => {
+  const unitStr = typeof levelOrUnit === "string" ? levelOrUnit : getUnitLevel(unitDescription, levelOrUnit);
+  if (unitDescription.prefixUnit) return `${unitStr}${numericValue}`;
+  return `${numericValue}${unitStr}`;
+};
+/** Convert string unit into level in description */
+const convertUnit = (unitDescription, fromUnit, toUnit) => {
+  // eslint-disable-next-line @typescript-eslint/init-declarations
+  let from;
+  // eslint-disable-next-line @typescript-eslint/init-declarations
+  let to;
+  const fromTrimmed = fromUnit.trim();
+  const toTrimmed = toUnit.trim();
+  for (let candidateLevel = 0; (from === undefined || to === undefined) && candidateLevel < unitDescription.levels.length; ++candidateLevel) {
+    const candidateUnit = getUnitLevel(unitDescription, candidateLevel);
+    if (from === undefined && fromTrimmed === candidateUnit) from = candidateLevel;
+    if (to === undefined && toTrimmed === candidateUnit) to = candidateLevel;
+  }
+  if (from === undefined || to === undefined) {
+    throw new Error(`Invalid units ("${fromUnit}", "${toUnit}")`);
+  }
+  return {
+    from,
+    to
+  };
+};
+const regexBefore = /^(?<unit>[^\d]+)\d+$/u;
+const regexAfter = /^\d+(?<unit>[^\d]+)$/u;
+/** Get the unit text from an input value */
+const getUnitFromValue = (value, unitDesc) => {
+  if (typeof value !== "string") return unitDesc.basename;
+  const regex = unitDesc.prefixUnit ? regexBefore : regexAfter;
+  const res = regex.exec(value);
+  if (!res?.groups) return unitDesc.basename;
+  const unit = res.groups.unit;
+  return unit.trim();
+};
+const regexValue = /^(?:[^\d]*)(?<value>\d+)(?:[^\d]*)$/u;
+/** Get the numeric value, stripping units */
+const getNumberValue = value => {
+  if (typeof value === "number") return value;
+  const res = regexValue.exec(value);
+  if (!res?.groups) throw new Error(`Missing value (${value})`);
+  return parseFloat(res.groups.value);
+};
+/** Get the numeric value, stripping units */
+const getBigintValue = value => {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number") return BigInt(value);
+  const res = regexValue.exec(value);
+  if (!res?.groups) throw new Error(`Missing value (${value})`);
+  return BigInt(res.groups.value);
+};
+/**
+ * Convert a numerical value from a given unit multiplier to another.
+ *
+ * @param value - Either the value in the base unit multiplier, or a string with a unit
+ *
+ * @public
+ */
+export const unitConvert = (unitDescription, value, target = unitDescription.basename) => {
+  const fromUnit = getUnitFromValue(value, unitDescription);
+  const levels = convertUnit(unitDescription, fromUnit, target);
+  let resValue = getNumberValue(value);
+  let currentLevel = levels.from;
+  if (levels.from < levels.to) {
+    while (currentLevel < levels.to) {
+      ++currentLevel;
+      resValue /= unitDescription.levels[currentLevel].multiplierFromPrevious;
+    }
+  } else {
+    while (currentLevel > levels.to) {
+      resValue *= unitDescription.levels[currentLevel].multiplierFromPrevious;
+      --currentLevel;
+    }
+  }
+  return resValue;
+};
+/**
+ * Convert a numerical value from a given unit multiplier to another.
+ *
+ * This is the bigint variant, and can only handle integer values.
+ *
+ * @param value - Either the value in the base unit multiplier, or a string with a unit
+ *
+ * @public
+ */
+export const unitConvertBigint = (unitDescription, value, target = unitDescription.basename) => {
+  const fromUnit = getUnitFromValue(value, unitDescription);
+  const levels = convertUnit(unitDescription, fromUnit, target);
+  let resValue = getBigintValue(value);
+  let currentLevel = levels.from;
+  if (levels.from < levels.to) {
+    while (currentLevel < levels.to) {
+      ++currentLevel;
+      resValue /= BigInt(unitDescription.levels[currentLevel].multiplierFromPrevious);
+    }
+  } else {
+    while (currentLevel > levels.to) {
+      resValue *= BigInt(unitDescription.levels[currentLevel].multiplierFromPrevious);
+      --currentLevel;
+    }
+  }
+  return resValue;
+};
+/**
+ * Display a value in the largest relevant unit.
+ *
+ * For example, a call with "5678B" would return "5.68kB".
+ * This will lose precision and is destined to human reading.
+ *
+ * @public
+ */
+export const unitString = (unitDescription, value, decimalPlaces = 2) => {
+  let candidateLevel = 1;
+  for (; candidateLevel < unitDescription.levels.length; ++candidateLevel) {
+    const unitName = getUnitLevel(unitDescription, candidateLevel);
+    const convertedValue = unitConvert(unitDescription, value, unitName);
+    if (convertedValue < 1) break;
+  }
+  --candidateLevel;
+  const unitName = getUnitLevel(unitDescription, candidateLevel);
+  const convertedValue = roundDecimals(unitConvert(unitDescription, value, unitName), decimalPlaces);
+  return addUnitName(unitDescription, convertedValue.toString(), unitName);
+};
+/**
+ * Display a value in the largest relevant unit.
+ *
+ * Bigint variant, will not return decimal values.
+ *
+ * For example, a call with "5678B" would return "5,7kB".
+ * This will lose precision and is destined to human reading.
+ *
+ * @public
+ */
+export const unitStringBigint = (unitDescription, value) => {
+  let candidateLevel = 1;
+  for (; candidateLevel < unitDescription.levels.length; ++candidateLevel) {
+    const unitName = getUnitLevel(unitDescription, candidateLevel);
+    const convertedValue = unitConvertBigint(unitDescription, value, unitName);
+    if (convertedValue < 1) break;
+  }
+  --candidateLevel;
+  const unitName = getUnitLevel(unitDescription, candidateLevel);
+  const convertedValue = unitConvertBigint(unitDescription, value, unitName);
+  return addUnitName(unitDescription, convertedValue.toString(), unitName);
+};
+/**
+ * Convert a size in bytes from one unit to another.
+ *
+ * @param targetUnit - Target unit (`kB`, `MB`, etc.). Defaults to `B`.
+ *
+ * @public
+ */
+export const byteConvert = (value, targetUnit) => unitConvert(byteUnit, value, targetUnit);
+/**
+ * Convert a size in bytes from one unit to another.
+ *
+ * Bigint based function; can only handle integer values.
+ *
+ * @param targetUnit - Target unit (`kB`, `MB`, etc.). Defaults to `B`.
+ *
+ * @public
+ */
+export const byteConvertBigint = (value, targetUnit) => unitConvertBigint(byteUnit, value, targetUnit);
+/**
+ * Display a human-readable byte size value.
+ *
+ * @public
+ */
+export const byteString = (value, decimalPlaces) => unitString(byteUnit, value, decimalPlaces);
+/**
+ * Display a human-readable byte size value.
+ *
+ * Bigint variant, only handle integer values.
+ *
+ * @public
+ */
+export const byteStringBigint = value => unitStringBigint(byteUnit, value);
+/**
+ * Convert a short time from one unit to another.
+ *
+ * @param targetUnit - Target unit (`ms`, `h`, etc.). Defaults to `s`.
+ *
+ * @public
+ */
+export const timeConvert = (value, targetUnit) => unitConvert(timeUnit, value, targetUnit);
+/**
+ * Convert a short time from one unit to another.
+ *
+ * Biting based function; can only handle integer values.
+ *
+ * @param targetUnit - Target unit (`ms`, `h`, etc.). Defaults to `s`.
+ *
+ * @public
+ */
+export const timeConvertBigint = (value, targetUnit) => unitConvertBigint(timeUnit, value, targetUnit);
+/**
+ * Display a human-readable short time value.
+ *
+ * @public
+ */
+export const timeString = (value, decimalPlaces) => unitString(timeUnit, value, decimalPlaces);
+/**
+ * Display a human-readable short time value.
+ *
+ * Bigint variant, only handle integer values.
+ *
+ * @public
+ */
+export const timeStringBigint = value => unitStringBigint(timeUnit, value);

package/web/utils/buffer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * Check that Buffer can convert from/to Base64.
+ *
+ * @internal
+ */
+export declare const haveBufferBase64: () => boolean;
+/**
+ * Check that Buffer can convert from/to UTF8.
+ *
+ * @internal
+ */
+export declare const haveBufferUTF8: () => boolean;
+/**
+ * Check that Buffer can convert from/to hex.
+ *
+ * @internal
+ */
+export declare const haveBufferHex: () => boolean;
+/** @internal */
+export declare const bufferAb2B64: (data: ArrayBuffer) => string;
+/** @internal */
+export declare const bufferB642Ab: (data: string, strict?: boolean) => ArrayBuffer;
+/** @internal */
+export declare const bufferBuf82Hex: (buf8: Uint8Array, addPrefix?: boolean) => string;
+/** @internal */
+export declare const bufferHex2Buf8: (hex: string) => Uint8Array;
+/** @internal */
+export declare const bufferBuf82B64: (buf8: Uint8Array) => string;
+/** @internal */
+export declare const bufferB642Buf8: (b64: string, strict?: boolean) => Uint8Array;
+/** @internal */
+export declare const bufferBuf82Utf8: (buf8: Uint8Array) => string;
+/** @internal */
+export declare const bufferUtf82Buf8: (utf8: string) => Uint8Array;

package/web/utils/buffer.js

@@ -0,0 +1,76 @@
+/**
+ * @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 { getArrayBuffer } from "../bits/arraybuffer.js";
+import { b64Len, b64EffectiveData } from "../bits/base64.js";
+import { clearHexInput } from "../bits/hex.js";
+/** Check that Buffer is available somehow */
+const haveBuffer = () => typeof Buffer !== "undefined";
+/** Check that Buffer can convert from/to the given encoding */
+const haveBufferEncoding = (encodingName, testValue) => {
+  if (!haveBuffer()) {
+    return false;
+  }
+  try {
+    return Buffer.from(testValue, encodingName).toString(encodingName) === testValue;
+  } catch {
+    return false;
+  }
+};
+/**
+ * Check that Buffer can convert from/to Base64.
+ *
+ * @internal
+ */
+export const haveBufferBase64 = () => haveBufferEncoding("base64", "abcd");
+/**
+ * Check that Buffer can convert from/to UTF8.
+ *
+ * @internal
+ */
+export const haveBufferUTF8 = () => haveBufferEncoding("utf8", "Spôŗjṫìck☺");
+/**
+ * Check that Buffer can convert from/to hex.
+ *
+ * @internal
+ */
+export const haveBufferHex = () => haveBufferEncoding("hex", "deadbeef");
+/** @internal */
+export const bufferAb2B64 = data => Buffer.from(data).toString("base64");
+/** @internal */
+export const bufferB642Ab = (data, strict) => {
+  const buffer = Buffer.from(strict === undefined ? data : b64EffectiveData(data, strict), "base64");
+  if (strict && buffer.byteLength !== b64Len(data, true)) throw new Error("Invalid base64 length");
+  return getArrayBuffer(buffer);
+};
+/** @internal */
+export const bufferBuf82Hex = (buf8, addPrefix) => {
+  const hexResult = Buffer.from(buf8).toString("hex");
+  return addPrefix ? `0x${hexResult}` : hexResult;
+};
+/** @internal */
+export const bufferHex2Buf8 = hex => new Uint8Array(Buffer.from(clearHexInput(hex), "hex"));
+/** @internal */
+export const bufferBuf82B64 = buf8 => Buffer.from(buf8).toString("base64");
+/** @internal */
+export const bufferB642Buf8 = (b64, strict) => {
+  const result = new Uint8Array(Buffer.from(strict === undefined ? b64 : b64EffectiveData(b64, strict), "base64"));
+  if (strict && result.byteLength !== b64Len(b64, true)) throw new Error("Invalid base64 length");
+  return result;
+};
+/** @internal */
+export const bufferBuf82Utf8 = buf8 => Buffer.from(buf8).toString("utf8");
+/** @internal */
+export const bufferUtf82Buf8 = utf8 => new Uint8Array(Buffer.from(utf8, "utf8"));

package/web/utils/fourbytes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * Crawl a byte buffer four bytes at a time.
+ *
+ * @internal
+ */
+export default class FourBytes {
+    #private;
+    constructor(src: Uint8Array);
+    get byte1(): number | undefined;
+    get byte2(): number | undefined;
+    get byte3(): number | undefined;
+    get byte4(): number | undefined;
+    advance: (count: number) => void;
+}

package/web/utils/fourbytes.js

@@ -0,0 +1,45 @@
+/**
+ * @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.
+ * 
+ */
+// The whole purpose of this class is to count to four.
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+/**
+ * Crawl a byte buffer four bytes at a time.
+ *
+ * @internal
+ */
+export default class FourBytes {
+  #src;
+  #cursor = 0;
+  constructor(src) {
+    this.#src = src;
+  }
+  get byte1() {
+    return this.#src[this.#cursor];
+  }
+  get byte2() {
+    return this.#src[this.#cursor + 1];
+  }
+  get byte3() {
+    return this.#src[this.#cursor + 2];
+  }
+  get byte4() {
+    return this.#src[this.#cursor + 3];
+  }
+  advance = count => {
+    this.#cursor += count;
+  };
+}
+/* eslint-enable @typescript-eslint/no-magic-numbers */