console.js

  1. /**
  2.  * Console APIs
  3.  *
  4.  * The Console APIs provide functionality to allow developers to perform debugging tasks,
  5.  * such as logging messages or the values of variables at set points in your code.
  6.  *
  7.  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/console}
  8.  *
  9.  * @module Console
  10.  */
  12. /* eslint-disable no-control-regex */
  14. import { performance } from 'perf_hooks';
  15. import { green, yellow, cyan, red, bright_black } from 'colors';
  17. const { callConsole } = process.binding('stdio');
  19. // Returns a string with as many spaces as the parameter specified.
  20. function pre(amount) {
  21.   return ' '.repeat(amount);
  22. }
  24. // Small util for objects that might not have a `.toString` method.
  25. function objectToString(value) {
  26.   return Object.prototype.toString.call(value);
  27. }
  29. /**
  30.  * Stringifies almost all JavaScript built-in types.
  31.  *
  32.  * @ignore
  33.  * @param {*} value
  34.  * @param {WeakSet} seen
  35.  * @param {number} depth
  36.  * @returns {string}
  37.  */
  39. function stringify(value, seen, depth = 0) {
  40.   switch (typeof value) {
  41.     case 'string':
  42.       return depth > 0 ? stringifyText(value) : value;
  43.     case 'number':
  44.     case 'boolean':
  45.       return yellow(String(value));
  46.     case 'undefined':
  47.       return bright_black(String(value));
  48.     case 'symbol':
  49.       return green(String(value));
  50.     case 'bigint':
  51.       return yellow(String(value) + 'n');
  52.     case 'object':
  53.       return !value ? 'null' : stringifyObject(value, seen, ++depth);
  54.     case 'function':
  55.       return !value.name
  56.         ? cyan('[Function (anonymous)]')
  57.         : cyan(`[Function: ${value.name}]`);
  58.     default:
  59.       return '[Unknown]';
  60.   }
  61. }
  63. function stringifyText(value) {
  64.   const text = value.length > 100 ? `${value.slice(0, 100)}...` : value;
  65.   const textEscaped = JSON.stringify(text);
  66.   return green(textEscaped);
  67. }
  69. function isArray(value) {
  70.   return Array.isArray(value);
  71. }
  73. function stringifyArray(arr, seen, depth) {
  74.   // Special formatting required if array has only numbers.
  75.   const hasOnlyNumbers = arr.every((elem) => typeof elem === 'number');
  77.   const entries = [];
  78.   for (const elem of arr) {
  79.     entries.push(stringify(elem, seen, depth));
  80.   }
  82.   // Remove the color characters to get the proper length.
  83.   const uncoloredEntries = entries.join('').replace(/\u001b\[[0-9;]*m/g, '');
  85.   // Multiline formatting.
  86.   if (uncoloredEntries.length > 60) {
  87.     const start = '[\n';
  88.     const end = `\n${pre((depth - 1) * 2)}]`;
  89.     const entriesPretty = prettifyArray(entries, depth, hasOnlyNumbers);
  90.     return `${start}${entriesPretty}${end}`;
  91.   }
  93.   // Inline formatting.
  94.   return entries.length > 0 ? `[ ${entries.join(', ')} ]` : `[]`;
  95. }
  97. function isTypedArray(value) {
  98.   switch (Object.prototype.toString.call(value)) {
  99.     case '[object Int8Array]':
  100.     case '[object Uint8Array]':
  101.     case '[object Uint8ClampedArray]':
  102.     case '[object Uint16Array]':
  103.     case '[object Int32Array]':
  104.     case '[object Uint32Array]':
  105.     case '[object Float32Array]':
  106.     case '[object Float64Array]':
  107.       return true;
  108.     default:
  109.       return false;
  110.   }
  111. }
  113. // Calculate the grid size (trying to make perfect squares and minimizing empty space).
  114. // 1. Max out at 12xN.
  115. // 2. Max out at 01xN (if the lengthier element is too big).
  116. function getMaxElementsPerRow(arr, avgElementLength, maxElementLength) {
  117.   if (maxElementLength > 30) return 1;
  118.   return Math.min(
  119.     Math.max(
  120.       Math.floor((Math.sqrt(arr.length) * avgElementLength) / maxElementLength),
  121.       1
  122.     ),
  123.     12
  124.   );
  125. }
  127. function prettifyArray(arr, depth = 0, hasOnlyNumbers) {
  128.   // Remove the color characters so we can calculate the AVG and MAX correctly.
  129.   const uncolored = arr.map(
  130.     (elem) => elem.replace(/\u001b\[[0-9;]*m/g, '').length
  131.   );
  133.   const maxElementLength = Math.max(...uncolored);
  134.   const avgElementLength = uncolored.reduce((a, b) => a + b) / uncolored.length;
  136.   // Calculate the grid size.
  137.   const maxElementsPerRow = getMaxElementsPerRow(
  138.     arr,
  139.     avgElementLength,
  140.     maxElementLength
  141.   );
  143.   // Tries to align the columns.
  144.   const alignColumn = (elem, i) => {
  145.     const length = elem.replace(/\u001b\[[0-9;]*m/g, '').length;
  146.     const shift = maxElementsPerRow === 1 ? 0 : maxElementLength - length;
  147.     if (hasOnlyNumbers) {
  148.       return i === arr.length - 1
  149.         ? pre(shift) + elem
  150.         : pre(shift) + elem + ', ';
  151.     } else {
  152.       return i === arr.length - 1
  153.         ? elem + pre(shift)
  154.         : elem + ', ' + pre(shift);
  155.     }
  156.   };
  158.   // Creates rows of length `maxElementsPerRow`.
  159.   const groupRows = (acc, elem, i) => {
  160.     if (acc.atRow === maxElementsPerRow || i === 0) {
  161.       acc.list.push([elem]);
  162.       acc.atRow = 1;
  163.     } else {
  164.       acc.list[acc.list.length - 1].push(elem);
  165.       acc.atRow++;
  166.     }
  167.     return acc;
  168.   };
  170.   // Indents row based on the depth we're currently in.
  171.   const indentRow = (row) => pre(depth * 2) + row.join('');
  173.   let output = arr.map(alignColumn);
  175.   output = output.reduce(groupRows, { atRow: 0, list: [] });
  176.   output = output.list.map(indentRow).join('\n');
  178.   return output;
  179. }
  181. function stringifyTypedArray(arr, depth = 0) {
  182.   // Colorize internal values.
  183.   let pretty = arr
  184.     .toString()
  185.     .split(',')
  186.     .map((elem) => yellow(elem));
  188.   // Get typed-array's specific type.
  189.   const type = Object.prototype.toString
  190.     .call(arr)
  191.     .replace('[object ', '')
  192.     .replace(']', '');
  194.   if (pretty.length > 50) {
  195.     pretty = prettifyArray(pretty, depth, true);
  196.     return `${type}(${arr.length}) [\n${pretty}\n${pre((depth - 1) * 2)}]`;
  197.   }
  199.   return `${type}(${arr.length}) [ ${pretty.join(', ')} ]`;
  200. }
  202. function isDate(value) {
  203.   return Object.prototype.toString.call(value) === '[object Date]';
  204. }
  206. function stringifyDate(date) {
  207.   return date.toISOString();
  208. }
  210. function isRexExp(value) {
  211.   return Object.prototype.toString.call(value) === '[object RegExp]';
  212. }
  214. function stringifyRexExp(exp) {
  215.   return exp.toString();
  216. }
  218. function isError(value) {
  219.   return Object.prototype.toString.call(value) === '[object Error]';
  220. }
  222. function stringifyError(error) {
  223.   return error.stack;
  224. }
  226. function isArrayBuffer(value) {
  227.   return value instanceof ArrayBuffer;
  228. }
  230. function stringifyArrayBuffer(value) {
  231.   return `ArrayBuffer { byteLength: ${stringify(value.byteLength)} }`;
  232. }
  234. function isPromise(value) {
  235.   return value instanceof Promise;
  236. }
  238. function stringifyPromise(value) {
  239.   // We have to use a Rust binding to inspect the contents of a promise
  240.   // object because JS doesn't expose that kind of functionality.
  241.   const binding = process.binding('promise');
  242.   const { state, value: promiseValue } = binding.peek(value);
  244.   if (state === 'PENDING') {
  245.     return `Promise { ${cyan('<pending>')} }`;
  246.   }
  248.   const output = stringify(promiseValue, undefined, 1);
  249.   const end = `${output.length > 50 ? '\n' : ' '}}`;
  251.   const prefix =
  252.     state === 'FULFILLED'
  253.       ? `${output.length > 50 ? '\n  ' : ''}`
  254.       : `${output.length > 50 ? '\n  ' : ''}${red('<rejected>')} `;
  256.   return 'Promise { ' + prefix + output + end;
  257. }
  259. const specialCharsRegex = new RegExp('[^A-Za-z0-9|_]+');
  261. /**
  262.  * Specifically stringifies JavaScript objects.
  263.  *
  264.  * @ignore
  265.  * @param {*} value
  266.  * @param {WeakSet} seen
  267.  * @param {number} depth
  268.  * @returns {string}
  269.  */
  271. function stringifyObject(value, seen = new WeakSet(), depth) {
  272.   // We have to check the type of the value parameter to decide which stringify
  273.   // transformer we should use.
  274.   if (isArray(value)) {
  275.     return stringifyArray(value, seen, depth);
  276.   }
  278.   if (isArrayBuffer(value)) {
  279.     return stringifyArrayBuffer(value);
  280.   }
  282.   if (isTypedArray(value)) {
  283.     return stringifyTypedArray(value, depth);
  284.   }
  286.   if (isDate(value)) {
  287.     return stringifyDate(value);
  288.   }
  290.   if (isRexExp(value)) {
  291.     return stringifyRexExp(value);
  292.   }
  294.   if (isError(value)) {
  295.     return stringifyError(value);
  296.   }
  298.   if (isPromise(value)) {
  299.     return stringifyPromise(value);
  300.   }
  302.   // It's an object type that console does not support.
  303.   if (objectToString(value) !== '[object Object]') {
  304.     const type = objectToString(value).replace('[object ', '').replace(']', '');
  305.     return `${type} {}`;
  306.   }
  308.   // Looks like it's a regular object.
  309.   const entries = [];
  310.   for (const key of Object.keys(value)) {
  311.     if (seen.has(value[key])) {
  312.       entries.push(`${pre(depth * 2)}${key}: [Circular]`);
  313.       continue;
  314.     }
  315.     // The following wraps in quotes object keys that contain special
  316.     // characters like { "Foo-Bar": 123 }.
  317.     const keyValue = specialCharsRegex.test(key) ? `"${key}"` : key;
  319.     seen.add(value);
  320.     entries.push(
  321.       `${pre(depth * 2)}${keyValue}: ${stringify(value[key], seen, depth)}`
  322.     );
  323.   }
  325.   // Output the class name if the object is a class instance.
  326.   const className = value?.constructor?.name;
  327.   const prefix = !className || className === 'Object' ? '' : className + ' ';
  329.   // Apply multi-line formatting on long properties.
  330.   if (entries.map((v) => v.trim()).join('').length > 50) {
  331.     const start = `${prefix}{\n`;
  332.     const end = `\n${pre((depth - 1) * 2)}}`;
  333.     return `${start}${entries.join(',\n')}${end}`;
  334.   }
  336.   // Inline formatting.
  337.   const entriesPretty = entries.map((v) => v.trim());
  338.   const content = entries.length > 0 ? `{ ${entriesPretty.join(', ')} }` : `{}`;
  340.   return `${prefix}${content}`;
  341. }
  343. /**
  344.  * Shows the given message and waits for the user's input.
  345.  *
  346.  * @param {String} [message] - A string of text to display to the user.
  347.  * @param {String} [defaultValue] - A string containing the default value displayed in the text input field.
  348.  */
  349. export function prompt(message = 'Prompt', defaultValue = null) {
  350.   // Write prompt message to stdout.
  351.   process.stdout.write(
  352.     `${message} ${defaultValue ? `[${defaultValue}] ` : ''}`
  353.   );
  354.   // Read and return user's input.
  355.   return process.stdin.read() || defaultValue;
  356. }
  358. /**
  359.  * Console is a subset implementation of MDN's Console API.
  360.  */
  361. export class Console {
  362.   // Holds timers initialized by console.
  363.   // https://developer.mozilla.org/en-US/docs/Web/API/Console/time
  364.   #timers = new Map();
  366.   /**
  367.    * Outputs data to the `stdout` stream.
  368.    *
  369.    * @param  {...*} args - Prints to stdout with newline.
  370.    */
  371.   log(...args) {
  372.     const output = args.map((arg) => stringify(arg)).join(' ');
  373.     process.stdout.write(`${output}\n`);
  374.   }
  376.   /**
  377.    * An alias to `console.log()`.
  378.    *
  379.    * @param  {...*} args - Prints to stdout with newline.
  380.    */
  381.   info(...args) {
  382.     const output = args.map((arg) => stringify(arg)).join(' ');
  383.     process.stdout.write(`${output}\n`);
  384.   }
  386.   /**
  387.    * An alias to `console.log()`.
  388.    *
  389.    * @param  {...*} args - Prints to stdout with newline.
  390.    */
  391.   debug(...args) {
  392.     const output = args.map((arg) => stringify(arg)).join(' ');
  393.     process.stdout.write(`${output}\n`);
  394.   }
  396.   /**
  397.    * Same as `console.log` but prepends the output with "WARNING".
  398.    *
  399.    * @param  {...*} args - Prints to stdout with newline.
  400.    */
  401.   warn(...args) {
  402.     const output = args.map((arg) => stringify(arg)).join(' ');
  403.     process.stderr.write(`WARNING: ${output}\n`);
  404.   }
  406.   /**
  407.    * Same as `console.log` but prepends the output with "WARNING".
  408.    *
  409.    * @param  {...*} args - Prints to stdout with newline.
  410.    */
  411.   error(...args) {
  412.     const output = args.map((arg) => stringify(arg)).join(' ');
  413.     process.stderr.write(`WARNING: ${output}\n`);
  414.   }
  416.   /**
  417.    * Clears the console if the environment allows it.
  418.    */
  419.   clear() {
  420.     try {
  421.       process.binding('stdio').clear();
  422.     } catch (e) {
  423.       this.warn('This environment does not support console clearing');
  424.     }
  425.   }
  427.   /**
  428.    * Starts a timer you can use to track how long an operation takes.
  429.    *
  430.    * @param {String} [label] - A string representing the name to give the new timer.
  431.    */
  432.   time(label = 'default') {
  433.     if (this.#timers.has(label)) {
  434.       this.warn(`Timer '${label}' already exists`);
  435.       return;
  436.     }
  438.     this.#timers.set(label, performance.now());
  439.   }
  441.   /**
  442.    * Logs the current value of a timer that was previously started by calling
  443.    * console.time() to the console.
  444.    *
  445.    * @param {String} [label] - The name of the timer to log to the console.
  446.    */
  447.   timeLog(label = 'default') {
  448.     if (!this.#timers.has(label)) {
  449.       this.warn(`Timer '${label}' does not exist`);
  450.       return;
  451.     }
  453.     const difference = performance.now() - this.#timers.get(label);
  454.     this.log(`${label}: ${difference} ms`);
  455.   }
  457.   /**
  458.    * Stops a timer that was previously started by calling console.time().
  459.    *
  460.    * @param {String} [label] - A string representing the name of the timer to stop.
  461.    */
  462.   timeEnd(label = 'default') {
  463.     if (!this.#timers.has(label)) {
  464.       this.warn(`Timer '${label}' does not exist`);
  465.       return;
  466.     }
  468.     this.timeLog(label);
  469.     this.#timers.delete(label);
  470.   }
  471. }
  473. // This wrapper forwards console messages to V8's internal console implementation,
  474. // triggering the `Runtime.consoleAPICalled` event. This ensures that the
  475. // attached debugger (if exists) is notified about the console call.
  476. //
  477. // https://github.com/v8/v8/blob/master/src/inspector/v8-console.cc
  478. // https://chromedevtools.github.io/devtools-protocol/tot/Runtime/#event-consoleAPICalled
  479. //
  480. export function wrapConsole(console, consoleFromV8) {
  481.   // Get the property names of the console prototype.
  482.   const prototype = Object.getPrototypeOf(console);
  483.   const propertyNames = Object.getOwnPropertyNames(prototype);
  485.   for (const key of Object.keys(consoleFromV8)) {
  486.     // If global console has the same method as inspector console,
  487.     // then wrap these two methods into one.
  488.     if (propertyNames.includes(key)) {
  489.       console[key] = callConsole.bind(
  490.         console,
  491.         consoleFromV8[key],
  492.         console[key]
  493.       );
  494.     } else {
  495.       // Add additional console APIs from the inspector.
  496.       console[key] = consoleFromV8[key];
  497.     }
  498.   }
  499. }
  501. export default { Console, prompt, wrapConsole };