nhb-toolbox 4.12.33 → 4.12.34

package/CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.12.34] - 2025-06-12
+
+- **Updated** `format()` and `convert()` methods in `Currency` class. `format()` now accepts `CurrencyCode` as optional second parameter and `convert()` method now returns a new `Currency` instance.
+
 ## [4.12.33] - 2025-06-11
 
 - **Trim** input string for `numberToWordsOrdinal` utility.

package/dist/cjs/number/Currency.js

@@ -5,7 +5,7 @@ const utilities_1 = require("./utilities");
 /**
  * * A utility class for handling currency operations like formatting and conversion.
  *
- * - Supports formatting based on locale.
+ * - Supports formatting based on locale and currency code.
  * - Converts between **fiat currencies supported by `api.frankfurter.app`**.
  * - Automatically caches conversion rates to reduce redundant API calls.
  * - Intended for use with numeric inputs (number or numeric string).
@@ -18,7 +18,7 @@ class Currency {
      *
      * - Generated using the `en-US` locale during construction.
      * - This is a display-friendly version of the currency value.
-     * - For formatting with other locales, use the `format(locale)` method.
+     * - For formatting with other locales, use the `format()` method.
      */
     currency;
     /**
@@ -38,12 +38,15 @@ class Currency {
         Currency.#rateCache.clear();
     }
     /**
-     * @instance Formats the currency for a given locale.
-     * @param locale - The target locale (e.g., 'de-DE')
-     * @returns The formatted currency string
+     * @instance Formats the stored amount as a localized currency string.
+     *
+     * @param locale - Optional. A BCP 47 locale string (e.g., `'de-DE'`, `'en-US'`). Defaults to `'en-US'` if not provided.
+     * @param code - Optional. An ISO 4217 currency code (e.g., `'USD'`, `'EUR'`) used solely for formatting purposes.
+     *            _This does not alter the internal currency code set during instantiation._
+     * @returns A string representing the formatted currency value according to the specified locale and currency code.
      */
-    format(locale) {
-        return (0, utilities_1.formatCurrency)(this.#amount, this.#code, locale);
+    format(locale, code) {
+        return (0, utilities_1.formatCurrency)(this.#amount, code ?? this.#code, locale);
     }
     /**
      * @instance Converts the current currency amount to a target currency using real-time exchange rates.
@@ -60,25 +63,27 @@ class Currency {
      *   - `fallbackRate`: A manual exchange rate to use if the API call fails or currency is not supported.
      *   - `forceRefresh`: If true, ignores cached rates and fetches fresh data.
      * @returns The converted amount as a number.
-     * @throws Will throw if the API call fails and no `fallbackRate` is provided.
+     * @throws Will throw error if the API call fails and no `fallbackRate` is provided.
      */
     async convert(to, options) {
         const key = `${this.#code}->${to}`;
         if (!options?.forceRefresh && Currency.#rateCache.has(key)) {
             const cachedRate = Currency.#rateCache.get(key);
-            return this.#amount * cachedRate;
+            return new Currency(this.#amount * cachedRate, to);
         }
         try {
             const rate = await this.#fetchFromFrankfurter(to);
             Currency.#rateCache.set(key, rate);
-            return this.#amount * rate;
+            return new Currency(this.#amount * rate, to);
         }
         catch (error) {
             if (options?.fallbackRate != null) {
                 console.warn(`Currency conversion failed (${this.#code} → ${to}): ${error.message}. Using fallback rate...`);
-                return this.#amount * options.fallbackRate;
+                return new Currency(this.#amount * options.fallbackRate, to);
+            }
+            else {
+                throw new Error(`Currency conversion failed (${this.#code} → ${to}): ${error.message}`);
             }
-            throw new Error(`Currency conversion failed (${this.#code} → ${to}): ${error.message}`);
         }
     }
     /**

package/dist/dts/number/Currency.d.ts

@@ -3,7 +3,7 @@ import type { ConvertOptions, CurrencyCode, LocaleCode, SupportedCurrency } from
 /**
  * * A utility class for handling currency operations like formatting and conversion.
  *
- * - Supports formatting based on locale.
+ * - Supports formatting based on locale and currency code.
  * - Converts between **fiat currencies supported by `api.frankfurter.app`**.
  * - Automatically caches conversion rates to reduce redundant API calls.
  * - Intended for use with numeric inputs (number or numeric string).
@@ -15,7 +15,7 @@ export declare class Currency {
      *
      * - Generated using the `en-US` locale during construction.
      * - This is a display-friendly version of the currency value.
-     * - For formatting with other locales, use the `format(locale)` method.
+     * - For formatting with other locales, use the `format()` method.
      */
     readonly currency: string;
     /**
@@ -28,11 +28,14 @@ export declare class Currency {
     /** * Clears cached rates that were fetched previously. */
     static clearRateCache(): void;
     /**
-     * @instance Formats the currency for a given locale.
-     * @param locale - The target locale (e.g., 'de-DE')
-     * @returns The formatted currency string
+     * @instance Formats the stored amount as a localized currency string.
+     *
+     * @param locale - Optional. A BCP 47 locale string (e.g., `'de-DE'`, `'en-US'`). Defaults to `'en-US'` if not provided.
+     * @param code - Optional. An ISO 4217 currency code (e.g., `'USD'`, `'EUR'`) used solely for formatting purposes.
+     *            _This does not alter the internal currency code set during instantiation._
+     * @returns A string representing the formatted currency value according to the specified locale and currency code.
      */
-    format(locale?: LocaleCode): string;
+    format(locale?: LocaleCode, code?: CurrencyCode): string;
     /**
      * @instance Converts the current currency amount to a target currency using real-time exchange rates.
      *
@@ -48,8 +51,8 @@ export declare class Currency {
      *   - `fallbackRate`: A manual exchange rate to use if the API call fails or currency is not supported.
      *   - `forceRefresh`: If true, ignores cached rates and fetches fresh data.
      * @returns The converted amount as a number.
-     * @throws Will throw if the API call fails and no `fallbackRate` is provided.
+     * @throws Will throw error if the API call fails and no `fallbackRate` is provided.
      */
-    convert(to: SupportedCurrency | CurrencyCode, options?: ConvertOptions): Promise<number>;
+    convert(to: SupportedCurrency | CurrencyCode, options?: ConvertOptions): Promise<Currency>;
 }
 //# sourceMappingURL=Currency.d.ts.map

package/dist/dts/number/Currency.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Currency.d.ts","sourceRoot":"","sources":["../../../src/number/Currency.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EACX,cAAc,EACd,YAAY,EAEZ,UAAU,EACV,iBAAiB,EACjB,MAAM,SAAS,CAAC;AAGjB;;;;;;;GAOG;AACH,qBAAa,QAAQ;;IAGpB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;gBACS,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY;IAQ/C,0DAA0D;IAC1D,MAAM,CAAC,cAAc,IAAI,IAAI;IAI7B;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM;IAInC;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CACZ,EAAE,EAAE,iBAAiB,GAAG,YAAY,EACpC,OAAO,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,CAAC;CA6DlB"}
+{"version":3,"file":"Currency.d.ts","sourceRoot":"","sources":["../../../src/number/Currency.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EACX,cAAc,EACd,YAAY,EAEZ,UAAU,EACV,iBAAiB,EACjB,MAAM,SAAS,CAAC;AAGjB;;;;;;;GAOG;AACH,qBAAa,QAAQ;;IAGpB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;gBACS,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY;IAQ/C,0DAA0D;IAC1D,MAAM,CAAC,cAAc,IAAI,IAAI;IAI7B;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,MAAM;IAIxD;;;;;;;;;;;;;;;;OAgBG;IACG,OAAO,CACZ,EAAE,EAAE,iBAAiB,GAAG,YAAY,EACpC,OAAO,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,QAAQ,CAAC;CA6DpB"}

package/dist/dts/number/types.d.ts

@@ -78,6 +78,7 @@ export interface ConvertOptions {
     /**  If true, bypasses the cache and fetches fresh rate. */
     forceRefresh?: boolean;
 }
+/** Type Interface for API Response from `api.frankfurter.app` */
 export interface FrankFurter {
     amount: number;
     base: CurrencyCode;

package/dist/dts/number/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/number/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/number/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/number/Currency.js

@@ -2,7 +2,7 @@ import { formatCurrency } from './utilities.js';
 /**
  * * A utility class for handling currency operations like formatting and conversion.
  *
- * - Supports formatting based on locale.
+ * - Supports formatting based on locale and currency code.
  * - Converts between **fiat currencies supported by `api.frankfurter.app`**.
  * - Automatically caches conversion rates to reduce redundant API calls.
  * - Intended for use with numeric inputs (number or numeric string).
@@ -15,7 +15,7 @@ export class Currency {
      *
      * - Generated using the `en-US` locale during construction.
      * - This is a display-friendly version of the currency value.
-     * - For formatting with other locales, use the `format(locale)` method.
+     * - For formatting with other locales, use the `format()` method.
      */
     currency;
     /**
@@ -35,12 +35,15 @@ export class Currency {
         Currency.#rateCache.clear();
     }
     /**
-     * @instance Formats the currency for a given locale.
-     * @param locale - The target locale (e.g., 'de-DE')
-     * @returns The formatted currency string
+     * @instance Formats the stored amount as a localized currency string.
+     *
+     * @param locale - Optional. A BCP 47 locale string (e.g., `'de-DE'`, `'en-US'`). Defaults to `'en-US'` if not provided.
+     * @param code - Optional. An ISO 4217 currency code (e.g., `'USD'`, `'EUR'`) used solely for formatting purposes.
+     *            _This does not alter the internal currency code set during instantiation._
+     * @returns A string representing the formatted currency value according to the specified locale and currency code.
      */
-    format(locale) {
-        return formatCurrency(this.#amount, this.#code, locale);
+    format(locale, code) {
+        return formatCurrency(this.#amount, code ?? this.#code, locale);
     }
     /**
      * @instance Converts the current currency amount to a target currency using real-time exchange rates.
@@ -57,25 +60,27 @@ export class Currency {
      *   - `fallbackRate`: A manual exchange rate to use if the API call fails or currency is not supported.
      *   - `forceRefresh`: If true, ignores cached rates and fetches fresh data.
      * @returns The converted amount as a number.
-     * @throws Will throw if the API call fails and no `fallbackRate` is provided.
+     * @throws Will throw error if the API call fails and no `fallbackRate` is provided.
      */
     async convert(to, options) {
         const key = `${this.#code}->${to}`;
         if (!options?.forceRefresh && Currency.#rateCache.has(key)) {
             const cachedRate = Currency.#rateCache.get(key);
-            return this.#amount * cachedRate;
+            return new Currency(this.#amount * cachedRate, to);
         }
         try {
             const rate = await this.#fetchFromFrankfurter(to);
             Currency.#rateCache.set(key, rate);
-            return this.#amount * rate;
+            return new Currency(this.#amount * rate, to);
         }
         catch (error) {
             if (options?.fallbackRate != null) {
                 console.warn(`Currency conversion failed (${this.#code} → ${to}): ${error.message}. Using fallback rate...`);
-                return this.#amount * options.fallbackRate;
+                return new Currency(this.#amount * options.fallbackRate, to);
+            }
+            else {
+                throw new Error(`Currency conversion failed (${this.#code} → ${to}): ${error.message}`);
             }
-            throw new Error(`Currency conversion failed (${this.#code} → ${to}): ${error.message}`);
         }
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.12.33",
+  "version": "4.12.34",
   "description": "A versatile collection of smart, efficient, and reusable utility functions and classes for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",