README.md

⚡ Quick-and-dirty debugging output for tired JS programmers

Table of contents

• What is Q
• Sample output of using q()
• Why is this better than console.log?
• Changelog
• Install
• Usage
• Shell Integration
  • ZSH Plugin for Q
• Editor integrations
  • Jetbrains Intellij and Webstorm
    • For JavaScript:
    • For TypeScript:
    • Sample usage
• FAQ
  • Haven't I seen this somewhere before?
  • Why q?
  • Why the npm module is called qqd?
  • Is q safe for concurrent use?
  • What about production?
  • How to prevent calls to Q in production?
  • Haven't I seen this README somewhere before?

What is Q

q is a better way to do print statement debugging.

Use q instead of console.log and your variables will be nicely printed in $TMPDIR/q.

Sample output of using q()

Why is this better than console.log?

• ⚡ Faster to type
• 🍱 Pretty-printed vars and expressions
• 🔍 Easier to see inside objects
• 🙈 Does not go to noisy-ass stdout. It goes to $TMPDIR/q.
• 🎨 Pretty colors!

Bonus points:

• Provide a type definition for completion in IDE
• Honor NO_COLOR environment variable to disable coloring

Changelog

See CHANGELOG.md

Install

npm install qqd

Tips: qqd is for "Q is Quick Debugging".

Usage

const { q } = require("qqd");
q(a, b, c);

// Or shorter
require("qqd").q(a, b, c);

Then tail the q file:

tail -f $TMPDIR/q

# Or if $TMPDIR is not defined:
tail -f /tmp/q

For best results, dedicate a terminal to tailing $TMPDIR/q while you work, or see below the Shell integration.

Shell Integration

To quickly open the Q file and clearing it, add this two functions to your shell.

Note that there is also a ZSH Plugin, see the instructions below.

These two functions allows you to quickly tail Q, or to empty the Q file and tail it:

$ qq
Tailing Q log...
06:14:11 foobar

$ rmqq # File is emptied before
Tailing Q log...

ZSH Plugin for Q

The ZSH Plugin for Q adds the two functions, qq and rmqq, as seen above to your shell.

Usage with Zgen (or any ZSH plugin manager):

zgen load tomsquest/q.plugin.zsh

Then you can:

$ qq
Tailing Q log...
06:14:11 foobar

$ rmqq # File is emptied before
Tailing Q log...

Editor integrations

Jetbrains Intellij and Webstorm

For JavaScript:

1. In Settings
2. Open Editor > Live Templates
3. In JavaScript, add a new template
4. Click on Define next to No applicable contexts yet and pick JavaScript and TypeScript
5. Set:
   • Abbreviation: q
   • Description: Pretty-print with Q
   • Template Text: q($VAR$);
6. Open Edit variables and pick completeSmart() in the Expression column
7. Press OK

For TypeScript:

1. In Settings
2. Open Editor > Live Templates
3. Click on the + icon and select > Template Group and fill "TypeScript"
4. Go to the newly created group TypeScript, add a new template
5. Click on Define next to No applicable contexts yet and pick TypeScript
6. Set:
   • Abbreviation: q
   • Description: Pretty-print with Q
   • Template Text: q($VAR$);
7. Open Edit variables and pick completeSmart() in the Expression column
8. Press OK

Sample usage

Here, by pressing q, I can select the first, or the second option:

FAQ

Haven't I seen this somewhere before?

Python programmers will recognize this as a Javascript port of the q module by zestyping.
Go programmers will recognize this as a port of the q module by y0ssar1an.

Ping does a great job of explaining q in his awesome lightning talk from PyCon 2013. Watch it! It's funny :)

Why q?

Because q is quick to type ⚡⚡⚡.

Why the npm module is called qqd?

On NPM, the q, dd ("dirty debug") and even qdd ("quick dirty debug") were already published.
qqd seems to be a good choice, short and meaning Q is Quick Debugging.

Is q safe for concurrent use?

Yes. Q uses fs.writeFileSync() so the writes are synchronous/blocking.

What about production?

Q does not do anything if NODE_ENV is production.

This is for safety: you do not want Q to write stuff when running in production.

Still, it is advised to prevent shipping any calls to Q before shipping code (like you could to for console.log).

How to prevent calls to Q in production?

With ESLint, add the "Disallow specific imports (no-restricted-imports)" rules to an existing .eslintrc.js:

"no-restricted-imports": ["error", "qqd"]

Alternative for Node.js, the ESLint Node plugin provides two rules:

• node/no-restricted-import
• node/no-restricted-require

Haven't I seen this README somewhere before?

Yes, it is largely inspired by the very good README of the q module by y0ssar1an.