In part 1 we looked at the NIF, the Portuguese tax number. This time it's its less famous sibling: the NISS (Número de Identificação da Segurança Social), the 11-digit social security number.
You'll run into it as soon as you build anything around employment: HR and payroll software, onboarding forms, contracts, timesheets. And just like the NIF, "it has 11 digits" is not real validation.
So here's @edyspider/validate-niss.
TL;DR
npm i @edyspider/validate-niss
import { validateNISS, randomNISS } from '@edyspider/validate-niss';
validateNISS('12345678910'); // true
validateNISS('99999999999'); // false
randomNISS(); // e.g. '12109072813'
- Zero runtime dependencies
- Works with ES modules, CommonJS and TypeScript (types included)
- Runs in Node.js 22.12+, Bun, Deno and the browser
The rules
A NISS has two checks you can do locally.
1. The first digit says who it belongs to.
| First digit | Meaning |
|---|---|
1 |
Individual (singular person) |
2 |
Organisation (collective person) |
Anything starting with 0 or 3–9 is rejected.
2. The last digit is a check digit. This is where the NISS differs from the NIF. Instead of the 9, 8, 7… weights and mod 11, it uses prime numbers as weights and mod 10:
- multiply the first 10 digits by
29, 23, 19, 17, 13, 11, 7, 5, 3, 2; - add everything up;
- the check digit is
9 - (sum mod 10).
Here's 12345678910 worked out:
1×29 + 2×23 + 3×19 + 4×17 + 5×13 + 6×11 + 7×7 + 8×5 + 9×3 + 1×2 = 449
449 mod 10 = 9
9 - 9 = 0 ✅ matches the last digit
And the code:
const WEIGHTS = [29, 23, 19, 17, 13, 11, 7, 5, 3, 2];
function computeCheckDigit(base) {
const sum = WEIGHTS.reduce(
(total, weight, index) => total + Number(base[index]) * weight,
0,
);
return 9 - (sum % 10);
}
Same disclaimer as last time: this catches typos, not fraud. A NISS can pass the check and still not belong to anyone. Only Social Security (PT: Segurança Social) can confirm that.
Using it in a form
validateNISS() takes unknown and is strict: only an 11-digit string passes.
validateNISS(12345678910); // false, numbers are rejected on purpose
validateNISS(' 12345678910'); // false, leading space
validateNISS('12345678910\n'); // false, trailing new line
validateNISS(null); // false
That strictness is deliberate: the validator tells you whether the value is a NISS, and cleaning user input stays your call. With Zod, for example:
import { z } from 'zod';
import { validateNISS } from '@edyspider/validate-niss';
const employeeSchema = z.object({
name: z.string().min(1),
niss: z
.string()
.transform((value) => value.replace(/\s/g, ''))
.refine(validateNISS, { message: 'Invalid NISS' }),
});
Combined with part 1, you can validate both numbers an employee form usually asks for:
import { validateNIF } from '@edyspider/validate-nif';
import { validateNISS } from '@edyspider/validate-niss';
const isValidEmployee = (e: { nif: string; niss: string }) =>
validateNIF(e.nif) && validateNISS(e.niss);
CommonJS and CDN work too:
const { validateNISS } = require('@edyspider/validate-niss');
import { validateNISS } from 'https://cdn.jsdelivr.net/npm/@edyspider/validate-niss@2/+esm';
Test data with randomNISS()
randomNISS() returns a random valid NISS starting with 1 or 2. Handy for seeding a payroll demo, writing tests, or filling a staging database without using real people's numbers:
import { randomNISS } from '@edyspider/validate-niss';
const fakeEmployee = { name: 'Test Employee', niss: randomNISS() };
Lessons from rewriting v1
Version 2.0.0 is a rewrite, and going back to code I wrote in 2024 was humbling. The old version had a few bugs worth sharing, because they're easy to make:
-
require()was broken. In 1.0.2,maininpackage.jsonpointed to a file that didn't exist, sorequire('@edyspider/validate-niss')threwMODULE_NOT_FOUND. If your tests import fromsrc/instead of the package name, you'll never notice. The v2 tests now import@edyspider/validate-nissitself, through bothimportandrequire(). -
The validator leaked global variables.
factor,calcandiwere assigned withoutletorconst, so callingvalidateNISS()quietly created globals. Native ES modules run in strict mode, so that mistake now throws instead of hiding. -
It was too permissive. v1 accepted NISS numbers starting with
3to9. v2 only accepts1and2. That's the one breaking change to watch for if you upgrade. -
randomNISS()existed but was never published. It's on npm for the first time in v2.
The rest matches the NIF package: native ESM with a CommonJS entry point, TypeScript types for both, no runtime dependencies, tests on the built-in Node.js test runner, and releases published from GitHub Actions with npm provenance. The full list is in the changelog.
Try it online
To check or generate a NISS without writing code: edyspider.com/tools/niss.
Next up
The last part of the series is the biggest package: NIB and IBAN validation, plus finding a bank's name and SWIFT/BIC straight from the account number, with @edyspider/validate-bank-account-pt.
- 📦 npm: @edyspider/validate-niss
- 💻 GitHub: edyspider/validate-niss
Spotted an edge case? Open an issue or drop it in the comments. A ⭐ on GitHub is always appreciated.
Top comments (0)