@keeex/utils 7.0.1

package/lib/path.js

@@ -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.
+ * 
+ */
+const forbiddenCharacters = ["<", ">", ":", '"', "/", "\\", "|", "?", "*"];
+/**
+ * Sanitize a filename
+ *
+ * Removes some characters known to cause issues with file names.
+ *
+ * Does not work on path.
+ *
+ * @public
+ */
+export const sanitizeFilename = (filename, replacement = "_") => filename
+    .split("")
+    .map((c) => (forbiddenCharacters.includes(c) ? replacement : c))
+    .join("");

package/lib/promise.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * Create a promise that resolves after a given delay.
+ *
+ * @public
+ */
+export declare const delayPromise: (delayInMS: number) => Promise<void>;
+export type PromiseFunction<T> = () => Promise<T>;
+/** Retry a promise until it succeed.
+ *
+ * This is probably a bad idea (or a bad implementation). Avoid using it.
+ *
+ * @public
+ */
+export declare const retryPromise: <T>(promiseFunction: PromiseFunction<T>, retryDelayInS: number, retryTimeoutInS: number) => Promise<T>;
+export type PromiseFunc<T> = () => Promise<T | void>;
+/**
+ * Try all promises in the array until one resolves with a truthy value.
+ *
+ * @public
+ */
+export declare const firstTruthy: <T>(promiseFuncs: Array<PromiseFunc<T>>) => Promise<T>;
+/**
+ * Drop a promise and silence any exception.
+ *
+ * This is to be used *only* on dropped promises to explicitly silence any warning.
+ */
+export declare const dropPromise: <T>(promise: Promise<T>) => void;

package/lib/promise.js

@@ -0,0 +1,78 @@
+/**
+ * @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-env node */
+import { timeConvert } from "./units.js";
+/**
+ * Create a promise that resolves after a given delay.
+ *
+ * @public
+ */
+export const delayPromise = (delayInMS) => 
+// eslint-disable-next-line promise/avoid-new
+new Promise((resolve) => {
+    setTimeout(resolve, delayInMS);
+});
+/** Retry a promise until it succeed.
+ *
+ * This is probably a bad idea (or a bad implementation). Avoid using it.
+ *
+ * @public
+ */
+export const retryPromise = async (promiseFunction, retryDelayInS, retryTimeoutInS) => {
+    const firstCallTime = timeConvert(`${Date.now()}ms`);
+    // eslint-disable-next-line @typescript-eslint/init-declarations
+    let firstError;
+    while (timeConvert(`${Date.now()}ms`) - firstCallTime < retryTimeoutInS) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const result = await promiseFunction();
+            return result;
+        }
+        catch (e) {
+            if (firstError === undefined)
+                firstError = e;
+            // eslint-disable-next-line no-await-in-loop
+            await delayPromise(timeConvert(retryDelayInS, "ms"));
+        }
+    }
+    throw firstError;
+};
+/**
+ * Try all promises in the array until one resolves with a truthy value.
+ *
+ * @public
+ */
+export const firstTruthy = async (promiseFuncs) => {
+    for (const promiseFunc of promiseFuncs) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const res = await promiseFunc();
+            if (res)
+                return res;
+        }
+        catch { }
+    }
+    throw new Error("No result");
+};
+/**
+ * Drop a promise and silence any exception.
+ *
+ * This is to be used *only* on dropped promises to explicitly silence any warning.
+ */
+export const dropPromise = (promise) => {
+    // eslint-disable-next-line @typescript-eslint/no-empty-function, promise/prefer-await-to-then
+    promise.catch(() => { });
+};

package/lib/starttime.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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 the number of seconds since the program/JavaScript environment started.
+ *
+ * The result is always rounded to a decisecond at most.
+ *
+ * @public
+ */
+export declare const getElapsedTime: () => number;

package/lib/starttime.js

@@ -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.
+ * 
+ */
+const startTime = Date.now();
+const CENTI = 100;
+const DECI = 10;
+/**
+ * Return the number of seconds since the program/JavaScript environment started.
+ *
+ * The result is always rounded to a decisecond at most.
+ *
+ * @public
+ */
+export const getElapsedTime = () => {
+    const resultValue = Date.now() - startTime;
+    return Math.round(resultValue / CENTI) / DECI;
+};

package/lib/string.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @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.
+ * 
+ */
+/**
+ * JavaScript implementation of Java's hashCode
+ *
+ * Source: https://stackoverflow.com/a/7616484
+ *
+ * @public
+ */
+export declare const hashCode: (str: string) => number;
+export type HashCallback = (value: string) => string;
+/**
+ * Simplify a string, removing all characters outside of a restricted subset.
+ *
+ * @param replacement - The replacement for each character removed.
+ * Defaults to ""
+ *
+ * @param subset - A regex to be used as the filter subset.
+ * Defaults to /[^[a-zA-Z0-9_]/g
+ *
+ * @param hash - A hash function to use as fallback.
+ * Defaults to hashCode().
+ *
+ * @returns
+ * The stripped down string. If the string ends empty after stripping, it will
+ * fall back to the hash function to not return an empty string.
+ *
+ * If the hash function is used, its result is converted to a string but is not
+ * subject to the restriction of subset.
+ *
+ * @public
+ */
+export declare const simplify: (str: string, replacement?: string, subset?: RegExp, hash?: HashCallback) => string;
+/**
+ * Encode a string containing multi-bytes characters using URI encoding.
+ *
+ * Only the multi-bytes characters are encoded; any ASCII (\<127) character is
+ * kept as-is, except for the "%" character.
+ *
+ * @public
+ */
+export declare const encodeUTF8: (str: string) => string;
+/**
+ * Decode a string containing escaped UTF-8 sequences
+ *
+ * This is almost an alias to decodeURIComponent
+ *
+ * @public
+ */
+export declare const decodeUTF8: (str: string, skipErrors?: boolean) => string;
+/** Capitalize (or uncapitalize) the first character of a string */
+export declare const capitalize: (str: string, upperFirstLetter: boolean) => string;

package/lib/string.js

@@ -0,0 +1,108 @@
+/**
+ * @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 hashCodeShift = 5;
+/**
+ * JavaScript implementation of Java's hashCode
+ *
+ * Source: https://stackoverflow.com/a/7616484
+ *
+ * @public
+ */
+export const hashCode = (str) => Array.from(str).reduce((hash, chr) => (hash << hashCodeShift) - hash + chr.charCodeAt(0), 0);
+/**
+ * Simplify a string, removing all characters outside of a restricted subset.
+ *
+ * @param replacement - The replacement for each character removed.
+ * Defaults to ""
+ *
+ * @param subset - A regex to be used as the filter subset.
+ * Defaults to /[^[a-zA-Z0-9_]/g
+ *
+ * @param hash - A hash function to use as fallback.
+ * Defaults to hashCode().
+ *
+ * @returns
+ * The stripped down string. If the string ends empty after stripping, it will
+ * fall back to the hash function to not return an empty string.
+ *
+ * If the hash function is used, its result is converted to a string but is not
+ * subject to the restriction of subset.
+ *
+ * @public
+ */
+export const simplify = (str, replacement, subset, hash) => {
+    const result = str.replace(subset ?? /[^[a-zA-Z0-9_]/gu, replacement ?? "");
+    return result.length > 0 ? result : String((hash ?? hashCode)(str));
+};
+// Only filter character point higher than 127
+const FILTER_LIMIT = 127;
+/**
+ * Encode a string containing multi-bytes characters using URI encoding.
+ *
+ * Only the multi-bytes characters are encoded; any ASCII (\<127) character is
+ * kept as-is, except for the "%" character.
+ *
+ * @public
+ */
+export const encodeUTF8 = (str) => Array.from(str)
+    .map((chr) => {
+    if (chr.charCodeAt(0) > FILTER_LIMIT || chr.startsWith("%") || chr.length > 1) {
+        return encodeURIComponent(chr);
+    }
+    return chr;
+})
+    .join("");
+/**
+ * Decode a string containing escaped UTF-8 sequences
+ *
+ * This is almost an alias to decodeURIComponent
+ *
+ * @public
+ */
+export const decodeUTF8 = (str, skipErrors) => {
+    try {
+        const fixedString = str.replace(/%(?<trailer>[0-9a-fA-F][^0-9a-fA-F]|[^0-9a-fA-F]|[0-9a-fA-F]$|$)/gu, "%25$<trailer>");
+        return decodeURIComponent(fixedString);
+    }
+    catch (error) {
+        if (!skipErrors)
+            throw error;
+    }
+    const outputParts = [];
+    let cursor = 0;
+    while (cursor < str.length) {
+        try {
+            const part = decodeURIComponent(str.substring(cursor));
+            outputParts.push(part);
+            cursor = str.length;
+        }
+        catch {
+            const nextPercentPosition = str.indexOf("%", cursor);
+            outputParts.push(str.substring(cursor, nextPercentPosition + 1));
+            cursor = nextPercentPosition + 1;
+        }
+    }
+    return outputParts.join("");
+};
+/** Capitalize (or uncapitalize) the first character of a string */
+export const capitalize = (str, upperFirstLetter) => {
+    const firstLetter = str.charAt(0);
+    const transformedFirstLetter = upperFirstLetter
+        ? firstLetter.toUpperCase()
+        : firstLetter.toLowerCase();
+    const rest = str.slice(1);
+    return `${transformedFirstLetter}${rest}`;
+};

package/lib/types/array.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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 { PredicateOptions, TypePredicate } from "./types.js";
+/** Shorthand for an object that can be either T or an array of T */
+export type Arrayable<T> = Array<T> | T;
+/**
+ * Check that a given object is an array of string
+ *
+ * @public
+ */
+export declare const isStringArray: TypePredicate<Array<string>>;
+/**
+ * Check that a given object is an array where each value have the given type.
+ *
+ * @public
+ */
+export declare const isArrayOfType: <T>(obj: unknown, predicate: TypePredicate<T>, options?: PredicateOptions) => obj is Array<T>;
+export declare const isArrayableOfType: <T>(obj: unknown, predicate: TypePredicate<T>, options?: PredicateOptions) => obj is Arrayable<T>;
+/** @public */
+export declare const makeArrayOfTypePredicate: <ValueType>(valuePredicate: TypePredicate<ValueType>) => TypePredicate<Array<ValueType>>;
+export declare const makeArrayableOfTypePredicate: <ValueType>(valuePredicate: TypePredicate<ValueType>) => TypePredicate<Arrayable<ValueType>>;

package/lib/types/array.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 { PredicateError } from "./predicateerror.js";
+import { getPredicateOptions } from "./types.js";
+// #endregion
+/**
+ * Check that a given object is an array of string
+ *
+ * @public
+ */
+export const isStringArray = (obj, options = false) => {
+    const opt = getPredicateOptions(options);
+    if (!Array.isArray(obj)) {
+        PredicateError.expected(opt.raise, undefined, "an array");
+        return false;
+    }
+    for (const value of obj) {
+        if (typeof value !== "string") {
+            PredicateError.expected(opt.raise, "<array>", "a string");
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * Check that a given object is an array where each value have the given type.
+ *
+ * @public
+ */
+export const isArrayOfType = (obj, predicate, options = false) => {
+    const opt = getPredicateOptions(options);
+    if (!Array.isArray(obj)) {
+        PredicateError.expected(opt.raise, undefined, "an array");
+        return false;
+    }
+    for (const value of obj) {
+        if (!predicate(value, opt)) {
+            PredicateError.predicateFailed(opt.raise, "<array>");
+            return false;
+        }
+    }
+    return true;
+};
+export const isArrayableOfType = (obj, predicate, options = false) => {
+    if (Array.isArray(obj))
+        return isArrayOfType(obj, predicate, options);
+    return predicate(obj, options);
+};
+/** @public */
+export const makeArrayOfTypePredicate = (valuePredicate) => (obj, options = false) => isArrayOfType(obj, valuePredicate, options);
+export const makeArrayableOfTypePredicate = (valuePredicate) => (obj, options = false) => isArrayableOfType(obj, valuePredicate, options);

package/lib/types/enum.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @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 { PredicateOptions, TypePredicate } from "./types.js";
+/**
+ * Return an enum-type value whose key matches the provided key string.
+ *
+ * @public
+ */
+export declare const keyToEnum: <EnumType>(key: string, enumType: Record<string, EnumType>) => EnumType;
+/**
+ * Check if an object is of the given enum type.
+ *
+ * @public
+ */
+export declare const isEnumType: <EnumType>(obj: unknown, enumType: unknown, options?: PredicateOptions) => obj is EnumType;
+/** @public */
+export declare const makeEnumTypePredicate: <EnumType>(enumType: unknown) => TypePredicate<EnumType>;

package/lib/types/enum.js

@@ -0,0 +1,44 @@
+/**
+ * @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 { PredicateError } from "./predicateerror.js";
+import { getPredicateOptions } from "./types.js";
+/**
+ * Return an enum-type value whose key matches the provided key string.
+ *
+ * @public
+ */
+export const keyToEnum = (key, enumType) => {
+    if (typeof enumType !== "object")
+        throw new Error("Invalid enum type");
+    for (const enumKey of Object.keys(enumType))
+        if (key === enumKey)
+            return enumType[enumKey];
+    throw new Error("Invalid enum key");
+};
+/**
+ * Check if an object is of the given enum type.
+ *
+ * @public
+ */
+export const isEnumType = (obj, enumType, options = false) => {
+    const opt = getPredicateOptions(options);
+    const res = Object.values(enumType).includes(obj);
+    if (!res)
+        PredicateError.expected(opt.raise, undefined, "value from enum");
+    return res;
+};
+/** @public */
+export const makeEnumTypePredicate = (enumType) => (obj, options = false) => isEnumType(obj, enumType, options);

package/lib/types/predicateerror.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @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.
+ * 
+ */
+interface PredicateErrorCtor {
+    keyName?: string;
+    error?: string;
+    cause?: Array<Error> | Error;
+}
+/**
+ * Construct an error whose message indicate what property failed to validate and why
+ *
+ * The static function provided will raise the appropriate error if the `raise` parameter is true,
+ * and do nothing otherwise.
+ *
+ * @internal
+ */
+export declare class PredicateError extends Error {
+    #private;
+    constructor(params: PredicateErrorCtor);
+    get keyName(): string | undefined;
+    get error(): string | undefined;
+    static readonly mandatory: (raise: boolean, keyName: string) => void;
+    static readonly expected: (raise: boolean, keyName: string | undefined, expectedMessage: string, value?: unknown) => void;
+    static readonly predicateFailed: (raise: boolean, keyName: string | undefined) => void;
+    static readonly allTryFailed: (raise: boolean, keyName: string | undefined, cause: Array<Error>) => void;
+    static readonly keyError: (raise: boolean, keyName: string, cause: Error) => void;
+}
+export {};