This package has been deprecated

Author message:

Package no longer supported

maskose

A composable way to make masks.

---

Table of contents

• Installation
• API
  • Functions
    • mkCreate
    • mkMaskValue
    • mkUnmaskValue
    • mkMatch
    • mkRemoveToBePutChars
    • mkBoostChar
    • mkBoostMask
  • Mask characters
    • mkCharNum
    • mkCharLetter
    • mkCharToBePut
    • mkCharGroup
  • Boosts
    • mkMaskBoostEndless
    • mkMaskBoostRightToLeft
    • mkCharBoostRepeat
    • mkCharBoostValueLengthEqualTo
    • mkCharBoostValueLengthGreaterThan
    • mkCharBoostValueLengthLessThan
• Examples
  • US currency mask
  • BR cellphone number mask

Installation

yarn add maskose

or with npm:

npm install maskose

API

Functions

mkCreate

mkCreate(chars: MaskoseMaskChar[]): MaskoseMask

Creates a left-to-right non-endless mask with the provided characters.

mkMaskValue

mkMaskValue(mask: MaskoseMask): (value: string) => string

Note: this is an unary function that returns another unary function.

Masks the provided value using the provided mask. If a character in the provided value doesn't match its correspondent mask character, the masking stops and the portion of the value masked until this point is returned.

mkUnmaskValue

mkUnmaskValue(mask: MaskoseMask): (value: string) => string

Note: this is an unary function that returns another unary function.

Unmasks the provided value using the provided mask. If a character in the provided value doesn't match its correspondent mask character, the unmasking stops and the portion of the value unmasked until this point is returned.

mkMatch

mkMatch(mask: MaskoseMask): (value: string) => string

Note: this is an unary function that returns another unary function.

Checks whether the provided value matches the provided mask. To be a successful check, the provided value has to be already masked.

mkRemoveToBePutChars

mkRemoveToBePutChars(value: string)

Removes all characters that are considered to-be-put characters from the provided value.

Note: The difference between mkRemoveToBePutChars and mkUnmaskValue is that both of them remove to-be-put characters, but only the later also checks if those characters are in the places specified when creating the provided mask. In other words, mkUnmaskValue is a reversed version of mkMaskValue, while mkRemoveToBePutChars just removes every character that is considered a to-be-put, regardless of whether they're in the 'right places'.

mkBoostChar

mkBoostChar(char: MaskoseMaskChar):
  (charBoosts: MaskoseBoost<MaskoseMaskChar>[]) => MaskoseMaskChar

Note: this is an unary function that returns another unary function.

Adds a list of boosts to a mask character.

mkBoostMask

mkBoostMask(mask: MaskoseMask):
  (charBoosts: MaskoseBoost<MaskoseMask>[]) => MaskoseMask

Note: this is an unary function that returns another unary function.

Adds a list of boosts to a mask.

Mask characters

type MaskoseMaskChar =
  | MaskoseMaskCharNum
  | MaskoseMaskCharLetter
  | MaskoseMaskCharToBePut
  | MaskoseMaskCharGroup

mkCharNum

mkCharNum(): MaskoseMaskCharNum

Represents a character in the range 0 to 9.

mkCharLetter

mkCharLetter(
  options?: {
    caseSensitive?: boolean
  }
): MaskoseMaskCharLetter

Represents a character in the range A to Z. If options.caseSensitive is not specified, it default to false.

mkCharToBePut

mkCharToBePut(
  char: '(' | ')' | '[' | ']' | '-' | '/' | '\\' | ',' | '.' | ' '
): MaskoseMaskCharToBePut

Represents a character that's not expected to be in the value that will be masked, but expected to be in the value that will be unmasked. This is the type of character that will be put in the value when masking. A good example of a character like this is the dash (-) in a phone number mask.

mkCharGroup

mkCharGroup(chars: MaskoseMaskChar[]): MaskoseMaskCharGroup

Represents a group of characters. It's mostly used to boost more than one character at once.

Boosts

type MaskoseBoost<T extends (
  | MaskoseMaskChar
  | MaskoseMask
)> = (val: T) => T;

Note: despite the fact that MaskoseBoost seems like the type signature of the identity function, it represents the fact that a boost is a function that will always return an object of the same type of the received one. What a boost does is creating a shallow copy of the provided object, altering one or more of the copy's props and returning the copy.

mkMaskBoostEndless

mkMaskBoostEndless(): MaskoseBoost<MaskoseMask>

Note: this is a nullary function that returns an unary function.

Makes the provided mask an endless mask. An endless mask is a mask that will match any character that comes after its chars list's tail only if this character matches its chars list's tail. See the examples section below to see when this might be useful.

mkMaskBoostRightToLeft

mkMaskBoostRightToLeft(): MaskoseBoost<MaskoseMask>

Note: this is a nullary function that returns an unary function.

Makes the provided mask a mask whose characters will be read from right to left. Besides changing the order in which the provided mask's characters are read, it also changes the order in which the characters of the masked or unmasked value are read. This boost is mostly used when dealing with number-formating masks, e.g. a currency mask. See the examples section below to see when this might be useful.

mkCharBoostRepeat

mkCharBoostRepeat(
  num: number
): MaskoseBoost<MaskoseMaskChar>

Note: this is an unary function that returns another unary function.

Makes the provided mask character be repeated num times. See the examples section below to see when this might be useful.

mkCharBoostValueLengthEqualTo

mkCharBoostValueLengthEqualTo(
  values: {
    masked: number;
    unmasked: number;
  }
): MaskoseBoost<MaskoseMaskChar>

Note: this is an unary function that returns another unary function.

Makes the provided mask character only present in a mask if the value to be masked is equal to values.unmasked or the value to be unmasked is equal to value.masked. Which one of these checks will be made depends on the type of value that a function expects. For example, mkMaskValue will check the values.unmasked value, while mkUnmaskValue will check the values.masked value.

mkCharBoostValueLengthGreaterThan

mkCharBoostValueLengthGreaterThan(
  values: {
    masked: number;
    unmasked: number;
  }
): MaskoseBoost<MaskoseMaskChar>

Note: this is an unary function that returns another unary function.

Makes the provided mask character only present in a mask if the value to be masked is greater than values.unmasked or the value to be unmasked is greater than value.masked. Which one of these checks will be made depends on the type of value that a function expects. For example, mkMaskValue will check the values.unmasked value, while mkUnmaskValue will check the values.masked value.

mkCharBoostValueLengthLessThan

mkCharBoostValueLengthLessThan(
  values: {
    masked: number;
    unmasked: number;
  }
): MaskoseBoost<MaskoseMaskChar>

Note: this is an unary function that returns another unary function.

Makes the provided mask character only present in a mask if the value to be masked is less than values.unmasked or the value to be unmasked is less than value.masked. Which one of these checks will be made depends on the type of value that a function expects. For example, mkMaskValue will check the values.unmasked value, while mkUnmaskValue will check the values.masked value.

Examples

US currency mask

const mask = mkCreate([
  mkCharGroup([
    mkCharBoostRepeat(3)(mkCharNum()),
    mkCharToBePut(',')
  ]),
  mkCharBoostRepeat(3)(mkCharNum()),
  mkCharToBePut('.'),
  mkCharBoostRepeat(2)(mkCharNum())
]);

const maskBoosted = mkBoostMask(mask)([
  mkMaskBoostEndless(),
  mkMaskBoostRightToLeft()
]);

const mkMaskValueWithMask = mkMaskValue(maskBoosted);
const mkUnmaskValueWithMask = mkUnmaskValue(maskBoosted);
const mkMatchWithMask = mkMatch(maskBoosted);

// Masking
console.log(mkMaskValueWithMask('12345'));
'123.45'

console.log(mkMaskValueWithMask('123456789'));
'1,234,567.89'

console.log(mkMaskValueWithMask('ABCDE56789'));
'567.89'

// Unmasking
console.log(mkUnmaskValueWithMask('5,678.30'));
'567830'

console.log(mkUnmaskValueWithMask('ABCDEFG'));
''

console.log(mkUnmaskValueWithMask('1.230,500.10'));
'23050010'

// Matching
console.log(mkMatchWithMask('5,678.30'));
true

console.log(mkMatchWithMask('980.351,9345.10'));
false

console.log(mkMatchWithMask('1,900,800,300.50'));
true

BR cellphone number mask

const mask = mkCreate([
  mkCharToBePut('('),
  mkCharBoostRepeat(2)(mkCharNum()),
  mkCharToBePut(')'),
  mkCharToBePut(' '),
  mkCharBoostValueLengthGreaterThan({
    masked: 14,
    unmasked: 10
  })(mkCharNum()),
  mkCharBoostRepeat(4)(mkCharNum()),
  mkCharToBePut('-'),
  mkCharBoostRepeat(4)(mkCharNum())
]);

const mkMaskValueWithMask = mkMaskValue(mask);
const mkUnmaskValueWithMask = mkUnmaskValue(mask);
const mkMatchWithMask = mkMatch(mask);

// Masking
console.log(mkMaskValueWithMask('9912345678'));
'(99) 1234-5678'

console.log(mkMaskValueWithMask('99123456789'));
'(99) 12345-6789'

console.log(mkMaskValueWithMask('991234'));
'(99) 1234'

// Unmasking
console.log(mkUnmaskValueWithMask('(11) 9876-5432'));
'1198765432'

console.log(mkUnmaskValueWithMask('(11) 98765-4321'));
'11987654321'

console.log(mkUnmaskValueWithMask('(1B) 98765-4321'));
'1'

// Matching
console.log(mkMatchWithMask('(11) 9876-5432'));
true

console.log(mkMatchWithMask('(11) 98765-4321'));
true

console.log(mkMatchWithMask('(1B) 98765-4321'));
false