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

``bash
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

`typescript
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'
`

$3

React:
`tsx
import { isValidKVNR } from 'kvnr-utils';

function KVNRInput() {
const [kvnr, setKvnr] = useState('');
const isValid = isValidKVNR(kvnr);

return (
value={kvnr}
onChange={(e) => setKvnr(e.target.value)}
className={isValid ? 'valid' : 'invalid'}
/>
);
}
`

Angular:
`typescript
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

$3

Validates a KVNR string.

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

$3

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

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

Development

`bash


Install dependencies

npm install

Run tests

npm test

Build

npm run build
``

License

MIT © Kevin Mirzaian