@island.is/kennitala v3.1.2

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,
  isPerson,
  isCompany,
  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)
isPerson('3108962099');            // returns true
isPerson('601010-0890');           // returns false (invalid date)
isPerson(3108962099);              // returns false (invalid input type)
isPerson('31^_^08!!96LOL20T_T99'); // returns false (invalid format)

// Check if a kennitala is valid for a company (returns false for persons)
isCompany('6010100890');  // returns true
isCompany('601010-0890'); // returns true
isCompany('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 to true to allow validation of test kennitala numbers.

• Returns: true if the kennitala is valid, false otherwise.

isPerson(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 in isValid.

• Returns: true if the kennitala is valid for a person, false otherwise.

isCompany(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.

isTemporary(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

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, otherwise returns the kennitala string unchanged.

formatKennitala(kennitala: string, spacer?: boolean): string

Formats the kennitala by adding a - spacer between the 6th and 7th digits. Does not validate the input.

• 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" | "invalid"; // 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, startingIncrement = 20): string

Generates a valid kennitala for a person based on a Date object to specify the birth date.

• Parameters:

  • date: The birth date to use for generating the kennitala.
  • startingIncrement: The starting increment for digits 7 and 8 (default: 20).

• Returns: A valid kennitala string.

generateCompany(date: Date): string

Generates a valid kennitala for a company based on a Date object to specify the registration date.

• Parameters:

  • date: The date to use for generating the company kennitala.

• Returns: A valid kennitala string.

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.