@scottlexium/finpro
Version:
🚀 FinPro.js by Scott Lexium - The most comprehensive TypeScript library for financial data operations. Features 154+ currencies, 250+ countries, MongoDB-style queries, dual ESM/CommonJS support, and flag integration. Created by Scott Lexium for modern Ja
375 lines (304 loc) • 13.6 kB
Markdown
# FinPro.js 🚀
*By Scott Lexium*
[](https://badge.fury.io/js/@scottlexium/finpro)
[](https://github.com/Scottlexium/finpro-issues/actions/workflows/ci.yml)
[](https://codecov.io/gh/Scottlexium/finpro-issues)
[](http://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.npmjs.com/package/@scottlexium/finpro)
**The most comprehensive TypeScript library for financial data operations** - Created by Scott Lexium for developers who need reliable currency, country, and geography data with MongoDB-style query capabilities.
> **Scott Lexium's FinPro.js** is trusted by developers worldwide for financial data management, offering unmatched performance and type safety for modern JavaScript/TypeScript applications.
## ✨ Features
- 🔍 **Advanced Query Builder** - MongoDB-style queries with chaining support
- 💱 **Currency Management** - 154 fiat currencies with real-time formatting
- 🌍 **Geography Data** - 250 countries, 520 states/provinces, 185 languages
- 🏳️ **Flag Integration** - Automatic flag URLs from flagcdn.com
- 🎯 **TypeScript First** - Full type safety and IntelliSense support
- 🧩 **Modular Architecture** - Easy to extend with crypto and commodities
- ⚡ **Performance Optimized** - Sub-100ms query execution
- 🔄 **Dual Module Support** - Full ESM and CommonJS compatibility
- 📦 **Tree Shakeable** - Import only what you need
- 🛡️ **Production Ready** - Battle-tested in enterprise applications
## 🚀 Quick Start
**Created by Scott Lexium** - This library provides everything you need for financial data operations.
### Installation
```bash
npm install @scottlexium/finpro
# or
yarn add @scottlexium/finpro
```
### Module Support
**FinPro.js now supports both ES Modules and CommonJS!** Choose the import style that works best for your project:
#### ESM (ES Modules) - Recommended
```typescript
import { finance } from '@scottlexium/finpro';
// or import specific modules
import { Finance, FiatModule } from '@scottlexium/finpro';
```
#### CommonJS - Full Support
```javascript
const { finance } = require('@scottlexium/finpro');
// or require specific modules
const { Finance, FiatModule } = require('@scottlexium/finpro');
```
Both import styles provide identical functionality and performance.
### Basic Usage
```typescript
// Works with both import and require!
// Get all currencies - Scott Lexium's comprehensive currency database
const currencies = finance.currencies().exec();
// Find specific currency
const usd = finance.currency().findOne({ code: 'USD' });
// Advanced querying with chaining - MongoDB-style queries by Scott Lexium
const majorCurrencies = finance.currencies()
.find({ isActive: true })
.where('code').in(['USD', 'EUR', 'GBP', 'JPY'])
.sort({ name: 1 })
.exec();
// Format currency amounts with localization
const formatted = finance.formatCurrency('USD', 1234.56);
console.log(formatted); // "$1,234.56"
// Returns: "$1,234.56"
// Get countries and states
const countries = finance.countries().exec();
const usStates = finance.states().find({ country_code: 'US' }).exec();
```
## 📚 Documentation
- **[API Reference](#api-reference)** - Core classes and methods
- **[Examples & Use Cases](./EXAMPLES.md)** - Real-world usage examples
- **[Data Structures](#data-structures)** - Type definitions and interfaces
For comprehensive examples, real-world use cases, and advanced usage patterns, see **[EXAMPLES.md](./EXAMPLES.md)**.
## API Reference
### Finance Class
The main class providing access to all financial data modules with a fluent, chainable API.
```typescript
const finance = new Finance();
// Direct access methods (recommended for most use cases)
finance.currencies() // Get currency query builder → QueryBuilder<Currency>
finance.currency() // Get single currency query builder → QueryBuilder<Currency>
finance.countries() // Get countries query builder → QueryBuilder<Country>
finance.country() // Single country query builder → QueryBuilder<Country>
finance.states() // Get states query builder → QueryBuilder<State>
finance.state() // Single state query builder → QueryBuilder<State>
finance.languages() // Get languages query builder → QueryBuilder<Language>
finance.language() // Single language query builder → QueryBuilder<Language>
// Module access (for advanced usage and direct data access)
finance.fiat // Fiat currency module with all currency operations
finance.geography // Geography data module (countries, states, languages)
finance.crypto // Crypto module (placeholder for future expansion)
finance.commodities // Commodities module (placeholder for future expansion)
```
#### What Each Method Returns:
- **Query builders** return a `QueryBuilder<T>` instance that supports method chaining
- **Direct modules** provide access to raw data and specialized methods
- **All queries** must end with `.exec()` to return actual data
### Currency Operations
```typescript
// Get all currencies (154 fiat currencies)
const allCurrencies = finance.currencies().exec();
// Find by currency code
const euro = finance.currency().findOne({ code: 'EUR' }).exec()[0];
// Filter active currencies only
const activeCurrencies = finance.currencies().find({ isActive: true }).exec();
// Currency formatting with localization
finance.formatCurrency('USD', 1234.56); // "$1,234.56"
finance.formatCurrency('EUR', 1234.56, { locale: 'de-DE' }); // "1.234,56 €"
finance.formatCurrency('JPY', 1234.56, { locale: 'ja-JP' }); // "¥1,235"
// Get major currencies
const majorCurrencies = finance.currencies()
.where('code').in(['USD', 'EUR', 'GBP', 'JPY'])
.exec();
```
### Geography Operations
```typescript
// Countries (250 countries)
const allCountries = finance.countries().exec();
const usa = finance.country().findOne({ id: 'US' }).exec()[0];
const europeanCountries = finance.countries().find({ continent: 'EU' }).exec();
// States/Provinces (520 subdivisions)
const allStates = finance.states().exec();
const usStates = finance.states().find({ country_code: 'US' }).exec();
const canadianProvinces = finance.states().find({ country_code: 'CA' }).exec();
// Languages (185 languages)
const allLanguages = finance.languages().exec();
const english = finance.language().findOne({ id: 'en' }).exec()[0];
```
### Query Builder
MongoDB-style querying with method chaining and type safety:
```typescript
// Basic filtering and chaining
const result = finance.currencies()
.find({ isActive: true }) // Initial filter
.where('region').equals('Europe') // Additional conditions
.where('decimals').gte(2) // Numeric comparisons
.where('name').regex(/euro|dollar/i) // Pattern matching
.sort({ name: 1 }) // Sorting
.limit(10) // Pagination
.exec(); // Execute query
// Available methods:
finance.currencies()
.find(filter) // Basic filtering
.findOne(filter) // Single document
.where(field).equals(value) // Exact match
.where(field).in([values]) // Array membership
.where(field).regex(pattern) // Pattern matching
.where(field).gt/gte/lt/lte(value) // Numeric comparisons
.sort({ field: 1 }) // Sorting (1=asc, -1=desc)
.skip(n).limit(n) // Pagination
.count() // Count results
.exec() // Execute and return data
```
For detailed examples, advanced usage patterns, and real-world use cases, see **[EXAMPLES.md](./EXAMPLES.md)**.
## 📊 Data Structures
### Currency Object
```typescript
interface Currency {
readonly id: string; // Currency code (uppercase)
readonly type: 'fiat'; // Currency type
readonly code: string; // ISO 4217 currency code
readonly symbol: string; // Currency symbol ($, €, £)
readonly name: string; // Full currency name
readonly decimals: number; // Decimal places (0-4)
readonly isActive: boolean; // Currently active/tradable
readonly countries: readonly string[]; // Array of country codes using this currency
readonly region?: string; // Geographic region (optional)
readonly centralBank?: string; // Central bank name (optional)
}
// Example:
{
id: "USD",
type: "fiat",
code: "USD",
symbol: "$",
name: "US Dollar",
decimals: 2,
isActive: true,
countries: ["US", "EC", "SV", "PA", ...], // 18 countries
region: "Americas",
centralBank: "Federal Reserve"
}
```
### Country Object
```typescript
interface Country {
readonly id?: string; // ISO 3166-1 alpha-2 code (inherited from Entity)
readonly name: string; // Country name
readonly native: string; // Native country name
readonly phone: readonly number[]; // Country calling codes
readonly continent: string; // Continent code
readonly capital: string; // Capital city
readonly currency: readonly string[]; // Currency codes array
readonly languages: readonly string[]; // Language codes array
}
// Example:
{
name: "United States",
native: "United States",
phone: [1],
continent: "NA",
capital: "Washington D.C.",
currency: ["USD", "USN", "USS"],
languages: ["en"]
}
```
### State/Province Object
```typescript
interface State {
readonly id?: string; // Inherited from Entity (optional)
readonly code: string; // State/province code
readonly name: string; // State/province name
readonly type: string; // Type (state, province, territory, etc.)
readonly country_code: string; // Country ISO code
}
// Example:
{
code: "AB",
name: "Alberta",
type: "province",
country_code: "CA"
}
```
### Language Object
```typescript
interface Language {
readonly id?: string; // Language identifier (inherited from Entity)
readonly name: string; // English name
readonly native: string; // Native language name
readonly rtl?: number; // RTL indicator (optional)
}
// Example:
{
name: "Afar",
native: "Afar"
}
```
### Enhanced Currency with Flags
```typescript
interface CurrencyWithFlags extends Currency {
readonly flag?: string; // Primary flag URL
readonly flags?: {
readonly svg?: string; // SVG flag URL
readonly png?: Record<string, string>; // PNG flags in different sizes
readonly allCountries?: Record<string, string>; // Flags for all countries using this currency
};
}
// Example:
{
id: "USD",
type: "fiat",
code: "USD",
symbol: "$",
name: "US Dollar",
decimals: 2,
isActive: true,
countries: ["US", "EC", "SV", ...],
region: "Americas",
centralBank: "Federal Reserve",
flag: "https://flagcdn.com/w160/us.png",
flags: {
svg: "https://flagcdn.com/us.svg",
png: {
w20: "https://flagcdn.com/w20/us.png",
w160: "https://flagcdn.com/w160/us.png",
w320: "https://flagcdn.com/w320/us.png",
// ... more sizes
},
allCountries: {
"US": "https://flagcdn.com/w160/us.png",
"EC": "https://flagcdn.com/w160/ec.png",
// ... flags for all countries using USD
}
}
}
```
## ⚡ Performance & Optimization
- **In-memory operations**: All data is loaded into memory for sub-100ms queries
- **Optimized filtering**: Efficient array filtering with early termination
- **Lazy evaluation**: Query builders are lightweight until `.exec()` is called
- **Type safety**: Full TypeScript support prevents runtime errors
- **Memory efficient**: ~440KB total data loaded into memory
- **Tree shakeable**: Import only what you need
### Best Practices
```typescript
// ✅ Good: Chain filters efficiently
const result = finance.currencies()
.find({ isActive: true }) // Filter first (reduces dataset)
.where('region').equals('Europe') // Then apply additional filters
.sort({ name: 1 }) // Sort filtered results
.limit(10) // Limit after sorting
.exec();
// ✅ Good: Use count() for counting
const activeCount = finance.currencies()
.find({ isActive: true })
.count();
```
For more performance tips and advanced examples, see **[EXAMPLES.md](./EXAMPLES.md)**.
## 📋 License
MIT License - see the [LICENSE](./LICENSE) file for details.
## 📖 More Documentation
- **[EXAMPLES.md](./EXAMPLES.md)** - Comprehensive examples and real-world use cases
- **[API Reference](#api-reference)** - Complete API documentation
- **[Performance Guide](./EXAMPLES.md#performance-best-practices)** - Optimization tips and best practices
---
Made with ❤️ for the JavaScript/TypeScript community