Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Re-write README to better present installation options #74

Merged
merged 1 commit into from
Jul 12, 2024
Merged

Re-write README to better present installation options #74

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 43 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,55 @@
# why-is-node-running

Node is running but you don't know why? `why-is-node-running` is here to help you.
Node.js is running but you don't know why? `why-is-node-running` is here to help you.

## Installation

Node 20.11 and above (ECMAScript modules):
If you want to use `why-is-node-running` in your code, you can install it as a local dependency of your project. If you want to use it as a CLI, you can install it globally, or use `npx` to run it without installing it.

### As a local dependency

Node.js 20.11 and above (ECMAScript modules):

```bash
npm install --save-dev why-is-node-running
```

Node.js 8 or higher (CommonJS):

```bash
npm install --save-dev why-is-node-running@v2.x
```

### As a global package

```bash
npm i why-is-node-running -g
npm install --global why-is-node-running
why-is-node-running /path/to/some/file.js
```

Node 8 or higher (CommonJS):
Alternatively if you do not want to install the package globally, you can run it with [`npx`](https://docs.npmjs.com/cli/commands/npx):

```bash
npm i why-is-node-running@v2.x -g
npx why-is-node-running /path/to/some/file.js
```

## Usage
## Usage (as a dependency)

```js
import whyIsNodeRunning from 'why-is-node-running' // should be your first import
import net from 'node:net'
import { createServer } from 'node:net'

function createServer () {
const server = net.createServer()
setInterval(function () {}, 1000)
function startServer () {
const server = createServer()
setInterval(() => {}, 1000)
server.listen(0)
}

createServer()
createServer()
startServer()
startServer()

setTimeout(function () {
whyIsNodeRunning() // logs out active handles that are keeping node running
}, 100)
// logs out active handles that are keeping node running
setImmediate(() => whyIsNodeRunning())
```

Save the file as `example.js`, then execute:
Expand All @@ -45,45 +61,33 @@ node ./example.js
Here's the output:

```
There are 5 handle(s) keeping the process running
There are 4 handle(s) keeping the process running

# Timeout
/home/maf/dev/node_modules/why-is-node-running/example.js:6 - setInterval(function () {}, 1000)
/home/maf/dev/node_modules/why-is-node-running/example.js:10 - createServer()
/path/to/project/example.js:6 - setInterval(() => {}, 1000)
/path/to/project/example.js:10 - startServer()

# TCPSERVERWRAP
/home/maf/dev/node_modules/why-is-node-running/example.js:7 - server.listen(0)
/home/maf/dev/node_modules/why-is-node-running/example.js:10 - createServer()
/path/to/project/example.js:7 - server.listen(0)
/path/to/project/example.js:10 - startServer()

# Timeout
/home/maf/dev/node_modules/why-is-node-running/example.js:6 - setInterval(function () {}, 1000)
/home/maf/dev/node_modules/why-is-node-running/example.js:11 - createServer()
/path/to/project/example.js:6 - setInterval(() => {}, 1000)
/path/to/project/example.js:11 - startServer()

# TCPSERVERWRAP
/home/maf/dev/node_modules/why-is-node-running/example.js:7 - server.listen(0)
/home/maf/dev/node_modules/why-is-node-running/example.js:11 - createServer()

# Timeout
/home/maf/dev/node_modules/why-is-node-running/example.js:13 - setTimeout(function () {
/path/to/project/example.js:7 - server.listen(0)
/path/to/project/example.js:11 - startServer()
```

**Important Note!**
`unref`ed timers do not prevent the Node process from exiting. If you are running with Node v11.0.0 and above, `unref`ed timers will not be listed in the above list. Unfortunately, this is not supported in node versions below v11.0.0.

## CLI
## Usage (as a CLI)

You can also run `why-is-node-running` as a standalone if you don't want to include it inside your code. Sending `SIGUSR1`/`SIGINFO` signal to the process will produce the log. (`Ctrl + T` on macOS and BSD systems)
You can run `why-is-node-running` as a standalone if you don't want to include it inside your code. Sending `SIGUSR1`/`SIGINFO` signal to the process will produce the log. (`Ctrl + T` on macOS and BSD systems)

```bash
why-is-node-running /path/to/some/file.js
```

Alternatively if you do not want to install the package globally, you can run it with `npx`:

```bash
npx why-is-node-running /path/to/some/file.js
```

```
probing module /path/to/some/file.js
kill -SIGUSR1 31115 for logging
Expand All @@ -95,7 +99,7 @@ To trigger the log:
kill -SIGUSR1 31115
```

## Import CLI Option
## Usage (with Node.js' `--import` option)

You can also use Node's [`--import`](https://nodejs.org/api/cli.html#--importmodule) option to preload `why-is-node-running`:

Expand Down