nhb-toolbox 4.12.34 → 4.12.36

package/CHANGELOG.md

@@ -6,9 +6,15 @@ All notable changes to the package will be documented here.
 
 ---
 
-## [4.12.34] - 2025-06-12
+## [4.12.36] - 2025-06-13
 
-- **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.
+- **Added** new `convertSync()` method in `Currency` class to convert currency without network request.
+
+## [4.12.34-35] - 2025-06-12
+
+- **Updated** `format()` and `convert()` methods in `Currency` class:
+  - `format()` method now accepts `CurrencyCode` as optional second parameter
+  - `convert()` method now returns a new `Currency` instance.
 
 ## [4.12.33] - 2025-06-11
 

package/dist/cjs/number/Currency.js

@@ -62,8 +62,11 @@ class Currency {
      * @param options - Optional settings:
      *   - `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.
+     * @returns A new `Currency` instance with the converted amount in the target currency.
      * @throws Will throw error if the API call fails and no `fallbackRate` is provided.
+     *
+     * @example
+     * await new Currency(100, 'USD').convert('EUR');
      */
     async convert(to, options) {
         const key = `${this.#code}->${to}`;
@@ -86,6 +89,37 @@ class Currency {
             }
         }
     }
+    /**
+     * @instance Converts the current currency amount to a target currency using either a cached rate or a manual exchange rate.
+     *
+     * - This method is **synchronous** and does **not perform any network requests**.
+     * - If a cached rate exists for the currency pair, it is used.
+     * - If no cached rate is found, `rate` is used as a manual exchange rate.
+     * - If neither are available, the original instance is returned unchanged.
+     *
+     * @param to - The target currency code to convert to.
+     * @param rate - A manual exchange rate to use if no cached rate is available.
+     * @returns A new `Currency` instance with the converted amount, or the original instance if no rate is available.
+     *
+     * @example
+     * const usd = new Currency(100, 'USD');
+     * const eur = usd.convertSync('EUR', 0.92);
+     *
+     * console.log(eur.currency); // €92.00
+     */
+    convertSync(to, rate) {
+        const key = `${this.#code}->${to}`;
+        const cachedRate = Currency.#rateCache.get(key);
+        if (cachedRate) {
+            return new Currency(this.#amount * cachedRate, to);
+        }
+        else if (rate) {
+            return new Currency(this.#amount * rate, to);
+        }
+        else {
+            return this;
+        }
+    }
     /**
      * @private Attempts to fetch rate from frankfurter.app
      * @param to - Target currency code

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

@@ -50,9 +50,31 @@ export declare class Currency {
      * @param options - Optional settings:
      *   - `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.
+     * @returns A new `Currency` instance with the converted amount in the target currency.
      * @throws Will throw error if the API call fails and no `fallbackRate` is provided.
+     *
+     * @example
+     * await new Currency(100, 'USD').convert('EUR');
      */
     convert(to: SupportedCurrency | CurrencyCode, options?: ConvertOptions): Promise<Currency>;
+    /**
+     * @instance Converts the current currency amount to a target currency using either a cached rate or a manual exchange rate.
+     *
+     * - This method is **synchronous** and does **not perform any network requests**.
+     * - If a cached rate exists for the currency pair, it is used.
+     * - If no cached rate is found, `rate` is used as a manual exchange rate.
+     * - If neither are available, the original instance is returned unchanged.
+     *
+     * @param to - The target currency code to convert to.
+     * @param rate - A manual exchange rate to use if no cached rate is available.
+     * @returns A new `Currency` instance with the converted amount, or the original instance if no rate is available.
+     *
+     * @example
+     * const usd = new Currency(100, 'USD');
+     * const eur = usd.convertSync('EUR', 0.92);
+     *
+     * console.log(eur.currency); // €92.00
+     */
+    convertSync(to: CurrencyCode, rate: number): 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;;;;;;;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"}
+{"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;;;;;;;;;;;;;;;;;;;OAmBG;IACG,OAAO,CACZ,EAAE,EAAE,iBAAiB,GAAG,YAAY,EACpC,OAAO,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,QAAQ,CAAC;IA6BpB;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ;CA6CrD"}

package/dist/esm/number/Currency.js

@@ -59,8 +59,11 @@ export class Currency {
      * @param options - Optional settings:
      *   - `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.
+     * @returns A new `Currency` instance with the converted amount in the target currency.
      * @throws Will throw error if the API call fails and no `fallbackRate` is provided.
+     *
+     * @example
+     * await new Currency(100, 'USD').convert('EUR');
      */
     async convert(to, options) {
         const key = `${this.#code}->${to}`;
@@ -83,6 +86,37 @@ export class Currency {
             }
         }
     }
+    /**
+     * @instance Converts the current currency amount to a target currency using either a cached rate or a manual exchange rate.
+     *
+     * - This method is **synchronous** and does **not perform any network requests**.
+     * - If a cached rate exists for the currency pair, it is used.
+     * - If no cached rate is found, `rate` is used as a manual exchange rate.
+     * - If neither are available, the original instance is returned unchanged.
+     *
+     * @param to - The target currency code to convert to.
+     * @param rate - A manual exchange rate to use if no cached rate is available.
+     * @returns A new `Currency` instance with the converted amount, or the original instance if no rate is available.
+     *
+     * @example
+     * const usd = new Currency(100, 'USD');
+     * const eur = usd.convertSync('EUR', 0.92);
+     *
+     * console.log(eur.currency); // €92.00
+     */
+    convertSync(to, rate) {
+        const key = `${this.#code}->${to}`;
+        const cachedRate = Currency.#rateCache.get(key);
+        if (cachedRate) {
+            return new Currency(this.#amount * cachedRate, to);
+        }
+        else if (rate) {
+            return new Currency(this.#amount * rate, to);
+        }
+        else {
+            return this;
+        }
+    }
     /**
      * @private Attempts to fetch rate from frankfurter.app
      * @param to - Target currency code

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.12.34",
+  "version": "4.12.36",
   "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",