@pedrobslisboa/js-string-mask

@pedrobslisboa/string-mask

A light weight string mask library for JavaScript.

Badges

/npm/v/express

Table of contents

• Installation
• Usage
• Tokens
  • Recursive group
• Api
  • Options
• Examples
  • Phone mask
  • CPF mask
  • Price mask
  • Date mask
  • Credit card mask
• License

Installation

npm install @pedrobslisboa/string-mask

# or

yarn add @pedrobslisboa/string-mask

Usage

import StringMask from '@pedrobslisboa/string-mask';

const phoneMaskedValues = new StringMask({mask: '[phone]');
phoneMaskedValues.apply('11999999999');

console.log(phoneMaskedValues.maskedValue); // [phone]
console.log(phoneMaskedValues.unmaskedValue); // 11999999999

// You can also pass a string with the mask
phoneMaskedValues.apply('[phone]');

console.log(phoneMaskedValues.maskedValue); // [phone]
console.log(phoneMaskedValues.unmaskedValue); // 11999999999

Tokens

Token	Description
0	Int
A	Letter
S	Letter or Int
*	Any char
{	Start escape group
}	End escape group
[	Start recursive group
]	End recursive group
$	Escape next char

Recursive group

Use recursive groups to repeat a group of tokens; use this pattern at the end of the mask. Having a recursive group in the middle of the mask will result in a misbehavior.

Maybe in future versions this will be able to be used in the middle of the mask.

import StringMask from '@pedrobslisboa/string-mask';

const priceMask = new StringMask({ mask: '[.000],00', reverse: true });

// The mask will be applied from right to left
// the recursive group will be applied until the end of the string
// So, the result will be 1.234.567,89.
// Mapped to mask:      [   1][.234][.567],89
//                      [.000][.000][.000],00
priceMask.apply('123456789');

console.log(maskedPrice.maskedValue); // 1.234.567,89

Api

type MaskedValue = {
  maskedValue: string;
  unmaskedValue: string;
};

interface IStringMask {
  // The masked value
  readonly maskedValue: string;
  // The unmasked value
  readonly unmaskedValue: string;

  // The options used to create the mask
  readonly options: Options;

  // Apply the mask to a string
  apply(
    value: string,
    options?: {
      onProcessFixedChar?: () => void;
      onProcessInputChar?: () => void;
    },
  ): MaskedValue;

  // Change the options of the mask
  updateOptions(options: Options): MaskedValue;
}

Constructor

constructor(options?: Options);

Option	Description	Default
mask	The mask to be applied	-
reverse	Apply the mask in reverse order	false

Examples

Phone mask

import StringMask from '@pedrobslisboa/string-mask';

const phoneMaskedValues = new StringMask({ mask: '[phone]' });
phoneMaskedValues.apply('11999999999');

console.log(phoneMaskedValues.maskedValue); // [phone]

CPF mask

import StringMask from '@pedrobslisboa/string-mask';

const cpfMaskedValues = new StringMask({ mask: '000.000.000-00' });
cpfMaskedValues.apply('12345678909');

console.log(cpfMaskedValues.maskedValue); // 123.456.789-09

Price mask

import StringMask from '@pedrobslisboa/string-mask';

const priceMask = new StringMask({ mask: '[.000],00', reverse: true });
priceMask.apply('123456789');

console.log(priceMask.maskedValue); // 1.234.567,89

Date mask

import StringMask from '@pedrobslisboa/string-mask';

const dateMask = new StringMask({ mask: '00/00/0000' });
dateMask.apply('01012021');

console.log(dateMask.maskedValue); // 01/01/2021

Credit card mask

import StringMask from '@pedrobslisboa/string-mask';

const creditCardMask = new StringMask({ mask: '0000 0000 0000 0000' });
creditCardMask.apply('1234567890123456');

console.log(creditCardMask.maskedValue); // 1234 5678 9012 3456

License

MIT License