iban-tools

A tiny TypeScript library for working with IBANs.

Features

• Strict IBAN validation following ISO 13616
  • Enforces correct length per country
  • Only accepts uppercase A–Z and digits 0–9 (no spaces, no hidden Unicode)
  • Validates check digits (mod-97 == 1)
• Tolerant workflow helpers
  • normalizeIban to canonicalize user input (strip spaces, normalize digits, uppercase)
  • isValidIbanTolerant to validate after normalization
  • formatIban to pretty-print in groups (default 4)
  • getIbanCountry to read the ISO country code safely
• Metadata access
  • getIbanMetadata returns { country, length, sepa }
    • country: ISO 3166 alpha-2 code
    • length: official IBAN length for that country
    • sepa: whether the country/territory is part of the SEPA (Single Euro Payments Area)
• Check digit calculation
  • computeCheckDigits(country, bban) returns the correct 2-digit IBAN check digits
  • Useful for constructing valid IBANs programmatically or verifying BBAN → IBAN conversion
• Lightweight, zero dependencies

Installation

npm install @emaddehnavi/iban-tools

Usage

1) Strict IBAN validation (no spaces, uppercase only)

import { isValidIban } from "@emaddehnavi/iban-tools";

// Valid German IBAN
console.log(isValidIban("DE89370400440532013000")); // true

// Invalid (contains spaces)
console.log(isValidIban("DE89 3704 0044 0532 0130 00")); // false

// Invalid (lowercase)
console.log(isValidIban("de89370400440532013000")); // false

// Invalid (wrong check digits)
console.log(isValidIban("DE00370400440532013000")); // false

2) Tolerant validation (normalize first)

import { isValidIbanTolerant } from "@emaddehnavi/iban-tools";

// Accepts spaces, hyphens, and non-ASCII digits; validates the canonical IBAN
console.log(isValidIbanTolerant("de89 3704-0044\u00A0 0532 0130 00")); // true

3) Normalize user input

import { normalizeIban } from "@emaddehnavi/iban-tools";

console.log(normalizeIban("de89 3704-0044\u00A0 0532 0130 00"));
// -> "DE89370400440532013000"

4) Pretty-print an IBAN (validates by default)

import { formatIban } from "@emaddehnavi/iban-tools";

console.log(formatIban("DE89370400440532013000"));
// -> "DE89 3704 0044 0532 0130 00"

console.log(formatIban("DE89370400440532013000", { groupSize: 3 }));
// -> "DE8 937 040 044 053 201 300 0"

5) Country detection

import { getIbanCountry } from "@emaddehnavi/iban-tools";

console.log(getIbanCountry("DE89 3704 0044 0532 0130 00")); // "DE"
console.log(getIbanCountry("XX12 3456")); // null

6) Metadata access

import { getIbanMetadata } from "@emaddehnavi/iban-tools";

console.log(getIbanMetadata("DE89 3704 0044 0532 0130 00")); // -> { country: "DE", length: 22, sepa: true }
console.log(getIbanMetadata("TR330006100519786457841326")); // -> { country: "TR", length: 26, sepa: false }

7) Check digit calculation

import { computeCheckDigits, isValidIban } from "@emaddehnavi/iban-tools";

const bban = "370400440532013000";
const country = "DE";
const checkDigits = computeCheckDigits(country, bban);

console.log(checkDigits); // "89"

const iban = `${country}${checkDigits}${bban}`;
console.log(iban);             // "DE89370400440532013000"
console.log(isValidIban(iban)); // true

API

• isValidIban(iban: string): boolean — strict validator (ASCII uppercase, exact length, mod-97).
• isValidIbanTolerant(iban: string): boolean — normalize then validate.
• normalizeIban(input: string): string — canonicalize to A–Z0–9.
• formatIban(iban: string, opts?: { groupSize?: number; validate?: boolean }): string — pretty print; validates by default.
• getIbanCountry(iban: string): string | null — two-letter country code if length & shape match.
• getIbanMetadata(iban: string): { country: string; length: number; sepa: boolean } | null — returns metadata including country code, official IBAN length, and SEPA membership.
• computeCheckDigits(country: string, bban: string): string — compute the two check digits for a given country + BBAN, per ISO 13616. Useful for constructing valid IBANs.

License

MIT