@keeex/utils 7.0.1

package/lib/cron/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * Function to execute a single task
+ *
+ * If it returns a promise, the task is considerred running as long as the
+ * promise didn't complete
+ */
+export type TaskFunction = () => Promise<void> | void;
+export type LoggerFunction = (error: Error) => void;
+/**
+ * Behavior when a task is scheduled to start while it's already running
+ */
+export declare enum Overrun {
+    /**
+     * Skip this start
+     */
+    SKIP = "skip",
+    /**
+     * Immediately restart the task once it finish
+     */
+    AFTER = "after"
+}
+/**
+ * Options when scheduling a task
+ */
+export interface TaskOptions {
+    /**
+     * Behavior when the task is scheduled to restart before it have completed.
+     *
+     * Default to IGNORE when scheduling a task.
+     */
+    overrun?: Overrun;
+}
+/**
+ * Same as TaskOptions, but all members are required
+ */
+export interface CompleteTaskOptions {
+    overrun: Overrun;
+}

package/lib/cron/types.js

@@ -0,0 +1,31 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * Behavior when a task is scheduled to start while it's already running
+ */
+export var Overrun;
+(function (Overrun) {
+    /**
+     * Skip this start
+     */
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    Overrun["SKIP"] = "skip";
+    /**
+     * Immediately restart the task once it finish
+     */
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    Overrun["AFTER"] = "after";
+})(Overrun || (Overrun = {}));

package/lib/cron.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.
+ * 
+ */
+import ScheduledTask from "./cron/scheduledtask.js";
+import { TaskFunction, TaskOptions, Overrun, CompleteTaskOptions } from "./cron/types.js";
+export { Overrun };
+export type { ScheduledTask, TaskFunction, TaskOptions, CompleteTaskOptions };
+export declare const setLoggerFunction: (logFunc?: import("./cron/types.js").LoggerFunction) => void;
+/**
+ * Schedule a task for execution
+ *
+ * @param cronDefinition - CRON timing for the task
+ * @param task - The task function to run at the scheduled time
+ * @param taskOptions - The behavior of the task
+ */
+export declare const schedule: (cronDefinition: string, task: TaskFunction, taskOptions?: TaskOptions) => ScheduledTask;
+export declare const stop: () => void;

package/lib/cron.js

@@ -0,0 +1,47 @@
+/**
+ * @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 { setLoggerFunction as bitsSetLoggerFunction } from "./cron/logger.js";
+import ScheduledTask from "./cron/scheduledtask.js";
+import { Overrun } from "./cron/types.js";
+const scheduledTasks = [];
+export { Overrun };
+export const setLoggerFunction = bitsSetLoggerFunction;
+/**
+ * Set default values for task options
+ */
+const getDefaultTaskOptions = (taskOptions) => {
+    const result = taskOptions ?? {};
+    return {
+        overrun: Overrun.SKIP,
+        ...result,
+    };
+};
+/**
+ * Schedule a task for execution
+ *
+ * @param cronDefinition - CRON timing for the task
+ * @param task - The task function to run at the scheduled time
+ * @param taskOptions - The behavior of the task
+ */
+export const schedule = (cronDefinition, task, taskOptions) => {
+    const newTask = new ScheduledTask(cronDefinition, task, getDefaultTaskOptions(taskOptions));
+    scheduledTasks.push(newTask);
+    return newTask;
+};
+export const stop = () => {
+    scheduledTasks.forEach((task) => task.cancel());
+    scheduledTasks.length = 0;
+};

package/lib/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/lib/dict.js

@@ -0,0 +1,74 @@
+/**
+ * @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/lib/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/lib/error.js

@@ -0,0 +1,41 @@
+/**
+ * @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/lib/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/lib/global.js

@@ -0,0 +1,53 @@
+/**
+ * @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/lib/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/lib/hex.js

@@ -0,0 +1,58 @@
+/**
+ * @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";
+import { OutputFormat } from "@keeex/bubble_babble";
+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/lib/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/lib/idx.js

@@ -0,0 +1,81 @@
+/**
+ * @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";
+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 ? "-…" : ""}`;
+};