Registry / serialization / sprintf-kit

sprintf-kit

JSON →
library2.0.2jsnpmunverified

sprintf-kit is a JavaScript library providing a modular `printf` format string parser and basic formatter. It allows developers to create custom `sprintf`-like functions by explicitly configuring specific modifier resolvers (e.g., for `%s`, `%d`). The library's core is its detailed `printf` syntax parser, which breaks down format strings into literals and placeholder metadata. It also offers a format function generator and a parts resolver generator, enabling granular control over how strings are processed and substitutions are applied. Currently at version 2.0.2, the package has seen infrequent but recent maintenance, with the last major update (v2.0.0) occurring in 2018, focusing on internal structure and advanced parsing capabilities. Its modularity and explicit modifier configuration differentiate it from simpler `sprintf` implementations that might bundle all modifiers by default.

serialization
npm install sprintf-kit
github ↗package ↗
INSTALL
IMPORT
SIG · SPRINTF-KIT
S
sprintf-kit
serializationjavascriptv2.0.2
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (format function)
✓ const format = require('sprintf-kit');
✗ import format from 'sprintf-kit';
The default export is a function generator that takes a configuration object for modifiers. The package is CommonJS-first.
parse
✓ const parse = require('sprintf-kit/parse');
✗ import { parse } from 'sprintf-kit';
Parses the format string into a data map of literals and placeholders. Explicit CommonJS `require` for sub-paths.
getResolver
✓ const getResolver = require('sprintf-kit/get-resolver');
✗ import { getResolver } from 'sprintf-kit';
Generates a resolver function that returns resolved parts with metadata. In v2.0.0, it was renamed from `getResolver` to `getPartsResolver` in internal commits, but the public API `get-resolver` path remained stable.
modifiers/s (string modifier)
✓ const s = require('sprintf-kit/modifiers/s');
✗ import { s } from 'sprintf-kit/modifiers/s';
Individual modifiers are imported from sub-paths to be configured with the main format function. This granular approach allows for tree-shaking and custom modifier sets.

This quickstart demonstrates how to set up a custom `sprintf` formatter using `sprintf-kit`, including defining specific modifiers and optionally styling literal parts of the string with an external library like `cli-color`.

const format = require('sprintf-kit'); const s = require('sprintf-kit/modifiers/s'); const d = require('sprintf-kit/modifiers/d'); const clc = require('cli-color'); // Configure a format function with string and decimal modifiers const customFormat = format({ s: s, d: d, // Optional: add a 'rest' formatter for unhandled arguments rest: args => args.length > 0 ? ` (and ${args.join(', ')})` : '' }); console.log(customFormat('Hello %s, you have %d new messages.', 'Alice', 5)); // Expected output: "Hello Alice, you have 5 new messages." console.log(customFormat('User %s logged in from %s, but ignored %d.', 'Bob', '192.168.1.1', 10, 'extra arg')); // Expected output: "User Bob logged in from 192.168.1.1, but ignored 10. (and extra arg)" // Example with custom literal decoration (e.g., for console coloring) const coloredFormat = format({ s: s, d: d, literal: literal => clc.green(literal) // Make non-placeholder text green }); console.log(coloredFormat('This is a %s message with a %d number.', 'colorful', 123));
Debug
Known issues
breakingIn v2.0.0, the `getResolver` utility was renamed to `getPartsResolver` internally, however, the public API path `sprintf-kit/get-resolver` remains the correct way to import the resolver. The change was internal and might affect direct deep imports that bypassed the `/get-resolver` entrypoint.
fix
Ensure you are importing the resolver via `require('sprintf-kit/get-resolver')`.
affects: >=2.0.0
breakingWith v2.0.0, the `flags` property within the placeholder metadata returned by the `parse` utility changed from an array to a string for simplicity.
fix
Update any code that processes the `flags` property to expect a string instead of an array. For example, `placeholder.flags.includes('0')` should become `placeholder.flags && placeholder.flags.includes('0')`.
affects: >=2.0.0
gotchaUnlike some `sprintf` implementations that provide a full suite of default modifiers, `sprintf-kit` requires you to explicitly configure which modifiers (`%s`, `%d`, etc.) your format function will support by providing them as an object to the `sprintf-kit` factory function. Unconfigured modifiers will be output as literal strings.
fix
Always pass an object mapping modifier types (e.g., `s`, `d`) to their respective resolver functions (e.g., `require('sprintf-kit/modifiers/s')`) when creating your format function.
affects: >=1.0.0
gotchaThe `parse` utility returns an `isParameterIndexingValid` property. If you use parameter indexing (e.g., `%2$s`) in some but not all placeholders within a format string, this property will be `false`, indicating inconsistent usage. While not strictly an error, it flags a potential logical inconsistency in your format string design.
fix
For consistent and predictable behavior, either use parameter indexing for all placeholders or for none. Review `isParameterIndexingValid` to ensure your format string logic is as intended.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 's')
Attempting to use a placeholder type (e.g., %s) without explicitly configuring its corresponding modifier when creating the format function.
fix
Ensure all desired modifiers are explicitly passed to the `require('sprintf-kit')` factory function. For example: `require('sprintf-kit')({ s: require('sprintf-kit/modifiers/s') });`
Output contains literal '%%' instead of a single '%' character.
Incorrect handling of the `%%` escape sequence, which should produce a literal percent sign.
fix
This was a bug fixed in v2.0.1. Ensure your `sprintf-kit` version is 2.0.1 or newer. If on an older version, manually replace `%%` with a single `%` in your format string or upgrade the package.
Invalid value: [Object] displayed in output instead of formatted content.
The default modifiers (e.g., `d` for numbers, `s` for strings) might output placeholder tokens like `[Object]` or `[Error]` for values they cannot process or serialize, such as non-JSON-serializable objects.
fix
Ensure the argument types match the expected modifier types. For complex objects, consider providing a custom modifier or a `j` (JSON) modifier if available and appropriate, or explicitly stringify the object before passing it.
Upgrade
Version history
2.0.2latest on npm
Audit
Dependencies
cli-coloroptionalUsed in examples for decorating literal strings in the format function; it is an optional utility for styling output.
Agent activity
9 hits · last 30 days
node
6
Amazon
1
Bingbot
1
Resources
githubhttps://github.com/medikoo/sprintf-kit ↗
packagehttps://www.npmjs.com/package/sprintf-kit ↗
sprintf-kit — npm install sprintf-kit · libregistry