jmerle/node-icecream

🍦 Quick and easy variable and expression debugging

node-icecream

node-icecream is a Node.js port of the icecream library for Python.

Installation

Installing node-icecream is easy:

$ yarn add node-icecream

Or with npm:

$ npm install node-icecream

Usage

Take the following code as an example:

function foo() {
    return 'bar';
}

console.log(`foo(): ${foo()}`);
// > foo(): bar

With node-icecream, the above would become:

const ic = require('node-icecream')();

function foo() {
    return 'bar';
}

ic(foo());
// > 🍦 foo(): 'bar'

With arguments

node-icecream will return the argument(s) it is given, so you can easily plug it into existing code.

const ic = require('node-icecream')();

function foo() {
    return 'bar';
}

const result = ic(foo());
// > 🍦 foo(): 'bar'
// result === 'bar'

const results = ic(foo(), foo(), foo());
// > 🍦 foo(): 'bar', foo(): 'bar', foo(): 'bar'
// results === ['bar', 'bar', 'bar']

Without arguments

When not given any arguments, node-icecream will print the filename and the line number where it was called from. The filename shown is relative from the project's root path.

const ic = require('node-icecream')();

function foo() {
    ic();

    // For example purposes only
    if (true) {
        ic();
        return 'bar';
    }

    ic();
    return 'something is wrong';
}

ic(foo());
// > 🍦 index.js:4
// > 🍦 index.js:8
// > 🍦 foo(): 'bar'

With existing logger

node-icecream can easily be used together with an existing logger. The following is an example on how to use node-icecream with the debug package.

const debug = require('debug')('example');
const ic = require('node-icecream')({
    prefix: '',
    outputFunction: debug,
});

function foo() {
    ic();
    return 'bar';
}

ic(foo());
// > example index.js:8 +0ms
// > example foo(): 'bar' +11ms

Options

node-icecream can easily be configured to use a different prefix or print to somewhere else. Configuration is applied when requiring node-icecream:

const ic = require('node-icecream')({ prefix: 'prefix: ' });

Available options

• prefix (default: '🍦 ' on all systems except for Windows, where it is '[ic] ') is the prefix to use. This can be both a string or a function. If it is a function, it is called every time just before printing. This option can be useful when you need timestamps to be printed.
• outputFunction (default: console.log) is the function that is called to print the output. By default, it simply uses console.log(), but the option makes it easy to log to existing loggers aswell.

Contributing

Bug reports, feature requests and pull requests are all welcome! Continue reading for some help on getting up and running, or head over to the issues page to report a bug or request a new feature.

Getting up and running locally

The following needs to be done to start working on the project:

# Clone the repository
$ git clone https://github.com/jmerle/node-icecream.git

# cd into the cloned repository
$ cd node-icecream

# Install the necessary dependencies
$ yarn

# Do your thing

# Lint the code for style issues
$ yarn lint

# Run tests
$ yarn test

Pull requests

When starting to work on a new feature, please make sure to work off of the develop branch. This branch contains the latest code, so the master branch is a direct representation of what you get when installing through npm. Similarly, also send pull requests to the develop branch.

TypeScript

node-icecream comes with TypeScript definitions. The default import syntax can be used, which imports a wrapper around the ic function to make configuration possible.

import ice from 'node-icecream';

const ic = ice({ prefix: '[prefix] ' });

function foo(): string {
    return 'bar';
}

ic(foo());
// > [prefix] foo(): 'bar'

Limitations

• Doesn't work in the REPL.

License

MIT

node-icecream's Issues

SyntaxError: 'import' and 'export' may appear only with 'sourceType: module' (1:0)

Here's what I'm trying to do:

import ice from "node-icecream"

const ic = ice({ outputFunction: log.debug });
// ...
const someVariable = ic(someFunctionCall());

And here's what I get:

    SyntaxError: 'import' and 'export' may appear only with 'sourceType: module' (1:0)

      79 |
      80 | function mapStateToProps(state: State): StateProps {
    > 81 |   const { activeBuf } = ic(getActive(state));
         |                         ^
      82 |
      83 |   log.debug({ activeBuf });
      84 |

      at Parser.Object.<anonymous>.pp$4.raise (node_modules/node-icecream/node_modules/acorn/dist/acorn.js:2757:13)
      at Parser.Object.<anonymous>.pp$1.parseStatement (node_modules/node-icecream/node_modules/acorn/dist/acorn.js:799:16)
      at Parser.Object.<anonymous>.pp$1.parseTopLevel (node_modules/node-icecream/node_modules/acorn/dist/acorn.js:706:23)
      at Parser.parse (node_modules/node-icecream/node_modules/acorn/dist/acorn.js:551:15)
      at Object.parse (node_modules/node-icecream/node_modules/acorn/dist/acorn.js:5290:37)
      (further are lines from my project)

It happens when I run tests through jest. My project uses Typescript and ts-jest to run typescript test files.

Is use in browser javascript possible?

I'd like to use ice-cream in my browser app, which uses npm packages via a bundler (esbuild, in my case). Unfortunately esbuild complains with

node-icecream/index.js:1:19: error: Could not resolve "fs" (set platform to "node" when building for node)

which makes sense since the browser is not able to access the filesystem. Perhaps a fork of ice-cream with fs features removed is the only way around this?