@ordius/adonisjs-currencyx 1.4.9

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright (c) 2023
+
+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,508 @@
+# AdonisJS CurrencyX
+
+> AdonisJS integration for CurrencyX with database provider and cache support. Seamlessly integrate currency conversion into your AdonisJS applications.
+
+[![npm version](https://badge.fury.io/js/@mixxtor%2Fcurrencyx-adonisjs.svg)](https://badge.fury.io/js/@mixxtor%2Fcurrencyx-adonisjs)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![AdonisJS](https://img.shields.io/badge/AdonisJS-v6-purple.svg)](https://adonisjs.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- 🚀 **AdonisJS Integration** - Seamless integration with AdonisJS v6 framework
+- 💾 **Database Exchange** - Store exchange rates in your database using Lucid ORM
+- 🔄 **Multiple Exchanges** - Google Finance, Fixer.io, and database exchanges
+- 📦 **Cache Support** - Built-in caching with AdonisJS Cache
+- 🎯 **Type Safety** - Full TypeScript support with intelligent inference
+- 🔧 **Easy Setup** - Simple configuration and installation
+- 🌐 **Service Container** - Registered as AdonisJS service for dependency injection
+- 🏗️ **Repository Pattern** - Clean architecture following AdonisJS patterns
+
+## 📦 Installation
+
+```bash
+npm install @ordius/adonisjs-currencyx
+```
+
+## 🚀 Setup
+
+### 1. Configure the package
+
+```bash
+node ace configure @ordius/adonisjs-currencyx
+```
+
+This will:
+
+- Create `config/currency.ts` configuration file
+- Create Currency model and migration stubs
+- Register the service provider
+
+### 2. Configure providers
+
+Edit `config/currency.ts`:
+
+```typescript
+import env from '#start/env'
+import { defineConfig, exchanges } from '@ordius/adonisjs-currencyx'
+
+export default defineConfig({
+  /*
+  |--------------------------------------------------------------------------
+  | Default Exchange
+  |--------------------------------------------------------------------------
+  */
+  default: env.get('CURRENCY_PROVIDER', 'database') as 'database' | 'google' | 'fixer',
+
+  /*
+  |--------------------------------------------------------------------------
+  | Exchange Configurations
+  |--------------------------------------------------------------------------
+  */
+  exchanges: {
+    /*
+    |--------------------------------------------------------------------------
+    | Database Exchange
+    |--------------------------------------------------------------------------
+    | Uses your local database to store and retrieve exchange rates.
+    */
+    database: exchanges.database({
+      model: () => import('#models/currency'),
+      base: 'USD',
+      columns: {
+        code: 'code',
+        rate: 'exchange_rate',
+      },
+      // Cache configuration (optional)
+      // cache: {
+      //   service: () => import('@adonisjs/cache/services/main'),
+      //   ttl: '1h',          // Cache TTL (human readable or milliseconds)
+      //   keyPrefix: 'currency' // Cache key prefix
+      // }
+    }),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Google Finance Exchange
+    |--------------------------------------------------------------------------
+    | Free exchange using Google Finance API. No API key required.
+    */
+    google: exchanges.google({
+      base: env.get('CURRENCY_BASE', 'USD'),
+      timeout: 5000,
+    }),
+
+    /*
+    |--------------------------------------------------------------------------
+    | Fixer.io Exchange
+    |--------------------------------------------------------------------------
+    | Requires API key from fixer.io.
+    */
+    // fixer: exchanges.fixer({
+    //   accessKey: env.get('FIXER_API_KEY'),
+    //   base: env.get('CURRENCY_BASE', 'USD'),
+    //   timeout: 10000
+    // })
+  },
+})
+```
+
+### 3. Create Currency model
+
+```bash
+node ace make:model Currency
+```
+
+```typescript
+// app/models/currency.ts
+import { DateTime } from 'luxon'
+import { BaseModel, column } from '@adonisjs/lucid/orm'
+
+export default class Currency extends BaseModel {
+  @column({ isPrimary: true })
+  declare id: number
+
+  @column()
+  declare code: string
+
+  @column()
+  declare name: string
+
+  @column()
+  declare exchange_rate: number
+
+  @column.dateTime({ autoCreate: true })
+  declare createdAt: DateTime
+
+  @column.dateTime({ autoCreate: true, autoUpdate: true })
+  declare updatedAt: DateTime
+}
+```
+
+### 4. Create migration
+
+```bash
+node ace make:migration create_currencies_table
+```
+
+```typescript
+// database/migrations/xxx_create_currencies_table.ts
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+export default class extends BaseSchema {
+  protected tableName = 'currencies'
+
+  async up() {
+    this.schema.createTable(this.tableName, (table) => {
+      table.increments('id')
+      table.string('code', 3).notNullable().unique()
+      table.string('name').notNullable()
+      table.decimal('exchange_rate', 15, 8).notNullable()
+      table.timestamp('created_at')
+      table.timestamp('updated_at')
+    })
+  }
+
+  async down() {
+    this.schema.dropTable(this.tableName)
+  }
+}
+```
+
+### 5. Run migration
+
+```bash
+node ace migration:run
+```
+
+## 💡 Usage
+
+### Basic Usage in Controllers
+
+```typescript
+// app/controllers/exchange_controller.ts
+import { inject } from '@adonisjs/core'
+import type { HttpContext } from '@adonisjs/core/http'
+import CurrencyService from '@ordius/adonisjs-currencyx/services/main'
+
+@inject()
+export default class ExchangeController {
+  constructor(private currency: CurrencyService) {}
+
+  async convert({ request, response }: HttpContext) {
+    const { amount, from, to } = request.only(['amount', 'from', 'to'])
+
+    const result = await this.currency.convert({
+      amount: Number(amount),
+      from,
+      to,
+    })
+
+    if (result.success) {
+      return response.json({
+        success: true,
+        data: {
+          amount,
+          from,
+          to,
+          result: result.result,
+          rate: result.info.rate,
+          timestamp: result.info.timestamp,
+        },
+      })
+    }
+
+    return response.status(400).json({
+      success: false,
+      error: result.error?.info,
+    })
+  }
+
+  async getRates({ request, response }: HttpContext) {
+    const { base, codes } = request.only(['base', 'codes'])
+
+    const result = await this.currency.getExchangeRates({
+      base,
+      codes: codes.split(','),
+    })
+
+    if (result.success) {
+      return response.json({
+        success: true,
+        data: result,
+      })
+    }
+
+    return response.status(400).json({
+      success: false,
+      error: result.error?.info,
+    })
+  }
+}
+```
+
+### Exchange Switching
+
+```typescript
+// Switch to different exchange at runtime
+await this.currency.use('google')
+const googleResult = await this.currency.convert({ amount: 100, from: 'USD', to: 'EUR' })
+
+await this.currency.use('fixer')
+const fixerResult = await this.currency.convert({ amount: 100, from: 'USD', to: 'EUR' })
+
+await this.currency.use('database')
+const dbResult = await this.currency.convert({ amount: 100, from: 'USD', to: 'EUR' })
+```
+
+### Database Exchange Usage
+
+Seed your database with exchange rates:
+
+```typescript
+// database/seeders/currency_seeder.ts
+import { BaseSeeder } from '@adonisjs/lucid/seeders'
+import Currency from '#models/currency'
+
+export default class extends BaseSeeder {
+  async run() {
+    const rates = [
+      { code: 'USD', name: 'US Dollar', exchange_rate: 1.0 },
+      { code: 'EUR', name: 'Euro', exchange_rate: 0.85 },
+      { code: 'GBP', name: 'British Pound', exchange_rate: 0.73 },
+      { code: 'JPY', name: 'Japanese Yen', exchange_rate: 110.0 },
+      { code: 'CAD', name: 'Canadian Dollar', exchange_rate: 1.25 },
+      { code: 'AUD', name: 'Australian Dollar', exchange_rate: 1.35 },
+    ]
+
+    for (const rate of rates) {
+      await Currency.updateOrCreate({ code: rate.code }, rate)
+    }
+  }
+}
+```
+
+Run the seeder:
+
+```bash
+node ace db:seed
+```
+
+### Caching
+
+Enable caching for better performance:
+
+```typescript
+// config/currency.ts
+database: exchanges.database({
+  model: () => import('#models/currency'),
+  base: 'USD',
+  columns: {
+    code: 'code',
+    rate: 'exchange_rate',
+  },
+  cache: {
+    service: () => import('@adonisjs/cache/services/main'), // AdonisJS cache service
+    ttl: '1h', // Cache TTL (human readable or milliseconds)
+    keyPrefix: 'currency', // Cache key prefix
+  },
+})
+```
+
+## 📚 API Reference
+
+The AdonisJS integration provides the same API as the core CurrencyX package:
+
+### Core Methods
+
+```typescript
+// Convert currency
+const result = await currency.convert({
+  amount: 100,
+  from: 'USD',
+  to: 'EUR',
+})
+
+// Get exchange rates
+const rates = await currency.getExchangeRates({
+  base: 'USD',
+  codes: ['EUR', 'GBP', 'JPY'],
+})
+```
+
+### Convenience Methods
+
+```typescript
+// Shorthand for getting rates
+const rates = await currency.latestRates({ base: 'USD', codes: ['EUR', 'GBP'] })
+
+// Get exchange rates with same API as core library
+const rates = await currency.getExchangeRates({ base: 'USD', codes: ['EUR', 'GBP'] })
+```
+
+### Exchange Management
+
+```typescript
+// Switch exchanges
+currency.use('google')
+
+// Get current exchange
+const current = currency.getCurrentExchange()
+
+// List available exchanges
+const exchanges = currency.getAvailableExchanges()
+```
+
+### Utility Methods
+
+```typescript
+// Format currency (object parameters)
+const formatted = currency.formatCurrency({ amount: 1234.56, code: 'USD', locale: 'en-US' })
+
+// Round values
+const rounded = currency.round(123.456789, { precision: 2, direction: 'up' })
+
+// Get supported currencies
+const currencies = await currency.getSupportedCurrencies()
+
+// Currency information utilities
+const allCurrencies = currency.getList()
+const usdInfo = currency.getByCode('USD')
+const dollarCurrencies = currency.getBySymbol('$')
+const usCurrency = currency.getByCountry('US')
+const euroCurrencies = currency.filterByName('Euro')
+const usCurrencies = currency.filterByCountry('US')
+
+// Round money according to currency rules
+const rounded = currency.roundMoney(123.456, 'USD')
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+Add these to your `.env` file:
+
+```env
+# Default exchange
+CURRENCY_PROVIDER=database
+
+# Base currency
+CURRENCY_BASE=USD
+
+# Fixer.io API key (if using fixer exchange)
+FIXER_API_KEY=your_api_key_here
+```
+
+### Exchange Configuration
+
+#### Database Exchange
+
+```typescript
+database: exchanges.database({
+  model: () => import('#models/currency'), // Your Currency model
+  base: 'USD', // Base currency
+  columns: {
+    code: 'code', // Currency code column
+    rate: 'exchange_rate', // Exchange rate column
+  },
+  cache: {
+    // Optional caching
+    service: () => import('@adonisjs/cache/services/main'), // AdonisJS cache service
+    ttl: '1h', // Cache TTL (human readable or milliseconds)
+    keyPrefix: 'currency', // Cache key prefix
+  },
+})
+```
+
+#### Google Finance Exchange
+
+```typescript
+google: exchanges.google({
+  base: 'USD', // Base currency
+  timeout: 5000, // Request timeout (optional)
+})
+```
+
+#### Fixer.io Exchange
+
+```typescript
+fixer: exchanges.fixer({
+  accessKey: 'your-api-key', // Required
+  base: 'USD', // Base currency (default: 'USD' for this library)
+  timeout: 10000, // Request timeout (optional)
+})
+```
+
+## 🛡️ Error Handling
+
+All methods return result objects with success indicators:
+
+```typescript
+const result = await currency.convert({
+  amount: 100,
+  from: 'USD',
+  to: 'EUR',
+})
+
+if (result.success) {
+  // Handle success
+  console.log(`Converted: ${result.result}`)
+  console.log(`Rate: ${result.info.rate}`)
+  console.log(`Timestamp: ${result.info.timestamp}`)
+} else {
+  // Handle error
+  console.error(`Error: ${result.error?.info}`)
+  console.error(`Type: ${result.error?.type}`)
+}
+```
+
+## 🧪 Testing
+
+The package includes comprehensive tests. Run them with:
+
+```bash
+npm test
+```
+
+For development testing:
+
+```bash
+npm run quick:test
+```
+
+For test coverage:
+
+```bash
+npm run test
+# Coverage report will be generated in ./coverage/
+```
+
+## 📋 Requirements
+
+- **Node.js** >= 20.6.0
+- **AdonisJS** >= 6.19.0
+- **@adonisjs/lucid** >= 21.7.0 (for database provider)
+- **@adonisjs/cache** >= 1.3.0 (optional, for caching)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read the contributing guidelines before submitting PRs.
+
+## 📄 License
+
+MIT License - see [LICENSE.md](./LICENSE.md) file for details.
+
+## 📦 Related Packages
+
+- [@mixxtor/currencyx-js](https://www.npmjs.com/package/@mixxtor/currencyx-js) - Core currency conversion library
+
+---
+
+<div align="center">
+
+**[Documentation](https://github.com/mixxtor/currencyx-adonisjs#readme)** • **[Issues](https://github.com/mixxtor/currencyx-adonisjs/issues)** • **[Contributing](./CONTRIBUTING.md)**
+
+Made with ❤️ by [Mixxtor](https://github.com/mixxtor)
+
+</div>

package/build/configure.d.ts

@@ -0,0 +1,2 @@
+import type ConfigureCommand from '@adonisjs/core/commands/configure';
+export declare function configure(command: ConfigureCommand): Promise<void>;

package/build/configure.js

@@ -0,0 +1,50 @@
+/*
+|--------------------------------------------------------------------------
+| Configure hook
+|--------------------------------------------------------------------------
+|
+| The configure hook is called when someone runs "node ace configure <package>"
+| command. You are free to perform any operations inside this function to
+| configure the package.
+|
+| To make things easier, you have access to the underlying "ConfigureCommand"
+| instance and you can use codemods to modify the source files.
+|
+*/
+import { stubsRoot } from './stubs/main.js';
+export async function configure(command) {
+    const codemods = await command.createCodemods();
+    /**
+     * Publish config file
+     */
+    await codemods.makeUsingStub(stubsRoot, 'config/currency.stub', {});
+    /**
+     * Register provider
+     */
+    await codemods.updateRcFile((rcFile) => {
+        rcFile.addProvider('@ordius/adonisjs-currencyx/currency_provider');
+    });
+    /**
+     * Create currency model if it doesn't exist
+     */
+    const project = await codemods.getTsMorphProject();
+    const modelExists = project?.getSourceFile('app/models/currency.ts');
+    if (!modelExists) {
+        await codemods.makeUsingStub(stubsRoot, 'models/currency.stub', {});
+    }
+    /**
+     * Create migration if it doesn't exist
+     */
+    const migrationPattern = 'database/migrations/*_create_currencies_table.ts';
+    const migrationFiles = project?.getSourceFiles(migrationPattern) || [];
+    const migrationExists = migrationFiles.length > 0;
+    if (!migrationExists) {
+        const timestamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '');
+        await codemods.makeUsingStub(stubsRoot, 'migrations/create_currencies_table.stub', {
+            migration: {
+                className: 'CreateCurrenciesTable',
+                fileName: `${timestamp}_create_currencies_table.ts`,
+            },
+        });
+    }
+}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export { configure } from './configure.js';
+export { stubsRoot } from './stubs/main.js';
+export { defineConfig, exchanges } from './src/define_config.js';
+export type { CurrencyCode, DatabaseConfig, CacheConfig, CurrencyConfig, CurrencyRecord, CurrencyExchanges, InferExchanges, } from './src/types.js';
+export { DatabaseExchange } from './src/exchanges/database.js';

package/build/index.js

@@ -0,0 +1,13 @@
+/*
+|--------------------------------------------------------------------------
+| Package entrypoint
+|--------------------------------------------------------------------------
+|
+| Export values from the package entrypoint as you see fit.
+|
+*/
+export { configure } from './configure.js';
+export { stubsRoot } from './stubs/main.js';
+export { defineConfig, exchanges } from './src/define_config.js';
+// Database Provider
+export { DatabaseExchange } from './src/exchanges/database.js';

package/build/providers/currency_provider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @ordius/adonisjs-currencyx
+ *
+ * (c) Mixxtor
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import type { ApplicationService } from '@adonisjs/core/types';
+import type CurrencyService from '@mixxtor/currencyx-js';
+/**
+ * Extend AdonisJS container bindings with currency service
+ */
+declare module '@adonisjs/core/types' {
+    interface ContainerBindings {
+        'currency.manager': CurrencyService;
+    }
+}
+export default class CurrencyProvider {
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    /**
+     * Register currency service
+     */
+    register(): Promise<void>;
+    /**
+     * Boot the provider
+     */
+    boot(): Promise<void>;
+    /**
+     * Shutdown the provider
+     */
+    shutdown(): Promise<void>;
+}

package/build/providers/currency_provider.js

@@ -0,0 +1,46 @@
+/**
+ * @ordius/adonisjs-currencyx
+ *
+ * (c) Mixxtor
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { createCurrency } from '@mixxtor/currencyx-js';
+import { configProvider } from '@adonisjs/core';
+import { RuntimeException } from '@adonisjs/core/exceptions';
+export default class CurrencyProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    /**
+     * Register currency service
+     */
+    async register() {
+        this.app.container.singleton('currency.manager', async () => {
+            const currencyConfigProvider = this.app.config.get('currency');
+            if (!currencyConfigProvider) {
+                throw new RuntimeException('Currency configuration not found. Make sure you have a "config/currency.ts" file with "defineConfig" export');
+            }
+            const config = await configProvider.resolve(this.app, currencyConfigProvider);
+            if (!config) {
+                throw new RuntimeException('Invalid "config/currency.ts" file. Make sure you are using the "defineConfig" method');
+            }
+            // Create currency service with all providers
+            return createCurrency(config);
+        });
+    }
+    /**
+     * Boot the provider
+     */
+    async boot() {
+        // Nothing to boot
+    }
+    /**
+     * Shutdown the provider
+     */
+    async shutdown() {
+        // Nothing to shutdown
+    }
+}

package/build/services/main.d.ts

@@ -0,0 +1,19 @@
+import type CurrencyService from '@mixxtor/currencyx-js';
+import type { CurrencyExchanges } from '../src/types.js';
+/**
+ * Currency service with full type inference
+ *
+ * Usage:
+ * ```ts
+ * import currency from '@ordius/adonisjs-currencyx/services/currency'
+ *
+ * // Direct usage - no type casting needed
+ * const rates = await currency.latestRates()
+ *
+ * // Provider switching with type inference
+ * const googleProvider = currency.use('google')  // Only configured providers
+ * const rates = await googleProvider.latestRates()
+ * ```
+ */
+declare let currency: CurrencyService<Record<keyof CurrencyExchanges, CurrencyExchanges[keyof CurrencyExchanges]>>;
+export { currency as default };