node-iso11649

3.0.0 verified Sat May 09 auth: no javascript

ISO 11649:2009 RF creditor reference generation, validation, and parsing library for Node.js. Version 3.0.0, pure ESM with TypeScript types. No dependencies, 4 KB (1.2 KB gzipped). Key differentiators: lightweight, zero-dependency, supports pretty formatting, and includes a fallback random generation when no base reference is provided. The library handles the complete RF reference lifecycle including checksum calculation (MOD97-10) and formatting.

Common errors

error Cannot find module 'node-iso11649' ↓

cause Using CommonJS require() with an ESM-only package.

fix

Use ESM import syntax: import { generate } from 'node-iso11649'

error TypeError: generate is not a function ↓

cause Incorrect import style, e.g. import * as iso11649 from 'node-iso11649' then iso11649.generate()? The package uses named exports.

fix

Correct import: import { generate } from 'node-iso11649'

error ValidationError: Invalid reference format ↓

cause Input to generate() or validate() contains characters other than 0-9 and A-Z, or exceeds 21 characters.

fix

Ensure the reference string contains only digits 0-9 and letters A-Z (case-insensitive), max 21 characters before adding RF.

Warnings

breaking v3.0.0 drops CommonJS support. The package is ESM-only and cannot be required with require(). ↓

fix Switch to ESM imports: import { generate } from 'node-iso11649'

gotcha generate() without arguments uses Date.now() and Math.random() which are not cryptographically secure. Uniqueness is not guaranteed. ↓

fix In production, provide a base reference or use cryptographically secure random values as part of the input.

gotcha The input to generate() must contain only digits 0-9 and letters A-Z (case-insensitive), spaces are allowed but stripped. Max length 21 characters before RF prefix. ↓

fix Sanitize input to ensure it matches the allowed characters and length.

Install

npm install node-iso11649

yarn add node-iso11649

pnpm add node-iso11649

Imports

generate

wrong

const generate = require('node-iso11649').generate

correct

import { generate } from 'node-iso11649'

ESM-only since v3; CommonJS require is not supported.

validate

wrong

import Validate from 'node-iso11649'

correct

import { validate } from 'node-iso11649'

Named export, not default export.

parse
```
import { parse } from 'node-iso11649'
```
Named export.
type GenerateOptions
```
import type { GenerateOptions } from 'node-iso11649'
```
TypeScript type export for the options parameter in generate().

Quickstart

Demonstrates generating RF creditor references from an existing reference, with pretty formatting, random generation, validation, and parsing.

import { generate, validate, parse } from 'node-iso11649';

const ref = generate('12345 12345');
console.log(ref); // RF451234512345

const prettyRef = generate('12345 12345', { pretty: true });
console.log(prettyRef); // RF45 1234 5123 45

const randomRef = generate();
console.log(randomRef); // e.g., RF4714508655422864

console.log(validate('RF451234512345')); // true
console.log(validate('RF00TEST')); // false

const parsed = parse('RF47 1450 8655 4228 64');
console.log(parsed); // 14508655422864

const invalid = parse('RF00TEST');
console.log(invalid); // null