Extends string.js with extra functionality, like chalk and sprintf support.
It is recommended that you read the existing documentation for string.js first.
The following examples use S as the variable name shorthand for creating new
StringExtra objects, however you can choose whichever name you like (e.g. $$).
Node.js:
const { create: S } = require('@unicorn-fail/string-extra').default;ES6/TypeScript:
import { create as S } from '@unicorn-fail/string-extra';Simple usage:
S(['Placeholders %s can have their own %s too!', 'values', 'styles']).magenta.argStyle.cyanBright.bold.underline;
S(['Object value: %j', object]).magenta.prefix(S('debug').cyan.bgBlackBright).suffix(S(['(elapsed time: %s)', elapsedTime]).dim);Q: Why not just use ES6 interpolation?
A: Chainability and portability but also for the sake of brevity and
simplicity. The entire string and placeholders are styled independently and
formatted only when the object needs to be rendered to an actual string. This
allows the object to be passed around more easily and allows dynamic updates
to the format value, placeholders values (args), or styles throughout a given
workflow (think task runners/loggers where lines can have multiple states).
If you needed to update a string using interpolation, you'd have to manually
construct something like the following each and every time something changed:
chalk.magenta(`Placeholders ${chalk.cyanBright.bold.underline('values')} can have their own ${chalk.cyanBright.bold.underline('styles')} too!`);
chalk.cyan.bgBlackBright('debug') + ' ' + chalk.magenta(`Object value: ${chalk.whiteBright.bold(JSON.stringify(object))}`) + ' ' + chalk.dim(`(elapsed time: ${chalk.whiteBright.bold(elapsedTime)}`);$ node examples.js (see file):
See the test file or TypeScript definition for more details.
@todo - finish documenting new methods/properties