finprim

Financial primitives for modern TypeScript applications.

IBAN · BIC/SWIFT · Card · Sort Code · VAT · Routing Number · Loan/EMI · Currency
One library. Zero dependencies. Fully typed.

---

Every fintech team builds this internally. Sort code validation here, an IBAN check there, a custom currency formatter somewhere else. It's fragmented, inconsistent, and expensive to maintain. finprim is the open source version of what your team has already written three times.

---

Quick Start

npm install finprim

import { validateIBAN, validateCardNumber, formatCurrency } from 'finprim'

const iban = validateIBAN('GB29NWBK60161331926819')
// { valid: true, value: 'GB29NWBK60161331926819', formatted: 'GB29 NWBK 6016 1331 9268 19', countryCode: 'GB' }

const card = validateCardNumber('4532015112830366')
// { valid: true, formatted: '4532 0151 1283 0366', network: 'Visa', last4: '0366' }

formatCurrency(1000.5, 'GBP', 'en-GB')
// '£1,000.50'

That's it. No config. No setup. Just import and use.

---

Why finprim?

Problem	finprim
5 different npm packages for financial validation	One unified library
Custom glue code between validators	Consistent API across all validators
Runtime type confusion	Branded TypeScript types for compile-time safety
No framework integration	Built-in Zod schemas, React hooks, NestJS pipes
Heavy dependency trees	Zero runtime dependencies

---

Features

• Validators - IBAN (80+ countries), BIC/SWIFT, UK sort code & account number, card number (Luhn + network detection), EU VAT, US ABA routing number
• Loan math - EMI calculation and full amortization schedules
• Formatting - Display-ready IBAN, sort code, account number, and multi-locale currency formatting
• Branded types - Compile-time correctness that prevents invalid data from flowing through your system
• Framework integrations - Zod schemas, React hooks, NestJS pipes (all optional)
• Production-ready - Input length guards, type checking, no sensitive data logging
• Lightweight - Zero dependencies, tree-shakeable ESM + CJS

---

Integrations

finprim works standalone or plugs into your existing stack:

Import path	What it contains	Extra dependency
finprim	Core validators, formatters, loan math	none
finprim/zod	Zod schemas for validation pipelines	zod
finprim/react	React hooks for form inputs	react
finprim/nest	NestJS validation pipes	@nestjs/common

---

Usage Examples

Validation

import {
  validateIBAN,
  validateUKSortCode,
  validateUKAccountNumber,
  validateBIC,
  validateCardNumber,
  validateCurrencyCode,
  validateEUVAT,
  validateUSRoutingNumber,
} from 'finprim'

validateIBAN('GB29NWBK60161331926819')
// { valid: true, value: 'GB29NWBK60161331926819', formatted: 'GB29 NWBK 6016 1331 9268 19', countryCode: 'GB' }

validateUKSortCode('60-16-13')
// { valid: true, value: '601613', formatted: '60-16-13' }

validateUKAccountNumber('31926819')
// { valid: true, value: '31926819', formatted: '3192 6819' }

validateCardNumber('4532015112830366')
// { valid: true, formatted: '4532 0151 1283 0366', network: 'Visa', last4: '0366' }

validateEUVAT('DE123456789')
// { valid: true, value: 'DE123456789', formatted: 'DE 123456789', countryCode: 'DE' }

validateUSRoutingNumber('021000021')
// { valid: true, value: '021000021', formatted: '021000021' }

Formatting & Display

import { formatIBAN, formatSortCode, formatUKAccountNumber, formatCurrency, parseMoney } from 'finprim'

formatIBAN('GB29NWBK60161331926819')        // 'GB29 NWBK 6016 1331 9268 19'
formatSortCode('601613')                     // '60-16-13'
formatUKAccountNumber('31926819')            // '3192 6819'

formatCurrency(1000.5, 'GBP', 'en-GB')      // '£1,000.50'
formatCurrency(1000.5, 'EUR', 'de-DE')       // '1.000,50 €'
formatCurrency(1000.5, 'USD', 'en-US')       // '$1,000.50'

parseMoney('£1,000.50')
// { valid: true, amount: 1000.50, currency: 'GBP', formatted: '£1,000.50' }

Loan / EMI Calculation

import { calculateEMI, getLoanSchedule } from 'finprim'

calculateEMI(100_000, 10, 12)
// Monthly payment amount

getLoanSchedule(100_000, 10, 12)
// [{ month, payment, principal, interest, balance }, ...]

Branded Types

import type { IBAN, SortCode, AccountNumber } from 'finprim'

// Invalid data cannot be passed where valid data is expected
function processPayment(iban: IBAN, amount: number) { /* ... */ }

const result = validateIBAN(input)
if (result.valid) {
  processPayment(result.value, 100) // result.value is typed as IBAN
}

Zod Schemas

import { z } from 'zod'
import { ibanSchema, sortCodeSchema, accountNumberSchema, currencySchema } from 'finprim/zod'

const PaymentSchema = z.object({
  iban: ibanSchema,
  sortCode: sortCodeSchema,
  accountNumber: accountNumberSchema,
  amount: z.number().positive(),
  currency: currencySchema,
})

React Hooks

import { useIBANInput, useCardNumberInput, useCurrencyInput } from 'finprim/react'

function PaymentForm() {
  const iban = useIBANInput()
  const card = useCardNumberInput()
  const currency = useCurrencyInput('GBP', 'en-GB')

  return (
    <form>
      <input value={iban.value} onChange={iban.onChange} aria-invalid={iban.valid === false} />
      <input value={card.formatted} onChange={card.onChange} aria-invalid={card.valid === false} />
      <input value={currency.formatted} onChange={currency.onChange} />
    </form>
  )
}

NestJS Pipes

import { IbanValidationPipe, SortCodeValidationPipe, createValidationPipe } from 'finprim/nest'
import { validateIBAN } from 'finprim'

@Get('iban/:iban')
findByIban(@Param('iban', IbanValidationPipe) iban: string) {
  return this.service.findByIban(iban)
}

// Create a custom pipe from any validator
const MyPipe = createValidationPipe(validateIBAN)

---

API Reference

Validation

Function	Input	Returns
validateIBAN(input)	string	IBANValidationResult (includes countryCode)
validateUKSortCode(input)	string	ValidationResult<SortCode>
validateUKAccountNumber(input)	string	ValidationResult<AccountNumber>
validateCurrencyCode(input)	string	ValidationResult<CurrencyCode>
validateBIC(input)	string	ValidationResult<BIC>
validateCardNumber(input)	string	CardValidationResult (includes network, last4)
validateEUVAT(input)	string	VATValidationResult (includes countryCode)
validateUSRoutingNumber(input)	string	ValidationResult<RoutingNumber>

Formatting

Function	Input	Returns
formatIBAN(input)	string	string (space-separated)
formatSortCode(input)	string	string (XX-XX-XX)
formatUKAccountNumber(input)	string	string (XXXX XXXX)
formatCurrency(amount, currency, locale?)	number, SupportedCurrency, string?	string
parseMoney(input)	string	MoneyResult

Loan

Function	Input	Returns
calculateEMI(principal, rate, months)	number, number, number	number
getLoanSchedule(principal, rate, months)	number, number, number	LoanScheduleEntry[]

---

Roadmap

• IBAN validation (80+ countries)
• BIC/SWIFT validation
• Card number validation (Luhn + network detection)
• EU VAT number validation
• US routing number validation
• UK sort code and account number validation
• Loan/EMI calculation
• Format-only helpers
• Currency formatting with locale support
• Branded TypeScript types
• Zod schema integration
• React hooks
• NestJS pipes
• More locale coverage
• SEPA credit transfer XML generation
• ACH file format support

---

Security

• Input length - All string validators reject input longer than 256 characters
• Type checking - Validators require non-empty strings; numeric helpers require finite numbers and sane bounds
• No sensitive logging - The library does not log or persist input
• Format helpers - Cap input length and accept only strings

---

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

git clone https://github.com/tintolee/finprim.git
cd finprim
npm install
npm test

---

License

MIT