stdnum 1.9.16 → 1.10.1

package/src/es/dni.ts

@@ -0,0 +1,83 @@
+/**
+ * DNI (Documento Nacional de Identidad, Spanish personal identity codes).
+ *
+ * The DNI is a 9 digit number used to identify Spanish citizens. The last
+ * digit is a checksum letter.
+ *
+ * Foreign nationals, since 2010 are issued an NIE (Número de Identificación
+ * de Extranjeros, Foreigner's Identity Number) instead.
+ *
+ * Sources:
+ *   https://www.oecd.org/tax/automatic-exchange/crs-implementation-and-assistance/tax-identification-numbers/SPAIN-TIN.pdf
+ *
+ * PERSON
+ */
+
+import * as exceptions from '../exceptions';
+import { strings } from '../util';
+import { Validator, ValidateReturn } from '../types';
+
+const checkDigits = 'TRWAGMYFPDXBNJZSQVHLCKE';
+
+export function calcCheckDigit(value: string): string {
+  return checkDigits[parseInt(value.substr(0, 8), 10) % 23];
+}
+
+function clean(input: string): ReturnType<typeof strings.cleanUnicode> {
+  return strings.cleanUnicode(input, ' -');
+}
+
+const impl: Validator = {
+  name: 'Spanish Personal Identify Code',
+  localName: 'Documento Nacional de Identidad',
+  abbreviation: 'DNI',
+  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, 8).join('-');
+  },
+
+  validate(input: string): ValidateReturn {
+    const [value, error] = clean(input);
+
+    if (error) {
+      return { isValid: false, error };
+    }
+    if (value.length !== 9) {
+      return { isValid: false, error: new exceptions.InvalidLength() };
+    }
+
+    const [body, check] = strings.splitAt(value, 8);
+
+    if ('KLM'.includes(body[0]) && strings.isdigits(body.substring(1))) {
+      // Currently no test data for these cases, so
+      // we're assuming they're good based on format
+    } else if (!strings.isdigits(body)) {
+      // Not all digits in the body, it's not valid
+      return { isValid: false, error: new exceptions.InvalidComponent() };
+    } else if (calcCheckDigit(body) !== check) {
+      // Check the checksum on a non-[KLM] person
+      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/es/index.ts

@@ -0,0 +1,5 @@
+export * as cif from './cif';
+export * as dni from './dni';
+export * as nie from './nie';
+export * as nif from './nif';
+export * as nss from './nss';

package/src/es/nie.spec.ts

@@ -0,0 +1,28 @@
+import { validate, format } from './nie';
+import { InvalidLength, InvalidChecksum } from '../exceptions';
+
+describe('es/nie', () => {
+  it('format:x-2482300w', () => {
+    const result = format('x-2482300w');
+
+    expect(result).toEqual('X-2482300-W');
+  });
+
+  it('validate:x-2482300w', () => {
+    const result = validate('x-2482300w');
+
+    expect(result.isValid && result.compact).toEqual('X2482300W');
+  });
+
+  it('validate:X2482300', () => {
+    const result = validate('X2482300');
+
+    expect(result.error).toBeInstanceOf(InvalidLength);
+  });
+
+  it('validate:x-2482300a', () => {
+    const result = validate('x-2482300a');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+});

package/src/es/nie.ts

@@ -0,0 +1,79 @@
+/**
+ * NIE (Número de Identificación de Extranjero, Spanish foreigner number).
+ *
+ * The NIE is an identification number for foreigners. It is a 9 digit number
+ * where the first digit is either X, Y or Z and last digit is a checksum
+ * letter.
+ *
+ * Sources:
+ *    https://es.wikipedia.org/wiki/N%C3%BAmero_de_identidad_de_extranjero
+ *
+ * PERSON
+ */
+
+import * as exceptions from '../exceptions';
+import { strings } from '../util';
+import * as dni from './dni';
+import { Validator, ValidateReturn } from '../types';
+
+const checkDigits = 'XYZ';
+
+function clean(input: string): ReturnType<typeof strings.cleanUnicode> {
+  return strings.cleanUnicode(input, ' -');
+}
+
+const impl: Validator = {
+  name: 'Spanish Foreign Number',
+  localName: 'Número de Identificación de Extranjero',
+  abbreviation: 'NIE',
+  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, 8).join('-');
+  },
+
+  validate(input: string): ValidateReturn {
+    const [value, error] = clean(input);
+
+    if (error) {
+      return { isValid: false, error };
+    }
+    if (value.length !== 9) {
+      return { isValid: false, error: new exceptions.InvalidLength() };
+    }
+
+    const [first, body, check] = strings.splitAt(value, 1, 8);
+
+    if (
+      !strings.isdigits(body) ||
+      !checkDigits.includes(first) ||
+      strings.isdigits(check)
+    ) {
+      return { isValid: false, error: new exceptions.InvalidComponent() };
+    }
+
+    if (dni.calcCheckDigit(`${checkDigits.indexOf(first)}${body}`) !== 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/es/nif.spec.ts

@@ -0,0 +1,52 @@
+import { validate, format } from './nif';
+import { InvalidLength, InvalidChecksum } from '../exceptions';
+
+describe('es/nif', () => {
+  it('format:ES B58378431', () => {
+    const result = format('ES B58378431');
+
+    expect(result).toEqual('B-58378431');
+  });
+
+  it('validate:ES B-58378431', () => {
+    const result = validate('ES B-58378431');
+
+    expect(result.isValid && result.compact).toEqual('B58378431');
+  });
+
+  it('validate:B64717838', () => {
+    const result = validate('B64717838');
+
+    expect(result.isValid && result.compact).toEqual('B64717838');
+  });
+
+  it('validate:54362315K', () => {
+    const result = validate('54362315K');
+
+    expect(result.isValid && result.compact).toEqual('54362315K');
+  });
+
+  it('validate:X-5253868-R', () => {
+    const result = validate('X-5253868-R');
+
+    expect(result.isValid && result.compact).toEqual('X5253868R');
+  });
+
+  it('validate:M-1234567-L', () => {
+    const result = validate('M-1234567-L');
+
+    expect(result.isValid && result.compact).toEqual('M1234567L');
+  });
+
+  it('validate:B647178390', () => {
+    const result = validate('54362315');
+
+    expect(result.error).toBeInstanceOf(InvalidLength);
+  });
+
+  it('validate:B64717839', () => {
+    const result = validate('B64717839');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+});

package/src/es/nif.ts

@@ -0,0 +1,95 @@
+/**
+ * NIF (Número de Identificación Fiscal, Spanish VAT number).
+ *
+ * The Spanish VAT number is a 9-digit number where either the first, last
+ * digits or both can be letters.
+ * The number is either a DNI (Documento Nacional de Identidad, for
+ *
+ * Spaniards), a NIE (Número de Identificación de Extranjero, for
+ * foreigners) or a CIF (Código de Identificación Fiscal, for legal
+ * entities and others).
+ *
+ * VAT (PERSON/ENTITY)
+ */
+
+import * as exceptions from '../exceptions';
+import { strings } from '../util';
+import { Validator, ValidateReturn } from '../types';
+import * as nie from './nie';
+import * as dni from './dni';
+import * as cif from './cif';
+
+function clean(input: string): ReturnType<typeof strings.cleanUnicode> {
+  const [value, err] = strings.cleanUnicode(input, ' -./');
+
+  if (err) {
+    return [value, err];
+  }
+  if (value.startsWith('ES')) {
+    return [value.substr(2), null];
+  }
+
+  return [value, null];
+}
+
+const impl: Validator = {
+  name: 'Spanish VAT Number',
+  localName: 'Número de Identificación Fiscal',
+  abbreviation: 'NIF',
+  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 };
+    }
+    if (value.length !== 9) {
+      return { isValid: false, error: new exceptions.InvalidLength() };
+    }
+
+    if ('KLM'.includes(value[0])) {
+      // K: Spanish younger than 14 year old
+      // L: Spanish living outside Spain without DNI
+      // M: granted the tax to foreigners who have no NIE
+      // these use the old checkdigit algorithm (the DNI one)
+      if (value[value.length - 1] !== dni.calcCheckDigit(value.substr(1))) {
+        return { isValid: false, error: new exceptions.InvalidChecksum() };
+      }
+      return {
+        isValid: true,
+        compact: value,
+        isIndividual: true,
+        isCompany: false,
+      };
+    }
+    if (strings.isdigits(value[0])) {
+      // Natural resident (DNI)
+      return dni.validate(value);
+    }
+    if ('XYZ'.includes(value[0])) {
+      // Foreign natural person (NIE)
+      return nie.validate(value);
+    }
+
+    // Otherwise it has to be a (CIF)
+    return cif.validate(value);
+  },
+};
+
+export const { name, localName, abbreviation, validate, format, compact } =
+  impl;

package/src/es/nss.spec.ts

@@ -0,0 +1,28 @@
+import { validate, format } from './nss';
+import { InvalidLength, InvalidComponent } from '../exceptions';
+
+describe('es/nss', () => {
+  it('format:281234567840', () => {
+    const result = format('281234567840');
+
+    expect('28-1234567840').toEqual(result);
+  });
+
+  it.each(['281234567840'])('validate:%s', (value: string) => {
+    const result = validate(value);
+
+    expect(value).toEqual(result.isValid && result.compact);
+  });
+
+  it('validate:77 12345678 40', () => {
+    const result = validate('77 12345678 40');
+
+    expect(result.error).toBeInstanceOf(InvalidComponent);
+  });
+
+  it('validate:28 12345678 4', () => {
+    const result = validate('28 12345678 4');
+
+    expect(result.error).toBeInstanceOf(InvalidLength);
+  });
+});

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;