@keeex/utils 7.0.1

package/web/dict.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @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.
+ * 
+ */
+export type Dictionary = Record<string, unknown>;
+/** Function used for smart copy of objects. */
+export type CopyFunction = (valueFromSecondary: unknown) => unknown;
+/**
+ * Copy all properties from secondary into primary.
+ *
+ * Update primary in place.
+ *
+ * @param copier - Function to create copy of each property values.
+ * By default create a shallow copy.
+ * The function accept one argument: the value to copy.
+ *
+ * @returns
+ * Returns primary.
+ *
+ * @public
+ */
+export declare const update: (primary: Dictionary, secondary: Dictionary, copier?: CopyFunction) => Dictionary;
+/**
+ * Merge two dictionaries.
+ *
+ * If both op1 and op2 have properties with the same key, values from op2 will erase values from
+ * op1.
+ *
+ * @param copier - Function to create copy of each property values.
+ * By default create a shallow copy.
+ * The function accept one argument: the value to copy.
+ *
+ * @public
+ */
+export declare const merge: (op1: Dictionary, op2: Dictionary, copier?: CopyFunction) => Dictionary;
+export type PrimitiveTypeObject = Record<string, unknown> | Array<unknown> | string | number | boolean;
+/**
+ * Perform a deep copy of a dictionary with only primitive types (string, number, boolean) and other
+ * objects and arrays of such types.
+ *
+ * This is not strongly typed because lazy.
+ *
+ * @public
+ */
+export declare const deepCopyPrimitive: (source: unknown) => unknown;

package/web/dict.js

@@ -0,0 +1,67 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * Copy all properties from secondary into primary.
+ *
+ * Update primary in place.
+ *
+ * @param copier - Function to create copy of each property values.
+ * By default create a shallow copy.
+ * The function accept one argument: the value to copy.
+ *
+ * @returns
+ * Returns primary.
+ *
+ * @public
+ */
+export const update = (primary, secondary, copier) => copier ? (Object.keys(secondary).forEach(propName => {
+  primary[propName] = copier(secondary[propName]);
+}), primary) : Object.assign(primary, secondary);
+/**
+ * Merge two dictionaries.
+ *
+ * If both op1 and op2 have properties with the same key, values from op2 will erase values from
+ * op1.
+ *
+ * @param copier - Function to create copy of each property values.
+ * By default create a shallow copy.
+ * The function accept one argument: the value to copy.
+ *
+ * @public
+ */
+export const merge = (op1, op2, copier) => update(update({}, op1, copier), op2, copier);
+/**
+ * Perform a deep copy of a dictionary with only primitive types (string, number, boolean) and other
+ * objects and arrays of such types.
+ *
+ * This is not strongly typed because lazy.
+ *
+ * @public
+ */
+export const deepCopyPrimitive = source => {
+  if (typeof source === "string") return source;
+  if (typeof source === "number") return source;
+  if (typeof source === "boolean") return source;
+  if (Array.isArray(source)) return source.map(deepCopyPrimitive);
+  if (typeof source === "object" && source) {
+    const res = {};
+    const rec = source;
+    for (const key of Object.keys(rec)) {
+      res[key] = deepCopyPrimitive(rec[key]);
+    }
+    return res;
+  }
+};

package/web/error.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * Make sure the provided value is an Error instance
+ *
+ * For things that are not an error, they are stringified as possible and used as a message.
+ *
+ * This function should never throw on its own.
+ *
+ * @public
+ */
+export declare const asError: (e: unknown) => Error;

package/web/error.js

@@ -0,0 +1,39 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * Make sure the provided value is an Error instance
+ *
+ * For things that are not an error, they are stringified as possible and used as a message.
+ *
+ * This function should never throw on its own.
+ *
+ * @public
+ */
+export const asError = e => {
+  if (e instanceof Error) return e;
+  if (typeof e === "string") return new Error(e);
+  const cast = e;
+  if (cast.toString && typeof cast.toString === "function") {
+    const str = cast.toString();
+    if (str !== "[object Object]") return new Error(cast.toString());
+  }
+  try {
+    return new Error(JSON.stringify(e));
+  } catch {}
+  return new Error("Unknown error", {
+    cause: e
+  });
+};

package/web/global.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * Retrieve a value stored at a global level in the current execution environment.
+ *
+ * @public
+ */
+export declare const getGlobalValue: (key: string) => unknown;
+/**
+ * Store a value at a global level in the current execution environment.
+ *
+ * @public
+ */
+export declare const setGlobalValue: (key: string, value: unknown) => void;

package/web/global.js

@@ -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.
+ * 
+ */
+const getGlobalObject = () => {
+  if (typeof window !== "undefined") return window;
+  if (typeof global !== "undefined") return global;
+  throw new Error("No global object available");
+};
+const globalKey = "kx_global_holder";
+/**
+ * Retrieve a value stored at a global level in the current execution environment.
+ *
+ * @public
+ */
+export const getGlobalValue = key => {
+  const globalObject = getGlobalObject();
+  if (!(globalKey in globalObject)) return;
+  const globalHolder = globalObject[globalKey];
+  return globalHolder[key];
+};
+/**
+ * Store a value at a global level in the current execution environment.
+ *
+ * @public
+ */
+export const setGlobalValue = (key, value) => {
+  const globalObject = getGlobalObject();
+  // eslint-disable-next-line @typescript-eslint/init-declarations
+  let globalHolder;
+  if (globalKey in globalObject) {
+    globalHolder = globalObject[globalKey];
+  } else {
+    globalHolder = {};
+    globalObject[globalKey] = globalHolder;
+  }
+  globalHolder[key] = value;
+};

package/web/hex.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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.
+ * 
+ */
+/** Add the "0x" if asked */
+export declare const prependPrefix: (value: string, prefix: boolean) => string;
+/** Check that a string is an hexadecimal string */
+export declare const isHexString: (value: string) => boolean;
+/**
+ * Convert source data to hexadecimal representation.
+ *
+ * @param src - The source value.
+ * Accepts many type of input, handled in reasonable ways:
+ *
+ * - `number` and `bigint`: converted to their hexadecimal representation
+ * - `string`: can be either an hexadecimal, base64, or IDX string
+ * - `Uint8Array` and `Array<number>`: converted to the hexadecimal representation of their content
+ *
+ * @param withPrefix - Whether to prefix the result with `0x`.
+ */
+export declare const toHex: (src: number | bigint | string | Uint8Array | Array<number>, withPrefix?: boolean) => string;

package/web/hex.js

@@ -0,0 +1,52 @@
+/**
+ * @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 * as bubble from "@keeex/bubble_babble/web/bubble_babble.js";
+import { OutputFormat } from "@keeex/bubble_babble/web/bubble_babble.js";
+import { check } from "./idx.js";
+import { b642buf8, buf82hex } from "./uint8array.js";
+const HEXA_BASE = 16;
+const HEX_PREFIX = "0x";
+/** Add the "0x" if asked */
+export const prependPrefix = (value, prefix) => {
+  if (value.startsWith(HEX_PREFIX) && !prefix) return value.slice(HEX_PREFIX.length);
+  if (!value.startsWith(HEX_PREFIX) && prefix) return `0x${value}`;
+  return value;
+};
+/** Check that a string is an hexadecimal string */
+export const isHexString = value => /^(?:0x)?[0-9a-fA-F]+$/u.test(value);
+/**
+ * Convert source data to hexadecimal representation.
+ *
+ * @param src - The source value.
+ * Accepts many type of input, handled in reasonable ways:
+ *
+ * - `number` and `bigint`: converted to their hexadecimal representation
+ * - `string`: can be either an hexadecimal, base64, or IDX string
+ * - `Uint8Array` and `Array<number>`: converted to the hexadecimal representation of their content
+ *
+ * @param withPrefix - Whether to prefix the result with `0x`.
+ */
+export const toHex = (src, withPrefix = false) => {
+  if (typeof src === "number" || typeof src === "bigint") {
+    const bi = BigInt(src);
+    return prependPrefix(bi.toString(HEXA_BASE), withPrefix);
+  }
+  if (src instanceof Uint8Array) return buf82hex(src, withPrefix);
+  if (Array.isArray(src)) return buf82hex(new Uint8Array(src), withPrefix);
+  if (check(src)) return toHex(bubble.decode(src, OutputFormat.Uint8Array), withPrefix);
+  if (isHexString(src)) return prependPrefix(src, withPrefix);
+  return toHex(b642buf8(src, true), withPrefix);
+};

package/web/idx.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.
+ * 
+ */
+/**
+ * Check that an IDX is valid
+ *
+ * Accept anything that is valid regardless of the first and last character.
+ *
+ * @public
+ */
+export declare const check: (candidate: string) => boolean;
+/**
+ * Raise an exception if the value isn't a valid IDX.
+ *
+ * @public
+ */
+export declare const checkException: (candidate: string) => void;
+/**
+ * Change first and last letter of an IDX.
+ *
+ * @public
+ */
+export declare const changeExtrem: (candidate: string, extrems?: string) => string;
+/**
+ * Split an IDX into its words.
+ *
+ * @public
+ */
+export declare const split: (idx: string) => Array<string>;
+/**
+ * Return the head of an IDX.
+ *
+ * @param count - Number of words to include
+ *
+ * @param ellipsis - Append an ellipsis at the end
+ *
+ * @public
+ */
+export declare const head: (idx: string, count: number, ellipsis?: boolean) => string;

package/web/idx.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 { decode as bubbleDecode } from "@keeex/bubble_babble/web/bubble_babble.js";
+const IDX_REGEX = /^(?<delim>[a-z])[aeiouy][bcdfghjklmnpqrstvwxz][aeiouy][bcdfghjklmnpqrstvwxz]-(?:[bcdfghjklmnpqrstvwxz][aeiouy][bcdfghjklmnpqrstvwxz][aeiouy][bcdfghjklmnpqrstvwxz]-){15}[bcdfghjklmnpqrstvwxz][aeiouy][bcdfghjklmnpqrstvwxz][aeiouy]\k<delim>$/u;
+/** Replace the first and last character of a string */
+const changeExtremNoCheck = (candidate, extrems) => `${extrems}${candidate.substring(1, candidate.length - 1)}${extrems}`;
+const SHA256_BYTE_LENGTH = 32;
+/**
+ * Check that an IDX is valid
+ *
+ * Accept anything that is valid regardless of the first and last character.
+ *
+ * @public
+ */
+export const check = candidate => {
+  try {
+    return IDX_REGEX.test(candidate) && bubbleDecode(changeExtremNoCheck(candidate, "x")).byteLength === SHA256_BYTE_LENGTH;
+  } catch {
+    return false;
+  }
+};
+/**
+ * Raise an exception if the value isn't a valid IDX.
+ *
+ * @public
+ */
+export const checkException = candidate => {
+  if (!check(candidate)) throw new Error(`Invalid IDX: "${candidate}"`);
+};
+/**
+ * Change first and last letter of an IDX.
+ *
+ * @public
+ */
+export const changeExtrem = (candidate, extrems = "x") => {
+  if (extrems.length !== 1) throw new Error(`Invalid extrems value "${extrems}"`);
+  checkException(candidate);
+  return changeExtremNoCheck(candidate, extrems);
+};
+/**
+ * Split an IDX into its words.
+ *
+ * @public
+ */
+export const split = idx => {
+  checkException(idx);
+  return idx.split("-");
+};
+const IDX_WORDS_COUNT = 17;
+/**
+ * Return the head of an IDX.
+ *
+ * @param count - Number of words to include
+ *
+ * @param ellipsis - Append an ellipsis at the end
+ *
+ * @public
+ */
+export const head = (idx, count, ellipsis = false) => {
+  if (count >= IDX_WORDS_COUNT) return idx;
+  const words = split(idx).slice(0, count);
+  return `${words.join("-")}${ellipsis ? "-…" : ""}`;
+};

package/web/json.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @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 { TypePredicate } from "./types/types.js";
+/**
+ * All the primitive types supported in a JSON file.
+ *
+ * @public
+ */
+export type JSONPrimitiveType = null | string | number | boolean;
+/**
+ * All possible value type in a JSON file.
+ *
+ * @public
+ */
+export type JSONValueType = JSONPrimitiveType | JSONArray | JSONObject;
+/**
+ * All supported arrays in a JSON files.
+ *
+ * @public
+ */
+export type JSONArray = Array<JSONValueType>;
+/**
+ * All supported objects in a JSON files.
+ *
+ * @public
+ */
+export interface JSONObject {
+    [key: string]: JSONValueType;
+}
+/**
+ * JSON.parse() with typed return.
+ *
+ * @public
+ */
+export declare const jsonParse: <T>(value: unknown, predicate?: TypePredicate<T>) => T;
+/**
+ * Do a JSON stringify operation with optional canonization of properties' order.
+ *
+ * @param order - Sort all properties using their UTF-8 point value.
+ * This is roughly alphabetical order when there are no non-ASCII characters.
+ *
+ * @public
+ */
+export declare const jsonStringify: (source: unknown, order?: boolean, prettyIndent?: boolean | number) => string;

package/web/json.js

@@ -0,0 +1,98 @@
+/**
+ * @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.
+ * 
+ */
+const JSON_DEFAULT_INDENT = 2;
+/**
+ * JSON.parse() with typed return.
+ *
+ * @public
+ */
+export const jsonParse = (value, predicate) => {
+  const res = typeof value === "string" ? JSON.parse(value) : value;
+  if (predicate && !predicate(res, {
+    raise: true
+  })) throw new Error("Unexpected state");
+  return res;
+};
+/** Return the expected indentation step */
+const indentStep = prettyIndent => {
+  if (prettyIndent === false) return 0;
+  if (prettyIndent === true) return JSON_DEFAULT_INDENT;
+  return prettyIndent;
+};
+/** Indent a string */
+const indentStr = (level, value) => {
+  const lines = value.split("\n");
+  const indentedLines = lines.map(c => `${" ".repeat(level)}${c}`);
+  return indentedLines.join("\n");
+};
+/** Helper for Array.map() */
+const indenter = level => value => indentStr(level, value);
+const processArray = (source, prettyIndent) => {
+  const outputElem = source.map(c => {
+    if (c === undefined) return "null";
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    return jsonStringify(c, true, prettyIndent);
+  });
+  if (outputElem.length === 0) return "[]";
+  if (prettyIndent === false) return `[${outputElem.join(",")}]`;
+  return `[\n${outputElem.map(indenter(indentStep(prettyIndent))).map((c, id) => id === outputElem.length - 1 ? `${c}\n` : `${c},\n`).join("")}]`;
+};
+const utf8Sort = (a, b) => {
+  const maxLen = Math.max(a.length, b.length);
+  for (let cursor = 0; cursor < maxLen; ++cursor) {
+    const aCode = a.charCodeAt(cursor);
+    const bCode = b.charCodeAt(cursor);
+    if (isNaN(aCode) || aCode < bCode) return -1;
+    if (isNaN(bCode) || aCode > bCode) return 1;
+  }
+  return 0;
+};
+/**
+ * Do a JSON stringify operation with optional canonization of properties' order.
+ *
+ * @param order - Sort all properties using their UTF-8 point value.
+ * This is roughly alphabetical order when there are no non-ASCII characters.
+ *
+ * @public
+ */
+export const jsonStringify = (source, order = false, prettyIndent = false) => {
+  if (!order) {
+    if (prettyIndent) {
+      return JSON.stringify(source, null, typeof prettyIndent === "boolean" ? JSON_DEFAULT_INDENT : prettyIndent);
+    }
+    return JSON.stringify(source);
+  }
+  if (Array.isArray(source)) return processArray(source, prettyIndent);
+  const sourceType = typeof source;
+  if (["string", "number", "boolean"].includes(sourceType) || source === null) {
+    return JSON.stringify(source);
+  }
+  if (sourceType !== "object") throw new Error("Invalid object input");
+  const casted = source;
+  const outputElem = [];
+  for (const key of Object.keys(casted).sort(utf8Sort)) {
+    const value = casted[key];
+    if (value === undefined) continue;
+    if (prettyIndent === false) {
+      outputElem.push(`${JSON.stringify(key)}:${jsonStringify(value, true, prettyIndent)}`);
+    } else {
+      outputElem.push(`${JSON.stringify(key)}: ${jsonStringify(value, true, prettyIndent)}`);
+    }
+  }
+  if (outputElem.length === 0) return "{}";
+  if (prettyIndent === false) return `{${outputElem.join(",")}}`;
+  return `{\n${outputElem.map(indenter(indentStep(prettyIndent))).map((c, id) => id === outputElem.length - 1 ? `${c}\n` : `${c},\n`).join("")}}`;
+};