fmt-tag
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    fmt-tag

    version issues downloads license

    Format template literals.

    Installation

    This package is distributed via npm:

    npm install fmt-tag
    

    Motivation

    Template literals and template tags provide a unique API to build tools around strings. What started as a fun blog post about template tags ended up being this full-fledged library that might hopefully be useful to someone!

    Usage

    You can use this library either as an ES module or a CommonJS package:

    import fmt from "fmt-tag";

    - or -

    const fmt = require("fmt-tag");

    Please note that this library uses extensively Intl, which is not supported on older browsers (https://caniuse.com/?search=Intl) or Node versions < 16.

    You can tag any template literal and append formatting hints right after interpolations to apply specific formatting to that substitutive value.

    const name = "Alice";
    const money = 20;
    
    console.log(fmt`${name} has ${money}:c(USD) in her pocket!`);
    // "Alice has $20 in her pocket!"

    Hints can also be dynamic, for example displaying a specific currency based on a country variable, as follows:

    const name = "Alice";
    const money = 20;
    const country = "UK";
    
    console.log(fmt`${name} has ${money}:c(${country === "UK" ? "GBP" : "USD"}) in her pocket!`);
    // "Alice has £20 in her pocket!"

    The formatting uses the host's default language settings. You can also pass in a specific locale via fmt.use(locale).

    fmt.use(locale: string)

    Sets a locale to be used when formatting template literals. By default, the formatting will use the host's default language settings.

    Formatters

    There are a few formatters available (more to come!).

    Currency

    Key Options
    :c Any valid currency symbol (e.g. :c(USD), :c(EUR), ...)

    Date

    Key Options
    :d - :d(DD-MM-YYYY) => 01/01/1970
    - :d(DD-mm-YYYY) => 1 Jan 1970
    - :d(DD-mmm-YYYY) => 1 January 1970
    - :d(ddd-mmm-YYYY) => Thursday, 1 January 1970

    Number

    Key Options
    :n Number of digits (e.g. :n(2) => 42.00)

    Relative Time

    Key Options
    :r RelativeTimeUnit (e.g. ${-1}:r(weeks) => last week)

    String

    Key Options
    :s
    (default)
    - :s => No transformation
    - :s(U) => Uppercase
    - :s(l) => lowercase

    Time

    Key Options
    :t - :t(HH:mm) => 06:56
    - :t(HH:mm aa) => 06:56 am
    - :t(HH:mm:ss) => 06:56:07
    - :t(HH:mm:ss aa) => 06:56:07 am
    - :t(HH:mm:ss TZ) => 06:56:07 UTC
    - :t(HH:mm:ss TZ+) => 06:56:07 Coordinated Universal Time

    Custom formatters

    Custom formatters can be registerd using fmt.register(tag, fn). This allows for user-created formatters that can then be used as the pre-existing formatters.

    To avoid any potential conflicts or overrides, custom formatters need to have an uppercase tag, whereas pre-defined formatters always use a lowercase character.

    const tag = "V";
    const fn = function (locale) {
      return function (str, option) {
        // Yes, you can use other formatters in custom formatters!
        return fmt`${str} version ${option}:n(1)`;
      };
    };
    
    fmt.register(tag, fn);
    
    const name = "Alice";
    
    console.log(fmt`Welcome to ${name}:V(3)!`);
    // "Welcome to Alice version 3.0!"

    Note that registering multiple custom formatters with the same tag will override previously registered ones.

    Acknowledgements

    Thanks to Jack Hsu and his article on implementing an internationalization library using template literals (https://jaysoo.ca/2014/03/20/i18n-with-es2015-template-literals/) for the inspiration!

    License

    MIT

    Install

    npm i fmt-tag

    DownloadsWeekly Downloads

    4

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    13.9 kB

    Total Files

    6

    Last publish

    Collaborators

    • antoniovdlc