feat: add examples and format patterns to validators (#108)

README.md

@@ -27,6 +27,23 @@ VAT, Person and Tax identifiers.
 
 All country validators are in the "namespace" of the ISO country code.
 
+## Examples and formats
+
+Each validator also lists example numbers and the shape of its formatted
+output, for placeholder text ("e.g. 390.533.447-05") or input masks:
+
+    console.log(stdnum.BR.cpf.examples); // ['39053344705']
+    console.log(stdnum.BR.cpf.formats); // ['nnn.nnn.nnn-nn']
+    console.log(stdnum.BR.cpf.format(stdnum.BR.cpf.examples[0])); // '390.533.447-05'
+
+`examples` are valid numbers in compact form. `formats` describe what
+`format()` returns, in IBAN registry style: `n` is a digit, `a` an upper case
+letter (A-Z), `c` a digit or upper case letter, and any other character is
+literal (so `CHE-nnn.nnn.nnn` starts with the letters `CHE`). A number that
+comes in several shapes, such as different lengths, has one pattern per shape.
+The patterns describe shape only: a number that fits a pattern can still fail
+`validate()`, for example on its check digit.
+
 ## Bundle size: tree-shakeable imports
 
 The `stdnum` object eagerly references every country, so importing it bundles

src/ad/nrt.ts

@@ -26,6 +26,8 @@ const impl: Validator = {
   name: 'Andorra Tax Register Number',
   localName: 'Número de Registre Tributari',
   abbreviation: 'NRT',
+  examples: ['U132950X'],
+  formats: ['a-nnnnnn-a'],
   compact(input: string): string {
     const [value, err] = clean(input);
 
@@ -85,5 +87,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/ad/passport.ts

@@ -24,6 +24,8 @@ const impl: Validator = {
   name: 'Andorran Passport Number',
   localName: 'Passaport andorrà',
   abbreviation: 'Passport',
+  examples: ['O1234567'],
+  formats: ['annnnnnn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -66,5 +68,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/af/passport.ts

@@ -25,6 +25,8 @@ const impl: Validator = {
   name: 'Afghan Passport Number',
   localName: 'د تذکره افغانستان',
   abbreviation: 'PASSPORT',
+  examples: ['P01234567'],
+  formats: ['annnnnnnn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -67,5 +69,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/af/tin.ts

@@ -24,6 +24,8 @@ const impl: Validator = {
   name: 'Afghan Tax Identification Number',
   localName: 'Tax Identification Number',
   abbreviation: 'TIN',
+  examples: ['1234567890'],
+  formats: ['nnnnnnnnnn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -63,5 +65,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/ag/passport.ts

@@ -24,6 +24,8 @@ const impl: Validator = {
   name: 'Antiguan and Barbudan Passport Number',
   localName: 'Antigua and Barbuda passport',
   abbreviation: 'PASSPORT',
+  examples: ['B123456'],
+  formats: ['annnnnn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -66,5 +68,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/ai/passport.ts

@@ -25,6 +25,8 @@ const impl: Validator = {
   name: 'Anguillan Passport Number',
   localName: 'Anguilla Passport',
   abbreviation: 'Passport',
+  examples: ['123456789', 'AB123456'],
+  formats: ['nnnnnnnnn', 'aannnnnn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -67,5 +69,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/ai/tin.ts

@@ -30,6 +30,8 @@ const impl: Validator = {
   name: 'Anguilla Tax Identification Number',
   localName: 'Tax Identification Number',
   abbreviation: 'TIN',
+  examples: ['1234567890'],
+  formats: ['nnnnn-nnnnn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -92,5 +94,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/al/nipt.ts

@@ -37,6 +37,8 @@ const impl: Validator = {
   name: 'Albanian VAT Number',
   localName: 'Numri i Identifikimit për Personin e Tatueshëm',
   abbreviation: 'NIPT',
+  examples: ['J91402501L'],
+  formats: ['annnnnnnna'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -107,5 +109,13 @@ const impl: Validator = {
     };
   },
 };
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/al/passport.ts

@@ -25,6 +25,8 @@ const impl: Validator = {
   name: 'Albanian Passport Number',
   localName: 'Pasaportë shqiptar',
   abbreviation: 'Passport',
+  examples: ['BG1234567'],
+  formats: ['aannnnnnn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -67,5 +69,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/am/passport.ts

@@ -26,6 +26,8 @@ const impl: Validator = {
   name: 'Armenian Passport Number',
   localName: 'Հայաստան անձնագիր',
   abbreviation: 'PASSPORT',
+  examples: ['AN1234567'],
+  formats: ['aannnnnnn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -68,5 +70,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/am/tin.ts

@@ -36,6 +36,8 @@ const impl: Validator = {
   name: 'Armenian Tax Identification Number',
   localName: 'Հարկ վճարողի հաշվառման համար',
   abbreviation: 'ՀՎՀՀ',
+  examples: ['01234565'],
+  formats: ['nnnnnnnn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -86,5 +88,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/ao/bi.ts

@@ -24,6 +24,8 @@ const impl: Validator = {
   name: 'Angola Identity Card',
   localName: 'Bilhete de Identidade',
   abbreviation: 'BI',
+  examples: ['000204688CA010'],
+  formats: ['nnnnnnnnnaannn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -63,5 +65,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/ao/nif.ts

@@ -19,6 +19,8 @@ const impl: Validator = {
   name: 'Angola Tax Identification Number',
   localName: 'Número de Identificação Fiscal',
   abbreviation: 'NIF',
+  examples: ['0000000001', '003534962LA033'],
+  formats: ['nnnnnnnnnn', 'nnnnnnnnnaannn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -68,5 +70,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/ao/passport.ts

@@ -27,6 +27,8 @@ const impl: Validator = {
   name: 'Angolan Passport Number',
   localName: 'Passaporte angolano',
   abbreviation: 'Passport',
+  examples: ['N1234567', 'NA1234567'],
+  formats: ['annnnnnn', 'aannnnnnn'],
 
   compact(input: string): string {
     const [value, err] = clean(input);
@@ -69,5 +71,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;

src/ar/cbu.ts

@@ -25,6 +25,8 @@ const impl: Validator = {
   name: 'Single Banking Code',
   localName: 'Clave Bancaria Uniforme',
   abbreviation: 'CBU',
+  examples: ['2850590940090418135201'],
+  formats: ['nnnnnnnn nnnnnnnnnnnnnn'],
   compact(input: string): string {
     const [value, err] = clean(input);
 
@@ -94,5 +96,13 @@ const impl: Validator = {
   },
 };
 
-export const { name, localName, abbreviation, validate, format, compact } =
-  impl;
+export const {
+  name,
+  localName,
+  abbreviation,
+  examples,
+  formats,
+  validate,
+  format,
+  compact,
+} = impl;