mongoose-currency-convert 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mauro Cunsolo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# mongoose-currency-convert
+
+[![npm version](https://img.shields.io/npm/v/mongoose-currency-convert.svg)](https://www.npmjs.com/package/mongoose-currency-convert)
+[![Release](https://github.com/maku85/mongoose-currency-convert/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/maku85/mongoose-currency-convert/actions/workflows/release.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight Mongoose plugin for automatic currency conversion at save time - flexible, extensible, and service-agnostic.
+
+## Features
+
+- **Automatic currency conversion** for specified fields when saving documents or updating them.
+- **Customizable exchange rate logic** via a user-provided function or extension plugin.
+- **Support for nested paths and array elements** in documents (e.g. `items.0.price`).
+- **Pluggable rounding function** (default: round to 2 decimals).
+- **Simple in-memory cache** for exchange rates (optional).
+- **Error handling and rollback** on conversion failure.
+- **Fully tested** with high code coverage.
+- **Compatible with ESM and CommonJS**.
+
+## Installation
+
+```sh
+npm install mongoose-currency-convert
+# or
+pnpm add mongoose-currency-convert
+```
+
+## Usage
+
+```ts
+import mongoose, { Schema } from 'mongoose';
+import { currencyConversionPlugin } from 'mongoose-currency-convert';
+
+const ProductSchema = new Schema({
+  price: {
+    amount: Number,
+    currency: String,
+    date: Date,
+  },
+  priceConversion: {
+    amount: Number,
+    currency: String,
+    date: Date,
+  },
+  items: [
+    {
+      price: Number,
+      currency: String,
+    }
+  ]
+});
+
+ProductSchema.plugin(currencyConversionPlugin, {
+  fields: [
+    {
+      sourcePath: 'price.amount',
+      currencyPath: 'price.currency',
+      datePath: 'price.date',
+      targetPath: 'priceConversion',
+      toCurrency: 'EUR',
+    },
+    {
+      sourcePath: 'items.0.price',
+      currencyPath: 'items.0.currency',
+      targetPath: 'items.0.converted',
+      toCurrency: 'EUR',
+    }
+  ],
+  getRate: async (from, to, date) => {
+    // Implement your logic to fetch the exchange rate
+    return 0.85; // Example: USD → EUR
+  },
+  // Optional: custom rounding function
+  round: (value) => Math.round(value * 100) / 100,
+});
+
+const Product = mongoose.model('Product', ProductSchema);
+```
+
+## Supported Mongoose Operations
+
+- `save`
+- `updateOne`
+- `findOneAndUpdate`
+
+Currency conversion is automatically applied when saving or updating documents using these operations.
+
+## Plugin Options
+
+- `fields`: Array of field mapping objects:
+  - `sourcePath`: Path to the source amount (supports nested and array paths).
+  - `currencyPath`: Path to the source currency.
+  - `datePath` (optional): Path to the date for conversion.
+  - `targetPath`: Path to write the converted value.
+  - `toCurrency`: Target currency code.
+- `getRate(from: string, to: string, date: Date)`: Async function returning the exchange rate.
+- `round(value: number)`: Optional rounding function.
+- `allowedCurrencyCodes`: Optional array of allowed currency codes (ISO 4217).
+- `onError(ctx)`: Optional callback called when a conversion error occurs. Receives an object with details.
+- `fallbackRate`: Optional fallback rate if the conversion rate is invalid or missing.
+- `rollbackOnError`: Optional boolean. If true, revokes all conversions made if there's an error.
+- `cache`: Optional cache object for exchange rates (see `SimpleCache`).
+- `dateTransform(date: Date)`: Optional function to transform the conversion date.
+
+## Caching Exchange Rates
+
+You can use the built-in in-memory cache (`SimpleCache` in `src/utils/cache.ts`) or provide your own cache implementation (e.g. backed by Redis, Memcached, etc.).
+
+### Using the Internal SimpleCache
+```ts
+import { SimpleCache } from 'mongoose-currency-convert';
+
+const cache = new SimpleCache();
+
+ProductSchema.plugin(currencyConversionPlugin, {
+  fields: [/* ... */],
+  getRate: async (from, to, date) => { /* ... */ },
+  cache,
+});
+```
+
+### Using an External Cache (e.g. Redis)
+You can implement the `CurrencyRateCache` interface to use any external service:
+
+```ts
+import { createClient } from 'redis';
+import type { CurrencyRateCache } from 'mongoose-currency-convert';
+
+class RedisCache implements CurrencyRateCache<number> {
+  private client = createClient({ url: 'redis://localhost:6379' });
+  constructor() { this.client.connect(); }
+
+  async get(key: string): Promise<number | undefined> {
+    const value = await this.client.get(key);
+    return value ? Number(value) : undefined;
+  }
+  async set(key: string, value: number): Promise<void> {
+    await this.client.set(key, value.toString(), { EX: 86400 }); // 1 day expiry
+  }
+}
+
+const cache = new RedisCache();
+
+ProductSchema.plugin(currencyConversionPlugin, {
+  fields: [/* ... */],
+  getRate: async (from, to, date) => { /* ... */ },
+  cache,
+});
+```
+
+## Error Handling Example
+
+You can handle conversion errors using the `onError` callback:
+
+```ts
+ProductSchema.plugin(currencyConversionPlugin, {
+  fields: [/* ... */],
+  getRate: async () => { throw new Error('rate error'); },
+  onError: (ctx) => {
+    console.error('Conversion error:', ctx);
+  },
+  rollbackOnError: true,
+});
+```
+
+## TypeScript Support
+
+- Fully typed, with exported types for plugin options and error context.
+- Example:
+
+```ts
+import type { CurrencyPluginOptions, CurrencyPluginErrorContext } from 'mongoose-currency-convert';
+```
+
+## Extension Plugins (e.g. BCE)
+
+You can use or create extension plugins that provide a ready-to-use `getRate` function for external services (e.g. European Central Bank, exchangerate.host, etc.).
+
+| Package | Description |
+|---------|-------------|
+| `mongoose-currency-converter-bce` | BCE provider for automatic exchange rate lookup. |
+
+### How to Create Your Own Extension Plugin
+
+1. Import the types from the base plugin:
+   ```ts
+   import type { GetRateFn } from 'mongoose-currency-convert';
+   ```
+2. Implement a factory function that returns a `getRate` function:
+   ```ts
+   export function createMyGetRate(): GetRateFn {
+     return async function getRate(from, to, date) {
+       // Fetch rate from your service
+       // Return the rate
+     };
+   }
+   ```
+3. Use your plugin in the base plugin configuration:
+   ```ts
+   ProductSchema.plugin(currencyConversionPlugin, {
+     fields: [/* ... */],
+     getRate: createMyGetRate(),
+     cache,
+   });
+   ```
+
+> **Note:** The cache is managed by the base plugin. Extension plugins should not read or write to the cache directly; they only fetch rates from external services.
+
+## Limitations & Known Issues
+
+- Only `save`, `updateOne`, and `findOneAndUpdate` are supported for automatic conversion.
+- Array paths are supported, but deep array updates (e.g. `items.$.price`) may require manual handling.
+- Only `$set` and direct field updates are converted in update operations; other MongoDB operators (`$inc`, `$push`, etc.) are not automatically converted.
+- The list of supported currency codes is static (ISO 4217).
+- If you use custom cache, ensure it implements the required interface.
+
+## Compatibility
+
+- Node.js >= 18.x
+- Mongoose >= 7.x
+- TypeScript >= 5.x (optional)
+
+## Contributing
+
+Contributions are welcome! To contribute:
+- Fork the repository and create a new branch.
+- Submit a pull request with a clear description of your changes.
+- Follow the coding style and add tests for new features or bug fixes.
+- For major changes, open an issue first to discuss your idea.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details (if available).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes and release history.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./plugin";

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./plugin"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB"}

package/dist/plugin.d.ts

@@ -0,0 +1,10 @@
+import type { Schema } from "mongoose";
+import type { CurrencyPluginErrorContext, CurrencyPluginOptions, CurrencyRateCache } from "./types";
+export declare function currencyConversionPlugin(schema: Schema, options: CurrencyPluginOptions & {
+    allowedCurrencyCodes?: string[];
+    onError?: (ctx: CurrencyPluginErrorContext) => void;
+    fallbackRate?: number;
+    rollbackOnError?: boolean;
+    cache?: CurrencyRateCache<number>;
+    dateTransform?: (date: Date) => Date;
+}): void;

package/dist/plugin.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.currencyConversionPlugin = currencyConversionPlugin;
+const helpers_1 = require("./utils/helpers");
+function currencyConversionPlugin(schema, options) {
+    const { fields, getRate, round = helpers_1.defaultRound, allowedCurrencyCodes, onError, fallbackRate, rollbackOnError, cache, dateTransform, } = options;
+    if (!fields || !Array.isArray(fields) || fields.length === 0) {
+        throw new Error('[mongoose-currency-convert] option "fields" must be a non-empty array');
+    }
+    if (typeof getRate !== "function") {
+        throw new Error('[mongoose-currency-convert] option "getRate" must be a function');
+    }
+    async function applyCurrencyConversion(doc) {
+        const convertedFields = [];
+        for (const field of fields) {
+            const { sourcePath, currencyPath, datePath, targetPath, toCurrency } = field;
+            const amount = (0, helpers_1.getNestedValue)(doc, sourcePath);
+            const fromCurrency = (0, helpers_1.getNestedValue)(doc, currencyPath);
+            if (amount == null || typeof fromCurrency !== "string" || !fromCurrency)
+                continue;
+            if (!(0, helpers_1.isValidCurrencyCode)(fromCurrency, allowedCurrencyCodes)) {
+                console.warn(`[mongoose-currency-convert] Invalid source currency code: ${fromCurrency}`);
+                continue;
+            }
+            if (!(0, helpers_1.isValidCurrencyCode)(toCurrency, allowedCurrencyCodes)) {
+                console.warn(`[mongoose-currency-convert] Invalid target currency code: ${toCurrency}`);
+                continue;
+            }
+            const dateValue = datePath ? (0, helpers_1.getNestedValue)(doc, datePath) : undefined;
+            let conversionDate = dateValue &&
+                (typeof dateValue === "string" ||
+                    typeof dateValue === "number" ||
+                    dateValue instanceof Date)
+                ? new Date(dateValue)
+                : new Date();
+            if (dateTransform)
+                conversionDate = dateTransform(conversionDate);
+            let rate;
+            const cacheKey = `${fromCurrency}_${toCurrency}_${conversionDate.toISOString().slice(0, 10)}`;
+            try {
+                if (cache)
+                    rate = await cache.get(cacheKey);
+                if (rate === undefined) {
+                    rate = await getRate(fromCurrency, toCurrency, conversionDate);
+                    if (cache && rate !== undefined && !Number.isNaN(rate)) {
+                        await cache.set(cacheKey, rate);
+                    }
+                }
+                if (!rate || Number.isNaN(rate)) {
+                    if (typeof fallbackRate === "number") {
+                        rate = fallbackRate;
+                    }
+                    else {
+                        throw new Error("Invalid rate");
+                    }
+                }
+                const convertedValue = {
+                    amount: round(Number(amount) * rate),
+                    currency: toCurrency,
+                    date: conversionDate,
+                };
+                (0, helpers_1.setNestedValue)(doc, targetPath, convertedValue);
+                convertedFields.push(targetPath);
+            }
+            catch (err) {
+                if (onError) {
+                    onError({
+                        field: sourcePath,
+                        fromCurrency: fromCurrency,
+                        toCurrency,
+                        date: conversionDate,
+                        error: err,
+                    });
+                }
+                else {
+                    console.error(`[mongoose-currency-convert] Error converting ${sourcePath}:`, err);
+                }
+                if (rollbackOnError) {
+                    for (const path of convertedFields) {
+                        (0, helpers_1.setNestedValue)(doc, path, undefined);
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    schema.pre("save", async function () {
+        const doc = this.toObject({ depopulate: true });
+        await applyCurrencyConversion(doc);
+        Object.assign(this, doc);
+    });
+    async function handleUpdateMiddleware(next) {
+        const update = this.getUpdate();
+        if (!update)
+            return next();
+        const updateAny = update;
+        let doc;
+        if (typeof updateAny.$set === "object" && updateAny.$set !== null) {
+            doc = { ...updateAny.$set };
+            await applyCurrencyConversion(doc);
+            updateAny.$set = doc;
+        }
+        else {
+            doc = { ...updateAny };
+            await applyCurrencyConversion(doc);
+            Object.assign(updateAny, doc);
+        }
+        next();
+    }
+    schema.pre("findOneAndUpdate", handleUpdateMiddleware);
+    schema.pre("updateOne", handleUpdateMiddleware);
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+export interface CurrencyFieldConfig {
+    sourcePath: string;
+    currencyPath: string;
+    datePath?: string;
+    targetPath: string;
+    toCurrency: string;
+}
+export interface CurrencyPluginOptions {
+    fields: CurrencyFieldConfig[];
+    getRate: (from: string, to: string, date?: Date) => Promise<number>;
+    round?: (value: number) => number;
+}
+export interface CurrencyPluginErrorContext {
+    field: string;
+    fromCurrency: string;
+    toCurrency: string;
+    date: Date;
+    error: unknown;
+}
+export interface CurrencyRateCache<T = unknown> {
+    get(key: string): Promise<T | undefined> | T | undefined;
+    set(key: string, value: T): Promise<void> | void;
+    delete?(key: string): Promise<void> | void;
+    clear?(): Promise<void> | void;
+}
+export interface CacheEntry<T> {
+    value: T;
+    expiresAt: number;
+}
+export type GetRateFn = (from: string, to: string, date?: Date) => Promise<number>;

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils/cache.d.ts

@@ -0,0 +1,10 @@
+export declare class SimpleCache<T = unknown> {
+    private store;
+    private ttl;
+    constructor(ttlMinutes?: number);
+    private isExpired;
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    delete(key: string): void;
+    clear(): void;
+}

package/dist/utils/cache.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleCache = void 0;
+class SimpleCache {
+    store = new Map();
+    ttl;
+    constructor(ttlMinutes = 60) {
+        this.ttl = ttlMinutes * 60 * 1000;
+    }
+    isExpired(entry) {
+        return Date.now() > entry.expiresAt;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (this.isExpired(entry)) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        this.store.set(key, {
+            value,
+            expiresAt: Date.now() + this.ttl,
+        });
+    }
+    delete(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+exports.SimpleCache = SimpleCache;
+//# sourceMappingURL=cache.js.map

package/dist/utils/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":";;;AAEA,MAAa,WAAW;IACd,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IACzC,GAAG,CAAS;IAEpB,YAAY,aAAqB,EAAE;QACjC,IAAI,CAAC,GAAG,GAAG,UAAU,GAAG,EAAE,GAAG,IAAI,CAAC;IACpC,CAAC;IAEO,SAAS,CAAC,KAAoB;QACpC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ;QACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,KAAK;YACL,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG;SACjC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF;AAtCD,kCAsCC"}

package/dist/utils/helpers.d.ts

@@ -0,0 +1,5 @@
+export declare function getPathArray(path: string): string[];
+export declare function getNestedValue(obj: unknown, path: string | string[]): unknown;
+export declare function setNestedValue(obj: unknown, path: string | string[], value: unknown): void;
+export declare function defaultRound(value: number): number;
+export declare function isValidCurrencyCode(code: string, allowedCodes?: string[]): boolean;

package/dist/utils/helpers.js

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPathArray = getPathArray;
+exports.getNestedValue = getNestedValue;
+exports.setNestedValue = setNestedValue;
+exports.defaultRound = defaultRound;
+exports.isValidCurrencyCode = isValidCurrencyCode;
+const ISO_4217_CODES = [
+    "USD",
+    "EUR",
+    "GBP",
+    "JPY",
+    "CHF",
+    "CAD",
+    "AUD",
+    "NZD",
+    "CNY",
+    "SEK",
+    "NOK",
+    "DKK",
+    "RUB",
+    "INR",
+    "BRL",
+    "ZAR",
+    "SGD",
+    "HKD",
+    "MXN",
+    "KRW",
+    "TRY",
+    "PLN",
+    "CZK",
+    "HUF",
+    "ILS",
+    "THB",
+    "MYR",
+    "IDR",
+    "PHP",
+    "TWD",
+    "SAR",
+    "AED",
+    "COP",
+    "CLP",
+    "PEN",
+    "ARS",
+    "VND",
+    "EGP",
+    "UAH",
+    "QAR",
+    "KZT",
+    "BGN",
+    "RON",
+    "HRK",
+    "ISK",
+    "LTL",
+    "LVL",
+    "EEK",
+    "SKK",
+    "YER",
+    "OMR",
+    "BHD",
+    "JOD",
+    "LBP",
+    "KWD",
+    "MAD",
+    "DZD",
+    "TND",
+    "LYD",
+    "SDG",
+    "IQD",
+    "SYP",
+    "MRO",
+    "CVE",
+    "GMD",
+    "GNF",
+    "SLL",
+    "XOF",
+    "XAF",
+    "XPF",
+    "XCD",
+    "XDR",
+    "XUA",
+    "XSU",
+    "XTS",
+    "XXX",
+];
+const pathCache = new Map();
+function getPathArray(path) {
+    if (pathCache.has(path)) {
+        const cached = pathCache.get(path);
+        if (cached)
+            return [...cached];
+    }
+    const arr = path.split(".");
+    pathCache.set(path, arr);
+    return [...arr];
+}
+function getNestedValue(obj, path) {
+    const keys = Array.isArray(path) ? path : getPathArray(path);
+    return keys.reduce((acc, key) => {
+        if (acc && typeof acc === "object") {
+            if (!Number.isNaN(Number(key)) && Array.isArray(acc)) {
+                return acc[Number(key)];
+            }
+            return acc[key];
+        }
+        return undefined;
+    }, obj);
+}
+function setNestedValue(obj, path, value) {
+    const parts = Array.isArray(path) ? [...path] : [...getPathArray(path)];
+    const last = parts.pop();
+    if (!last)
+        return;
+    let target = obj;
+    for (const key of parts) {
+        if (!Number.isNaN(Number(key)) && Array.isArray(target)) {
+            if (!target[Number(key)])
+                target[Number(key)] = {};
+            target = target[Number(key)];
+        }
+        else {
+            if (typeof target[key] !== "object" || target[key] === null) {
+                target[key] = {};
+            }
+            target = target[key];
+        }
+    }
+    if (!Number.isNaN(Number(last)) && Array.isArray(target)) {
+        target[Number(last)] = value;
+    }
+    else {
+        target[last] = value;
+    }
+}
+function defaultRound(value) {
+    return Math.round(value * 100) / 100;
+}
+function isValidCurrencyCode(code, allowedCodes) {
+    const list = allowedCodes || ISO_4217_CODES;
+    return typeof code === "string" && list.includes(code.toUpperCase());
+}
+//# sourceMappingURL=helpers.js.map

package/dist/utils/helpers.js.map

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

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "mongoose-currency-convert",
+  "version": "0.1.0",
+  "description": "A lightweight Mongoose plugin for automatic currency conversion at save time - flexible, extensible, and service-agnostic.",
+  "keywords": [
+    "mongoose",
+    "plugin",
+    "currency",
+    "conversion",
+    "exchange-rate",
+    "mongodb",
+    "typescript",
+    "money"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "maku85",
+    "email": "makuma85@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maku85/mongoose-currency-convert.git"
+  },
+  "homepage": "https://github.com/maku85/mongoose-currency-convert#readme",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils/helpers.js",
+      "require": "./dist/utils/helpers.cjs",
+      "types": "./dist/utils/helpers.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepare": "husky",
+    "lint": "biome check src --verbose",
+    "format": "biome format src --write",
+    "release": "semantic-release",
+    "prepublishOnly": "npm run build",
+    "test": "mocha --config .mocharc.json",
+    "test:watch": "mocha --watch --config .mocharc.json",
+    "coverage": "nyc npm test"
+  },
+  "peerDependencies": {
+    "mongoose": ">=7.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.2.5",
+    "@commitlint/config-conventional": "^20.0.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/npm": "^12.0.2",
+    "@types/chai": "^5.2.2",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^24.7.0",
+    "chai": "^6.2.0",
+    "commitlint": "^20.1.0",
+    "husky": "^9.1.7",
+    "mocha": "^11.7.4",
+    "mongoose": "^8.19.0",
+    "nyc": "^17.1.0",
+    "semantic-release": "^24.2.9",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "nyc": {
+    "extension": [
+      ".ts"
+    ],
+    "include": [
+      "src/**/*.ts"
+    ],
+    "exclude": [
+      "test/**/*.ts",
+      "dist/**/*.ts"
+    ],
+    "reporter": [
+      "text",
+      "lcov"
+    ],
+    "all": true,
+    "check-coverage": true,
+    "lines": 90,
+    "functions": 90,
+    "branches": 80,
+    "statements": 90
+  }
+}