Options
All
  • Public
  • Public/Protected
  • All
Menu

Namespace utils

Provides functionality to create custom formatters.

// esm
import { formatters } from '@paychex/core';
formatters.utils.withReplacement(...);

// cjs
const { formatters } = require('@paychex/core');
formatters.utils.withReplacement(...);

// iife
const { formatters } = window['@paychex/core'];
formatters.utils.withReplacement(...);

// amd
require(['@paychex/core'], function({ formatters }) { ... });
define(['@paychex/core'], function({ formatters }) { ... });
example
const { toDigits } = formatters.create({ locale: 'en-US' });
const toSSN = formatters.utils.withReplacement(toDigits, /^\d{5}(\d{4})$/, 'XXX-XX-$1');
console.log(toSSN('123.45.6789')); // 'XXX-XX-6789'
example
const phoneMask = formatters.utils.MASKS.AlphaNumeric('(###) ###-####');
const asPhoneNumber = formatters.utils.withMask(String, phoneMask);
console.log(asPhoneNumber(1234567890)); // '(123) 456-7890'

Index

Interfaces

Type aliases

Variables

Functions

Type aliases

MaskPredicate

MaskPredicate: (pattern: string) => boolean

Type declaration

    • (pattern: string): boolean

    • Parameters

      • pattern: string

      Returns boolean

StringReplacer

StringReplacer: (substring: string, ...args: any[]) => string

Type declaration

    • (substring: string, ...args: any[]): string

    • Parameters

      • substring: string
      • Rest ...args: any[]

      Returns string

TokenArray

TokenArray: [string, MaskPredicate]

Variables

MASKS

MASKS: MaskCollection = ...

Contains useful predefined mask factories you can use to create your own simple formatters.

readonly

Functions

tokens

  • Constructs a new MaskFactory for use with withMask.

    throws

    Must pass array of arrays to tokens method.

    example
    const factory = formatters.utils.tokens([
      ['*', (v) => /./.test(v)], // have * match anything
      ['0', (v) => /\d/.test(v)], // have 0 match any digit
      ['.', (v) => /[a-z]/i.test(v)], // have period match any letter
    ]);
    const mask = factory('#000-**-....');
    const format = formatters.utils.withMask(String, mask);
    console.log(format('1234abcdefg')); // '#123-4a-bcde'

    Parameters

    • array: TokenArray[]

      Each element should be an array of 2 items: the token string, and the predicate to run with the input character to see if it matches the token type.

    Returns MaskFactory

    A MaskFactory that can be invoked with a pattern to return a Mask instance.

withMask

  • Creates a Formatter that will apply the specified mask logic to the returned string.

    example
    const phoneMask = formatters.utils.MASKS.AlphaNumeric('(###) ###-####');
    const asPhoneNumber = formatters.utils.withMask(String, phoneMask);
    console.log(asPhoneNumber(1234567890)); // '(123) 456-7890'
    example
    const factory = formatters.utils.tokens([
        ['0', (v) => /\d/.test(v)], // use 0 to represent a single number
    ]);
    const mask = factory('00-000');
    const toPartCode = formatters.utils.withMask(String, mask);
    console.log(toPartCode('90.7.00')); // '90-700'
    example
    // you can use \\ to identify a string literal. these will not
    // be treated as mask tokens but instead be returned in the output
    // string as-is
    const extension = formatters.utils.MASKS.AlphaNumeric('\\x####');
    const toExtension = formatters.utils.withMask(String, extension);
    console.log(toExtension(1234)); // 'x1234'

    Parameters

    • formatter: Formatter

      The formatter to wrap.

    • mask: Mask

      The Mask instance to use. A Mask factory can be constructed using tokens, or you can use an existing Mask factory available on the MASKS property.

    Returns Formatter

    A Formatter instance which will apply the specified mask.

withReplacement

  • Replaces the output of the inner formatter according to the given rules.

    You can use a regular expression or string as your search criteria, and you can use a string or function to perform the replacement. See the MDN docs for details.

    example
    const { toDigits } = formatters.create({ locale: 'en-US' });
    const toSSN = formatters.utils.withReplacement(toDigits, /^\d{5}(\d{4})$/, 'XXX-XX-$1');
    console.log(toSSN('123.45.6789')); // 'XXX-XX-6789'
    example
    const maskChars = formatters.utils.withReplacement(String, /[a-z]/, '*');
    console.log(maskChars('abc123xyz')); // '***123***'
    example
    const onlyNumbers = formatters.utils.withReplacement(String, /[^\d]/g, () => '');
    console.log(onlyNumbers('abc123xyz')); // '123'

    Parameters

    • formatter: Formatter

      The format function whose output should be replaced.

    • pattern: string | RegExp

      The string or regular expression to match against the output.

    • replacer: string | StringReplacer

      The replacement logic. Either a string or function.

    Returns Formatter

    A format function that will perform the requested replacement.