js-format/README.md

@e22m4u/js-format

English | Русский

The string interpolation utility for JavaScript.

• standard specifiers %s, %d, and %j (see util.format)
• %v outputs primitive value or constructor name
• %l outputs an array as a comma-separated list "foo", 10, true

Additionally:

• built-in Errorf class with error message interpolation

Installation

npm install @e22m4u/js-format

Overview

The module supports ESM and CommonJS standards.

ESM

import {format} from '@e22m4u/js-format';

CommonJS

const {format} = require('@e22m4u/js-format');

Specifiers

The format method returns a formatted string using the first argument as a printf-like template which can contain zero or more format specifiers. Each specifier is replaced with the converted value from the corresponding argument.

specifier	description
%s	String will be used to convert a value
%d	Number will be used to convert a value
%j	JSON representation
%v	see below
%l	see below

%v

Strings are wrapped in quotes, other primitives are converted to strings, and for more complex types the constructor name is output.

format('It is %v', 'foo');        // It is "foo"
format('It is %v', '');           // It is ""
format('It is %v', 10);           // It is 10
format('It is %v', 0);            // It is 0
format('It is %v', NaN);          // It is NaN
format('It is %v', Infinity);     // It is Infinity
format('It is %v', true);         // It is true
format('It is %v', false);        // It is false
format('It is %v', {foo: 'bar'}); // It is Object
format('It is %v', new Date());   // It is Date
format('It is %v', new Map());    // It is Map
format('It is %v', () => 10);     // It is Function
format('It is %v', undefined);    // It is undefined
format('It is %v', null);         // It is null

The %v specifier was designed to output values in error messages when it's important to have an idea of their types. However, outputting the contents of an object may be excessive for such a task. For this reason, objects are converted to the constructor name, which allows for a relatively accurate determination of the output value's type.

class MyClass {}

format('It is %v', 'MyClass');     // It is "MyClass"
format('It is %v', MyClass);       // It is MyClass
format('It is %v', new MyClass()); // It is MyClass (instance)

%l

Outputs array elements separated by commas.

format('An array of %l', ['foo', 10, true]);
// An array of "foo", 10, true

Array elements are converted to strings following the logic of the %v specifier.

Errorf

The Errorf class constructor passes arguments to the format function to form an error message.

Example:

import {Errorf} from '@e22m4u/js-format';

throw new Errorf(
  'It requires one of %l, but %v given.',
  [true, false, 'y', 'n'],
  new Map(),
);
// Error: It requires one of true, false, "y", "n", but Map given.

Tests

npm run test

License

MIT