Destroy

Destroy is a Node.js utility library that ensures streams get destroyed correctly by handling different APIs and Node.js bugs. It provides a single function that properly destroys streams while preventing memory leaks and resource leaks.

Package Information

• Package Name: destroy
• Package Type: npm
• Language: JavaScript
• Installation: npm install destroy

Core Imports

const destroy = require('destroy');

For Node.js with ES modules (requires import assertion or .mjs extension):

// Import as default export from CommonJS module
import destroy from 'destroy';

Basic Usage

const destroy = require('destroy');
const fs = require('fs');

// Create a read stream
const stream = fs.createReadStream('package.json');

// Later, destroy the stream properly
destroy(stream);

// Destroy with error suppression
destroy(stream, true);

Capabilities

Stream Destruction

Destroys a stream while handling different APIs and Node.js bugs to prevent resource leaks.

/**
 * Destroy the given stream, and optionally suppress any future `error` events.
 * 
 * @param {object} stream - The stream to destroy (can be any object, only streams will be affected)
 * @param {boolean} [suppress] - Whether to suppress future error events by removing existing error listeners and adding a no-op handler
 * @returns {object} The original stream object passed as the first parameter
 */
function destroy(stream, suppress): object

The function handles different stream types with specialized logic:

1. fs.ReadStream - Calls stream.destroy() and adds listener to open event to call stream.close() if fired (Node.js bug workaround for file descriptor leaks)
2. Zlib streams - Handles various zlib stream types (Gzip, Gunzip, Deflate, DeflateRaw, Inflate, InflateRaw, Unzip) with special destroy/close logic for Node.js bugs
3. General streams - For streams with destroy() method, calls it directly
4. Non-stream objects - Gracefully handles falsy values and non-stream objects by doing nothing

Parameters:

• stream (object): The stream to destroy. Can be any object, but only streams will be affected. Supported stream types include fs.ReadStream, zlib streams (Gzip, Gunzip, Deflate, DeflateRaw, Inflate, InflateRaw, Unzip), and any stream with a destroy() method.
• suppress (boolean, optional): When true, removes all existing error listeners and adds a no-op error handler to prevent uncaught error events during cleanup.

Returns: The original stream object passed as the first parameter.

Usage Examples:

const destroy = require('destroy');
const fs = require('fs');
const zlib = require('zlib');

// Basic stream destruction
const readStream = fs.createReadStream('data.txt');
destroy(readStream);

// With error suppression (prevents error events during cleanup)
const writeStream = fs.createWriteStream('output.txt');
destroy(writeStream, true);

// Handles zlib streams properly
const gzipStream = zlib.createGzip();
destroy(gzipStream);

// Safe with non-stream objects
destroy(null);        // Does nothing
destroy({});          // Does nothing
destroy(undefined);   // Does nothing

Error Handling

The destroy function is designed to be safe and will not throw errors. When the suppress parameter is set to true, it actively prevents error events from being emitted during the destruction process by:

1. Removing all existing error event listeners
2. Adding a no-op error handler to catch any errors during destruction

This is particularly useful in cleanup scenarios where error events could cause uncaught exceptions.

Types

/**
 * Main destroy function signature
 */
function destroy(stream: object, suppress?: boolean): object;

/**
 * Supported stream types (examples):
 */
interface SupportedStreams {
  // Node.js core streams
  fs.ReadStream: any;
  fs.WriteStream: any;
  net.Socket: any;
  
  // Zlib streams
  zlib.Gzip: any;
  zlib.Gunzip: any;
  zlib.Deflate: any;
  zlib.DeflateRaw: any;
  zlib.Inflate: any;
  zlib.InflateRaw: any;
  zlib.Unzip: any;
  
  // Any stream with destroy method
  Stream: any;
}

Node.js Compatibility

• Node.js version: >= 0.8
• Dependencies: None (uses only Node.js core modules)
• Module system: CommonJS only

The library includes specific workarounds for various Node.js versions and bugs related to stream destruction, making it a reliable choice for stream cleanup across different Node.js environments.