@creopse/utils 0.0.15 → 0.0.16

package/dist/helpers/functions/object.js

@@ -0,0 +1,141 @@
+/**
+ * Checks if the given value is an object and not an array or null.
+ *
+ * @param {any} value - The value to check.
+ * @return {boolean} Returns true if the value is an object and not an array or null, false otherwise.
+ */
+export function isRealObject(value) {
+    return typeof value === 'object' && !Array.isArray(value) && value !== null;
+}
+/**
+ * Determines if a given string is a valid JSON string representing an object.
+ *
+ * @param {string} str - The string to be checked.
+ * @return {boolean} Returns true if the string is a valid JSON string of an object, false otherwise.
+ */
+export const isStringifiedObject = (str) => {
+    try {
+        const parsed = JSON.parse(str);
+        return (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed));
+    }
+    catch (e) {
+        return false;
+    }
+};
+/**
+ * Recursively flattens a nested object into a single-level object with
+ * dot-separated property names.
+ *
+ * @example
+ * const obj = {
+ *   a: {
+ *     b: {
+ *       c: 1
+ *     }
+ *   }
+ * }
+ * const flattened = flattenObject(obj) // { 'a.b.c': 1 }
+ *
+ * @param {object} obj The object to flatten.
+ * @param {string} [prefix=''] The prefix to use for the flattened property names.
+ * @returns {object} The flattened object.
+ */
+export const flattenObject = (obj, prefix = '') => {
+    return Object.keys(obj).reduce((acc, k) => {
+        const pre = prefix.length ? `${prefix}.` : '';
+        if (typeof obj[k] === 'object' &&
+            obj[k] !== null &&
+            !Array.isArray(obj[k])) {
+            Object.assign(acc, flattenObject(obj[k], pre + k));
+        }
+        else {
+            acc[pre + k] = obj[k];
+        }
+        return acc;
+    }, {});
+};
+/**
+ * Recursively unflattens a single-level object with dot-separated property
+ * names into a nested object.
+ *
+ * @example
+ * const obj = { 'a.b.c': 1 }
+ * const unflattened = unflattenObject(obj) // { a: { b: { c: 1 } } }
+ *
+ * @param {object} obj The object to unflatten.
+ * @returns {object} The unflattened object.
+ */
+export const unflattenObject = (obj) => {
+    const result = {};
+    for (const key in obj) {
+        const keys = key.split('.');
+        keys.reduce((acc, part, index) => {
+            if (index === keys.length - 1) {
+                acc[part] = obj[key];
+            }
+            else {
+                if (!acc[part])
+                    acc[part] = {};
+            }
+            return acc[part];
+        }, result);
+    }
+    return result;
+};
+/**
+ * Renames a key in an object.
+ *
+ * @param {Object} obj - The object that contains the key to rename.
+ * @param {string} oldKey - The old key name.
+ * @param {string} newKey - The new key name.
+ */
+export const renameKey = (obj, oldKey, newKey) => {
+    if (Object.prototype.hasOwnProperty.call(obj, oldKey)) {
+        obj[newKey] = obj[oldKey];
+        delete obj[oldKey];
+    }
+};
+/**
+ * Creates a new object with a specified key renamed, leaving the original object unchanged.
+ *
+ * @param {Record<string, any>} obj - The original object containing the key to rename.
+ * @param {string} oldKey - The name of the key to rename.
+ * @param {string} newKey - The new name for the key.
+ * @returns {Record<string, any>} A new object with the key renamed.
+ */
+export const renameKeyImmutable = (obj, oldKey, newKey) => {
+    return Object.keys(obj).reduce((acc, key) => {
+        if (key === oldKey) {
+            acc[newKey] = obj[oldKey];
+        }
+        else {
+            acc[key] = obj[key];
+        }
+        return acc;
+    }, {});
+};
+/**
+ * Omits the specified keys from the given object.
+ *
+ * @param {T} obj The object to omit keys from.
+ * @param {K[]} keys The keys to omit.
+ * @returns {Omit<T, K>} A new object with the specified keys omitted.
+ */
+export const omitKeys = (obj, keys) => {
+    const result = { ...obj };
+    for (const key of keys) {
+        delete result[key];
+    }
+    return result;
+};
+/**
+ * Checks if the given object is empty.
+ *
+ * An object is considered empty if it is an object instance (i.e. `obj.constructor === Object`), and if it has no own enumerable property (i.e. `Object.keys(obj).length === 0`).
+ *
+ * @param {any} obj - The object to check.
+ * @returns {boolean} Returns true if the object is empty, false otherwise.
+ */
+export const isObjectEmpty = (obj) => {
+    return obj && Object.keys(obj).length === 0 && obj.constructor === Object;
+};

package/dist/helpers/functions/string.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Generates the initials of a given name.
+ *
+ * @param {string} name - The name to generate the initials from.
+ * @return {string} The initials of the given name.
+ */
+export declare function getNameInitials(name: string): string;
+/**
+ * Pads the left side of a string with a specified character until it reaches a specified length.
+ *
+ * @param {string} string - The string to be padded.
+ * @param {string} pad - The character used for padding.
+ * @param {number} length - The desired length of the resulting string.
+ * @return {string} The padded string.
+ */
+export declare function strPadLeft(string: string, pad: string, length: number): string;
+/**
+ * Capitalizes the first letter of a given string.
+ *
+ * @param {string} string - The string to capitalize.
+ * @return {string} The modified string with the first letter capitalized.
+ */
+export declare function capitalizeFirstLetter(string: string): string;
+/**
+ * Extracts uppercase words from the given input string.
+ *
+ * @param {string} input - The input string to extract uppercase words from.
+ * @return {RegExpMatchArray | null} An array of uppercase words found in the input string.
+ */
+export declare function extractUppercaseWords(input: string): RegExpMatchArray | null;
+/**
+ * Extracts lowercase words from the input string.
+ *
+ * @param {string} input - The string to extract lowercase words from.
+ * @return {RegExpMatchArray | null} An array of lowercase words extracted from the input string.
+ */
+export declare function extractLowercaseWords(input: string): RegExpMatchArray | null;
+/**
+ * Extracts numbers from a given string.
+ *
+ * @param {string} string - The string from which to extract numbers.
+ * @param {object} options - Optional parameters for customization.
+ * @param {boolean} options.array - Whether to return an array of numbers. Defaults to false.
+ * @param {boolean} options.float - Whether to include floating-point numbers. Defaults to true.
+ * @return {number | number[]} - The extracted number(s) from the string. If options.array is true, an array will be returned. Otherwise, a single number will be returned.
+ */
+export declare function extractNumber(string: string, { array, float }?: {
+    array?: boolean;
+    float?: boolean;
+}): number | number[];
+/**
+ * Extracts all alphabetic characters from a given string.
+ *
+ * @param {string} string - The input string.
+ * @param {Object} options - Optional parameters.
+ * @param {boolean} options.array - Whether to return the result as an array. Default is false.
+ * @return {string | string[]} - The extracted alphabetic characters, either as a string or an array.
+ */
+export declare function extractAlphabet(string: string, { array }?: {
+    array?: boolean;
+}): string | string[];
+/**
+ * Removes the specified searchString from the given str.
+ *
+ * @param {string} str - The original string.
+ * @param {string} searchString - The string to be removed from str.
+ * @return {string} The modified string with the searchString removed.
+ */
+export declare function removeFromString(str: string, searchString: string): string;
+/**
+ * Replaces multiple parts of a string based on a given set of replacements.
+ *
+ * @param {string} inputString - The original string to be modified.
+ * @param {Record<string, string>} replacements - An object containing key-value pairs where the key is the part to be replaced and the value is the replacement string.
+ * @return {string} - The modified string with all occurrences of the specified parts replaced.
+ */
+export declare function replaceStringParts(inputString: string, replacements: Record<string, string>): string;
+/**
+ * Checks if a given value is a title-like string.
+ *
+ * A title-like string is defined as a string that is not empty, not too long, not too short, does not contain newlines, and starts with a capital letter.
+ *
+ * The function takes an optional options object with the following properties:
+ * - thresholdScore: The minimum score required for the string to be considered title-like. Defaults to 2.
+ * - tooLongValue: The maximum length of the string for it to be considered title-like. Defaults to 200.
+ * - tooShortValue: The minimum length of the string for it to be considered title-like. Defaults to 3.
+ *
+ * The function returns an object with two properties: match and score. Match is a boolean indicating whether the string is title-like, and score is a number indicating how well the string matches the title-like criteria.
+ */
+export declare const isTitleLike: (value: any, options?: {
+    thresholdScore?: number;
+    tooLongValue?: number;
+    tooShortValue?: number;
+}) => {
+    match: boolean;
+    score: number;
+};
+/**
+ * Extracts a title-like value from the given data.
+ *
+ * This function first attempts to find a direct match by known field name.
+ * If no match is found, it then uses a heuristic scoring system to find a title-like value.
+ * Finally, it falls back to the first string value if no match is found.
+ *
+ * @param {unknown} data The data object to extract the title-like value from.
+ * @param {(value: string) => string} tr A function to translate the extracted value.
+ * @param {string} [defaultValue=''] The default value to return if no match is found.
+ * @returns {string | undefined} The extracted title-like value, or undefined if no match is found.
+ */
+export declare const extractTitleLike: (data: unknown, tr: (value: string) => string, defaultValue?: string) => string | undefined;

package/dist/helpers/functions/string.js

@@ -0,0 +1,211 @@
+import _ from 'lodash';
+import { isRealObject, isStringifiedObject } from './object';
+/**
+ * Generates the initials of a given name.
+ *
+ * @param {string} name - The name to generate the initials from.
+ * @return {string} The initials of the given name.
+ */
+export function getNameInitials(name) {
+    const nameSplit = name.split(' '), initials = nameSplit.length > 1
+        ? nameSplit[0].charAt(0).toUpperCase() +
+            nameSplit[1].charAt(0).toUpperCase()
+        : nameSplit[0].charAt(0).toUpperCase();
+    return initials;
+}
+/**
+ * Pads the left side of a string with a specified character until it reaches a specified length.
+ *
+ * @param {string} string - The string to be padded.
+ * @param {string} pad - The character used for padding.
+ * @param {number} length - The desired length of the resulting string.
+ * @return {string} The padded string.
+ */
+export function strPadLeft(string, pad, length) {
+    return (new Array(length + 1).join(pad) + string).slice(-length);
+}
+/**
+ * Capitalizes the first letter of a given string.
+ *
+ * @param {string} string - The string to capitalize.
+ * @return {string} The modified string with the first letter capitalized.
+ */
+export function capitalizeFirstLetter(string) {
+    return string.charAt(0).toUpperCase() + string.slice(1);
+}
+/**
+ * Extracts uppercase words from the given input string.
+ *
+ * @param {string} input - The input string to extract uppercase words from.
+ * @return {RegExpMatchArray | null} An array of uppercase words found in the input string.
+ */
+export function extractUppercaseWords(input) {
+    return input.match(/(\b[A-Z]['A-Z]+|\b[A-Z]\b)/g);
+}
+/**
+ * Extracts lowercase words from the input string.
+ *
+ * @param {string} input - The string to extract lowercase words from.
+ * @return {RegExpMatchArray | null} An array of lowercase words extracted from the input string.
+ */
+export function extractLowercaseWords(input) {
+    return input.match(/(\b[a-z]['a-z]+|\b[a-z]\b)/g);
+}
+/**
+ * Extracts numbers from a given string.
+ *
+ * @param {string} string - The string from which to extract numbers.
+ * @param {object} options - Optional parameters for customization.
+ * @param {boolean} options.array - Whether to return an array of numbers. Defaults to false.
+ * @param {boolean} options.float - Whether to include floating-point numbers. Defaults to true.
+ * @return {number | number[]} - The extracted number(s) from the string. If options.array is true, an array will be returned. Otherwise, a single number will be returned.
+ */
+export function extractNumber(string, { array = false, float = true } = {}) {
+    const result = string.toString().match(float ? /[+-]?\d+(\.\d+)?/g : /\d/g);
+    if (result)
+        return array
+            ? result.map((r) => parseFloat(r))
+            : parseFloat(result.join(''));
+    else
+        return array ? [0] : 0;
+}
+/**
+ * Extracts all alphabetic characters from a given string.
+ *
+ * @param {string} string - The input string.
+ * @param {Object} options - Optional parameters.
+ * @param {boolean} options.array - Whether to return the result as an array. Default is false.
+ * @return {string | string[]} - The extracted alphabetic characters, either as a string or an array.
+ */
+export function extractAlphabet(string, { array = false } = {}) {
+    const result = string.toString().match(/[a-zA-Z]/);
+    if (result)
+        return array ? result : result.join('');
+    else
+        return array ? [''] : '';
+}
+/**
+ * Removes the specified searchString from the given str.
+ *
+ * @param {string} str - The original string.
+ * @param {string} searchString - The string to be removed from str.
+ * @return {string} The modified string with the searchString removed.
+ */
+export function removeFromString(str, searchString) {
+    if (str.endsWith(searchString)) {
+        return str.slice(0, -searchString.length);
+    }
+    return str;
+}
+/**
+ * Replaces multiple parts of a string based on a given set of replacements.
+ *
+ * @param {string} inputString - The original string to be modified.
+ * @param {Record<string, string>} replacements - An object containing key-value pairs where the key is the part to be replaced and the value is the replacement string.
+ * @return {string} - The modified string with all occurrences of the specified parts replaced.
+ */
+export function replaceStringParts(inputString, replacements) {
+    if (Object.keys(replacements).length === 0) {
+        return inputString;
+    }
+    // Create a regular expression pattern by joining all keys of replacements with the "|" (OR) operator
+    const pattern = new RegExp(Object.keys(replacements).join('|'), 'g');
+    // Use the replace method with a callback function
+    const resultString = inputString.replace(pattern, (match) => {
+        // Use the match as a key to get the replacement value from the replacements object
+        return replacements[match];
+    });
+    return resultString;
+}
+/**
+ * Checks if a given value is a title-like string.
+ *
+ * A title-like string is defined as a string that is not empty, not too long, not too short, does not contain newlines, and starts with a capital letter.
+ *
+ * The function takes an optional options object with the following properties:
+ * - thresholdScore: The minimum score required for the string to be considered title-like. Defaults to 2.
+ * - tooLongValue: The maximum length of the string for it to be considered title-like. Defaults to 200.
+ * - tooShortValue: The minimum length of the string for it to be considered title-like. Defaults to 3.
+ *
+ * The function returns an object with two properties: match and score. Match is a boolean indicating whether the string is title-like, and score is a number indicating how well the string matches the title-like criteria.
+ */
+export const isTitleLike = (value, options) => {
+    if (typeof value !== 'string')
+        return { match: false, score: 0 };
+    const { thresholdScore = 2, tooLongValue = 200, tooShortValue = 3, } = options || {};
+    const trimmed = value.trim();
+    const isNotEmpty = trimmed.length > 0;
+    const isNotTooLong = trimmed.length < tooLongValue;
+    const isNotTooShort = trimmed.length >= tooShortValue;
+    const hasNoNewlines = !trimmed.includes('\n');
+    const startsWithCapital = /^[A-ZÀ-ÖØ-Þ]/.test(trimmed);
+    let score = 0;
+    if (isNotEmpty && isNotTooLong && isNotTooShort)
+        score += 1;
+    if (hasNoNewlines)
+        score += 1;
+    if (startsWithCapital)
+        score += 1;
+    return { match: score >= thresholdScore, score };
+};
+/**
+ * Extracts a title-like value from the given data.
+ *
+ * This function first attempts to find a direct match by known field name.
+ * If no match is found, it then uses a heuristic scoring system to find a title-like value.
+ * Finally, it falls back to the first string value if no match is found.
+ *
+ * @param {unknown} data The data object to extract the title-like value from.
+ * @param {(value: string) => string} tr A function to translate the extracted value.
+ * @param {string} [defaultValue=''] The default value to return if no match is found.
+ * @returns {string | undefined} The extracted title-like value, or undefined if no match is found.
+ */
+export const extractTitleLike = (data, tr, defaultValue) => {
+    if (!_.isObject(data) || !isRealObject(data))
+        return defaultValue;
+    const fields = [
+        'title',
+        'titre',
+        'name',
+        'nom',
+        'label',
+        'heading',
+        'text',
+        'texte',
+        'slug',
+        'subject',
+        'sujet',
+        'summary',
+        'description',
+        'content',
+        'body',
+    ];
+    // Step 1: Direct match by known field name
+    for (const field of fields) {
+        const foundKey = Object.keys(data).find((k) => k.toLowerCase() === field);
+        if (foundKey) {
+            const value = data[foundKey];
+            if (typeof value === 'string') {
+                return isStringifiedObject(value) ? tr(value) : value;
+            }
+        }
+    }
+    // Step 2: Heuristic scoring to find a title-like value
+    let bestScore = 0;
+    let bestValue;
+    let firstStrValue;
+    for (const [key, value] of Object.entries(data)) {
+        if (typeof value !== 'string')
+            continue;
+        const finalValue = isStringifiedObject(value) ? tr(value) : value;
+        if (!firstStrValue)
+            firstStrValue = finalValue;
+        const result = isTitleLike(finalValue, { tooLongValue: 500 });
+        if (result.match && result.score > bestScore) {
+            bestScore = result.score;
+            bestValue = finalValue;
+        }
+    }
+    // Step 3: Fallback to the first string value if no match is found
+    return bestValue || firstStrValue || defaultValue;
+};

package/dist/helpers/functions/svg.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks if the given string is a valid SVG document.
+ *
+ * @param {string} input - The string to be checked.
+ * @return {boolean} Returns true if the string is a valid SVG document, false otherwise.
+ */
+export declare function isSVG(input: string): boolean;

package/dist/helpers/functions/svg.js

@@ -0,0 +1,25 @@
+/**
+ * Checks if the given string is a valid SVG document.
+ *
+ * @param {string} input - The string to be checked.
+ * @return {boolean} Returns true if the string is a valid SVG document, false otherwise.
+ */
+export function isSVG(input) {
+    const svgRegex = /^\s*<svg\b[^>]*>.*<\/svg>\s*$/is;
+    try {
+        if (svgRegex.test(input)) {
+            const parser = new DOMParser();
+            const doc = parser.parseFromString(input, 'image/svg+xml');
+            const parserErrors = doc.getElementsByTagName('parsererror');
+            if (parserErrors.length > 0) {
+                return false;
+            }
+            const svgElements = doc.getElementsByTagName('svg');
+            return svgElements.length > 0 && svgElements[0].parentNode === doc;
+        }
+        return false;
+    }
+    catch (e) {
+        return false;
+    }
+}

package/dist/helpers/functions/time.d.ts

@@ -0,0 +1,97 @@
+import moment from 'moment';
+import 'moment/locale/fr';
+/**
+ * Waits for the given amount of milliseconds before resolving the promise.
+ * @param {number} ms - The time to wait in milliseconds.
+ * @returns {Promise<void>} - A promise that resolves after the specified time.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Returns the current timestamp in seconds.
+ *
+ * @returns {number} The current timestamp in seconds.
+ */
+export declare function getCurrentTimestamp(): number;
+/**
+ * Converts a timestamp in seconds into a formatted date string.
+ *
+ * @param {number} date - The timestamp in seconds to convert.
+ * @param {{locale?: string, pattern?: string}} options - Optional parameters for the conversion.
+ * @param {string} options.locale - The locale to use for the conversion. Defaults to 'en'.
+ * @param {string} options.pattern - The pattern to use for the conversion. Defaults to 'MM/DD/YYYY HH:mm'.
+ * @returns {string} The formatted date string.
+ */
+export declare function getDateFromTimestamp(date: number, { locale, pattern, }?: {
+    locale?: string;
+    pattern?: string;
+}): string;
+/**
+ * Converts a date string or Date object from one format to another.
+ *
+ * @param {string | Date} date - The date string or Date object to convert.
+ * @param {{inPattern?: string, outPattern?: string, locale?: string}} options - Optional parameters for the conversion.
+ * @param {string} options.inPattern - The pattern of the input date string. Defaults to 'YYYY-MM-DD'.
+ * @param {string} options.outPattern - The pattern of the output date string. Defaults to 'DD MMM YYYY'.
+ * @param {string} options.locale - The locale to use for the conversion. Defaults to 'fr'.
+ * @returns {string} The converted date string.
+ */
+export declare function reformatDate(date: string | Date, { inPattern, outPattern, locale, }?: {
+    inPattern?: string;
+    outPattern?: string;
+    locale?: string;
+}): string;
+/**
+ * Converts a date string or Date object into a formatted date string.
+ *
+ * @param {string | Date} date - The date string or Date object to convert.
+ * @param {{outPattern?: string, locale?: string}} options - Optional parameters for the conversion.
+ * @param {string} options.outPattern - The pattern of the output date string. Defaults to 'DD MMM YYYY'.
+ * @param {string} options.locale - The locale to use for the conversion. Defaults to 'fr'.
+ * @returns {string} The formatted date string.
+ */
+export declare function formatDate(date: string | Date, { outPattern, locale, }?: {
+    outPattern?: string;
+    locale?: string;
+}): string;
+/**
+ * Calculates the difference between the given date and today in the given unit.
+ *
+ * @param {string | Date} date - The date to calculate the difference for.
+ * @param {{pattern?: string, unit?: moment.unitOfTime.Diff}} options - Optional parameters for the calculation.
+ * @param {string} options.pattern - The pattern of the input date string. Defaults to 'YYYY-MM-DD'.
+ * @param {moment.unitOfTime.Diff} options.unit - The unit of time to calculate the difference in. Defaults to 'days'.
+ * @returns {number} The difference between the given date and today in the given unit.
+ */
+export declare function differenceWithToday(date: string | Date, { pattern, unit, }?: {
+    pattern?: string;
+    unit?: moment.unitOfTime.Diff;
+}): number;
+/**
+ * Calculates the difference between two dates.
+ *
+ * @param {string | Date} startDate - The start date.
+ * @param {string | Date} endDate - The end date.
+ * @param {{startDatePattern?: string, endDatePattern?: string, unit?: moment.unitOfTime.Diff}} options - Optional parameters for the calculation.
+ * @param {string} options.startDatePattern - The pattern of the start date string. Defaults to 'YYYY-MM-DD'.
+ * @param {string} options.endDatePattern - The pattern of the end date string. Defaults to 'YYYY-MM-DD'.
+ * @param {moment.unitOfTime.Diff} options.unit - The unit of time to calculate the difference in. Defaults to 'days'.
+ * @returns {number} The difference between the start and end dates in the given unit.
+ */
+export declare function differenceBetweenDates(startDate: string | Date, endDate: string | Date, { startDatePattern, endDatePattern, unit, }?: {
+    startDatePattern?: string;
+    endDatePattern?: string;
+    unit?: moment.unitOfTime.Diff;
+}): number;
+/**
+ * Calculates the difference between the given date and now.
+ *
+ * @param {string | Date} date - The date to calculate the difference from.
+ * @param {{locale?: string, pattern?: string}} options - Optional parameters for the calculation.
+ * @param {string} options.locale - The locale to use for the calculation. Defaults to 'en'.
+ * @param {string} options.pattern - The pattern of the date string. Defaults to 'YYYY-MM-DD HH:mm:ss'.
+ * @returns {string} The difference between the given date and now, relative to the given locale.
+ */
+export declare function differenceFromNow(date: string | Date, { locale, pattern, }?: {
+    locale?: string;
+    pattern?: string;
+}): string;