Why

Need for a solution that works on different stacks.

Features

• Mask, unmask input texts, apply custom rules.
• Money functions.

Table of Contents

• Getting Started
• TS Mask API
• Customize
• Examples
• License

Getting Started

Install

npm install ts-simple-mask

Quickstart

There are some ready-to-use standard rules:

• '0' = any digit
• 'A' = any alphanumeric
• 'S' = any letter
• 'X' = any letter and transform to uppercase
• 'x' = any letter and transform to lowercase
• 'Z' = any alphanumeric and transform to uppercase
• 'z' = any alphanumeric and transform to lowercase

import createTsMask from "ts-simple-mask";

const TsMask = createTsMask();
const { masked, unmasked } = TsMask.mask("01011987", "00/00/0000");

TS Mask API

• Mask text

mask(value: string, maskRule: string)

import createTsMask from "ts-simple-mask";

const TsMask = createTsMask();
const { masked, unmasked } = TsMask.mask("ABC-1A23", "SSS-0A00");

• Unmask text

unmask(value: string)

import createTsMask from "ts-simple-mask";

const TsMask = createTsMask();
const unmasked = TsMask.unmask("ABC-1A23");

• Mask money

maskMoney(value: string)

import createTsMask from "ts-simple-mask";

const TsMask = createTsMask();
const { masked, unmasked } = TsMask.maskMoney("123456");

• Unmask money

unmaskMoney(value: string)

import createTsMask from "ts-simple-mask";

const TsMask = createTsMask();
const unmasked = TsMask.unmaskMoney("1.234,56");

• Get default masks

getMask(value: string, type: MaskType)

import createTsMask from "ts-simple-mask";

const TsMask = createTsMask();
const value = "46963603006";
TsMask.mask(value, TsMask.getMask(value, MaskType.DOCUMENT_BR));

• Get placeholder

getPlaceholder(maskRule: string)

import createTsMask from "ts-simple-mask";

const TsMask = createTsMask();
const placeholder = TsMask.getPlaceholder("SSS-0A00");

• Interfaces

interface TsMaskOptions {
  rulesMask?: MaskRules;
  rulesMoney?: MaskMoneyRules;
}

interface MaskMoneyRules {
  thousands: string;
  decimal: string;
  precision: number;
  prefix?: string;
  allowNegative?: boolean;
  beforeMask?: (value: number) => number;
  afterMask?: (value: string) => string;
}

interface MaskRules {
  map: Map<string, MaskOptions>;
  beforeMask?: (value: string) => string;
  afterMask?: (value: string) => string;
}

interface MaskOptions {
  pattern: RegExp;
  transform?: (
    prevValue: string,
    newChar: string
  ) => { prevValue: string; newChar: string };
}

Customize

• Default Rules

const DEFAULT_MONEY_RULES = {
  thousands: ".",
  decimal: ",",
  precision: 2,
};

const DEFAULT_MASK_RULES = {
  map: new Map<string, MaskOptions>([
    ["0", { pattern: /\d/ }],
    ["A", { pattern: /[a-zA-Z0-9]/ }],
    ["S", { pattern: /[A-Za-z]/ }],
    [
      "X",
      {
        pattern: /[A-Za-z]/,
        transform: (prevValue, newChar) => ({
          prevValue,
          newChar: newChar.toLocaleUpperCase(),
        }),
      },
    ],
    [
      "x",
      {
        pattern: /[A-Za-z]/,
        transform: (prevValue, newChar) => ({
          prevValue,
          newChar: newChar.toLocaleLowerCase(),
        }),
      },
    ],
    [
      "Z",
      {
        pattern: /[a-zA-Z0-9]/,
        transform: (prevValue, newChar) => ({
          prevValue,
          newChar: newChar.toLocaleUpperCase(),
        }),
      },
    ],
    [
      "z",
      {
        pattern: /[a-zA-Z0-9]/,
        transform: (prevValue, newChar) => ({
          prevValue,
          newChar: newChar.toLocaleLowerCase(),
        }),
      },
    ],
  ]),
};

• Custom Rules

import createTsMask, { MaskOptions } from "ts-simple-mask";

const rulesMoney = {
  thousands: " ",
  decimal: ".",
  precision: 3,
  prefix: "R$",
};

const rulesMask = {
  map: new Map<string, MaskOptions>([
    [
      "#",
      {
        pattern: /[A-Za-z]/,
        transform: (prevValue, newChar) => ({
          prevValue,
          newChar: newChar.toLocaleUpperCase(),
        }),
      },
    ],
    ["9", { pattern: /\d/ }],
  ]),
};

const TsMask = createTsMask({
  rulesMask,
  rulesMoney,
});

const { masked, unmasked } = TsMask.mask("abcd", "####");
//transform uppercase
//return ABCD

const { masked, unmasked } = TsMask.maskMoney("123456789");
//return R$123 456.89

TsMask.setRuleMask(rulesMask);
TsMask.setRuleMoney(rulesMoney);
//change the mask rules

• Before Mask, After Mask

import createTsMask, { MaskOptions } from "ts-simple-mask";

const TsMask = createTsMask({
  rulesMask: {
    map: new Map<string, MaskOptions>([["#", { pattern: /[A-Za-z]/ }]]),
    beforeMask: (value) => (value === "hello" ? "helloworld" : value),
    afterMask: (value) => (value.length > 10 ? value.slice(0, -1) : value),
  },
  rulesMoney: {
    thousands: ".",
    decimal: ",",
    precision: 2,
    beforeMask: (value) => (value === 1000 ? 1001 : value),
    afterMask: (value) => "$" + value,
  },
});

const { masked } = TsMask.mask("hello", "###########");
//return helloworld

const { masked } = TsMask.maskMoney("1000");
//return $1001

Examples

Practical use examples

Vanilla JS

import createTsMask from "ts-simple-mask";

const TsMask = createTsMask();

const value = "31072024";
const { masked } = TsMask.mask(value, "00/00/0000");
document.querySelector(".masked").innerHTML = masked;

React

import React from "react";
import createTsMask from "ts-simple-mask";

const TsMask = createTsMask();

export const TextForm = () => {
  const [value, setValue] = React.useState("");

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const { masked } = TsMask.maskMoney(e.target.value);
    setValue(masked);
  };

  return <input type="text" value={value} onChange={handleChange} />;
};

React Native

import React from "react";
import { TextInput } from "react-native";
import createTsMask, { MaskType } from "ts-simple-mask";

const TsMask = createTsMask();

export const TextForm = () => {
  const [value, setValue] = React.useState("");

  const handleChange = (text: string) => {
    const { masked } = TsMask.mask(
      text,
      TsMask.getMask(text, MaskType.DOCUMENT_BR)
    );
    setValue(masked);
  };

  return <TextInput onChangeText={handleChange} value={value} />;
};

Vue

<script setup>
import createTsMask from "ts-simple-mask";

const TsMask = createTsMask();

const onInput = (event) => {
  const { masked } = TsMask.mask(event.target.value.toUpperCase(), "SSS-0A00");
  event.target.value = masked;
};
</script>

<template>
  <input @input="onInput" />
</template>

Nodejs

import createTsMask, { maskType } from "ts-simple-mask";

const TsMask = createTsMask();

router.get("/", async () => {
  const value = "123456789";
  const { masked } = TsMask.mask(
    value,
    TsMask.getMask(value, MaskType.ZIPCODE_BR)
  );
  return masked;
});

License

MIT