test-nino

The fastest NINO (UK National Insurance number) generator and validator. Generates and validates UK NI numbers to NIM39110 specifications on Gov.uk.

test-nino is a performance focused and has zero dependencies. The benchmarks speak for themselves.

- Getting Started
* Install
* Import
- Available functions
* random
* incremental
* validate
* normalise
- Benchmarks
- What is a valid UK National Insurance number?
- How many valid UK National Insurance numbers are there?

Getting Started

$3

You can install the test-nino package from npm:
``
npm i test-nino
`

$3

`js
// ESM/TypeScript
import * as testNino from 'test-nino';

// CommonJS
const testNino = require('test-nino');
`

Available functions

$3


Used to generate a random NINO:
`js
const nino = testNino.random();
// Returns a valid UK National Insurance number e.g. AA000000A
`
> Warning: it is not guaranteed that you couldn't generate the same NINO more than once using this method. If you require a unique NINO every time, I suggest you use the incremental generator.

$3

This method is best if you want to ensure you don't generate a duplicate NINO. This function utilises a JavaScript Generator to enumerate through all possible valid UK NI numbers AA000000A-ZY999999D (there are 1,492,000,000 in total).

The generator will enumerate on prefix, number and then suffix.

`js
// Create a generator instance
const uniqueNiGenerator = testNino.incremental();

for(let i = 0; i <= 10000000; i++) {
uniqueNiGenerator.next()
// Returns the next instance from the generator
// on the 1st iteration it will return { value: 'AA000000A', done: false }
// on the 2nd iteration it will return { value: 'AA000000B', done: false }
// ...
// on the 10000000th iteration it will return { value: 'AC500000A', done: false }
}
`

> The done property will only return true once all possible combinations have been enumerated.

$3


This function will validate the provided NINO and return an object which details which rules have passed or failed.
> It is expected that the NINO is already without formatting etc. - you can use normalise to prepare the NINO if required.

`js
// A valid NINO
testNino.validate("AB123456C");
// {
// rules: {
// type: true,
// length: true,
// prefix: true,
// number: true,
// suffix: true
// },
// outcome: true
// }

// An invalid NINO
testNino.validate(1);
// {
// rules: {
// type: false,
// },
// outcome: false
// }
`
> The object returned will always have an outcome property but the function fails fast and so will only return a result for each tested element of the NINO.

$3


This function will normalise NINOs, stripping whitespace and converting it to uppercase characters.
`js
testNino.normalise('aa 00 00 00 a') // AA000000A
testNino.normalise('BB 123456 B') // BB123456B
`
> This can be used as a primer for the validate function

Benchmarks

All benchmarks are ran using benchmark.js on Node v18.16.0. CommonJS imports are used for all packages to keep things fair. You can run the benchmarks yourself from the benchmarks folder. Results have been rounded to 3 significant figures to smooth out variances between runs and provide more comparable results.

$3

test-nino is more than 2.6x faster than the next fastest random NI number generator:

| package | version | ops/sec |
|------------------------------------------------------------------|---------|------------|
| fake-nino | 0.0.1 | 5,810,000 |
| random_uk_nino | 1.0.3 | 6,340,000 |
| avris-generator | 0.8.2 | 2,900,000 |
| test-nino | latest | 17,000,000 |

> Other packages use loops which go through the process of Generate random NINO > is it valid? > no > repeat, until a valid nino is given. This costs precious CPU time and blocks the Node Event Loop. test-nino is made different and instead stores the complete list of valid prefixes which are then picked at random. No loops result in consistent performance that is not guaranteed with other packages.

$3


test-nino is more than 14x faster than the next fastest validate function when validating a valid nino:

| package | version | valid (AA000000A) | invalid (A) | invalid (null) | invalid (AAX00000A) | invalid (AA00000XA) |
|--------------------------------------------------------------------------------------------|---------|-------------------| -----------------| ---------------- | ------------------- | ------------------- |
| valid-nino | 1.0.0 | 34,000,000 | 84,600,000 | 64,100,000 | 75,200,000 | 27,000,000 |
| is-national-insurance-number | 1.0.0 | 42,800,000 | 1,030,000,000 | 1,030,000,000 | 80,000,000 | 33,000,000 |
| avris-generator | 0.8.2 | 4,190,000 | 232,000 (throws) | 105,000 (throws) | 230,000 (throws) | 230,000 (throws) |
| test-nino | latest | 609,000,000 | 1,030,000,000 | 1,030,000,000 | 1,020,000,000 | 601,000,000 |

> Most other packages rely on Regex patterns, the validate function in test-nino` instead utilises indexed character lookups which are much faster. The function also fails fast, meaning even bigger gains for specific invalid scenarios.

What is a valid UK National Insurance number?

To cite the rules at the time of implementation from Gov.uk:
> A NINO is made up of 2 letters, 6 numbers and a suffix, which is always A, B, C, or D.
>
> It looks something like this: QQ 12 34 56 A
>
>All prefixes are valid except:
>
>* The characters D, F, I, Q, U, and V are not used as either the first or second letter of a NINO prefix.
>* The letter O is not used as the second letter of a prefix.
>* Prefixes BG, GB, KN, NK, NT, TN and ZZ are not to be used

How many valid UK National Insurance numbers are there?

First, let's consider the restrictions on the first two letters of the NINO prefix:

* The characters D, F, I, Q, U, and V are not used as either the first or second letter of the prefix, so there are 20 possible choices for the first letter (A-Z excluding D, F, I, Q, U, and V) and 19 possible choices for the second letter (A-Z excluding D, F, I, Q, U, V, and O).
* The prefixes BG, GB, KN, NK, NT, TN and ZZ are not to be used, so there are 20 x 19 - 7 = 373 possible combinations of the first two letters.

Next, let's consider the restrictions on the final letter, which is the suffix:

* The suffix can only be A, B, C, or D, so there are 4 possible suffixes.

Finally, let's consider the six numbers in the NINO:

* Each of the six numbers can have 10 possible values (0-9), so there are 10^6 (1 million) possible combinations of the six numbers.

Putting this all together, the number of possible unique NINOs would be:

373 (for the first two letters) x 10^6 (for the six numbers) x 4 (for the final letter) = 1,492,000,000 possible NINOs.