@temboplus/frontend-core 0.2.1 → 0.2.3

package/esm/src/models/currency/service.d.ts

@@ -0,0 +1,96 @@
+import { Currency } from "./currency.js";
+/**
+ * Service for managing currency data.
+ * @class CurrencyService
+ */
+export declare class CurrencyService {
+    private static instance;
+    private currencyList;
+    private currencyRecord;
+    private nameRecord;
+    private staticReferences;
+    private constructor();
+    /**
+     * Gets the singleton instance of CurrencyService.
+     * Creates the instance if it doesn't exist.
+     * @static
+     * @returns {CurrencyService} The singleton instance
+     */
+    static getInstance(): CurrencyService;
+    /**
+     * Initializes the service with currency data.
+     * Should be called once when your application starts.
+     */
+    private initialize;
+    /**
+     * Gets all currencies.
+     * @returns {Currency[]} Array of all currencies
+     */
+    getAll(): Currency[];
+    /**
+     * Gets all currencies as a record.
+     * @returns {Record<string, Currency>} Record of currency codes and currency objects
+     */
+    getAllAsRecord(): Record<string, Currency>;
+    /**
+     * Gets static currency references to be used by the Currency class.
+     * @returns {Map<string, Currency>} Map of static references
+     */
+    getStaticReferences(): Map<string, Currency>;
+    /**
+     * Retrieves a currency by its ISO code.
+     * @param {string} code The ISO code of the currency.
+     * @returns {Currency | undefined} The currency corresponding to the ISO code or `undefined` if not found.
+     */
+    fromCode(code: string): Currency | undefined;
+    /**
+     * Retrieves a currency by its name.
+     * @param {string} currencyName The name of the currency.
+     * @returns {Currency | undefined} The currency corresponding to the name or `undefined` if not found.
+     */
+    fromName(currencyName: string): Currency | undefined;
+    /**
+     * Validates if a given ISO currency code is valid
+     *
+     * @param {string | null | undefined} code - The currency code to validate.
+     *   Should be a three-letter ISO currency code (e.g., 'USD', 'EUR').
+     *
+     * @returns {boolean} Returns true if:
+     *   - The currency code is not null/undefined
+     *   - The currency code successfully resolves to a valid Currency instance
+     *   Returns false otherwise.
+     */
+    isValidCode(code?: string | null): boolean;
+    /**
+     * Validates if a given currency name is valid
+     *
+     * @param {string | null | undefined} currencyName - The currency name to validate.
+     *
+     * @returns {boolean} Returns true if:
+     *   - The currency name is not null/undefined
+     *   - The currency name successfully resolves to a valid Currency instance
+     *   Returns false otherwise.
+     */
+    isValidName(currencyName?: string | null): boolean;
+    /**
+     * Gets a regex-ready pattern matching all currency symbols
+     * Pattern is memoized for performance
+     * @returns {string} Pipe-separated pattern of escaped currency symbols
+     *
+     * @example
+     * const pattern = currencyService.getCurrencySymbolPattern();
+     * // Returns something like: "\$|€|\£|¥"
+     */
+    getCurrencySymbolPattern(): string;
+    /**
+     * Escapes special characters in a string for use in regular expressions
+     * @private
+     * @param {string} string - The string to escape
+     * @returns {string} The escaped string
+     *
+     * @example
+     * private escapeRegExp("$") // Returns "\$"
+     */
+    private escapeRegExp;
+}
+//# sourceMappingURL=service.d.ts.map

package/esm/src/models/currency/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../../src/src/models/currency/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAiBzC;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAkB;IACzC,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,cAAc,CAAgC;IACtD,OAAO,CAAC,UAAU,CAAgC;IAGlD,OAAO,CAAC,gBAAgB,CAAoC;IAE5D,OAAO;IAEP;;;;;OAKG;IACH,MAAM,CAAC,WAAW,IAAI,eAAe;IAQrC;;;OAGG;IACH,OAAO,CAAC,UAAU;IAmDlB;;;OAGG;IACH,MAAM,IAAI,QAAQ,EAAE;IAIpB;;;OAGG;IACH,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;IAI1C;;;OAGG;IACH,mBAAmB,IAAI,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC;IAI5C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAI5C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAmBpD;;;;;;;;;;OAUG;IACH,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAM1C;;;;;;;;;OASG;IACH,WAAW,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAMlD;;;;;;;;OAQG;IACH,wBAAwB,IAAI,MAAM;IAUlC;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;CAGrB"}

package/esm/src/models/currency/service.js

@@ -0,0 +1,194 @@
+import { Currency } from "./currency.js";
+import file from "../../data/currencies.js";
+/**
+ * Service for managing currency data.
+ * @class CurrencyService
+ */
+export class CurrencyService {
+    constructor() {
+        Object.defineProperty(this, "currencyList", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "currencyRecord", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "nameRecord", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        // Static references for direct access through Currency class
+        Object.defineProperty(this, "staticReferences", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    /**
+     * Gets the singleton instance of CurrencyService.
+     * Creates the instance if it doesn't exist.
+     * @static
+     * @returns {CurrencyService} The singleton instance
+     */
+    static getInstance() {
+        if (!CurrencyService.instance) {
+            CurrencyService.instance = new CurrencyService();
+            CurrencyService.instance.initialize();
+        }
+        return CurrencyService.instance;
+    }
+    /**
+     * Initializes the service with currency data.
+     * Should be called once when your application starts.
+     */
+    initialize() {
+        try {
+            const data = JSON.parse(JSON.stringify(file));
+            const currencies = Object.values(data).map((c) => new Currency(c.symbol, c.name, c.symbol_native, c.decimal_digits, c.rounding, c.code, c.name_plural));
+            const codeRecord = {};
+            const nameRecord = {};
+            currencies.forEach((currency) => {
+                // Populate code record
+                codeRecord[currency.code] = currency;
+                // Add to record by name
+                nameRecord[currency.name.toUpperCase()] = currency;
+                const upperCode = currency.code.toUpperCase();
+                // Add to static references for uppercase code
+                this.staticReferences.set(upperCode, currency);
+                // Add formatted full name static reference based on name property
+                // Transform from "US Dollar" to "US_DOLLAR"
+                const nameKey = currency.name
+                    .toUpperCase()
+                    .replace(/\s+/g, "_")
+                    .replace(/[-(),.']/g, "")
+                    .replace(/&/g, "AND");
+                this.staticReferences.set(nameKey, currency);
+            });
+            this.currencyRecord = codeRecord;
+            this.nameRecord = nameRecord;
+            this.currencyList = currencies;
+        }
+        catch (error) {
+            console.error("Failed to initialize CurrencyService:", error);
+        }
+    }
+    /**
+     * Gets all currencies.
+     * @returns {Currency[]} Array of all currencies
+     */
+    getAll() {
+        return this.currencyList;
+    }
+    /**
+     * Gets all currencies as a record.
+     * @returns {Record<string, Currency>} Record of currency codes and currency objects
+     */
+    getAllAsRecord() {
+        return this.currencyRecord;
+    }
+    /**
+     * Gets static currency references to be used by the Currency class.
+     * @returns {Map<string, Currency>} Map of static references
+     */
+    getStaticReferences() {
+        return this.staticReferences;
+    }
+    /**
+     * Retrieves a currency by its ISO code.
+     * @param {string} code The ISO code of the currency.
+     * @returns {Currency | undefined} The currency corresponding to the ISO code or `undefined` if not found.
+     */
+    fromCode(code) {
+        return this.currencyRecord[code.trim().toUpperCase()];
+    }
+    /**
+     * Retrieves a currency by its name.
+     * @param {string} currencyName The name of the currency.
+     * @returns {Currency | undefined} The currency corresponding to the name or `undefined` if not found.
+     */
+    fromName(currencyName) {
+        const input = currencyName.trim().toUpperCase();
+        // First try direct lookup in name record
+        const directMatch = this.nameRecord[input];
+        if (directMatch)
+            return directMatch;
+        // If not found, try more lenient matching
+        for (const [name, currObj] of Object.entries(this.nameRecord)) {
+            if (name.toUpperCase() === input) {
+                return currObj;
+            }
+        }
+        // Finally, try case-insensitive exact match
+        return this.currencyList.find((currency) => currency.name.toUpperCase() === input);
+    }
+    /**
+     * Validates if a given ISO currency code is valid
+     *
+     * @param {string | null | undefined} code - The currency code to validate.
+     *   Should be a three-letter ISO currency code (e.g., 'USD', 'EUR').
+     *
+     * @returns {boolean} Returns true if:
+     *   - The currency code is not null/undefined
+     *   - The currency code successfully resolves to a valid Currency instance
+     *   Returns false otherwise.
+     */
+    isValidCode(code) {
+        if (!code)
+            return false;
+        const currency = this.fromCode(code);
+        return !!currency;
+    }
+    /**
+     * Validates if a given currency name is valid
+     *
+     * @param {string | null | undefined} currencyName - The currency name to validate.
+     *
+     * @returns {boolean} Returns true if:
+     *   - The currency name is not null/undefined
+     *   - The currency name successfully resolves to a valid Currency instance
+     *   Returns false otherwise.
+     */
+    isValidName(currencyName) {
+        if (!currencyName)
+            return false;
+        const currency = this.fromName(currencyName);
+        return !!currency;
+    }
+    /**
+     * Gets a regex-ready pattern matching all currency symbols
+     * Pattern is memoized for performance
+     * @returns {string} Pipe-separated pattern of escaped currency symbols
+     *
+     * @example
+     * const pattern = currencyService.getCurrencySymbolPattern();
+     * // Returns something like: "\$|€|\£|¥"
+     */
+    getCurrencySymbolPattern() {
+        const symbols = new Set();
+        Object.values(this.currencyList).forEach((currency) => {
+            symbols.add(this.escapeRegExp(currency.symbol));
+            symbols.add(this.escapeRegExp(currency.symbolNative));
+        });
+        return Array.from(symbols).join("|");
+    }
+    /**
+     * Escapes special characters in a string for use in regular expressions
+     * @private
+     * @param {string} string - The string to escape
+     * @returns {string} The escaped string
+     *
+     * @example
+     * private escapeRegExp("$") // Returns "\$"
+     */
+    escapeRegExp(string) {
+        return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+}

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

@@ -1,4 +1,6 @@
 export * from "./amount/index.js";
 export * from "./bank/index.js";
 export * from "./phone_number/index.js";
+export * from "./country/index.js";
+export * from "./currency/index.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC"}

package/esm/src/models/index.js

@@ -1,3 +1,5 @@
 export * from "./amount/index.js";
 export * from "./bank/index.js";
 export * from "./phone_number/index.js";
+export * from "./country/index.js";
+export * from "./currency/index.js";

package/esm/src/models/phone_number/format.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Enumeration for various phone number formats
+ */
+export declare enum PhoneNumberFormat {
+    /** E.164 format with plus sign (e.g., +12025550123) */
+    INTERNATIONAL = "INTERNATIONAL",
+    /** National format with spaces (formatting varies by country) */
+    NATIONAL = "NATIONAL",
+    /** Compact format without country code (e.g., 2025550123) */
+    COMPACT = "COMPACT",
+    /** RFC3966 format (e.g., tel:+1-202-555-0123) */
+    RFC3966 = "RFC3966"
+}
+//# sourceMappingURL=format.d.ts.map

package/esm/src/models/phone_number/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../../src/src/models/phone_number/format.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,uDAAuD;IACvD,aAAa,kBAAkB;IAC/B,iEAAiE;IACjE,QAAQ,aAAa;IACrB,6DAA6D;IAC7D,OAAO,YAAY;IACnB,iDAAiD;IACjD,OAAO,YAAY;CACpB"}

package/esm/src/models/phone_number/format.js

@@ -0,0 +1,14 @@
+/**
+ * Enumeration for various phone number formats
+ */
+export var PhoneNumberFormat;
+(function (PhoneNumberFormat) {
+    /** E.164 format with plus sign (e.g., +12025550123) */
+    PhoneNumberFormat["INTERNATIONAL"] = "INTERNATIONAL";
+    /** National format with spaces (formatting varies by country) */
+    PhoneNumberFormat["NATIONAL"] = "NATIONAL";
+    /** Compact format without country code (e.g., 2025550123) */
+    PhoneNumberFormat["COMPACT"] = "COMPACT";
+    /** RFC3966 format (e.g., tel:+1-202-555-0123) */
+    PhoneNumberFormat["RFC3966"] = "RFC3966";
+})(PhoneNumberFormat || (PhoneNumberFormat = {}));

package/esm/src/models/phone_number/global/phone_number.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview
+ *
+ * # Global Phone Number Management System
+ *
+ * ## Features
+ * 1. Parsing and validation of international format phone numbers
+ * 2. Support for phone numbers across countries using standardized metadata
+ * 3. Standardized storage in E.164 format
+ * 4. Formatting options for display and API use:
+ *    - INTERNATIONAL: "+{dial_code}{compactNumber}" - Returns the number with a plus and country code
+ *    - COMPACT: Just the compactNumber without formatting
+ *    - NATIONAL: Not fully implemented for global numbers, returns the compact number
+ *    - RFC3966: "tel:+{dial_code}{compactNumber}" - Returns the number in URI format
+ * 5. Integration with Country class for country data
+ */
+import { Country } from "../../country/country.js";
+import { PhoneNumberFormat } from "../format.js";
+/**
+ * Options for parsing phone numbers
+ */
+export interface PhoneNumberParseOptions {
+    /**
+     * Default country to use when a dial code is shared by multiple countries
+     * This can be either a Country object or an ISO country code string
+     */
+    defaultCountry?: Country | string;
+    /**
+     * Whether to throw an error when encountering an ambiguous phone number
+     * with a shared dial code
+     */
+    throwOnAmbiguous?: boolean;
+}
+/**
+ * Represents a global phone number
+ */
+export declare class PhoneNumber {
+    /** The associated country object */
+    private _country;
+    /** The national number without country code or leading zeros */
+    private _compactNumber;
+    /**
+     * Private constructor to prevent direct instantiation.
+     * Use PhoneNumber.from() or PhoneNumber.fromWithCountry() instead.
+     *
+     * @param country - The Country object representing the phone number's country
+     * @param compactNumber - The phone number in compact format without country code
+     */
+    private constructor();
+    /**
+     * Gets the Country object associated with this phone number
+     */
+    get country(): Country;
+    /**
+     * Gets the country code (ISO) of the phone number
+     */
+    get countryCode(): string;
+    /**
+     * Gets the dial code (numeric) of the phone number
+     */
+    get dialCode(): number;
+    /**
+     * Gets the compact number (national number without formatting)
+     */
+    get compactNumber(): string;
+    /**
+     * Gets the full E.164 formatted number (e.g., +12025550123)
+     */
+    get formattedNumber(): string;
+    /**
+     * Gets a human-readable label for this phone number
+     * Uses international format with spaces for readability
+     */
+    get label(): string;
+    /**
+     * Formats the phone number according to the specified format
+     *
+     * @param format - The desired format
+     * @returns The formatted phone number string
+     */
+    getWithFormat(format: PhoneNumberFormat): string;
+    /**
+     * Formats the phone number in international format
+     * Returns +{dial_code}{compactNumber} format
+     */
+    private formatInternational;
+    /**
+     * Formats the phone number according to RFC3966
+     * Returns tel:+{dial_code}{compactNumber} format
+     */
+    private formatRFC3966;
+    /**
+     * Validates that this phone number meets the requirements for its country
+     * Relies entirely on pattern validation
+     *
+     * @returns True if the phone number is valid, false otherwise
+     */
+    validate(): boolean;
+    /**
+     * Creates a PhoneNumber from an international format string.
+     * Only accepts the international format with a leading '+'.
+     * Thoroughly cleans the input by removing all non-digit characters except the leading '+'.
+     *
+     * @param input - The phone number string in international format (e.g., "+1 (202) 555-0123")
+     * @param options - Options for handling parsing, including defaultCountry and throwOnAmbiguous
+     * @returns A PhoneNumber instance if parsing succeeded, undefined otherwise
+     * @throws SharedDialCodeError when a shared dial code is encountered and throwOnAmbiguous is true
+     */
+    static from(input: string, options?: PhoneNumberParseOptions): PhoneNumber | undefined;
+    /**
+     * Creates a PhoneNumber from various formats when a country is explicitly provided.
+     * Supports multiple input formats:
+     * - International format with plus and country code: "+{code}{number}" (e.g., "+12025550123")
+     * - Format with just country code: "{code}{number}" (e.g., "12025550123")
+     * - Local format with leading zero: "0{number}" (e.g., "02025550123")
+     * - Just the national number: "{number}" (e.g., "2025550123")
+     *
+     * Thoroughly cleans the input by removing all non-digit characters except the leading '+'.
+     *
+     * @param input - The phone number string in any format
+     * @param country - The Country object for this phone number
+     * @returns A PhoneNumber instance if parsing succeeded, undefined otherwise
+     */
+    static fromWithCountry(input: string, country: Country): PhoneNumber | undefined;
+    /**
+     * Checks if a string can be constructed into a valid phone number.
+     *
+     * @param input - The string to validate
+     * @param options - Options for handling parsing
+     * @returns True if the input can be parsed into a valid phone number, false otherwise
+     */
+    static canConstruct(input?: string | null, options?: PhoneNumberParseOptions): boolean;
+    /**
+     * Checks if a string can be constructed into a valid phone number with a given country.
+     *
+     * @param input - The string to validate
+     * @param country - The Country object to use
+     * @returns True if the input can be parsed into a valid phone number, false otherwise
+     */
+    static canConstructWithCountry(input?: string | null, country?: Country | null): boolean;
+    /**
+     * Type guard to check if an unknown object is a valid PhoneNumber instance.
+     *
+     * @param obj - The object to check
+     * @returns Type predicate indicating if the object is a valid PhoneNumber
+     */
+    static is(obj: unknown): obj is PhoneNumber;
+    /**
+     * Attempts to extract the country from a phone number string in international format.
+     *
+     * For shared dial codes, this will return undefined unless a default country is provided.
+     *
+     * @param input - The phone number string to parse (must be in international format)
+     * @param options - Options for handling shared dial codes
+     * @returns The Country object if found, undefined if ambiguous or not found
+     * @throws SharedDialCodeError when a shared dial code is encountered and throwOnAmbiguous is true
+     */
+    static getCountry(input: string, options?: PhoneNumberParseOptions): Country | undefined;
+}
+//# sourceMappingURL=phone_number.d.ts.map

package/esm/src/models/phone_number/global/phone_number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phone_number.d.ts","sourceRoot":"","sources":["../../../../../src/src/models/phone_number/global/phone_number.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAKnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAElC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,oCAAoC;IACpC,OAAO,CAAC,QAAQ,CAAU;IAC1B,gEAAgE;IAChE,OAAO,CAAC,cAAc,CAAS;IAE/B;;;;;;OAMG;IACH,OAAO;IAKP;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAKrB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;IACH,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;;OAGG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM;IAoBhD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;OAKG;IACH,QAAQ,IAAI,OAAO;IAuCnB;;;;;;;;;OASG;WACW,IAAI,CAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,uBAAuB,GAChC,WAAW,GAAG,SAAS;IAsG1B;;;;;;;;;;;;;OAaG;WACW,eAAe,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf,WAAW,GAAG,SAAS;IA0D1B;;;;;;OAMG;WACW,YAAY,CACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO;IAsBV;;;;;;OAMG;WACW,uBAAuB,CACnC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,EACrB,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,OAAO;IAaV;;;;;OAKG;WACW,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,WAAW;IA2BlD;;;;;;;;;OASG;WACW,UAAU,CACtB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,GAAG,SAAS;CAwDvB"}