@koloseum/utils 0.2.8 → 0.2.10

package/dist/utils.d.ts

@@ -1,6 +1,6 @@
 import type { Database } from "@koloseum/types/database";
 import type { CustomError, Microservice, MicroserviceGroup, MicroserviceObject, UserWithCustomMetadata } from "@koloseum/types/general";
-import type { IdentityType, PronounsCheckboxes, PronounsItem, Sex, SocialMediaPlatform } from "@koloseum/types/public-auth";
+import type { BranchAddressObject, County, IdentityType, PronounsCheckboxes, PronounsItem, Sex, SocialMediaPlatform } from "@koloseum/types/public-auth";
 import type { Page } from "@sveltejs/kit";
 import type { SupabaseClient, FunctionInvokeOptions, PostgrestError } from "@supabase/supabase-js";
 import type { IOptions } from "@suprsend/web-components/dist/types/interface.d.ts";
@@ -103,6 +103,12 @@ export declare const Utility: {
      * @returns The formatted identity type string
      */
     getIdentityTypeString: (identityType: IdentityType) => string;
+    /**
+     * Returns a list of all counties in Kenya.
+     * @param {"name" | "code"} sortBy - The field to sort the counties by, i.e. `name` or `code`; defaults to `name`
+     * @returns {Promise<County[]>} A list of objects with the county `name`, `code`, and a list of `subCounties`
+     */
+    getKenyaCounties: (sortBy?: "name" | "code") => Promise<County[]>;
     /**
      * Returns the URL for a menu item based on the slug.
      * @param {string} base - The base URL
@@ -183,12 +189,31 @@ export declare const Utility: {
      * @returns `true` if the page is active, `false` otherwise.
      */
     pageIsActive: (page: Page, slug: string | undefined, microservice?: Microservice<MicroserviceGroup>, base?: string) => boolean;
+    /**
+     * 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;
+    };
     /**
      * Parses a `CustomError` object within a page/layout server load function and returns an error to be thrown.
      * @param {CustomError} error - The error object
      * @returns A new `Error` object if the error is unexpected, or a Svelte error otherwise
      */
     parseLoadError: (error: CustomError) => Error | never;
+    /**
+     * Parses a Postgres interval string and returns a string in the specified format.
+     * @param {string} interval - The interval string to parse
+     * @param {"postgres" | "iso" | "iso-short"} type - The format to return the interval in; defaults to `postgres`
+     * @returns A string in the specified format
+     */
+    parsePostgresInterval: (interval: string, type?: "postgres" | "iso" | "iso-short") => string | null;
     /**
      * Parses a `PostgrestError` object and returns a custom error object if any has occurred.
      * @param {PostgrestError | null} postgrestError - The `PostgrestError` object, or `null` if no error occurred
@@ -224,6 +249,15 @@ export declare const Utility: {
      * - Source: https://stackoverflow.com/a/74579651
      */
     socialMediaHandleRegex: RegExp;
+    /**
+     * Validates address data submitted in a form and returns the validated data.
+     * @param {FormData} formData - The submitted form data
+     * @returns An object with the validated `address`, or an `error` if any has occurred
+     */
+    validateAddress: (formData: FormData) => Promise<{
+        address?: BranchAddressObject;
+        error?: CustomError;
+    }>;
     /**
      * Validates an E.164 phone number.
      * @param {string} phoneNumber - The phone number to be validated

package/dist/utils.js

@@ -2,10 +2,13 @@ import { v4 as uuidv4 } from "uuid";
 import { error as svelteError } from "@sveltejs/kit";
 import { FunctionsFetchError, FunctionsHttpError, FunctionsRelayError } from "@supabase/supabase-js";
 import validator from "validator";
-/* Helper functions */
+/* HELPERS */
+const parsePgInterval = (await import("postgres-interval")).default;
 const sanitize = (await import("sanitize-html")).default;
-const { isMobilePhone, isURL } = validator;
-/* Dummy data */
+const { trim, escape, isMobilePhone, isURL } = validator;
+const { KenyaAdministrativeDivisions } = (await import("kenya-administrative-divisions"));
+const kenyaAdmin = new KenyaAdministrativeDivisions();
+/* DUMMY DATA */
 export const Data = {
     /**
      * A generic authenticated user.
@@ -68,7 +71,7 @@ export const Data = {
         };
     }
 };
-/* Status messages */
+/* STATUS MESSAGES */
 export const Status = {
     /**
      * A generic error message.
@@ -83,7 +86,7 @@ export const Status = {
      */
     PASSWORD_RESET_REQUESTED: "If the provided email address is registered, you will receive a password reset link shortly."
 };
-/* Utility functions */
+/* UTILITY FUNCTIONS */
 export const Utility = {
     /**
      * Calls a Supabase Edge function.
@@ -328,6 +331,32 @@ export const Utility = {
             return "Driver's licence";
         return "";
     },
+    /**
+     * Returns a list of all counties in Kenya.
+     * @param {"name" | "code"} sortBy - The field to sort the counties by, i.e. `name` or `code`; defaults to `name`
+     * @returns {Promise<County[]>} A list of objects with the county `name`, `code`, and a list of `subCounties`
+     */
+    getKenyaCounties: async (sortBy = "name") => {
+        // Get all counties
+        const countiesData = await kenyaAdmin.getAll();
+        // Format counties
+        const counties = countiesData.map((county) => {
+            // Get list of sub-counties
+            const subCounties = [];
+            for (const subCounty of county.constituencies)
+                subCounties.push(subCounty.constituency_name);
+            subCounties.sort();
+            // Format county name and add to list
+            const countyName = county.county_name.split(" ");
+            let name = county.county_name;
+            if (countyName.length > 1)
+                name = countyName.map((word) => Utility.capitalise(word)).join(" ");
+            // Return county
+            return { name, code: county.county_code, subCounties };
+        });
+        // Return sorted counties
+        return counties.sort((a, b) => (sortBy === "name" ? a.name.localeCompare(b.name) : a.code - b.code));
+    },
     /**
      * Returns the URL for a menu item based on the slug.
      * @param {string} base - The base URL
@@ -981,7 +1010,7 @@ export const Utility = {
                                     {
                                         name: "Rankings",
                                         description: "Manage rankings for any Savanna Circuit season.",
-                                        slug: "rankings"
+                                        root: true
                                     },
                                     {
                                         name: "Tournaments",
@@ -989,20 +1018,15 @@ export const Utility = {
                                         slug: "tournaments",
                                         tabs: [
                                             {
-                                                name: "Players",
-                                                description: "Manage Players for any Savanna Circuit tournament.",
-                                                slug: "players"
+                                                name: "Events",
+                                                description: "Manage events for any Savanna Circuit tournament.",
+                                                root: true
                                             },
                                             {
                                                 name: "Tickets",
                                                 description: "Manage tickets for any Savanna Circuit tournament.",
                                                 slug: "tickets"
                                             },
-                                            {
-                                                name: "Events",
-                                                description: "Manage events for any Savanna Circuit tournament.",
-                                                slug: "events"
-                                            },
                                             {
                                                 name: "Settings",
                                                 description: "Manage settings for any Savanna Circuit tournament.",
@@ -1178,12 +1202,51 @@ export const Utility = {
         const target = `${cleanBase}/${slug}`;
         return page.url.pathname === target || page.url.pathname.startsWith(`${target}/`);
     },
+    /**
+     * 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 };
+    },
     /**
      * Parses a `CustomError` object within a page/layout server load function and returns an error to be thrown.
      * @param {CustomError} error - The error object
      * @returns A new `Error` object if the error is unexpected, or a Svelte error otherwise
      */
     parseLoadError: (error) => error.code === 500 ? new Error(error.message) : svelteError(error.code, { message: error.message }),
+    /**
+     * Parses a Postgres interval string and returns a string in the specified format.
+     * @param {string} interval - The interval string to parse
+     * @param {"postgres" | "iso" | "iso-short"} type - The format to return the interval in; defaults to `postgres`
+     * @returns A string in the specified format
+     */
+    parsePostgresInterval: (interval, type = "postgres") => {
+        // Return null if interval is falsy
+        if (!interval)
+            return null;
+        // Parse interval and return in the specified format
+        const parsed = parsePgInterval(interval);
+        if (type === "postgres")
+            return parsed.toPostgres();
+        if (type === "iso")
+            return parsed.toISOString();
+        if (type === "iso-short")
+            return parsed.toISOStringShort();
+        // Return null if type is invalid
+        return null;
+    },
     /**
      * Parses a `PostgrestError` object and returns a custom error object if any has occurred.
      * @param {PostgrestError | null} postgrestError - The `PostgrestError` object, or `null` if no error occurred
@@ -1277,6 +1340,102 @@ export const Utility = {
      * - Source: https://stackoverflow.com/a/74579651
      */
     socialMediaHandleRegex: /^([A-Za-z0-9_.]{3,25})$/gm,
+    /**
+     * Validates address data submitted in a form and returns the validated data.
+     * @param {FormData} formData - The submitted form data
+     * @returns An object with the validated `address`, or an `error` if any has occurred
+     */
+    validateAddress: async (formData) => {
+        // Building name
+        let buildingName = formData.get("building-name");
+        if (!buildingName)
+            return { error: Utility.customError(400, "Building name is required.") };
+        buildingName = Utility.sanitiseHtml(trim(escape(buildingName)));
+        // Unit number
+        let unitNumber = formData.get("unit-number") || undefined;
+        if (unitNumber) {
+            unitNumber = Utility.sanitiseHtml(trim(escape(unitNumber)));
+            if (unitNumber === "")
+                unitNumber = undefined;
+        }
+        // Street name
+        let streetName = formData.get("street-name");
+        if (!streetName)
+            return { error: Utility.customError(400, "Street name is required.") };
+        streetName = Utility.sanitiseHtml(trim(escape(streetName)));
+        // P.O. box and postal code
+        let boxNumber = formData.get("box-number") || undefined;
+        let postalCode = formData.get("postal-code") || undefined;
+        if (boxNumber) {
+            boxNumber = Utility.sanitiseHtml(trim(escape(boxNumber)));
+            if (boxNumber === "")
+                boxNumber = undefined;
+            if (boxNumber && !postalCode)
+                return { error: Utility.customError(400, "Postal code is required.") };
+        }
+        if (postalCode) {
+            postalCode = Utility.sanitiseHtml(trim(escape(postalCode)));
+            if (postalCode === "")
+                postalCode = undefined;
+            if (postalCode && !boxNumber)
+                return { error: Utility.customError(400, "P.O. box is required.") };
+        }
+        // Town
+        let town = formData.get("town");
+        if (!town)
+            return { error: Utility.customError(400, "City/town is required.") };
+        town = Utility.sanitiseHtml(trim(escape(town)));
+        // County
+        let county = undefined;
+        const countyCode = Number(formData.get("county-code"));
+        if (isNaN(countyCode))
+            return { error: Utility.customError(400, "County is invalid.") };
+        if (!countyCode)
+            return { error: Utility.customError(400, "County is required.") };
+        const counties = await kenyaAdmin.getAll();
+        if (!counties || counties.length === 0)
+            return { error: Utility.customError(400, "County is invalid.") };
+        const countyData = counties.find(({ county_code }) => county_code === countyCode);
+        if (!countyData)
+            return { error: Utility.customError(400, "County is invalid.") };
+        const { county_name, constituencies } = countyData;
+        county = county_name;
+        // Sub-county
+        let subCounty = formData.get("sub-county") || undefined;
+        if (subCounty) {
+            subCounty = Utility.sanitiseHtml(trim(escape(subCounty)));
+            if (subCounty === "")
+                subCounty = undefined;
+            else {
+                // Check if constituencies exists and is an array before mapping
+                if (!constituencies || !Array.isArray(constituencies))
+                    return { error: Utility.customError(400, "Sub-county data is unavailable.") };
+                // Get list of sub-counties
+                const subCounties = constituencies.map(({ constituency_name: name }) => name);
+                if (!subCounties.includes(subCounty))
+                    return { error: Utility.customError(400, "Sub-county is invalid.") };
+            }
+        }
+        // Additional information
+        let additionalInfo = formData.get("address-additional-info") || undefined;
+        if (additionalInfo) {
+            additionalInfo = Utility.sanitiseHtml(trim(escape(additionalInfo)));
+            if (additionalInfo === "")
+                additionalInfo = undefined;
+        }
+        // Create address object
+        const address = {
+            buildingName,
+            unitNumber,
+            streetName,
+            town,
+            subCounty,
+            county,
+            additionalInfo
+        };
+        // Return data
+        return { address };
+    },
     /**
      * Validates an E.164 phone number.
      * @param {string} phoneNumber - The phone number to be validated

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@koloseum/utils",
-	"version": "0.2.8",
+	"version": "0.2.10",
 	"author": "Koloseum Technologies Limited",
 	"type": "module",
 	"description": "Utility logic for use across Koloseum web apps (TypeScript)",
@@ -31,17 +31,19 @@
 	"dependencies": {
 		"@supabase/supabase-js": "^2.50.1",
 		"@sveltejs/kit": "^2.22.0",
+		"kenya-administrative-divisions": "^0.0.18",
 		"sanitize-html": "^2.17.0",
 		"uuid": "^11.1.0",
 		"validator": "^13.15.15"
 	},
 	"devDependencies": {
-		"@koloseum/types": "^0.2.1",
+		"@koloseum/types": "^0.2.4",
 		"@playwright/test": "^1.53.1",
 		"@suprsend/web-components": "^0.2.1",
 		"@types/sanitize-html": "^2.16.0",
 		"@types/uuid": "^10.0.0",
 		"@types/validator": "^13.15.2",
+		"postgres-interval": "^4.0.2",
 		"prettier": "^3.6.0",
 		"typescript": "^5.8.3",
 		"vitest": "^3.2.4"