maskose v0.0.5
Table of contents
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
andmkUnmaskValue
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 ofmkMaskValue
, whilemkRemoveToBePutChars
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