Node.js util module usage in Changesets

You will find this below import at line 4 in Changesets source code

import { format } from "util";

In this article, an overview of util module and its usage in Changesets is provided.

Util module

The util module is primarily designed to support the needs of Node.js’ own internal APIs. However, many of the utilities are useful for application and module developers as well. It can be accessed using:

const util = require('util');

You can read more about Util module here.

Util module has quite some APIs, but we are interested in Format API as this is what is found to be used in Changesets source code.

util.format(format[, …args])

The util.format() method returns a formatted string using the first argument as a printf-like format.

The first argument is a string containing zero or more placeholder tokens. Each placeholder token is replaced with the converted value from the corresponding argument. Supported placeholders are:

• %s — String.

• %d — Number (integer or floating point value).

• %i — Integer.

• %f — Floating point value.

• %j — JSON. Replaced with the string ‘[Circular]’ if the argument contains circular references.

• %o — Object. A string representation of an object with generic JavaScript object formatting. Similar to
  
  util.inspect() with options { showHidden: true, depth: 4, showProxy: true }. This will show the full object
  
  including non-enumerable symbols and properties.

• %O — Object. A string representation of an object with generic JavaScript object formatting. Similar to util.inspect()
  
  without options. This will show the full object not including non-enumerable symbols and properties.

• %% — single percent sign (‘%’). This does not consume an argument.

If the placeholder does not have a corresponding argument, the placeholder is not replaced.

util.format('%s:%s', 'foo');
// Returns: 'foo:%s'

If there are more arguments passed to the util.format() method than the number of placeholders, the extra arguments are coerced into strings then concatenated to the returned string, each delimited by a space. Excessive arguments whose typeof is ‘object’ or ‘symbol’ (except null) will be transformed by util.inspect().

util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'

If the first argument is not a string then util.format() returns a string that is the concatenation of all arguments separated by spaces. Each argument is converted to a string using util.inspect().

util.format(1, 2, 3); // '1 2 3'

If only one argument is passed to util.format(), it is returned as it is without any formatting.

util.format('%% %s'); // '%% %s'

Now that we understand the basics of Util module and the format API, let’s now look at format usage in Changesets.

util.format usage in Changesets

Searching for format, I found 2 instances where format is used.

\`\`\`
${format("", err).replace(process.cwd(), "<cwd>")}
\`\`\`

This just outputs error and there are no replacements to be made since the first argument is an empty string.

util
 .format("", …args)
 .split("\n")
 .join("\n" + fullPrefix + " ")

This produces a string separated by a space, assuming …args is comma separated

About me:

Hey, my name is Ramu Narasinga. I study large open-source projects and create content about their codebase architecture and best practices, sharing it through articles, videos.

I am open to work on an interesting project. Send me an email at [e-mail]

My Github - https://github.com/ramu-narasinga
My website - https://ramunarasinga.com
My Youtube channel - https://www.youtube.com/@thinkthroo
Learning platform - https://thinkthroo.com
Codebase Architecture - https://app.thinkthroo.com/architecture
Best practices - https://app.thinkthroo.com/best-practices
Production-grade projects - https://app.thinkthroo.com/production-grade-projects

References:

1. https://www.npmjs.com/package/util

2. https://github.com/changesets/changesets/blob/main/packages/cli/src/index.ts#L4

3. https://github.com/changesets/changesets/blob/main/packages/cli/src/index.ts#L88

4. https://nodejs.org/docs/latest-v8.x/api/util.html#util_util_format_format_args

5. https://github.com/changesets/changesets/blob/main/packages/logger/src/index.ts#L23

6. https://github.com/changesets/changesets/blob/main/packages/get-github-info/src/index.test.ts#L127

7. https://github.com/changesets/changesets/blob/main/packages/cli/src/index.ts#L88