kennitala
v2.0.6
Published
Icelandic social security number (kennitölur) utilities for servers and clients
Downloads
17,543
Maintainers
Readme
Kennitala
Icelandic national ID (kennitölur) utilities for servers and clients. Now with TypeScript support!
Install with npm:
npm install kennitala
Examples
import { isValid } from "kennitala";
// Check if a kennitala is valid for either a person or a company
isValid("3108962099"); // returns true
isValid("8281249124"); // returns false
Heads Up for Storing in Databases
This library validates kennitölur both with -
spacers and without, so remember to sanitize your kennitala before storing it in a database!
You can use the included sanitize
function:
import { sanitize } from "kennitala";
const sanitizedKennitala = sanitize("310896-2099");
// returns '3108962099'
More Examples
import {
isValid,
isPersonKennitala,
isCompanyKennitala,
formatKennitala,
info,
generatePerson,
generateCompany,
} from 'kennitala';
// Get detailed information about a kennitala
const kennitalaInfo = info('3108962099');
// kennitalaInfo contains:
{
kt: '3108962099',
valid: true,
type: 'person',
birthday: new Date('1996-08-31T00:00:00.000Z'),
birthdayReadable: 'Sat Aug 31 1996',
age: 27,
}
// Check if a kennitala is valid for a person (returns false for companies)
isPersonKennitala('3108962099'); // returns true
isPersonKennitala('601010-0890'); // returns false (invalid date)
isPersonKennitala(3108962099); // returns false (invalid input type)
isPersonKennitala('31^_^08!!96LOL20T_T99'); // returns false (invalid format)
// Check if a kennitala is valid for a company (returns false for persons)
isCompanyKennitala('6010100890'); // returns true
isCompanyKennitala('601010-0890'); // returns true
isCompanyKennitala('3108962099'); // returns false
// Format a kennitala by adding a traditional '-' spacer
formatKennitala('3108962099'); // returns '310896-2099'
formatKennitala('3108962099', false); // returns '3108962099'
API Documentation
Below is the API based on the type definitions from the refactored TypeScript library.
isValid(kennitala: string, options?: { allowTestKennitala?: boolean }): boolean
Checks if the kennitala checksum is correct for either a person or company. Non-digit characters are removed before validation.
Parameters:
kennitala
: The kennitala string to validate.options
(optional): An object with the following property:allowTestKennitala
(default:false
): Set totrue
to allow validation of test kennitala numbers.
Returns:
true
if the kennitala is valid,false
otherwise.
isPersonKennitala(kennitala: string, options?: { allowTestKennitala?: boolean }): boolean
Checks if the kennitala is valid for a person. The day of birth must be between 1-31. Non-digit characters are removed before validation.
Parameters:
kennitala
: The kennitala string to validate.options
(optional): Same as inisValid
.
Returns:
true
if the kennitala is valid for a person,false
otherwise.
isCompanyKennitala(kennitala: string): boolean
Checks if the kennitala is valid for a company. The day of birth must be between 41-71. Non-digit characters are removed before validation.
Parameters:
kennitala
: The kennitala string to validate.
Returns:
true
if the kennitala is valid for a company,false
otherwise.
isTemporaryKennitala(kennitala: string): boolean
Checks if the kennitala is a valid temporary ID.
Parameters:
kennitala
: The kennitala string to validate.
Returns:
true
if the kennitala is a valid temporary ID,false
otherwise.
sanitize(kennitala: string): string | undefined
Sanitizes the input by removing all non-digit characters.
Parameters:
kennitala
: The kennitala string to sanitize.
Returns: The sanitized kennitala string if input is valid,
undefined
otherwise.
formatKennitala(kennitala: string, spacer?: boolean): string
Formats the kennitala by adding a -
spacer between the 6th and 7th digits.
Parameters:
kennitala
: The kennitala string to format.spacer
(optional): Includes a-
spacer character by default.
Returns: The formatted kennitala string.
info(kennitala: string): KennitalaInfo | undefined
Returns an object containing information about the kennitala.
Parameters:
kennitala
: The kennitala string to analyze.
Returns: An object of type
KennitalaInfo
if valid,undefined
otherwise.
KennitalaInfo
Type Definition:
interface KennitalaInfo {
kt: string; // The sanitized kennitala
valid: boolean; // Whether the kennitala is valid
type: "person" | "company" | "temporary" | "unknown"; // Type of kennitala
age?: number; // Age calculated from the birthday (if applicable)
birthday?: Date; // Date object representing the birthday (if applicable)
birthdayReadable?: string; // Human-readable date string (if applicable)
}
generatePerson(date?: Date): string | undefined
Generates a valid kennitala for a person. Optionally accepts a Date
object to specify the birth date.
Parameters:
date
(optional): The birth date to use for generating the kennitala.
Returns: A valid kennitala string if generation is successful,
undefined
otherwise.
generateCompany(date?: Date): string | undefined
Generates a valid kennitala for a company. Optionally accepts a Date
object to specify the registration date.
Parameters:
date
(optional): The date to use for generating the company kennitala.
Returns: A valid kennitala string if generation is successful,
undefined
otherwise.
Testing
The library uses Jest for testing. To run the tests, use:
npm test
Building
To build the project, run:
npm run build
This will compile the TypeScript code and place the output in the dist/
folder.