@koloseum/utils 0.2.28 → 0.3.0

package/dist/formatting.d.ts

@@ -0,0 +1,125 @@
+import type { IdentityType, PronounsItem, Sex, SocialMediaPlatform, SocialMediaPlatformObject } from "@koloseum/types/public-auth";
+import type { MobilePhoneLocale } from "validator";
+export declare const Transform: {
+    /**
+     * Capitalises a given word.
+     * @param {string} word - The word to be capitalised
+     * @returns The capitalised word
+     */
+    capitalise: (word: string) => string;
+    /**
+     * Cleans a URL by removing the protocol and trailing slashes.
+     * @param {string} url - The URL to clean
+     * @returns {string} The cleaned URL
+     */
+    cleanUrl: (url: string) => string;
+    /**
+     * Formats a date in the format DD/MM/YYYY (by default) or YYYY-MM-DD (for client).
+     * @param {string} date - Date to be formatted
+     * @param {boolean} forClient - Specify whether the data is for displaying on the client; defaults to `false`
+     * @returns The formatted date string, or `null` if invalid input or in case of an error
+     */
+    formatDate: (date: string, forClient?: boolean) => string | null;
+    /**
+     * Formats a social media platform for display.
+     * @param {SocialMediaPlatform} platform - The social media platform to be formatted
+     * @returns The formatted social media platform string
+     */
+    formatSocialMediaPlatform: (platform: SocialMediaPlatform) => string;
+    /**
+     * Returns an age in years given a birth date.
+     * @param {Date | string | number | null} dateOfBirth - The date of birth
+     * @returns The age in years, or `NaN` if the input is invalid
+     */
+    getAge: (dateOfBirth: Date | string | number | null) => number;
+    /**
+     * Formats a date as a locale-specific string.
+     * @param {Date | string | number | null} date - Date to be formatted
+     * @param {boolean} withTime - Specify whether the date should include time; defaults to `false`
+     * @param {string} timeZone - The time zone to use for formatting; defaults to `Africa/Nairobi`
+     * @returns The formatted date string, or an empty string if invalid input
+     */
+    getDateString: (date: Date | string | number | null, withTime?: boolean, timeZone?: string) => string;
+    /**
+     * Formats an identity type for display.
+     * @param {IdentityType} identityType - The identity type to be formatted
+     * @returns The formatted identity type string
+     */
+    getIdentityTypeString: (identityType: IdentityType) => string;
+    /**
+     * Formats a date to an ISO string in Kenyan time, i.e. `Africa/Nairobi` (UTC+3).
+     * @param {Date | string | number | null} date - The date to format
+     * @returns {string} The formatted date in ISO string format, or an empty string if invalid input
+     */
+    getKenyanISOString: (date: Date | string | number | null) => string;
+    /**
+     * Returns a pronoun given pronouns and a type.
+     * @param {PronounsItem | null} pronouns - The pronouns to be formatted
+     * @param {"subject" | "object" | "possessive" | "reflexive"} type - The type of pronoun to be returned
+     * @param {Sex} sex - The user's sex; defaults to `undefined`
+     * @returns The formatted pronoun, or `null` if the input is invalid
+     */
+    getPronoun: (pronouns: PronounsItem | null, type: "subject" | "object" | "possessive" | "reflexive", sex?: Sex) => string | null;
+    /**
+     * Paginates an array.
+     * @template T - The type of array items; defaults to `any`
+     * @param {T[]} array - The array to paginate
+     * @param {number} page - The page number
+     * @param {number} pageSize - The number of items per page; defaults to 10
+     * @returns {Object} The paginated array and total number of pages
+     */
+    paginateArray: <T = any>(array: T[], page: number, pageSize?: number) => {
+        paginatedItems: T[];
+        totalPages: number;
+    };
+    /**
+     * Sanitises any potential HTML injected into user input.
+     * @param {string} input - The input to be sanitised
+     * @returns A sanitised string, or an empty string if the input is invalid
+     */
+    sanitiseHtml: (input: string) => string;
+};
+export declare const Validate: {
+    /**
+     * A regular expression for E.164 phone numbers.
+     *
+     * - Source: https://www.twilio.com/docs/glossary/what-e164
+     */
+    e164Regex: RegExp;
+    /**
+     * The minimum birth date (from today's date) for a user who is a minor, i.e. `YYYY-MM-DD`
+     */
+    minimumMinorBirthDate: string;
+    /**
+     * A regular expression for user passwords to match during authentication. It covers the following rules:
+     * - at least 8 characters long
+     * - at least one digit
+     * - at least one lowercase letter
+     * - at least one uppercase letter
+     * - at least one symbol
+     */
+    passwordRegex: RegExp;
+    /**
+     * A regular expression for social media handles, without a leading slash or @ character.
+     *
+     * - Source: https://stackoverflow.com/a/74579651
+     */
+    socialMediaHandleRegex: RegExp;
+    /**
+     * An array of values representing social media platforms recognised in the database.
+     */
+    socialMediaPlatforms: SocialMediaPlatformObject[];
+    /**
+     * Validates an E.164 phone number.
+     * @param {string} phoneNumber - The phone number to be validated
+     * @param {"any" | MobilePhoneLocale | MobilePhoneLocale[]} [locale="any"] - The locale(s) to validate the phone number against
+     * @returns `true` if the phone number is valid; `false` otherwise
+     */
+    validateE164: (phoneNumber: string, locale?: "any" | MobilePhoneLocale | MobilePhoneLocale[]) => boolean;
+    /**
+     * Validates a social media handle.
+     * @param {string} handle - The social media handle to be validated
+     * @returns `true` if the handle is valid; `false` otherwise
+     */
+    validateSocialMediaHandle: (handle: string) => boolean;
+};

package/dist/formatting.js

@@ -0,0 +1,369 @@
+import validator from "validator";
+/* HELPERS */
+const sanitize = (await import("sanitize-html")).default;
+const { isMobilePhone, isURL } = validator;
+/* DATA TRANSFORMATION HELPERS */
+export const Transform = {
+    /**
+     * Capitalises a given word.
+     * @param {string} word - The word to be capitalised
+     * @returns The capitalised word
+     */
+    capitalise: (word) => word.charAt(0).toUpperCase() +
+        word
+            .slice(1)
+            .split("")
+            .map((c) => c.toLowerCase())
+            .join(""),
+    /**
+     * Cleans a URL by removing the protocol and trailing slashes.
+     * @param {string} url - The URL to clean
+     * @returns {string} The cleaned URL
+     */
+    cleanUrl: (url) => url.replace(/^https?:\/\//, "").replace(/\/+$/, ""),
+    /**
+     * Formats a date in the format DD/MM/YYYY (by default) or YYYY-MM-DD (for client).
+     * @param {string} date - Date to be formatted
+     * @param {boolean} forClient - Specify whether the data is for displaying on the client; defaults to `false`
+     * @returns The formatted date string, or `null` if invalid input or in case of an error
+     */
+    formatDate: (date, forClient = false) => {
+        // Return null if no date is provided
+        if (date === "" || typeof date !== "string")
+            return null;
+        // Handle input
+        try {
+            // Parse date string
+            const parsedDate = Date.parse(date);
+            // Return null if date string is not parseable
+            if (isNaN(parsedDate))
+                return null;
+            // Use the Intl.DateTimeFormat with explicit options to ensure correct formatting
+            const formattedDate = new Intl.DateTimeFormat(forClient ? "fr-CA" : "en-KE", {
+                day: "2-digit",
+                month: "2-digit",
+                year: "numeric",
+                timeZone: "Africa/Nairobi"
+            }).format(parsedDate);
+            // Return formatted date string
+            return formattedDate;
+        }
+        catch (error) {
+            console.error(error);
+            return null;
+        }
+    },
+    /**
+     * Formats a social media platform for display.
+     * @param {SocialMediaPlatform} platform - The social media platform to be formatted
+     * @returns The formatted social media platform string
+     */
+    formatSocialMediaPlatform: (platform) => {
+        const platforms = Validate.socialMediaPlatforms.map(({ value }) => value);
+        if (!platforms.includes(platform))
+            return "";
+        if (platform === "tiktok")
+            return "TikTok";
+        if (platform === "twitter")
+            return "X (formerly Twitter)";
+        if (platform === "youtube")
+            return "YouTube";
+        return Transform.capitalise(platform);
+    },
+    /**
+     * Returns an age in years given a birth date.
+     * @param {Date | string | number | null} dateOfBirth - The date of birth
+     * @returns The age in years, or `NaN` if the input is invalid
+     */
+    getAge: (dateOfBirth) => {
+        // Return NaN if no date is provided
+        if (!dateOfBirth)
+            return NaN;
+        // Validate and process date of birth
+        let birthDate;
+        if (dateOfBirth instanceof Date) {
+            if (isNaN(dateOfBirth.getTime()))
+                return NaN;
+            birthDate = dateOfBirth;
+        }
+        else if (typeof dateOfBirth === "string") {
+            if (dateOfBirth === "" || isNaN(Date.parse(dateOfBirth)))
+                return NaN;
+            // Format date of birth if it's a string
+            const formattedDate = Transform.formatDate(dateOfBirth, true);
+            if (!formattedDate)
+                return NaN;
+            birthDate = new Date(formattedDate);
+        }
+        else if (typeof dateOfBirth === "number") {
+            if (isNaN(dateOfBirth))
+                return NaN;
+            birthDate = new Date(dateOfBirth);
+        }
+        else {
+            return NaN;
+        }
+        // Validate the final date object
+        if (isNaN(birthDate.getTime()))
+            return NaN;
+        // Calculate age
+        const currentDate = new Date();
+        const monthDiff = currentDate.getMonth() - birthDate.getMonth();
+        let age = currentDate.getFullYear() - birthDate.getFullYear();
+        // Return age
+        return monthDiff < 0 || (monthDiff === 0 && currentDate.getDate() < birthDate.getDate()) ? --age : age;
+    },
+    /**
+     * Formats a date as a locale-specific string.
+     * @param {Date | string | number | null} date - Date to be formatted
+     * @param {boolean} withTime - Specify whether the date should include time; defaults to `false`
+     * @param {string} timeZone - The time zone to use for formatting; defaults to `Africa/Nairobi`
+     * @returns The formatted date string, or an empty string if invalid input
+     */
+    getDateString: (date, withTime = false, timeZone = "Africa/Nairobi") => {
+        // Return empty string if no date is provided
+        if (!date)
+            return "";
+        // Validate date to format
+        let dateToFormat;
+        if (date instanceof Date) {
+            if (isNaN(date.getTime()))
+                return "";
+            dateToFormat = date;
+        }
+        else if (typeof date === "string" || typeof date === "number") {
+            if (typeof date === "string" && (date === "" || isNaN(Date.parse(date))))
+                return "";
+            if (typeof date === "number" && isNaN(date))
+                return "";
+            dateToFormat = new Date(date);
+        }
+        else
+            return "";
+        // Validate the final date object
+        if (isNaN(dateToFormat.getTime()))
+            return "";
+        // Format date
+        return dateToFormat.toLocaleString("en-KE", {
+            timeZone,
+            year: "numeric",
+            month: "long",
+            day: "numeric",
+            hour: withTime ? "numeric" : undefined,
+            minute: withTime ? "2-digit" : undefined,
+            hour12: withTime ? true : undefined
+        });
+    },
+    /**
+     * Formats an identity type for display.
+     * @param {IdentityType} identityType - The identity type to be formatted
+     * @returns The formatted identity type string
+     */
+    getIdentityTypeString: (identityType) => {
+        if (identityType === "national")
+            return "National ID";
+        if (identityType === "alien")
+            return "Alien ID";
+        if (identityType === "passport")
+            return "Passport";
+        if (identityType === "driver_licence")
+            return "Driver's licence";
+        return "";
+    },
+    /**
+     * Formats a date to an ISO string in Kenyan time, i.e. `Africa/Nairobi` (UTC+3).
+     * @param {Date | string | number | null} date - The date to format
+     * @returns {string} The formatted date in ISO string format, or an empty string if invalid input
+     */
+    getKenyanISOString: (date) => {
+        // Return empty string if no date is provided or input is invalid
+        if (!date || (typeof date !== "string" && typeof date !== "number" && !(date instanceof Date)))
+            return "";
+        // Get locale string to format
+        const dateObj = date instanceof Date ? date : new Date(date);
+        const localeString = dateObj.toLocaleString("sv-SE", {
+            timeZone: "Africa/Nairobi"
+        });
+        // Return formatted string
+        return localeString.replace(" ", "T") + "+03:00";
+    },
+    /**
+     * Returns a pronoun given pronouns and a type.
+     * @param {PronounsItem | null} pronouns - The pronouns to be formatted
+     * @param {"subject" | "object" | "possessive" | "reflexive"} type - The type of pronoun to be returned
+     * @param {Sex} sex - The user's sex; defaults to `undefined`
+     * @returns The formatted pronoun, or `null` if the input is invalid
+     */
+    getPronoun: (pronouns, type, sex) => {
+        // Get pronoun from pronouns item
+        if (pronouns) {
+            // Return subject pronoun
+            if (type === "subject") {
+                if (pronouns === "he/him/his/himself")
+                    return "he";
+                if (pronouns === "she/her/hers/herself")
+                    return "she";
+                if (pronouns === "they/them/their/themself")
+                    return "they";
+                if (pronouns === "name_only")
+                    return "";
+            }
+            // Return object pronoun
+            else if (type === "object") {
+                if (pronouns === "he/him/his/himself")
+                    return "him";
+                if (pronouns === "she/her/hers/herself")
+                    return "her";
+                if (pronouns === "they/them/their/themself")
+                    return "them";
+                if (pronouns === "name_only")
+                    return "";
+            }
+            // Return possessive pronoun
+            else if (type === "possessive") {
+                if (pronouns === "he/him/his/himself")
+                    return "his";
+                if (pronouns === "she/her/hers/herself")
+                    return "her";
+                if (pronouns === "they/them/their/themself")
+                    return "their";
+                if (pronouns === "name_only")
+                    return "";
+            }
+            // Return reflexive pronoun
+            else if (type === "reflexive") {
+                if (pronouns === "he/him/his/himself")
+                    return "himself";
+                if (pronouns === "she/her/hers/herself")
+                    return "herself";
+                if (pronouns === "they/them/their/themself")
+                    return "themself";
+                if (pronouns === "name_only")
+                    return "";
+            }
+        }
+        // Assume pronoun for sex if no pronouns are provided
+        else if (sex) {
+            // Return subject pronoun
+            if (type === "subject") {
+                if (sex === "male" || sex === "intersex_man")
+                    return "he";
+                if (sex === "female" || sex === "intersex_woman")
+                    return "she";
+                return "they";
+            }
+            // Return object pronoun
+            else if (type === "object") {
+                if (sex === "male" || sex === "intersex_man")
+                    return "him";
+                if (sex === "female" || sex === "intersex_woman")
+                    return "her";
+                return "them";
+            }
+            // Return possessive pronoun
+            else if (type === "possessive") {
+                if (sex === "male" || sex === "intersex_man")
+                    return "his";
+                if (sex === "female" || sex === "intersex_woman")
+                    return "her";
+                return "their";
+            }
+            // Return reflexive pronoun
+            else if (type === "reflexive") {
+                if (sex === "male" || sex === "intersex_man")
+                    return "himself";
+                if (sex === "female" || sex === "intersex_woman")
+                    return "herself";
+                return "themself";
+            }
+        }
+        // Return null
+        return null;
+    },
+    /**
+     * Paginates an array.
+     * @template T - The type of array items; defaults to `any`
+     * @param {T[]} array - The array to paginate
+     * @param {number} page - The page number
+     * @param {number} pageSize - The number of items per page; defaults to 10
+     * @returns {Object} The paginated array and total number of pages
+     */
+    paginateArray: (array, page, pageSize = 10) => {
+        // Define variables
+        const startIndex = (page - 1) * pageSize;
+        const endIndex = startIndex + pageSize;
+        const totalPages = Math.ceil(array.length / pageSize);
+        // Paginate items
+        const paginatedItems = array.slice(startIndex, endIndex);
+        // Return data
+        return { paginatedItems, totalPages };
+    },
+    /**
+     * Sanitises any potential HTML injected into user input.
+     * @param {string} input - The input to be sanitised
+     * @returns A sanitised string, or an empty string if the input is invalid
+     */
+    sanitiseHtml: (input) => typeof input !== "string" ? "" : sanitize(input, { allowedTags: [], allowedAttributes: {} })
+};
+/* DATA VALIDATION HELPERS */
+export const Validate = {
+    /**
+     * A regular expression for E.164 phone numbers.
+     *
+     * - Source: https://www.twilio.com/docs/glossary/what-e164
+     */
+    e164Regex: /^\+?[1-9]\d{1,14}$/,
+    /**
+     * The minimum birth date (from today's date) for a user who is a minor, i.e. `YYYY-MM-DD`
+     */
+    minimumMinorBirthDate: (() => {
+        const today = new Date();
+        const tomorrow = new Date();
+        tomorrow.setUTCDate(today.getDate() + 1);
+        const tomorrow18YearsAgo = tomorrow.getFullYear() - 18;
+        tomorrow.setFullYear(tomorrow18YearsAgo);
+        return tomorrow.toISOString().split("T")[0];
+    })(),
+    /**
+     * A regular expression for user passwords to match during authentication. It covers the following rules:
+     * - at least 8 characters long
+     * - at least one digit
+     * - at least one lowercase letter
+     * - at least one uppercase letter
+     * - at least one symbol
+     */
+    passwordRegex: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[!@#$%^&*()\-_+=|{}\[\]:;'<>,.?/~]).{8,}$/,
+    /**
+     * A regular expression for social media handles, without a leading slash or @ character.
+     *
+     * - Source: https://stackoverflow.com/a/74579651
+     */
+    socialMediaHandleRegex: /^([A-Za-z0-9_.]{3,25})$/gm,
+    /**
+     * An array of values representing social media platforms recognised in the database.
+     */
+    socialMediaPlatforms: [
+        { value: "facebook", linkPrefix: "https://www.facebook.com/" },
+        { value: "instagram", linkPrefix: "https://www.instagram.com/" },
+        { value: "kick", linkPrefix: "https://kick.com/" },
+        { value: "tiktok", linkPrefix: "https://www.tiktok.com/@" },
+        { value: "twitch", linkPrefix: "https://www.twitch.tv/" },
+        { value: "twitter", linkPrefix: "https://x.com/" },
+        { value: "youtube", linkPrefix: "https://www.youtube.com/@" }
+    ],
+    /**
+     * Validates an E.164 phone number.
+     * @param {string} phoneNumber - The phone number to be validated
+     * @param {"any" | MobilePhoneLocale | MobilePhoneLocale[]} [locale="any"] - The locale(s) to validate the phone number against
+     * @returns `true` if the phone number is valid; `false` otherwise
+     */
+    validateE164: (phoneNumber, locale = "en-KE") => isMobilePhone(phoneNumber, locale) && Boolean(phoneNumber.match(Validate.e164Regex)),
+    /**
+     * Validates a social media handle.
+     * @param {string} handle - The social media handle to be validated
+     * @returns `true` if the handle is valid; `false` otherwise
+     */
+    validateSocialMediaHandle: (handle) => !isURL(handle, { require_protocol: false }) &&
+        !handle.startsWith("@") &&
+        Boolean(handle.match(Validate.socialMediaHandleRegex))
+};

package/dist/general.d.ts

@@ -0,0 +1,54 @@
+export declare const Status: {
+    /**
+     * A generic error message.
+     */
+    ERROR: string;
+    /**
+     * A generic loading message.
+     */
+    LOADING: string;
+    /**
+     * A generic password reset request message.
+     */
+    PASSWORD_RESET_REQUESTED: string;
+};
+export declare const Cache: {
+    /**
+     * Delete cached data from Valkey.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     */
+    deleteData: (valkey: any, cachePrefix: string, key: string) => Promise<void>;
+    /**
+     * Generate cache key with consistent formatting
+     * @param prefix - The key prefix
+     * @param params - Additional parameters to include in the key
+     * @returns The formatted cache key
+     */
+    generateDataKey: (prefix: string, ...params: (string | number)[]) => string;
+    /**
+     * Get cached data from Valkey.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     * @returns The cached data, or `null` if not found
+     */
+    getData: <T>(valkey: any, cachePrefix: string, key: string) => Promise<T | null>;
+    /**
+     * Invalidate cache by pattern
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param pattern - The pattern to match keys against (e.g., "app-config*")
+     */
+    invalidateDataByPattern: (valkey: any, cachePrefix: string, pattern: string) => Promise<void>;
+    /**
+     * Set data in Valkey cache.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     * @param data - The data to cache
+     * @param ttl - The time to live in seconds; defaults to 1 hour
+     */
+    setData: <T>(valkey: any, cachePrefix: string, key: string, data: T, ttl?: number) => Promise<void>;
+};

package/dist/general.js

@@ -0,0 +1,88 @@
+/* STATUS MESSAGES */
+export const Status = {
+    /**
+     * A generic error message.
+     */
+    ERROR: "An unexpected error occurred. Kindly try again.",
+    /**
+     * A generic loading message.
+     */
+    LOADING: "Please wait…",
+    /**
+     * A generic password reset request message.
+     */
+    PASSWORD_RESET_REQUESTED: "If the provided email address is registered, you will receive a password reset link shortly."
+};
+/* CACHE HELPERS */
+export const Cache = {
+    /**
+     * Delete cached data from Valkey.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     */
+    deleteData: async (valkey, cachePrefix, key) => {
+        try {
+            await valkey.del(`${cachePrefix}${key}`);
+        }
+        catch (error) {
+            console.error("Cache delete error:", error);
+        }
+    },
+    /**
+     * Generate cache key with consistent formatting
+     * @param prefix - The key prefix
+     * @param params - Additional parameters to include in the key
+     * @returns The formatted cache key
+     */
+    generateDataKey: (prefix, ...params) => `${prefix}:${params.join(":")}`,
+    /**
+     * Get cached data from Valkey.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     * @returns The cached data, or `null` if not found
+     */
+    getData: async (valkey, cachePrefix, key) => {
+        try {
+            const cached = await valkey.get(`${cachePrefix}${key}`);
+            return cached ? JSON.parse(cached) : null;
+        }
+        catch (error) {
+            console.error("Cache get error:", error);
+            return null;
+        }
+    },
+    /**
+     * Invalidate cache by pattern
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param pattern - The pattern to match keys against (e.g., "app-config*")
+     */
+    invalidateDataByPattern: async (valkey, cachePrefix, pattern) => {
+        try {
+            const keys = await valkey.keys(`${cachePrefix}${pattern}`);
+            if (keys.length > 0)
+                await valkey.del(...keys);
+        }
+        catch (error) {
+            console.error("Cache pattern invalidation error:", error);
+        }
+    },
+    /**
+     * Set data in Valkey cache.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     * @param data - The data to cache
+     * @param ttl - The time to live in seconds; defaults to 1 hour
+     */
+    setData: async (valkey, cachePrefix, key, data, ttl = 3600) => {
+        try {
+            await valkey.setex(`${cachePrefix}${key}`, ttl, JSON.stringify(data));
+        }
+        catch (error) {
+            console.error("Cache set error:", error);
+        }
+    }
+};