Handling End-of-Life Streams

In this lesson, you will learn how to orchestrate a graceful shutdown sequence that ensures all buffered data is fully flushed through your pipeline before a process exits.

The Problem: Sudden Termination

When your application receives a termination signal (like SIGTERM), it’s tempting to simply kill the process. However, streams often maintain internal buffers—data that has been processed but not yet "drained" into the final destination (like a file or a network socket). If you close the process abruptly, you risk data loss because these pending chunks are discarded.

Orchestrating a Graceful Flush

To handle the end-of-life of a stream correctly, you must stop accepting new incoming data while allowing the existing pipeline to "finish" its current tasks. This is a two-step handshake:

1. Signal the source to stop: Stop your upstream ingestion (e.g., stop reading from the database or socket).
2. End the stream: Call .end() on your writable stream to signal that no more data will be written.

Node.js streams handle this via the finish event, which fires only after all data has been successfully flushed to the underlying system.

Example: Flushing to a File

const writable = createWriteStream('data.log');

process.on('SIGTERM', () => {
  console.log('Shutting down... flushing buffers.');
  
  // 1. End the stream to signal no more data
  writable.end();

  // 2. Wait for the 'finish' event to confirm data is written
  writable.on('finish', () => {
    console.log('All data flushed. Safe to exit.');
    process.exit(0);
  });
});

By listening for the finish event, you create a synchronization barrier that prevents the process from dying while the kernel is still busy committing your stream's final bytes to disk. This pattern ensures that your "end-of-life" strategy is predictable and data-safe, even during high-volume operations where buffers are frequently filled to capacity.

Key Takeaway: Never terminate a stream-based process immediately; always signal the stream to end and wait for the finish event to ensure all buffered data is safely committed.