## @e22m4u/js-format

*English | [Русский](README-ru.md)*

Extended version of the `format` utility for Node.js

- standard specifiers `%s`, `%d`, and `%j`
- added `%v` for outputting primitive values and constructor names
- added `%l` for outputting a comma-separated list `"foo", 10, true`

Additionally:
- built-in `Errorf` class with error message interpolation

## Installation

```bash
npm install @e22m4u/js-format
```

To load the ES-module, you need to set `"type": "module"`
in the `package.json` file, or use the `.mjs` extension.

## Examples

ES-import

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

### %v

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

```js
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.

```js
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.

```js
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:

```js
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

```bash
npm run test
```

## License

MIT