CLI sprintf Formatter

1.1.1 verified Thu Apr 23 auth: no javascript

cli-sprintf-format is a utility package that provides an enhanced `sprintf`-like formatting function specifically tailored for command-line interface (CLI) applications. It builds upon Node.js's `util.formatWithOptions`, offering more robust type resolution, error handling, and intelligent color support. The package automatically detects terminal color capabilities via `supports-color` and applies coloring not only to inspected objects but also to primitive values, including colored JSON output. The current stable version is 1.1.1, released in late 2021, suggesting a relatively stable but infrequent release cadence focused on maintenance and bug fixes. Key differentiators include its improved object inspection depth (defaulting to 4, configurable via `FORMAT_INSPECT_DEPTH`) and specialized handling of `%s` and `%#s` format specifiers for string output, allowing for colored and inline display or raw string output, respectively.

Common errors

error TypeError: cliFormat is not a function ↓

cause Attempting to import `cli-sprintf-format` as a named export in an ESM module or incorrectly destructuring a CommonJS require.

fix

For ESM, use import cliFormat from 'cli-sprintf-format';. For CommonJS, use const cliFormat = require('cli-sprintf-format');.

error Unexpected output format for strings (e.g., extra quotes, colors, newlines removed) ↓

cause Using `%s` format specifier, which passes strings through `util.inspect`, resulting in formatting and colorization.

fix

If raw string output is desired, switch to %#s instead of %s.

Warnings

gotcha When formatting strings with `%s`, cli-sprintf-format passes them through Node.js's `util.inspect` formatter. This results in colored output (if supported) and makes multiline strings appear inline. If you need the raw string output without this processing, use `%#s` instead. ↓

fix Use `%#s` instead of `%s` for string arguments that should not be processed by `util.inspect`.

gotcha Object inspection depth for `%o` and `%O` specifiers defaults to `4`. For deeply nested objects, this might truncate output. The depth can be overridden globally via the `FORMAT_INSPECT_DEPTH` environment variable. ↓

fix Set the `FORMAT_INSPECT_DEPTH` environment variable (e.g., `FORMAT_INSPECT_DEPTH=6 node your_script.js`) to increase the inspection depth, or consider stringifying objects explicitly if full depth is always required.

breaking A bug fix in v1.1.1 ensured consistent literal output in Node.js v12+ versions. While a 'fix', applications relying on the previous (buggy) behavior in Node.js v12 or higher might see subtle changes in string literal representation. ↓

fix Review string literal outputs in Node.js v12+ after upgrading to v1.1.1 to ensure no unintended formatting changes occurred. No code change is typically required unless specific literal formatting was being implicitly relied upon.

Install

npm install cli-sprintf-format

yarn add cli-sprintf-format

pnpm add cli-sprintf-format

Imports

cliFormat
wrong
```
const cliFormat = require('cli-sprintf-format').default;
```
correct
```
import cliFormat from 'cli-sprintf-format';
```
While the package is primarily CommonJS, it can be imported as a default export in ESM. The package exports a single function.
cliFormat (CJS)
```
const cliFormat = require('cli-sprintf-format');
```
This is the documented and primary way to import the formatter in CommonJS environments.

Quickstart

Demonstrates basic string, number, object, and JSON formatting, including the effect of environment variables on object inspection depth.

const cliFormat = require("cli-sprintf-format");

// Basic string and number formatting
console.log(cliFormat("User '%s' has %d unread messages.", "Alice", 5));

// Formatting with an object, showing default inspection depth and coloring
const userProfile = { id: 101, name: "Bob", email: "bob@example.com", settings: { theme: 'dark', notifications: true } };
console.log(cliFormat("Profile details: %o", userProfile));

// Formatting with JSON, which will also be colored if supported
const data = { status: 'success', items: [{ id: 1, value: 'test' }] };
console.log(cliFormat("API Response: %j", data));

// Using environment variable to control inspection depth (run with: FORMAT_INSPECT_DEPTH=2 node your-script.js)
console.log(cliFormat("Deep object (depth 2 via env): %o", { a: { b: { c: { d: 1 } } } }));