FinPro.js 🚀

By Scott Lexium

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

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

import { finance } from '@scottlexium/finpro';
// or import specific modules
import { Finance, FiatModule } from '@scottlexium/finpro';

CommonJS - Full Support

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

// 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 - Core classes and methods
• Examples & Use Cases - Real-world usage examples
• Data Structures - Type definitions and interfaces

For comprehensive examples, real-world use cases, and advanced usage patterns, see EXAMPLES.md.

API Reference

Finance Class

The main class providing access to all financial data modules with a fluent, chainable API.

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

// 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

// 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:

// 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.

📊 Data Structures

Currency Object

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

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

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

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

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

// ✅ 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.

📋 License

MIT License - see the LICENSE file for details.

📖 More Documentation

• EXAMPLES.md - Comprehensive examples and real-world use cases
• API Reference - Complete API documentation
• Performance Guide - Optimization tips and best practices

Made with ❤️ for the JavaScript/TypeScript community