stdnum 1.10.0 → 1.10.2

package/src/be/insz.ts

@@ -0,0 +1,55 @@
+/**
+ * The Belgian Social Security Identification Number is an 11 digit number.
+ * It can be either a National Register Number (NN, NISS) or BIS.
+ *
+ * Sources
+ *  https://fr.wikipedia.org/wiki/Numéro_de_registre_national
+ *  https://www2.deloitte.com/content/dam/Deloitte/be/Documents/tax/TaxAlerts/IndividualTaxAlerts/Social%20Security%20alert%20-%20BelgianIDpro%20-%2026%20Nov%202020.pdf
+ *
+ * PERSON
+ */
+
+import { strings } from '../util';
+import { validate as nnValidate } from './nn';
+import { validate as bisValidate } from './bis';
+import { Validator, ValidateReturn } from '../types';
+
+function clean(input: string): ReturnType<typeof strings.cleanUnicode> {
+  return strings.cleanUnicode(input, ' -.');
+}
+
+const impl: Validator = {
+  name: 'Belgian Social Security Identification Number',
+  localName: 'Identificatienummer van de Sociale Zekerheid',
+  abbreviation: 'INSZ, NISS',
+  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 results = [nnValidate(input), bisValidate(input)];
+    const validResult = results.find(r => r.isValid);
+    if (validResult) return validResult;
+
+    // The only case with two different error types is an invalid checksum and an
+    // invalid format. The identifier with the checksum error had correct
+    // formatting, so invalid checksum seems like the more descriptive error.
+
+    const checksumErrorResult = results.find(
+      r => r.error && r.error.name === 'InvalidChecksum',
+    );
+    return checksumErrorResult || results[0];
+  },
+};
+
+export const { name, localName, abbreviation, validate, format, compact } =
+  impl;

package/src/be/nn.spec.ts

@@ -0,0 +1,117 @@
+import { validate, format } from './nn';
+import { InvalidLength, InvalidChecksum, InvalidFormat } from '../exceptions';
+
+describe('be/nn', () => {
+  it('format:88 02 29-999.90', () => {
+    const result = format('88 02 29-999.90');
+
+    expect(result).toEqual('88022999990');
+  });
+
+  it('format:88022999990', () => {
+    const result = format('88022999990');
+
+    expect(result).toEqual('88022999990');
+  });
+
+  it('validate:1', () => {
+    const result = validate('1');
+
+    expect(result.error).toBeInstanceOf(InvalidLength);
+  });
+
+  it('validate:88022999990', () => {
+    const result = validate('88022999990');
+
+    expect(result.isValid && result.compact).toEqual('88022999990');
+  });
+
+  it('validate:88022999991', () => {
+    const result = validate('88022999991');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+
+  it('validate:87022999991', () => {
+    const result = validate('87022999991');
+
+    expect(result.error).toBeInstanceOf(InvalidFormat);
+  });
+
+  test.each([
+    '88022999297',
+    '85073003328',
+    '20070199922',
+    '20070199951',
+    '80000099902',
+    '00000199938',
+    '99000099913',
+  ])('validate:%s', value => {
+    const result = validate(value);
+
+    expect(result.isValid).toEqual(true);
+  });
+
+  it('validate:20070199952', () => {
+    const result = validate('20070199952');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+
+  it('validate:80000099903', () => {
+    const result = validate('80000099903');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+
+  it('validate:00000199939', () => {
+    const result = validate('00000199939');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+
+  it('validate:99000099942', () => {
+    const result = validate('99000099942');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+
+  it('validate:40000100133', () => {
+    const result = validate('40000100133');
+
+    expect(result.isValid && result.compact).toEqual('40000100133');
+  });
+
+  it('validate:00000199938', () => {
+    const result = validate('00000199938');
+
+    expect(result.isValid && result.compact).toEqual('00000199938');
+  });
+
+  it('validate:40000095579', () => {
+    const result = validate('40000095579');
+
+    expect(result.isValid && result.compact).toEqual('40000095579');
+  });
+
+  it('validate:(unspecified date in current year)', () => {
+    const yy = new Date().getFullYear() % 100;
+    const baseNum = parseInt(`${yy}0000999`, 10);
+    const twoPrefixedBaseNumber = parseInt(`${2}${baseNum}`, 10);
+    const checksum = 97 - (twoPrefixedBaseNumber % 97);
+    const id = `${baseNum}${checksum}`;
+
+    const result = validate(id);
+    expect(result.isValid && result.compact).toEqual(id);
+  });
+
+  it('validate:(unspecified date 100 years ago)', () => {
+    const yy = new Date().getFullYear() % 100;
+    const baseNum = parseInt(`${yy}0000999`, 10);
+    const checksum = 97 - (baseNum % 97);
+    const id = `${baseNum}${checksum}`;
+
+    const result = validate(id);
+    expect(result.isValid && result.compact).toEqual(id);
+  });
+});

package/src/be/nn.ts

@@ -0,0 +1,77 @@
+/**
+ * NN, NISS, RRN (Belgian national number).
+ *
+ * The national registration number (Rijksregisternummer, Numéro de registre
+ * national, Nationalregisternummer) is a unique identification number of
+ * natural persons who are registered in Belgium.
+ *
+ * The number consists of 11 digits and includes the person's date of birth and
+ * gender. It encodes the date of birth in the first 6 digits in the format
+ * YYMMDD. The following 3 digits represent a counter of people born on the same
+ * date, seperated by sex (odd for male and even for females respectively). The
+ * final 2 digits form a check number based on the 9 preceding digits.
+ *
+ * Source
+ *  https://nl.wikipedia.org/wiki/Rijksregisternummer
+ *  https://fr.wikipedia.org/wiki/Numéro_de_registre_national
+ *  https://www.ibz.rrn.fgov.be/fileadmin/user_upload/nl/rr/instructies/IT-lijst/IT000_Rijksregisternummer.pdf
+ *
+ * PERSON
+ */
+
+import * as exceptions from '../exceptions';
+import { strings } from '../util';
+import { validStructure, validChecksum } from './personIdentifierHelpers';
+import { Validator, ValidateReturn } from '../types';
+
+function clean(input: string): ReturnType<typeof strings.cleanUnicode> {
+  return strings.cleanUnicode(input, ' -.');
+}
+
+const impl: Validator = {
+  name: 'Belgian National Number',
+  localName: 'Numéro National',
+  abbreviation: 'NN, RN',
+  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 = impl.compact(input);
+
+    if (!strings.isdigits(value) || parseInt(value, 10) <= 0) {
+      return { isValid: false, error: new exceptions.InvalidFormat() };
+    }
+
+    if (value.length !== 11) {
+      return { isValid: false, error: new exceptions.InvalidLength() };
+    }
+
+    if (!validStructure(value)) {
+      return { isValid: false, error: new exceptions.InvalidFormat() };
+    }
+
+    if (!validChecksum(value)) {
+      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/be/personIdentifierHelpers.spec.ts

@@ -0,0 +1,254 @@
+import {
+  validStructure,
+  validChecksum,
+  toDateArray,
+} from './personIdentifierHelpers';
+
+describe('personIdentifierHelpers', () => {
+  const toDob = (string: string): string => {
+    const [y, m, d] = toDateArray(string).map(s => parseInt(s, 10));
+    return [y, m - 1, d].map(n => `${n}`.padStart(2, '0')).join('');
+  };
+
+  describe('validStructure', () => {
+    describe('default dob conversion', () => {
+      it('returns true for a valid 20th century date', () => {
+        expect(validStructure('99012599999')).toEqual(true);
+      });
+
+      it('returns true for a potential 21st century date', () => {
+        expect(validStructure('01012599999')).toEqual(true);
+      });
+
+      it('returns true for an unknown date of birth', () => {
+        expect(validStructure('01009999999')).toEqual(true);
+      });
+
+      it('returns false for a string that is neither an unknown date of birth or a valid date of birth', () => {
+        expect(validStructure('99999999999')).toEqual(false);
+      });
+    });
+
+    describe('specified dob conversion', () => {
+      it('returns true for a valid 20th century date', () => {
+        expect(validStructure('991331999999', toDob)).toEqual(true);
+      });
+
+      it('returns true for a potential 21st century date', () => {
+        expect(validStructure('011331999999', toDob)).toEqual(true);
+      });
+
+      it('returns true for an unknown date of birth', () => {
+        expect(validStructure('990199999999', toDob)).toEqual(true);
+      });
+
+      it('returns false for a string that is neither an unknown date of birth or a valid date of birth', () => {
+        expect(validStructure('99999999999', toDob)).toEqual(false);
+      });
+    });
+  });
+
+  describe('validChecksum', () => {
+    const range = Array.from({ length: 100 }, (_, n) => n);
+
+    describe('default dob conversion', () => {
+      describe('a date of birth valid in the 20th century only', () => {
+        const baseString = '990430999';
+        const checksum = 14;
+
+        it('returns true when the checksum is valid', () => {
+          const string = `${baseString}${checksum}`;
+          expect(validChecksum(string)).toEqual(true);
+        });
+
+        it('returns false when the checksum is invalid', () => {
+          const toCheck = range.filter(x => x !== checksum);
+          toCheck.forEach(cs => {
+            const string = `${baseString}${cs}`;
+            expect(validChecksum(string)).toEqual(false);
+          });
+        });
+      });
+
+      describe('a date of birth valid in the 21st century only', () => {
+        const baseString = '000229999'; // 1900 was not a leap year
+        const checksum = 17;
+
+        it('returns true when the checksum is valid', () => {
+          const string = `${baseString}${checksum}`;
+          expect(validChecksum(string)).toEqual(true);
+        });
+
+        it('returns false when the checksum is invalid', () => {
+          const toCheck = range.filter(x => x !== checksum);
+          toCheck.forEach(cs => {
+            const string = `${baseString}${cs}`;
+            expect(validChecksum(string)).toEqual(false);
+          });
+        });
+      });
+
+      describe('a date of birth valid in either the 20th or 21st century', () => {
+        const baseString = '100430999';
+        const twentiethCenturyChecksum = 85;
+        const twentyfirstCenturyChecksum = 17;
+
+        it('returns true when the checksum is valid for the 20th century', () => {
+          const string = `${baseString}${twentiethCenturyChecksum}`;
+          expect(validChecksum(string)).toEqual(true);
+        });
+
+        it('returns true when the checksum is valid for the 21th century', () => {
+          const string = `${baseString}${twentyfirstCenturyChecksum}`;
+          expect(validChecksum(string)).toEqual(true);
+        });
+
+        it('returns false when the checksum is invalid', () => {
+          const excludedChecksums = [
+            twentiethCenturyChecksum,
+            twentyfirstCenturyChecksum,
+          ];
+          const toCheck = range.filter(x => !excludedChecksums.includes(x));
+          toCheck.forEach(cs => {
+            const string = `${baseString}${cs}`;
+            expect(validChecksum(string)).toEqual(false);
+          });
+        });
+      });
+
+      describe('an unknown date of birth', () => {
+        const baseString = '100001999';
+        const twentiethCenturyChecksum = 54;
+        const twentyfirstCenturyChecksum = 83;
+
+        it('returns true when the checksum is valid for the 20th century', () => {
+          const string = `${baseString}${twentiethCenturyChecksum}`;
+          expect(validChecksum(string)).toEqual(true);
+        });
+
+        it('returns true when the checksum is valid for the 21th century', () => {
+          const string = `${baseString}${twentyfirstCenturyChecksum}`;
+          expect(validChecksum(string)).toEqual(true);
+        });
+
+        it('returns false when the checksum is invalid', () => {
+          const excludedChecksums = [
+            twentiethCenturyChecksum,
+            twentyfirstCenturyChecksum,
+          ];
+          const toCheck = range.filter(x => !excludedChecksums.includes(x));
+          toCheck.forEach(cs => {
+            const string = `${baseString}${cs}`;
+            expect(validChecksum(string)).toEqual(false);
+          });
+        });
+      });
+    });
+
+    describe('specified dob conversion', () => {
+      describe('a date of birth valid in the 20th century only', () => {
+        const baseString = '990631999';
+        const checksum = 95;
+
+        it('returns true when the checksum is valid', () => {
+          const string = `${baseString}${checksum}`;
+          expect(validChecksum(string, toDob)).toEqual(true);
+        });
+
+        it('returns false when the checksum is invalid', () => {
+          const toCheck = range.filter(x => x !== checksum);
+          toCheck.forEach(cs => {
+            const string = `${baseString}${cs}`;
+            expect(validChecksum(string, toDob)).toEqual(false);
+          });
+        });
+      });
+
+      describe('a date of birth valid in the 21st century only', () => {
+        const baseString = '000329999'; // 1900 was not a leap year
+        const checksum = 24;
+
+        it('returns true when the checksum is valid', () => {
+          const string = `${baseString}${checksum}`;
+          expect(validChecksum(string, toDob)).toEqual(true);
+        });
+
+        it('returns false when the checksum is invalid', () => {
+          const toCheck = range.filter(x => x !== checksum);
+          toCheck.forEach(cs => {
+            const string = `${baseString}${cs}`;
+            expect(validChecksum(string, toDob)).toEqual(false);
+          });
+        });
+      });
+
+      describe('a date of birth valid in either the 20th or 21st century', () => {
+        const baseString = '100430999';
+        const twentiethCenturyChecksum = 85;
+        const twentyfirstCenturyChecksum = 17;
+
+        it('returns true when the checksum is valid for the 20th century', () => {
+          const string = `${baseString}${twentiethCenturyChecksum}`;
+          expect(validChecksum(string, toDob)).toEqual(true);
+        });
+
+        it('returns true when the checksum is valid for the 21th century', () => {
+          const string = `${baseString}${twentyfirstCenturyChecksum}`;
+          expect(validChecksum(string, toDob)).toEqual(true);
+        });
+
+        it('returns false when the checksum is invalid', () => {
+          const excludedChecksums = [
+            twentiethCenturyChecksum,
+            twentyfirstCenturyChecksum,
+          ];
+          const toCheck = range.filter(x => !excludedChecksums.includes(x));
+          toCheck.forEach(cs => {
+            const string = `${baseString}${cs}`;
+            expect(validChecksum(string, toDob)).toEqual(false);
+          });
+        });
+      });
+
+      describe('an unknown date of birth', () => {
+        const baseString = '100101999';
+        const twentiethCenturyChecksum = 61;
+        const twentyfirstCenturyChecksum = 90;
+
+        it('returns true when the checksum is valid for the 20th century', () => {
+          const string = `${baseString}${twentiethCenturyChecksum}`;
+          expect(validChecksum(string, toDob)).toEqual(true);
+        });
+
+        it('returns true when the checksum is valid for the 21th century', () => {
+          const string = `${baseString}${twentyfirstCenturyChecksum}`;
+          expect(validChecksum(string, toDob)).toEqual(true);
+        });
+
+        it('returns false when the checksum is invalid', () => {
+          const excludedChecksums = [
+            twentiethCenturyChecksum,
+            twentyfirstCenturyChecksum,
+          ];
+          const toCheck = range.filter(x => !excludedChecksums.includes(x));
+          toCheck.forEach(cs => {
+            const string = `${baseString}${cs}`;
+            expect(validChecksum(string, toDob)).toEqual(false);
+          });
+        });
+      });
+    });
+  });
+
+  describe('toDateArray', () => {
+    it('works with a string of length 6', () => {
+      const string = '013150';
+      expect(toDateArray(string)).toEqual(['01', '31', '50']);
+    });
+
+    it('works with a string of length greater than 6', () => {
+      const string = '013150999';
+      expect(toDateArray(string)).toEqual(['01', '31', '50']);
+    });
+  });
+});

package/src/be/personIdentifierHelpers.ts

@@ -0,0 +1,130 @@
+import { strings, isValidDateCompactYYYYMMDD } from '../util';
+
+function getApproximatelyNow() {
+  const ONE_DAY = 1000 * 60 * 60 * 24;
+  return new Date(Date.now() + ONE_DAY);
+}
+
+function isInPast(date: string | number): boolean {
+  return new Date(String(date)) <= getApproximatelyNow();
+}
+
+function getFullYears(yy: string | number): number[] {
+  const yval = typeof yy === 'string' ? parseInt(yy, 10) : yy;
+
+  return [1900 + yval, 2000 + yval];
+}
+
+function getFirstSix(number: string): string {
+  return strings.splitAt(number, 6)[0];
+}
+
+function getBaseNumber(number: string): string {
+  return strings.splitAt(number, 9)[0];
+}
+
+function getChecksum(number: string): number {
+  const checksumString = strings.splitAt(number, 9)[1];
+  return parseInt(checksumString, 10);
+}
+
+export function toDateArray(number: string): string[] {
+  const [yy, mm, dd] = strings.splitAt(number, 2, 4, 6);
+
+  return [yy, mm, dd];
+}
+
+function getValidPastDates(yymmdd: string): Array<string> {
+  const [yy, mm, dd] = toDateArray(yymmdd);
+
+  return getFullYears(yy)
+    .filter(yyyy => isValidDateCompactYYYYMMDD(`${yyyy}${mm}${dd}`))
+    .map(yyyy => `${yyyy}-${mm}-${dd}`)
+    .filter(isInPast);
+}
+
+function isUnknownDob(dob: string): boolean {
+  if (['000001', '002001', '004001'].includes(dob)) {
+    return true;
+  }
+
+  const [yy, mm, dd] = toDateArray(dob);
+
+  return strings.isdigits(yy) && mm === '00' && strings.isdigits(dd);
+}
+
+function toChecksumBasis(year: number, baseNumber: string): number {
+  return parseInt(year < 2000 ? baseNumber : `${2}${baseNumber}`, 10);
+}
+
+function isValidDob(dob: string): boolean {
+  return Boolean(getValidPastDates(dob).length);
+}
+
+function defaultToDob(origFirstSix: string): string {
+  return origFirstSix;
+}
+
+function isValidFirstSix(
+  firstSix: string,
+  toDob: typeof defaultToDob,
+): boolean {
+  const dob = toDob(firstSix);
+  return isUnknownDob(dob) || isValidDob(dob);
+}
+
+export function validStructure(
+  number: string,
+  toDob: typeof defaultToDob = defaultToDob,
+): boolean {
+  const firstSix = getFirstSix(number);
+  return isValidFirstSix(firstSix, toDob);
+}
+
+function getChecksumBasesUnknownDob(baseNumber: string): Array<number> {
+  const firstSix = getFirstSix(baseNumber);
+  const [yy] = toDateArray(firstSix);
+
+  return getFullYears(yy)
+    .filter(isInPast)
+    .map(year => toChecksumBasis(year, baseNumber));
+}
+
+function getChecksumBasesForStandardDob(
+  baseNumber: string,
+  toDob: typeof defaultToDob,
+): Array<number> {
+  const firstSix = getFirstSix(baseNumber);
+  const dob = toDob(firstSix);
+  const validPastDates = getValidPastDates(dob);
+  const extractYearFromDate = (date: string): number =>
+    parseInt(date.split('-')[0], 10);
+  const validPastYears = validPastDates.map(extractYearFromDate);
+  return validPastYears.map(year => toChecksumBasis(year, baseNumber));
+}
+
+function getChecksumBases(
+  number: string,
+  toDob: typeof defaultToDob,
+): Array<number> {
+  const firstSix = getFirstSix(number);
+  const dob = toDob(firstSix);
+  const baseNumber = getBaseNumber(number);
+
+  if (isUnknownDob(dob)) return getChecksumBasesUnknownDob(baseNumber);
+
+  return getChecksumBasesForStandardDob(baseNumber, toDob);
+}
+
+function isValidChecksumPair(checksumBasis: number, checksum: number): boolean {
+  return !((checksumBasis + checksum) % 97);
+}
+
+export function validChecksum(
+  number: string,
+  toDob: typeof defaultToDob = defaultToDob,
+): boolean {
+  const checksumBases = getChecksumBases(number, toDob);
+  const checksum = getChecksum(number);
+  return checksumBases.some(csb => isValidChecksumPair(csb, checksum));
+}

package/src/be/vat.spec.ts

@@ -0,0 +1,46 @@
+import { validate, format } from './vat';
+import { InvalidLength, InvalidChecksum } from '../exceptions';
+
+describe('be/vat', () => {
+  it('format:403019261', () => {
+    const result = format('403019261');
+
+    expect(result).toEqual('0403019261');
+  });
+
+  it('validate:BE403019261', () => {
+    const result = validate('BE403019261');
+
+    expect(result.isValid && result.compact).toEqual('0403019261');
+  });
+
+  it('validate:(0)403019261', () => {
+    const result = validate('(0)403019261');
+
+    expect(result.isValid && result.compact).toEqual('0403019261');
+  });
+
+  it('validate:BE 428759497', () => {
+    const result = validate('BE 428759497');
+
+    expect(result.isValid && result.compact).toEqual('0428759497');
+  });
+
+  it('validate:BE 0417497106', () => {
+    const result = validate('BE 0417497106');
+
+    expect(result.isValid && result.compact).toEqual('0417497106');
+  });
+
+  it('validate:12345678', () => {
+    const result = validate('12345678');
+
+    expect(result.error).toBeInstanceOf(InvalidLength);
+  });
+
+  it('validate:BE431150351', () => {
+    const result = validate('BE431150351');
+
+    expect(result.error).toBeInstanceOf(InvalidChecksum);
+  });
+});