stdnum 1.10.0 → 1.10.2

package/src/es/nss.ts

@@ -0,0 +1,132 @@
+/**
+ * NSS (El número de Seguridad Social, Social Security Number).
+ *
+ * The SSN is a tax identification number for individuals entities. It has 12 digits
+ * where where the first 2 digits indicate province, followed by 8 digits and
+ * a 2 digit checksum
+ *
+ * Sources:
+ *   https://cis.ier.hit-u.ac.jp/English/society/conference1001/delgado-paper.pdf
+ *   https://www.grupoalquerque.es/ferias/2012/archivos/digitos/codigo_seguridad_social.pdf
+ *
+ * TAX/PERSON
+ */
+
+import * as exceptions from '../exceptions';
+import { strings } from '../util';
+import { Validator, ValidateReturn } from '../types';
+
+const PROVINCES = {
+  ÁLAVA: '01',
+  ALBACETE: '02',
+  ALICANTE: '03',
+  ALMERÍA: '04',
+  ASTURIAS: '33',
+  ÁVILA: '05',
+  BADAJOZ: '06',
+  BALEARES: '07',
+  BARCELONA: '08',
+  BURGOS: '09',
+  CÁCERES: '10',
+  CÁDIZ: '11',
+  CANTABRIA: '39',
+  CASTELLÓN: '12',
+  'CIUDAD REAL': '13',
+  CÓRDOBA: '14',
+  CORUÑA: '15',
+  CUENCA: '16',
+  GERONA: '17',
+  GRANADA: '18',
+  GUADALAJARA: '19',
+  GUIPÚZCOA: '20',
+  HUELVA: '21',
+  HUESCA: '22',
+  JAÉN: '23',
+  LEÓN: '24',
+  LÉRIDA: '25',
+  LUGO: '27',
+  MADRID: '28',
+  MÁLAGA: '29',
+  MURCIA: '30',
+  NAVARRA: '31',
+  ORENSE: '32',
+  PALENCIA: '34',
+  'PALMAS (LAS)': '35',
+  PONTEVEDRA: '36',
+  'RIOJA (LA)': '26',
+  SALAMANCA: '37',
+  'SANTA CRUZ DE TENERIFE': '38',
+  SEGOVIA: '40',
+  SEVILLA: '41',
+  SORIA: '42',
+  TARRAGONA: '43',
+  TERUEL: '44',
+  TOLEDO: '45',
+  VALENCIA: '46',
+  VALLADOLID: '47',
+  VIZCAYA: '48',
+  ZAMORA: '49',
+  ZARAGOZA: '50',
+  'OTROS TERRITORIOS': '53',
+  EXTRANJERO: '66',
+};
+const VALID_PROVINCES = Object.values(PROVINCES);
+
+function clean(input: string): ReturnType<typeof strings.cleanUnicode> {
+  return strings.cleanUnicode(input, ' -/');
+}
+
+const impl: Validator = {
+  name: 'Spanish Social Security Number',
+  localName: 'Número de Seguridad Social',
+  abbreviation: 'NSS',
+  compact(input: string): string {
+    const [value, err] = clean(input);
+
+    if (err) {
+      throw err;
+    }
+
+    return value;
+  },
+
+  format(input: string): string {
+    const [value] = clean(input);
+
+    return strings.splitAt(value, 2).join('-');
+  },
+
+  validate(input: string): ValidateReturn {
+    const [value, error] = clean(input);
+
+    if (error) {
+      return { isValid: false, error };
+    }
+    if (value.length !== 12) {
+      return { isValid: false, error: new exceptions.InvalidLength() };
+    }
+
+    if (!strings.isdigits(value)) {
+      return { isValid: false, error: new exceptions.InvalidComponent() };
+    }
+
+    const [province, body, check] = strings.splitAt(value, 2, 10);
+    if (!VALID_PROVINCES.includes(province)) {
+      return { isValid: false, error: new exceptions.InvalidComponent() };
+    }
+
+    if (parseInt(province + body, 10) % 97 !== parseInt(check, 10)) {
+      return { isValid: false, error: new exceptions.InvalidChecksum() };
+    }
+
+    return {
+      isValid: true,
+      compact: value,
+      isIndividual: true,
+      isCompany: false,
+    };
+  },
+};
+
+export const { name, localName, abbreviation, validate, format, compact } =
+  impl;

package/src/exceptions.ts

@@ -0,0 +1,66 @@
+/* eslint-disable max-classes-per-file */
+/**
+ * Collection of exceptions.
+ * The validation functions of stdnum should raise one of the below exceptions
+ * when validation of the number fails.
+ */
+
+/**
+ * Top-level error for validating numbers.
+ *
+ * This exception should normally not be raised, only subclasses of this
+ * exception.
+ */
+export class ValidationError extends Error {
+  constructor(msg: string) {
+    super(msg);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ *  Something is wrong with the format of the number.
+ *
+ *  This generally means characters or delimiters that are not allowed are
+ *  part of the number or required parts are missing.
+ */
+export class InvalidFormat extends ValidationError {
+  constructor(msg = 'The number has an invlidad format.') {
+    super(msg);
+    this.name = 'InvalidFormat';
+  }
+}
+
+/**
+ * The number's internal checksum or check digit does not match.
+ */
+export class InvalidChecksum extends ValidationError {
+  constructor(msg = "The number number's checksum or check digit is invalid.") {
+    super(msg);
+    this.name = 'InvalidChecksum';
+  }
+}
+
+/**
+ * The length of the number is wrong
+ */
+export class InvalidLength extends ValidationError {
+  constructor(msg = 'The number has an invalid length.') {
+    super(msg);
+    this.name = 'InvalidLength';
+  }
+}
+
+/**
+ * One of the parts of the number has an invalid reference.
+ *
+ * Some part of the number refers to some external entity like a country
+ * code, a date or a predefined collection of values. The number contains
+ * some invalid reference.
+ */
+export class InvalidComponent extends ValidationError {
+  constructor(msg = 'One of the parts of the number are invalid or unknown.') {
+    super(msg);
+    this.name = 'InvalidComponent';
+  }
+}

package/src/fi/alv.spec.ts

@@ -0,0 +1,28 @@
+import { validate, format } from './alv';
+import { InvalidLength, InvalidChecksum } from '../exceptions';
+
+describe('fi/alv', () => {
+  it('format:FI 20774740', () => {
+    const result = format('FI 20774740');
+
+    expect(result).toEqual('20774740');
+  });
+
+  it('validate:FI 20774740', () => {
+    const result = validate('FI 20774740');
+
+    expect(result.isValid && result.compact).toEqual('20774740');
+  });
+
+  it('validate:123458', () => {
+    const result = validate('123458');
+
+    expect(result.error).toBeInstanceOf(InvalidLength);
+  });
+
+  it('validate:20774741', () => {
+    const result = validate('20774741');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+});

package/src/fi/alv.ts

@@ -0,0 +1,76 @@
+/**
+ * ALV nro (Arvonlisäveronumero, Finnish VAT number).
+ *
+ * The number is an 8-digit code with a weighted checksum.
+ *
+ * ENTITY
+ */
+
+import * as exceptions from '../exceptions';
+import { strings } from '../util';
+import { Validator, ValidateReturn } from '../types';
+import { weightedSum } from '../util/checksum';
+
+function clean(input: string): ReturnType<typeof strings.cleanUnicode> {
+  const [value, err] = strings.cleanUnicode(input, ' ');
+  if (err !== null) {
+    return [value, err];
+  }
+  if (value.startsWith('FI')) {
+    return [value.substr(2), null];
+  }
+  return [value, null];
+}
+
+const impl: Validator = {
+  name: 'Finnish VAT Number',
+  localName: 'Arvonlisäveronumero Mervärdesskattenummer',
+  abbreviation: 'ALV nro',
+  compact(input: string): string {
+    const [value, err] = clean(input);
+
+    if (err) {
+      throw err;
+    }
+
+    return value;
+  },
+
+  format(input: string): string {
+    const [value] = clean(input);
+
+    return value;
+  },
+
+  validate(input: string): ValidateReturn {
+    const [value, error] = clean(input);
+
+    if (error) {
+      return { isValid: false, error };
+    }
+    if (value.length !== 8) {
+      return { isValid: false, error: new exceptions.InvalidLength() };
+    }
+    if (!strings.isdigits(value)) {
+      return { isValid: false, error: new exceptions.InvalidFormat() };
+    }
+
+    const sum = weightedSum(value, {
+      modulus: 11,
+      weights: [7, 9, 10, 5, 8, 4, 2, 1],
+    });
+    if (sum !== 0) {
+      return { isValid: false, error: new exceptions.InvalidChecksum() };
+    }
+
+    return {
+      isValid: true,
+      compact: value,
+      isIndividual: false,
+      isCompany: true,
+    };
+  },
+};
+
+export const { name, localName, abbreviation, validate, format, compact } =
+  impl;

package/src/fi/hetu.spec.ts

@@ -0,0 +1,37 @@
+import { validate, format } from './hetu';
+import { InvalidLength, InvalidChecksum } from '../exceptions';
+
+describe('fi/hetu', () => {
+  it('format:131052-308T', () => {
+    const result = format('131052-308T');
+
+    expect(result).toEqual('131052-308T');
+  });
+
+  it('validate:131052-308T', () => {
+    const result = validate('131052-308T');
+
+    expect(result.isValid && result.compact).toEqual('131052-308T');
+  });
+
+  test.each(['131022B3082', '131052X308T', '131052-308T'])(
+    'validate:%s',
+    value => {
+      const result = validate(value);
+
+      expect(result.isValid).toEqual(true);
+    },
+  );
+
+  it('validate:12345678', () => {
+    const result = validate('12345678');
+
+    expect(result.error).toBeInstanceOf(InvalidLength);
+  });
+
+  it('validate:131052-308U', () => {
+    const result = validate('131052-308U');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+});

package/src/fi/hetu.ts

@@ -0,0 +1,108 @@
+/**
+ * HETU (Henkilötunnus, Finnish personal identity code).
+ *
+ * Module for handling Finnish personal identity codes (HETU, Henkilötunnus).
+ * See https://www.vaestorekisterikeskus.fi/default.aspx?id=45 for checksum
+ * calculation details and https://tarkistusmerkit.teppovuori.fi/tarkmerk.htm#hetu1
+ * for historical details.
+ *
+ * PERSON
+ */
+
+import * as exceptions from '../exceptions';
+import { isValidDate, strings } from '../util';
+import { Validator, ValidateReturn } from '../types';
+
+function clean(input: string): ReturnType<typeof strings.cleanUnicode> {
+  return strings.cleanUnicode(input, ' ');
+}
+
+const CHECK_ALPHA = '0123456789ABCDEFHJKLMNPRSTUVWXY';
+const CENTURY: Record<string, string> = {
+  '+': '18',
+  '-': '19',
+  Y: '19',
+  X: '19',
+  W: '19',
+  V: '19',
+  U: '19',
+  A: '20',
+  B: '20',
+  C: '20',
+  D: '20',
+  E: '20',
+  F: '20',
+};
+const VALID_CENTURY = Object.keys(CENTURY);
+
+const impl: Validator = {
+  name: 'Finnish Personal Identity Code',
+  localName: 'Henkilötunnus',
+  abbreviation: 'HETU',
+
+  compact(input: string): string {
+    const [value, err] = clean(input);
+
+    if (err) {
+      throw err;
+    }
+
+    return value;
+  },
+
+  format(input: string): string {
+    const [value] = clean(input);
+
+    return value;
+  },
+
+  validate(input: string): ValidateReturn {
+    const [value, error] = clean(input);
+
+    if (error) {
+      return { isValid: false, error };
+    }
+    if (value.length !== 11) {
+      return { isValid: false, error: new exceptions.InvalidLength() };
+    }
+
+    const [front, , back, check2] = strings.splitAt(value, 6, 7, -1);
+    if (
+      !strings.isdigits(front) ||
+      !strings.isdigits(back) ||
+      !CHECK_ALPHA.includes(check2)
+    ) {
+      return { isValid: false, error: new exceptions.InvalidFormat() };
+    }
+    if (!VALID_CENTURY.includes(value[6])) {
+      return { isValid: false, error: new exceptions.InvalidComponent() };
+    }
+
+    const [dd, mm, yy, century, person, check] = strings.splitAt(
+      value,
+      2,
+      4,
+      6,
+      7,
+      10,
+    );
+    if (!isValidDate(`${CENTURY[century]}${yy}`, mm, dd, true)) {
+      return { isValid: false, error: new exceptions.InvalidComponent() };
+    }
+
+    const checkable = `${dd}${mm}${yy}${person}`;
+    if (CHECK_ALPHA[parseInt(checkable, 10) % CHECK_ALPHA.length] !== check) {
+      return { isValid: false, error: new exceptions.InvalidChecksum() };
+    }
+
+    return {
+      isValid: true,
+      compact: value,
+      isIndividual: true,
+      isCompany: false,
+    };
+  },
+};
+
+export const { name, localName, abbreviation, validate, format, compact } =
+  impl;

package/src/fi/index.ts

@@ -0,0 +1,3 @@
+export * as alv from './alv';
+export * as hetu from './hetu';
+export * as ytunnus from './ytunnus';

package/src/fi/ytunnus.spec.ts

@@ -0,0 +1,28 @@
+import { validate, format } from './ytunnus';
+import { InvalidLength, InvalidChecksum } from '../exceptions';
+
+describe('fi/ytunnus', () => {
+  it('format:20774740', () => {
+    const result = format('20774740');
+
+    expect(result).toEqual('2077474-0');
+  });
+
+  it('validate:2077474-0', () => {
+    const result = validate('2077474-0');
+
+    expect(result.isValid && result.compact).toEqual('20774740');
+  });
+
+  it('validate:1234567', () => {
+    const result = validate('1234567');
+
+    expect(result.error).toBeInstanceOf(InvalidLength);
+  });
+
+  it('validate:2077474-1', () => {
+    const result = validate('2077474-1');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+});

package/src/fi/ytunnus.ts

@@ -0,0 +1,49 @@
+/**
+ * Y-tunnus (Finnish business identifier).
+ *
+ *  The number is an 8-digit code with a weighted checksum.
+ *
+ * ENTITY
+ */
+
+import { strings } from '../util';
+import { Validator, ValidateReturn } from '../types';
+import { validate as alvValidate } from './alv';
+
+function clean(input: string): ReturnType<typeof strings.cleanUnicode> {
+  return strings.cleanUnicode(input, ' -');
+}
+
+const impl: Validator = {
+  name: 'Finnish Business Identifier',
+  localName: 'Yritys- ja yhteisötunnus',
+  abbreviation: 'Y-tunnus',
+  compact(input: string): string {
+    const [value, err] = clean(input);
+
+    if (err) {
+      throw err;
+    }
+
+    return value;
+  },
+
+  format(input: string): string {
+    const [value] = clean(input);
+
+    return strings.splitAt(value, -1).join('-');
+  },
+
+  validate(input: string): ValidateReturn {
+    const [value, error] = clean(input);
+
+    if (error) {
+      return { isValid: false, error };
+    }
+
+    return alvValidate(value);
+  },
+};
+
+export const { name, localName, abbreviation, validate, format, compact } =
+  impl;

package/src/fo/index.ts

@@ -0,0 +1 @@
+export * as vn from './vn';

package/src/fo/vn.spec.ts

@@ -0,0 +1,34 @@
+import { validate, format } from './vn';
+import { InvalidLength, InvalidFormat } from '../exceptions';
+
+describe('fo/vn', () => {
+  it('format:623857', () => {
+    const result = format('623857');
+
+    expect(result).toEqual('623857');
+  });
+
+  it('fvalidate:623857', () => {
+    const result = validate('623857');
+
+    expect(result.isValid && result.compact).toEqual('623857');
+  });
+
+  test.each(['623857', '33 28 28', '563.609'])('validate:%s', value => {
+    const result = validate(value);
+
+    expect(result.isValid).toEqual(true);
+  });
+
+  it('validate:62385', () => {
+    const result = validate('62385');
+
+    expect(result.error).toBeInstanceOf(InvalidLength);
+  });
+
+  it('validate:62385A', () => {
+    const result = validate('62385A');
+
+    expect(result.error).toBeInstanceOf(InvalidFormat);
+  });
+});

package/src/fo/vn.ts

@@ -0,0 +1,71 @@
+/**
+ * V-number (Vinnutal, Faroe Islands tax number).
+ *
+ * In the Faroe Islands the legal persons TIN equals the V number issued by the
+ * Faroese Tax Administration. It is a consecutive number.
+ *
+ * Source
+ *   https://www.taks.fo/fo/borgari/bolkar/at-stovna-virki/
+ *   https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/Faroe-islands-TIN.pdf
+ *
+ * ENTITY/PERSON
+ */
+
+import * as exceptions from '../exceptions';
+import { strings } from '../util';
+import { Validator, ValidateReturn } from '../types';
+
+function clean(input: string): ReturnType<typeof strings.cleanUnicode> {
+  return strings.cleanUnicode(input, ' -.');
+}
+
+// const validRe = /^[PCGQV]{1}00[A-Z0-9]{8}$/;
+
+// const ALPHABET = '0123456789X';
+
+const impl: Validator = {
+  name: 'Vinnutal',
+  localName: 'NAME',
+  abbreviation: 'VN',
+
+  compact(input: string): string {
+    const [value, err] = clean(input);
+
+    if (err) {
+      throw err;
+    }
+
+    return value;
+  },
+
+  format(input: string): string {
+    const [value] = clean(input);
+
+    return value;
+  },
+
+  validate(input: string): ValidateReturn {
+    const [value, error] = clean(input);
+
+    if (error) {
+      return { isValid: false, error };
+    }
+    if (value.length !== 6) {
+      return { isValid: false, error: new exceptions.InvalidLength() };
+    }
+
+    if (!strings.isdigits(value)) {
+      return { isValid: false, error: new exceptions.InvalidFormat() };
+    }
+
+    return {
+      isValid: true,
+      compact: value,
+      isIndividual: false,
+      isCompany: false,
+    };
+  },
+};
+
+export const { name, localName, abbreviation, validate, format, compact } =
+  impl;

package/src/fr/index.ts

@@ -0,0 +1,5 @@
+export * as nif from './nif';
+export * as nir from './nir';
+export * as siren from './siren';
+export * as siret from './siret';
+export * as tva from './tva';

package/src/fr/nif.spec.ts

@@ -0,0 +1,34 @@
+import { validate, format } from './nif';
+import { InvalidComponent, InvalidLength } from '../exceptions';
+
+describe('fr/nif', () => {
+  it('format:0701987765432', () => {
+    const result = format('0701987765432');
+
+    expect(result).toEqual('07 01 987 765 432');
+  });
+
+  test.each(['3023217600053', '0701987765493'])('validate:%s', value => {
+    const result = validate(value);
+
+    expect(result.isValid && result.compact).toEqual(value);
+  });
+
+  test.each(['0000000000000'])('validate:%s', value => {
+    const result = validate(value);
+
+    expect(result.isValid).toEqual(false);
+  });
+
+  it('validate:12345678', () => {
+    const result = validate('12345678');
+
+    expect(result.error).toBeInstanceOf(InvalidLength);
+  });
+
+  it('validate:9701987765432', () => {
+    const result = validate('9701987765432');
+
+    expect(result.error).toBeInstanceOf(InvalidComponent);
+  });
+});