@temboplus/frontend-core 0.1.0

package/esm/src/models/amount/amount.js

@@ -0,0 +1,229 @@
+// Regex explanation:
+// ^(?:\d{1,3}(?:,\d{3})*|\d+) - Either grouped digits with commas OR just digits
+// (?:\.\d+)?$ - Optional decimal part with any number of digits
+const AMOUNT_REGEX = /^(?:\d{1,3}(?:,\d{3})*|\d+)(?:\.\d+)?$/;
+class Amount {
+    constructor(value, text) {
+        Object.defineProperty(this, "value", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "text", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.value = value;
+        this.text = text;
+    }
+    /**
+     * Creates an Amount instance from a string or number input
+     * Returns undefined if input is invalid or negative
+     * @param input - The input value (string or number)
+     * @returns Amount instance or undefined if validation fails
+     */
+    static from(input) {
+        let amountText = input.toString().trim();
+        console.log(amountText);
+        if (hasComma(amountText)) {
+            if (!hasValidCommaPlacement(amountText))
+                return undefined;
+        }
+        amountText = removeCommasAndCurrency(amountText);
+        // Handle string input
+        if (!AMOUNT_REGEX.test(amountText))
+            return undefined;
+        // Convert string to number, removing commas
+        const value = Number(amountText.replace(/,/g, ""));
+        if (!Number.isFinite(value) || value < 0)
+            return undefined;
+        // Round to 2 decimal places and format the text representation
+        const roundedValue = Number(value.toFixed(2));
+        const text = roundedValue.toLocaleString("en-US", {
+            minimumFractionDigits: 2,
+            maximumFractionDigits: 2,
+        });
+        return new Amount(roundedValue, text);
+    }
+    /**
+     * Returns the formatted string representation of the amount with TZS prefix
+     */
+    get label() {
+        return `TZS ${this.text}`;
+    }
+    /**
+     * Returns the numeric value of the amount
+     */
+    get numericValue() {
+        return this.value;
+    }
+    /**
+     * Returns the formatted numeric value of the amount
+     */
+    get formattedNumericValue() {
+        return this.numericValue.toLocaleString("en-US", {
+            minimumFractionDigits: 2,
+            maximumFractionDigits: 2,
+        });
+    }
+    /**
+     * Checks if the amount is valid
+     * @param input amount to be checked for validity
+     * @returns true if the amount is valid, false otherwise
+     */
+    static canConstruct(input) {
+        /// (!input) alone does not work since input could 0 and (!input) return true for this case
+        if (input === undefined || input === null)
+            return false;
+        const amount = Amount.from(input);
+        if (!amount)
+            return false;
+        return true;
+    }
+    /**
+     * Checks if an unknown value is an Amount instance.
+     * Validates the structural integrity of an amount object.
+     *
+     * @param {unknown} obj - The value to validate
+     * @returns {obj is Amount} Type predicate indicating if the value is a valid Amount
+     *
+     * @example
+     * const maybeAmount = JSON.parse(someData);
+     * if (Amount.is(maybeAmount)) {
+     *   console.log(maybeAmount.label); // maybeAmount is typed as Amount
+     * }
+     *
+     * @see {@link Amount.canConstruct} for validating raw amount values
+     * @see {@link Amount.from} for constructing new instances
+     */
+    static is(obj) {
+        if (!obj || typeof obj !== "object")
+            return false;
+        const maybeAmount = obj;
+        // Check required properties exist with correct types
+        if (typeof maybeAmount.value !== "number")
+            return false;
+        if (typeof maybeAmount.text !== "string")
+            return false;
+        const value = maybeAmount.value;
+        const text = maybeAmount.text;
+        // Validate numeric constraints
+        if (!Number.isFinite(value) || value < 0)
+            return false;
+        const canConstruct = Amount.canConstruct(value);
+        if (!canConstruct)
+            return false;
+        const amount = Amount.from(value);
+        return amount != undefined && amount.value === value &&
+            amount.text === text;
+    }
+    /**
+     * Checks the validity of the amount data
+     * @returns true if the amount data is available and valid
+     */
+    validate() {
+        try {
+            return Amount.canConstruct(this.value);
+        }
+        catch (_) {
+            return false;
+        }
+    }
+}
+/**
+ * Removes commas and "TZS" symbol (if present) from a string.
+ * Handles both prefixed and suffixed "TZS" symbols, with or without spaces.
+ *
+ * @param {string} text - The input string to clean
+ * @returns {string} A string with commas and "TZS" symbol removed
+ *
+ * @example
+ * removeCommasAndCurrency("1,234.56");         // Returns: "1234.56"
+ * removeCommasAndCurrency("TZS 1,234.56");     // Returns: "1234.56"
+ * removeCommasAndCurrency("1,234.56 TZS");     // Returns: "1234.56"
+ * removeCommasAndCurrency("TZS1,234.56");      // Returns: "1234.56"
+ * removeCommasAndCurrency("1234.56");          // Returns: "1234.56"
+ * removeCommasAndCurrency("");                 // Returns: ""
+ *
+ * @remarks
+ * - Case insensitive for "TZS" symbol
+ * - Removes all commas regardless of position
+ * - Handles optional spaces around the currency symbol
+ * - Returns empty string if input is empty
+ */
+function removeCommasAndCurrency(text) {
+    return text
+        .replace(/TZS\s*|\s*TZS/gi, "") // Remove TZS with optional spaces
+        .replace(/,/g, ""); // Remove all commas
+}
+/**
+ * Checks if commas in a numeric string are correctly placed to separate groups of three digits.
+ * Only validates the part before the decimal point if one exists.
+ *
+ * @param {string} text - The input string to validate
+ * @returns {boolean} True if commas are correctly placed or if there are no commas, false otherwise
+ *
+ * @example
+ * hasValidCommaPlacement("1,234,567.89");     // Returns: true
+ * hasValidCommaPlacement("1234567.89");       // Returns: true (no commas)
+ * hasValidCommaPlacement("1,234.56");         // Returns: true
+ * hasValidCommaPlacement("1,23,456");         // Returns: false (incorrect grouping)
+ * hasValidCommaPlacement("1,2345");           // Returns: false (incorrect grouping)
+ * hasValidCommaPlacement(",123");             // Returns: false (leading comma)
+ * hasValidCommaPlacement("1,234,");           // Returns: false (trailing comma)
+ * hasValidCommaPlacement("1,,234");           // Returns: false (consecutive commas)
+ *
+ * @remarks
+ * - Validates comma placement in the whole number part only
+ * - Each group after the first must be exactly 3 digits
+ * - First group can be 1-3 digits
+ * - Returns true if the string contains no commas
+ * - Does not validate the decimal part if present
+ */
+function hasValidCommaPlacement(text) {
+    // Split at decimal point if it exists and take the whole number part
+    const wholeNumberPart = text.split(".")[0];
+    // If no commas, it's valid
+    if (!wholeNumberPart.includes(",")) {
+        return true;
+    }
+    // Split the whole number by commas
+    const groups = wholeNumberPart.split(",");
+    // Check for invalid cases:
+    // - Empty string before/after comma (e.g. ",123" or "123,")
+    // - More than one empty group (consecutive commas)
+    if (groups.some((group) => group.length === 0)) {
+        return false;
+    }
+    // First group can be 1-3 digits
+    if (groups[0].length > 3 || groups[0].length < 1) {
+        return false;
+    }
+    // All other groups must be exactly 3 digits
+    return groups.slice(1).every((group) => group.length === 3);
+}
+/**
+ * Checks if a string contains a comma character.
+ *
+ * @param {string} text - The input string to check
+ * @returns {boolean} True if the string contains at least one comma, false otherwise
+ *
+ * @example
+ * hasComma("1,234.56");     // Returns: true
+ * hasComma("1234.56");      // Returns: false
+ * hasComma("hello,world");  // Returns: true
+ * hasComma("");            // Returns: false
+ * hasComma(",");           // Returns: true
+ *
+ * @remarks
+ * - Returns false for empty strings
+ * - Returns true if one or more commas are present
+ * - Position of the comma doesn't matter
+ */
+function hasComma(text) {
+    return text.includes(",");
+}
+export { Amount, AMOUNT_REGEX };

package/esm/src/models/amount/amount.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.test.d.ts","sourceRoot":"","sources":["../../../../src/src/models/amount/amount.test.ts"],"names":[],"mappings":""}

package/esm/src/models/amount/antd_validator.d.ts

@@ -0,0 +1,40 @@
+import type { RuleObject } from "antd/es/form";
+import { Amount } from "./index.js";
+/**
+ * Validates a monetary amount according to specified business rules.
+ * This validator is designed for Ant Design Form components and performs the following validations:
+ * 1. Required field validation (if specified in rules)
+ * 2. Format validation using AMOUNT_REGEX pattern for valid numeric format
+ * 3. Minimum amount threshold of TZS 1,000
+ *
+ * @param {RuleObject} rule - Ant Design rule object containing validation rules
+ * @param {string | number | undefined} value - The amount to validate
+ * @returns {Promise<void>} Resolves if validation passes, rejects with Error if validation fails
+ * @throws {Error} Throws an error with a descriptive message for validation failures:
+ *  - "Amount is required." - When field is required but empty/undefined
+ *  - "Invalid amount format." - When value doesn't match expected numeric format
+ *  - "Invalid numeric value." - When value can't be parsed to a valid number
+ *  - "Amount must not be less than TZS 1000." - When value is below minimum threshold
+ *
+ * @example
+ * // Usage in Ant Design form rules:
+ * const rules = [
+ *   {
+ *     required: true,
+ *     validator: AMOUNT_VALIDATOR
+ *   }
+ * ];
+ *
+ * // Valid inputs:
+ * // "1,000"     -> Valid format, meets minimum
+ * // "1500.50"   -> Valid decimal
+ * // 2000        -> Valid number
+ *
+ * // Invalid inputs:
+ * // "abc"       -> Invalid format
+ * // "500"       -> Below minimum
+ * // ""          -> Empty when required
+ * // undefined   -> Missing when required
+ */
+export declare const AMOUNT_VALIDATOR: (rule: RuleObject, value: string | number | null | undefined) => Promise<Amount | undefined>;
+//# sourceMappingURL=antd_validator.d.ts.map

package/esm/src/models/amount/antd_validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"antd_validator.d.ts","sourceRoot":"","sources":["../../../../src/src/models/amount/antd_validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,gBAAgB,SACrB,UAAU,SACT,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,KACxC,OAAO,CAAC,MAAM,GAAG,SAAS,CA0B5B,CAAC"}

package/esm/src/models/amount/antd_validator.js

@@ -0,0 +1,58 @@
+import { Amount } from "./index.js";
+/**
+ * Validates a monetary amount according to specified business rules.
+ * This validator is designed for Ant Design Form components and performs the following validations:
+ * 1. Required field validation (if specified in rules)
+ * 2. Format validation using AMOUNT_REGEX pattern for valid numeric format
+ * 3. Minimum amount threshold of TZS 1,000
+ *
+ * @param {RuleObject} rule - Ant Design rule object containing validation rules
+ * @param {string | number | undefined} value - The amount to validate
+ * @returns {Promise<void>} Resolves if validation passes, rejects with Error if validation fails
+ * @throws {Error} Throws an error with a descriptive message for validation failures:
+ *  - "Amount is required." - When field is required but empty/undefined
+ *  - "Invalid amount format." - When value doesn't match expected numeric format
+ *  - "Invalid numeric value." - When value can't be parsed to a valid number
+ *  - "Amount must not be less than TZS 1000." - When value is below minimum threshold
+ *
+ * @example
+ * // Usage in Ant Design form rules:
+ * const rules = [
+ *   {
+ *     required: true,
+ *     validator: AMOUNT_VALIDATOR
+ *   }
+ * ];
+ *
+ * // Valid inputs:
+ * // "1,000"     -> Valid format, meets minimum
+ * // "1500.50"   -> Valid decimal
+ * // 2000        -> Valid number
+ *
+ * // Invalid inputs:
+ * // "abc"       -> Invalid format
+ * // "500"       -> Below minimum
+ * // ""          -> Empty when required
+ * // undefined   -> Missing when required
+ */
+export const AMOUNT_VALIDATOR = (rule, value) => {
+    // Convert value to string and remove whitespace
+    const amountString = value?.toString().trim();
+    // If field is empty/undefined/null
+    if (!amountString) {
+        // Only throw if the field is required
+        if (rule.required) {
+            return Promise.reject(new Error("Amount is required."));
+        }
+        // If field is not required and empty, validation passes
+        return Promise.resolve(undefined);
+    }
+    const amount = Amount.from(amountString);
+    if (!amount) {
+        return Promise.reject(new Error("Invalid amount format."));
+    }
+    if (amount.numericValue < 1000) {
+        return Promise.reject(new Error("Amount must not be less than TZS 1000."));
+    }
+    return Promise.resolve(amount);
+};

package/esm/src/models/amount/antd_validator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"antd_validator.test.d.ts","sourceRoot":"","sources":["../../../../src/src/models/amount/antd_validator.test.ts"],"names":[],"mappings":""}

package/esm/src/models/amount/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./antd_validator.js";
+export * from "./amount.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/src/models/amount/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/src/models/amount/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC"}

package/esm/src/models/amount/index.js

@@ -0,0 +1,2 @@
+export * from "./antd_validator.js";
+export * from "./amount.js";

package/esm/src/models/bank/antd_validator.d.ts

@@ -0,0 +1,11 @@
+import type { RuleObject } from "antd/es/form";
+import { Bank } from "./bank.js";
+/**
+ * Validator for SWIFT code field.
+ * Ensures the SWIFT code follows the correct format and is recognized in the list of valid codes.
+ * @param {RuleObject} rule The rule object for validation
+ * @param {string} value The value to validate.
+ * @throws Will throw an error if validation fails.
+ */
+export declare const SWIFT_CODE_VALIDATOR: (rule: RuleObject, value: string | null | undefined) => Promise<Bank | undefined>;
+//# sourceMappingURL=antd_validator.d.ts.map

package/esm/src/models/bank/antd_validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"antd_validator.d.ts","sourceRoot":"","sources":["../../../../src/src/models/bank/antd_validator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,SACzB,UAAU,SACT,MAAM,GAAG,IAAI,GAAG,SAAS,KAC/B,OAAO,CAAC,IAAI,GAAG,SAAS,CAoB1B,CAAC"}

package/esm/src/models/bank/antd_validator.js

@@ -0,0 +1,26 @@
+import { Bank } from "./bank.js";
+/**
+ * Validator for SWIFT code field.
+ * Ensures the SWIFT code follows the correct format and is recognized in the list of valid codes.
+ * @param {RuleObject} rule The rule object for validation
+ * @param {string} value The value to validate.
+ * @throws Will throw an error if validation fails.
+ */
+export const SWIFT_CODE_VALIDATOR = (rule, value) => {
+    const code = value?.toString().trim().toUpperCase();
+    // If field is empty/undefined/null
+    if (!code) {
+        // Only throw if the field is required
+        if (rule.required) {
+            return Promise.reject(new Error("SWIFT code is required."));
+        }
+        // If field is not required and empty, validation passes
+        return Promise.resolve(undefined);
+    }
+    const bank = Bank.fromSWIFTCode(code);
+    if (!bank) {
+        const error = new Error("SWIFT code is not recognized.");
+        return Promise.reject(error);
+    }
+    return Promise.resolve(bank);
+};

package/esm/src/models/bank/antd_validator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"antd_validator.test.d.ts","sourceRoot":"","sources":["../../../../src/src/models/bank/antd_validator.test.ts"],"names":[],"mappings":""}

package/esm/src/models/bank/bank.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Represents a bank with essential details.
+ * @class Bank
+ */
+export declare class Bank {
+    private readonly _fullName;
+    private readonly _shortName;
+    private readonly _swiftCode;
+    /**
+     * Creates a new Bank instance.
+     * @param {string} _fullName - The full name of the bank
+     * @param {string} _shortName - The short name or abbreviated name of the bank
+     * @param {string} _swiftCode - The SWIFT code associated with the bank
+     */
+    constructor(_fullName: string, _shortName: string, _swiftCode: string);
+    /**
+     * Gets the full name of the bank.
+     * @returns {string} The full name of the bank
+     */
+    get fullName(): string;
+    /**
+     * Gets the short name of the bank.
+     * @returns {string} The short name of the bank
+     */
+    get shortName(): string;
+    /**
+     * Gets the SWIFT code of the bank.
+     * @returns {string} The SWIFT code of the bank
+     */
+    get swiftCode(): string;
+    /**
+     * Creates a string representation of the bank.
+     * @returns {string} String representation of the bank
+     */
+    toString(): string;
+    /**
+     * Retrieves a bank by its SWIFT code.
+     * @param {string} swiftCode The SWIFT code of the bank.
+     * @returns {Bank | undefined} The bank corresponding to the SWIFT code or `undefined` if not found.
+     */
+    static fromSWIFTCode(swiftCode: string): Bank | undefined;
+    /**
+     * Retrieves a bank by its short or full name.
+     * @param {string} bankName The full name of the bank.
+     * @returns {Bank | undefined} The bank corresponding to the full name or `undefined` if not found.
+     */
+    static fromBankName(bankName: string): Bank | undefined;
+    /**
+     * Validates if a given SWIFT/BIC (Bank Identifier Code) is valid
+     *
+     * @param {string | null | undefined} swiftCode - The SWIFT/BIC code to validate.
+     *   Should be in the format of 8 or 11 characters (e.g., 'NMIBTZTZ' or 'CRDBTZTZXXX').
+     *
+     * @returns {boolean} Returns true if:
+     *   - The SWIFT code is not null/undefined
+     *   - The SWIFT code successfully creates a valid Bank instance
+     *   Returns false otherwise.
+     */
+    static isValidSwiftCode(swiftCode?: string | null): boolean;
+    /**
+     * Validates if a given bank name is valid
+     *
+     * @param {string | null | undefined} bankName - The bank name to validate.
+     *   Should be either 'CRDB' or 'NMB'.
+     *
+     * @returns {boolean} Returns true if:
+     *   - The bank name is not null/undefined
+     *   - The bank name successfully creates a valid Bank instance
+     *   Returns false otherwise.
+     */
+    static isValidBankName(bankName?: string | null): boolean;
+    /**
+     * Gets all banks from the JSON data.
+     * @returns {Bank[]} Array of all banks
+     */
+    static getAll(): Bank[];
+    /**
+     * Checks the validity of the bank data
+     * @returns true if the bank information is available and valid
+     */
+    validate(): boolean;
+    /**
+     * Attempts to create a Bank instance from a bank name or SWIFT code
+     * First tries to create from bank name, then from SWIFT code if bank name fails
+     *
+     * @param {string} input - The bank name or SWIFT code
+     * @returns {Bank | undefined} A Bank instance if valid input, undefined otherwise
+     *
+     * @example
+     * const bank = Bank.from('CORUTZTZ'); // From SWIFT code
+     * const sameBank = Bank.from('CRDB'); // From bank name
+     */
+    static from(input: string): Bank | undefined;
+    /**
+     * Validates if the input can be used to construct a valid Bank instance
+     * Checks if the input resolves to the same bank via both name and SWIFT code
+     *
+     * @param {string | null | undefined} input - The bank name or SWIFT code to validate
+     * @returns {boolean} True if input can construct a valid bank, false otherwise
+     *
+     * @example
+     * Bank.canConstruct('CORUTZTZ'); // true
+     * Bank.canConstruct(''); // false
+     * Bank.canConstruct(null); // false
+     */
+    static canConstruct(input?: string | null): boolean;
+    /**
+     * Checks if an unknown value is a Bank instance.
+     * Validates the structural integrity of a bank object.
+     *
+     * @param {unknown} obj - The value to validate
+     * @returns {obj is Bank} Type predicate indicating if the value is a valid Bank
+     *
+     * @example
+     * const maybeBank = JSON.parse(someData);
+     * if (Bank.is(maybeBank)) {
+     *   console.log(maybeBank.fullName); // maybeBank is typed as Bank
+     * }
+     *
+     * @see {@link Bank.fromSWIFTCode} for creating instances from SWIFT codes
+     * @see {@link Bank.fromBankName} for creating instances from bank names
+     */
+    static is(obj: unknown): obj is Bank;
+}
+//# sourceMappingURL=bank.d.ts.map

package/esm/src/models/bank/bank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bank.d.ts","sourceRoot":"","sources":["../../../../src/src/models/bank/bank.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,IAAI;IAQb,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAT7B;;;;;OAKG;gBAEgB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM;IAGrC;;;OAGG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;OAGG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;OAGG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;OAGG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAMzD;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAOvD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAM3D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAMzD;;;OAGG;IACH,MAAM,CAAC,MAAM,IAAI,IAAI,EAAE;IAWvB;;;OAGG;IACI,QAAQ,IAAI,OAAO;IAY1B;;;;;;;;;;OAUG;WACW,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAYnD;;;;;;;;;;;OAWG;WACW,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAY1D;;;;;;;;;;;;;;;OAeG;WACW,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,IAAI;CAwB5C"}