exit-on-epipe

What is exit-on-epipe?

The exit-on-epipe npm package is designed to automatically handle the 'EPIPE' error by attaching a listener to the 'process.stdout' and 'process.stderr' streams. This error typically occurs when a process writes to a stream (like stdout or stderr) but the stream has been closed, often because the output is being piped to another process which has terminated. Instead of throwing an error and potentially crashing the application, exit-on-epipe ensures the process exits gracefully.

What are exit-on-epipe's main functionalities?

Automatic EPIPE error handling

By simply requiring the exit-on-epipe package at the beginning of your application, it automatically handles EPIPE errors for stdout and stderr, preventing your application from crashing due to broken pipes. This is particularly useful in command-line applications that may be piped into other processes.

require('exit-on-epipe');
process.stdout.write('Hello, world!');

Other packages similar to exit-on-epipe

end-of-stream

The end-of-stream package is similar in that it helps manage stream end events, but it focuses on providing a callback when a stream or a writable has finished or failed, rather than specifically handling EPIPE errors. It's more general-purpose for stream management compared to the specific use case of exit-on-epipe.

pump

Pump is a package that helps to safely pipe streams together, handling cleanup and errors in a more comprehensive way than exit-on-epipe. While it doesn't specifically target EPIPE errors, it provides a robust solution for managing stream pipelines and can prevent some scenarios where EPIPE might occur.

README

exit-on-epipe

Cleanly exit on pipe errors in NodeJS scripts.

NOTE: The underlying problem was addressed in 8.x NodeJS versions but the fix was not backported to 6.x and other versions of NodeJS.

These errors are common in pipelines that involve NodeJS scripts. For example, take a simple script that prints out 10 lines:

for(var i = 0; i < 10; ++i) console.log(i)

NodeJS will print an error message if the output is truncated:

$ cat t.js
for(var i = 0; i < 10; ++i) console.log(i)
$ node --version
v6.11.1
$ node t.js  | head -n 1
0
events.js:160
      throw er; // Unhandled 'error' event
      ^

Error: write EPIPE
    at exports._errnoException (util.js:1018:11)
    at WriteWrap.afterWrite (net.js:800:14)

The process will cleanly exit if you require the module:

$ cat t.js
require("exit-on-epipe");
for(var i = 0; i < 10; ++i) console.log(i)
$ node t.js  | head -n 1
0

Installation

With npm:

$ npm install exit-on-epipe

Usage

For basic scripts, requiring at the top of the source file suffices:

require('exit-on-epipe');
// ... rest of source

For more advanced situations (e.g. handing other streams), call the module:

var eoepipe = require('exit-on-epipe');
eoepipe(stream);            // will exit process on an EPIPE error on stream
eoepipe(stream, handler);   // will call handler() instead of process.exit

Interface

The module exports a single function (exposed as the variable eoepipe).

eoepipe(stream, bail) will attach an error handler to stream which will:

• call the bail function if the error .code is "EPIPE" or .errno is 32
• defer to the default behavior if there are no other error handlers
• noop if the error is not EPIPE and if there are other error handlers

If the bail function is not specified, process.exit is used.

If the stream parameter is not specified, no action will be taken

Notes

The script will not perform any action if process or process.stdout are not available. It is safe to use in a web page.

License

Please consult the attached LICENSE file for details. All rights not explicitly granted by the Apache 2.0 license are reserved by the Original Author.

Badges