KVNR Utils

A lightweight TypeScript library for validating and formatting German Health Insurance Numbers (Krankenversichertennummer - KVNR).

Purpose

This library provides validation-only functionality for German Health Insurance Numbers:

• Format validation: Checks syntax and structure
• Check digit validation: Verifies mathematical correctness using official Luhn algorithm
• Input normalization: Handles whitespace and case variations

Features

• Validates format and check digit using the official modified Luhn algorithm
• Handles user input with whitespace and case variations
• Full type definitions included
• Lightweight with no external dependencies
• Well-tested with Jest
• Framework-agnostic (works everywhere JavaScript runs)

Installation

npm install kvnr-utils

Compatibility

This library is framework-agnostic and works with:

• Vanilla JavaScript/TypeScript (ES2020+)
• React (any version)
• Angular (any version)
• Vue.js (any version)
• Node.js (v14+)
• Next.js, Nuxt.js, SvelteKit etc.
• Webpack, Vite, Rollup - all bundlers
• Browser & Server-Side environments

No dependencies - works everywhere JavaScript runs!

Usage

import { isValidKVNR, normalizeKVNR } from 'kvnr-utils';

// Validate a KVNR
const isValid = isValidKVNR('A123456780'); // true (if check digit is correct)

// Normalize user input
const normalized = normalizeKVNR(' a123456780 '); // 'A123456780'

Framework Examples

React:

import { isValidKVNR } from 'kvnr-utils';

function KVNRInput() {
  const [kvnr, setKvnr] = useState('');
  const isValid = isValidKVNR(kvnr);
  
  return (
    <input 
      value={kvnr} 
      onChange={(e) => setKvnr(e.target.value)}
      className={isValid ? 'valid' : 'invalid'}
    />
  );
}

Angular:

import { isValidKVNR } from 'kvnr-utils';

@Component({...})
export class KVNRComponent {
  kvnr = '';
  
  get isValid() {
    return isValidKVNR(this.kvnr);
  }
}

KVNR Format

A German Health Insurance Number (KVNR) consists of:

• Position 1: Random uppercase letter (A-Z, no umlauts)
• Positions 2-9: Eight random digits
• Position 10: Check digit calculated using modified Luhn algorithm

Validation Algorithm

This library implements the official German specification for KVNR validation:

1. Format check: Validates the pattern ^[A-Z][0-9]{9}$
2. Letter conversion: Converts A-Z to 01-26
3. Modified Luhn algorithm:
   • Multiply digits alternately with weights 1-2-1-2-1-2-1-2-1-2
   • Calculate cross sum of each product
   • Sum all cross sums
   • Check digit = sum modulo 10

Source: Wikipedia - Krankenversichertennummer

API Reference

isValidKVNR(kvnr: string): boolean

Validates a KVNR string.

• Parameters: kvnr - The KVNR string to validate
• Returns: true if valid, false otherwise

normalizeKVNR(kvnr: string): string

Normalizes a KVNR string by trimming whitespace and converting to uppercase.

• Parameters: kvnr - The raw KVNR string
• Returns: Normalized KVNR string

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

License

MIT © Kevin Mirzaian