❤
npm
Sign UpSign In

@utils-fns/mask
TypeScript icon, indicating that this package has built-in type declarations

5.1.0 • Public • Published

@utils-fns/mask

npm License Repository

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:

🖥 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


Caio Queiroz

Linkedin Badge Gmail Badge

License

This API is licensed MIT.

Readme

Keywords

Package Sidebar

Install

npm i @utils-fns/mask

Weekly Downloads

1

Version

5.1.0

License

MIT

Unpacked Size

398 kB

Total Files

287

Last publish

Collaborators

  • caiocezarqueiroz
Try on RunKit
Report malware