@utils-fns/mask

@utils-fns/mask

README versions

Portuguese | English

The @utils-fns/mask library was intended to be part of a larger library, @utils-fns, which is being developed with the aim of providing unified tools to ease programmers' daily tasks. Our motivation is to simplify common tasks such as validators, masking values, sorting, searching and conversion methods, offering a comprehensive and efficient solution that makes it possible for use of this set of libraries in web - mobile - service environments.

Features

Masks: The @utils-fns/mask library provides the following masks:

• cpf
• nis
• cnpj
• date
• paymentSlip
• phone
• renavam
• cnh
• voterRegister
• cep
• generic masks
• numbers

Supported Environments

• Applications with javascript ES6 or higher
  • Modern browsers
  • Server-side
  • Electron
  • Mobile

Install

If you want to install the complete module, follow the documents in the @utils-fns/utils-fns.

To install the @utils-fns/mask library: use your preferred package manager

  yarn add @utils-fns/mask

  or

  npm install @utils-fns/mask

How to use

To access the features, just follow the example:

  //ES6
  import { mask } from "@utils-fns/mask";

  //CommomJS
  const { mask } = require("@utils-fns/mask");

So, just choose which validation tool will be used.

  const cpfMask = mask.cpf({ value: '75178780000' })
  /*
    return {
      unmask: '75178780000',
      value: '751.787.800-00',
    }
  */

Typescript

@utils-fns/validators is written in TypeScript with complete definitions.

Important type:

• EventHandleAdapter: <T = Event> = T | ChangeEvent<HTMLInputElement>

Generic Mask Patterns or Custom Patterns

For Generic masks or custom patterns, you must use the following characters to represent the pattern:

• A: Accepts uppercase and lowercase letters;
• a: Preventive. Accepts only lowercase letters;
• b: The system will convert the letter to lowercase;
• U: Impeditive. Accepts only capital letters;
• W: The system will convert the letter to uppercase;
• 9: Preventive. It only accepts numbers.

Examples

Mask	Entrance	Return
99999-999	61601640	61601-640
Waa-Aaa	foobar	Foo-bar
Waa-Aaa	fooBar	Foo-Bar
Waa-baa	fooBar	Foo-bar
Waa-aaa	fooBar	Foo-
baa-aaa	FooBar	foo-

Cpf Mask

Method	Params	Type
cpf	value	string | number | undefined
cpf	previousValue	string | number | undefined
cpf	allowEmpty	boolean | undefined
cpf	event	EventHandleAdapter | undefined

  import { mask } from "@utils-fns/mask";

  mask.cpf({ value: '75178780000' })
  /*
    return {
      unmask: '75178780000',
      value: '751.787.800-00',
    }
  */

  mask.cpf({ value: '' })
  /*
    return {
      unmask: '',
      value: '',
    }
  */

Nis Mask

Method	Params	Type
nis	value	string | number | undefined
nis	previousValue	string | number | undefined
nis	allowEmpty	boolean | undefined
nis	event	EventHandleAdapter | undefined

  import { mask } from "@utils-fns/mask";

  mask.nis({ value: '95726254769' })
  /*
    return {
      unmask: '95726254769',
      value: '957.26254.76-9',
    }
  */

  mask.nis({ value: '' })
  /*
    return {
      unmask: '',
      value: '',
    }
  */

Cnpj Mask

Method	Params	Type
cnpj	value	string | number | undefined
cnpj	previousValue	string | number | undefined
cnpj	allowEmpty	boolean | undefined
cnpj	event	EventHandleAdapter | undefined

  import { mask } from "@utils-fns/mask";

  mask.cnpj({ value: '46824095000169' })
  /*
    return {
      unmask: '46824095000169',
      value: '46.824.095/0001-69',
    }
  */

  mask.cnpj({ value: '' })
  /*
    return {
      unmask: '',
      value: '',
    }
  */

Date Mask

Method	Params	Type
date	value	string | number | undefined
date	previousValue	string | number | undefined
date	allowEmpty	boolean | undefined
date	event	EventHandleAdapter | undefined
date	patternDate.mask	DD/MM/YYYY | DD-MM-YYYY | DD/Mmm/YYYY | DD-Mmm-YYYY | DD/MMM/YYYY | DD-MMM-YYYY | MM-DD-YYYY | MM/DD/YYYY | MMM-DD-YYYY | MMM/DD/YYYY | Mmm/DD/YYYY | Mmm-DD-YYYY | YYYY/MM/DD | YYYY-MM-DD | YYYY/Mmm/DD | YYYY-Mmm-DD | YYYY/MMM/DD |YYYY-MMM-DD
date	patternDate.unmask	DD/MM/YYYY | DD-MM-YYYY | DD/Mmm/YYYY | DD-Mmm-YYYY | DD/MMM/YYYY | DD-MMM-YYYY | MM-DD-YYYY | MM/DD/YYYY | MMM-DD-YYYY | MMM/DD/YYYY | Mmm/DD/YYYY | Mmm-DD-YYYY | YYYY/MM/DD | YYYY-MM-DD | YYYY/Mmm/DD | YYYY-Mmm-DD | YYYY/MMM/DD |YYYY-MMM-DD

Observation:

Value	Representation	Example
DD	day - numeric	30
MM	month - numeric	01
MMM	month - Abbreviation	JAN
Mmm	month - Abbreviation	Jan
YYYY	year - numeric	2023

  import { mask } from "@utils-fns/mask";

  mask.date({
    value: '02091991',
    patternDate: {
      mask: 'DD/MM/YYYY',
      unmask: 'YYYY-MM-DD',
    },
  })
  /*
    return {
      unmask: '1991-09-02',
      value: '02/09/1991',
    }
  */

  mask.date({
    value: '02/Set/1991',
    patternDate: {
      mask: 'DD/Mmm/YYYY',
      unmask: 'YYYY/Mmm/DD',
    },
  })
  /*
    return {
      unmask: '1991/Set/02',
      value: '02/Set/1991',
    }
  */

 mask.date({
    value: 'SET021991',
    patternDate: {
      mask: 'MMM/DD/YYYY',
      unmask: 'YYYY/Mmm/DD',
    },
  })
  /*
    return {
      unmask: '1991/Set/02',
      value: 'SET/02/1991',
    }
  */

PaymentSlip Mask

Method	Params	Type
paymentSlip	value	string | number | undefined
paymentSlip	previousValue	string | number | undefined
paymentSlip	allowEmpty	boolean | undefined
paymentSlip	event	EventHandleAdapter | undefined
paymentSlip	onlyType.typeDigits	Cód. Barras | Linha Digitável
paymentSlip	onlyType.typePaymentSlip	Boleto Bancário | Boleto de Arrecadação

Observation:

• The onlyType parameter is optional, however if it is included as a method argument, typePaymentSlip must be passed.

  import { mask } from "@utils-fns/mask";

  mask.paymentSlip({
    value: '846100000005319901090112004961794445808053219016' })
  /*
    return {
      unmask: '846100000005319901090112004961794445808053219016',
      value: '84610000000-5 31990109011-2 00496179444-5 80805321901-6',
    }
  */

  mask.paymentSlip({
    value: '65590000020044250000594059050008194290000006050' })
  /*
    return {
      unmask: '65590000020044250000594059050008194290000006050',
      value: '65590.00002 00442.500005 94059.050008 1 94290000006050',
    }
  */

  mask.paymentSlip({ value: '84610000000319901090110049617944480805321901' })
  /*
    return {
      unmask: '84610000000319901090110049617944480805321901',
      value: '84610000000319901090110049617944480805321901',
    }
  */

  mask.paymentSlip({
    value: '846100000005319901090112004961794445808053219016',
    onlyType: {
      typePaymentSlip: 'Boleto de Arrecadação',
    },
  })
  /*
    return {
      unmask: '846100000005319901090112004961794445808053219016',
      value: '84610000000-5 31990109011-2 00496179444-5 80805321901-6',
    }
  */

Phone Mask

Method	Params	Type
phone	value	string | number | undefined
phone	previousValue	string | number | undefined
phone	allowEmpty	boolean | undefined
phone	event	EventHandleAdapter | undefined
phone	customPattern	string | undefined
phone	internationalNumber	boolean | undefined

Observation:

• The return of the following masks are configured by default for this method depending on the size of the value parameter:
  • public service telephones: 3 to 4 characters
    • 999 or 999-9.
  • standard phones: More than 4 characters
    • (99) 9999-9999 or (99) 99999-9999.
  • Passing the internationalNumber parameter, the default mask is:
    • +99 99 9999-9999 or +99 99 99999-9999.
• For masks with other formats, just pass the telephone format as an argument of the customPattern parameter, according to the section Generic mask patterns or custom patterns.

  import { mask } from "@utils-fns/mask";

  mask.phone({ value: '911' })
  /*
    return {
      unmask: '911',
      value: '911',
    }
  */

  mask.phone({ value: '9114' })
  /*
    return {
      unmask: '9114',
      value: '911-4',
    }
  */

  mask.phone({ value: '8599999999' })
  /*
    return {
      unmask: '8599999999',
      value: '(85) 9999-9999',
    }
  */

  mask.phone({ value: '85999999999' })
  /*
    return {
      unmask: '85999999999',
      value: '(85) 99999-9999',
    }
  */

   mask.phone({
    value: '558599999999',
    internationalNumber: true,
  })
  /*
    return {
      unmask: '558599999999',
      value: '+55 85 9999-9999',
    }
  */

  mask.phone({
    value: '393461234567',
    customPattern: '+99 (999) 999-9999',
  })
  /*
    return {
      unmask: '393461234567',
      value: '+39 (346) 123-4567',
    }
  */

Renavam Mask

Method	Params	Type
renavam	value	string | number | undefined
renavam	previousValue	string | number | undefined
renavam	allowEmpty	boolean | undefined
renavam	event	EventHandleAdapter | undefined

  import { mask } from "@utils-fns/mask";

  mask.renavam({ value: '97553114045' })
  /*
    return {
      unmask: '97553114045',
      value: '97553114045',
    }
  */

  mask.renavam({ value: '97553114045999999999999' })
  /*
    return {
      unmask: '97553114045',
      value: '97553114045',
    }
  */

Cnh Mask

Method	Params	Type
cnh	value	string | number | undefined
cnh	previousValue	string | number | undefined
cnh	allowEmpty	boolean | undefined
cnh	event	EventHandleAdapter | undefined

  import { mask } from "@utils-fns/mask";

  mask.cnh({ value: '37079809228' })
  /*
    return {
      unmask: '37079809228',
      value: '370798092-28',
    }
  */

  mask.cnh({ value: '3707980922837079809228' })
  /*
    return {
      unmask: '37079809228',
      value: '370798092-28',
    }
  */

Voter Register Mask

Method	Params	Type
voteRegister	value	string | number | undefined
voteRegister	previousValue	string | number | undefined
voteRegister	allowEmpty	boolean | undefined
voteRegister	event	EventHandleAdapter | undefined

  import { mask } from "@utils-fns/mask";

  mask.voteRegister({ value: '277258770140' })
  /*
    return {
      unmask: '277258770140',
      value: '2772.5877.0140',
    }
  */

  mask.voteRegister({ value: '4253.0481.0175' })
  /*
    return {
      unmask: '425304810175',
      value: '4253.0481.0175',
    }
  */

Cep Mask

Method	Params	Type
cep	value	string | number | undefined
cep	previousValue	string | number | undefined
cep	allowEmpty	boolean | undefined
cep	event	EventHandleAdapter | undefined

  import { mask } from "@utils-fns/mask";

  mask.cep({ value: '89015133' })
  /*
    return {
      unmask: '89015133',
      value: '89015-133',
    }
  */

  mask.cep({ value: '89015-133' })
  /*
    return {
      unmask: '89015133',
      value: '89015-133',
    }
  */

Generic Mask

Method	Params	Type
generic	pattern	string
generic	value	string | number | undefined
generic	previousValue	string | number | undefined
generic	allowEmpty	boolean | undefined
generic	event	EventHandleAdapter | undefined

Observation:

• The pattern parameter must be filled in as explained in the section Generic mask patterns or custom patterns.

  import { mask } from "@utils-fns/mask";

  mask.generic({
    value: '89015133',
    pattern: '99999-999'
  })
  /*
    return {
      unmask: '89015133',
      value: '89015-133',
    }
  */

  mask.generic({
    value: '999999999',
    pattern: '(85) 9 9999-9999'
  })
  /*
    return {
      unmask: '999999999',
      value: '(85) 9 9999-9999',
    }
  */

Numbers Mask

Method	Params	Type
maskNumber	value	string | number | null
maskNumber	previousValue	string | number | null | undefined
maskNumber	prefix	string | undefined
maskNumber	suffix	string | undefined
maskNumber	decimalPlaces	number | undefined
maskNumber	allowNegative	boolean | undefined
maskNumber	numberWithoutPonctuation	boolean | undefined
maskNumber	locale	af | ar-DZ | ar-EG | ar-MA | ar-SA | ar-TN | ar | az | be-tarask | be | bg | bn | bs | ca | cs | cy | da | de-AT | de | el | en-AU | en-CA | en-GB | en-IE | en-IN | en-NZ | en-US | en-ZA | eo | es | et | eu | fa-IR | fi | fr-CA | fr-CH | fr | fy | gd | gl | gu | he | hi | hr | ht | hu | hy | id | is | it-CH | it | ja-Hira | ja | ka | kk | km | kn | ko | lb | lt | lv | mk | mn | ms | mt | nb | nl-BE | nl | nn | oc | pl | pt-BR | pt | ro | ru | sk | sl | sq | sr-Latn | sr | sv | ta | te | th | tr | ug | uk | uz-Cyrl | uz | vi | zh-CN | zh-HK | zh-TW | undefined
maskNumber	event	EventHandleAdapter | undefined

Observation:

• The following parameters are configured by default:
  • prefix: '';
  • suffix: '';
  • decimalPlaces: 0;
  • allowNegative: false;
  • locale: 'pt-BR';
• The limit number of decimal places must be equal to 10.

  import { mask } from "@utils-fns/mask";

  mask.maskNumber({ value: 123.98 })
  /*
    return {
      unmask: '12398',
      value: '12.398'
    }
  */

   mask.maskNumber({ value: '123.98' })
  /*
    return {
      unmask: '12398',
      value: '12.398'
    }
  */

  mask.maskNumber({
    value: '-123.98',
    allowNegative: true,
  })
  /*
    return {
      unmask: '-12398',
      value: '-12.398'
    }
  */

  mask.maskNumber({
    value: 123.98,
    decimalPlaces: 10,
  })
  /*
    return {
      unmask: '0.0000012398',
      value: '0,0000012398',
    }
  */

  mask.maskNumber({
    value: 1323.98,
    decimalPlaces: 2,
    locale: 'en-US',
  })
  /*
    return {
      unmask: '1323.98',
      value: '1,323.98',
    }
  */

   mask.maskNumber({
    value: 1323.98,
    decimalPlaces: 2,
    locale: 'pt-BR',
    prefix: 'R$ ',
    suffix: ' Reais',
  })
  /*
    return {
      unmask: '1323.98',
      value: 'R$ 1.323,98 Reais',
    }
  */

  mask.maskNumber({
    value: -1323.98,
    decimalPlaces: 2,
    locale: 'pt-BR',
    prefix: 'R$ ',
    suffix: ' Reais',
    allowNegative: true,
  })
  /*
    return {
      unmask: '-1323.98',
      value: 'R$ -1.323,98 Reais',
    }
  */

Author

License

This API is licensed MIT.