util: introduce formatWithOptions()

Identical to `format()` except that it takes an options argument
that is passed through to `inspect()`.

PR-URL: #19372
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

Author: addaleax

doc/api/util.md

@@ -254,6 +254,24 @@ intended as a debugging tool. Some input values can have a significant
 performance overhead that can block the event loop. Use this function
 with care and never in a hot code path.
 
+## util.formatWithOptions(inspectOptions, format[, ...args])
+<!-- YAML
+added: REPLACEME
+-->
+
+* `inspectOptions` {Object}
+* `format` {string}
+
+This function is identical to [`util.format()`][], except in that it takes
+an `inspectOptions` argument which specifies options that are passed along to
+[`util.inspect()`][].
+
+```js
+util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 });
+  // Returns 'See object { foo: 42 }', where `42` is colored as a number
+  // when printed to a terminal.
+```
+
 ## util.getSystemErrorName(err)
 <!-- YAML
 added: v9.7.0
@@ -2054,6 +2072,7 @@ Deprecated predecessor of `console.log`.
 [`Set`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
 [`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
 [`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
+[`util.format()`]: #util_util_format_format_args
 [`util.inspect()`]: #util_util_inspect_object_options
 [`util.promisify()`]: #util_util_promisify_original
 [`util.types.isAnyArrayBuffer()`]: #util_util_types_isanyarraybuffer_value

lib/util.js

@@ -173,23 +173,28 @@ function tryStringify(arg) {
   }
 }
 
-function format(f) {
+const emptyOptions = {};
+function format(...args) {
+  return formatWithOptions(emptyOptions, ...args);
+}
+
+function formatWithOptions(inspectOptions, f) {
   let i, tempStr;
   if (typeof f !== 'string') {
-    if (arguments.length === 0) return '';
+    if (arguments.length === 1) return '';
     let res = '';
-    for (i = 0; i < arguments.length - 1; i++) {
-      res += inspect(arguments[i]);
+    for (i = 1; i < arguments.length - 1; i++) {
+      res += inspect(arguments[i], inspectOptions);
       res += ' ';
     }
-    res += inspect(arguments[i]);
+    res += inspect(arguments[i], inspectOptions);
     return res;
   }
 
-  if (arguments.length === 1) return f;
+  if (arguments.length === 2) return f;
 
   let str = '';
-  let a = 1;
+  let a = 2;
   let lastPos = 0;
   for (i = 0; i < f.length - 1; i++) {
     if (f.charCodeAt(i) === 37) { // '%'
@@ -206,12 +211,17 @@ function format(f) {
             tempStr = `${Number(arguments[a++])}`;
             break;
           case 79: // 'O'
-            tempStr = inspect(arguments[a++]);
+            tempStr = inspect(arguments[a++], inspectOptions);
             break;
           case 111: // 'o'
-            tempStr = inspect(arguments[a++],
-                              { showHidden: true, showProxy: true });
+          {
+            const opts = Object.assign({}, inspectOptions, {
+              showHidden: true,
+              showProxy: true
+            });
+            tempStr = inspect(arguments[a++], opts);
             break;
+          }
           case 105: // 'i'
             tempStr = `${parseInt(arguments[a++])}`;
             break;
@@ -244,7 +254,7 @@ function format(f) {
     if ((typeof x !== 'object' && typeof x !== 'symbol') || x === null) {
       str += ` ${x}`;
     } else {
-      str += ` ${inspect(x)}`;
+      str += ` ${inspect(x, inspectOptions)}`;
     }
   }
   return str;
@@ -1206,6 +1216,7 @@ module.exports = exports = {
   debuglog,
   deprecate,
   format,
+  formatWithOptions,
   getSystemErrorName,
   inherits,
   inspect,