npm package: @scottlexium/finpro
Description: 🚀 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
Author: Scott Lexium
Latest version: 2.1.0

# FinPro.js 🚀
*By Scott Lexium*

[![npm version](https://badge.fury.io/js/@scottlexium/finpro.svg)](https://badge.fury.io/js/@scottlexium/finpro)
[![CI/CD Pipeline](https://github.com/Scottlexium/finpro-issues/actions/workflows/ci.yml/badge.svg)](https://github.com/Scottlexium/finpro-issues/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/Scottlexium/finpro-issues/branch/main/graph/badge.svg)](https://codecov.io/gh/Scottlexium/finpro-issues)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
[![Downloads](https://img.shields.io/npm/dm/@scottlexium/finpro.svg)](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