bare-stream

Common errors

• TypeError: stream.pipe is not a function

  cause Attempting to use `.pipe()` on an object that is not a bare-stream (or streamx-compatible) instance, or on an instance that has been incorrectly initialized.
  fix Ensure that the object you are calling `.pipe()` on is an instance of `bare-stream.Readable` or `bare-stream.Transform`. Verify imports and constructor calls.

• ERR_STREAM_WRITE_AFTER_END: write after end

  cause Attempting to write data to a Writable or Transform stream after its `end()` method has been called or a `null` chunk has been pushed, signifying the end of the writable side.
  fix Check your logic for when data is being written to the stream. Ensure that no `write()` calls occur after `stream.end()` or after `this.push(null)` in a `Transform` stream, unless specifically designed for that behavior.

• ReferenceError: Readable is not defined

  cause The `Readable` class (or Writable, Transform) was not correctly imported or required into the scope before being used.
  fix Add `import { Readable } from 'bare-stream'` (for ESM) or `const { Readable } = require('bare-stream')` (for CJS) at the top of your file to make the class available.

Warnings

• gotcha bare-stream's API closely mirrors `streamx` which has subtle differences from Node.js's built-in `stream` module. Developers accustomed to Node.js streams should review `streamx` documentation to understand variations in constructor options, `_read`/`_write` signatures, and backpressure handling.
  Fix: Consult the `streamx` documentation for precise API details and migration guides. Be mindful of differences in `highWaterMark` behavior and `_read` implementation.
• breaking While v2.13.0 introduced `Web TransformStream` creation, prior versions might not fully support Web Streams API compatibility. Projects targeting browser environments or Web Streams might encounter unexpected behavior on older versions.
  Fix: Upgrade to `bare-stream@2.13.0` or higher to leverage improved Web TransformStream compatibility. Thoroughly test stream implementations in target browser environments.
• gotcha Failing to handle stream errors can lead to unhandled promise rejections or silent failures, potentially causing resource leaks or stalled pipelines. Each stream in a pipeline can emit an 'error' event independently.
  Fix: Always attach an 'error' event listener to every stream in your pipeline. For complex pipelines, consider using `pipeline` from 'node:stream/promises' (or a compatible utility) for automatic error propagation and resource cleanup.
• gotcha Incorrect backpressure management in stream implementations can lead to memory exhaustion when a producer stream overwhelms a slower consumer. This is especially critical in high-throughput scenarios.
  Fix: Ensure your custom `_read` and `_write` implementations correctly respect the `callback` argument. For `Readable` streams, `_read` should only push data when `push` returns `true` or when explicitly called after a `_read` trigger. For `Writable` streams, `callback` should be invoked only after the chunk is fully processed.

Install

• npm install bare-stream npm
• yarn add bare-stream yarn
• pnpm add bare-stream pnpm

Imports

• Readable
  wrong:

  const Readable = require('bare-stream').Readable

  correct:

  import { Readable } from 'bare-stream'

  While CommonJS `require` is supported, named ESM imports are the recommended modern pattern for tree-shaking and future compatibility. Type declarations are automatically picked up by TypeScript when using named imports.
• Writable
  wrong:

  import Writable from 'bare-stream/writable'

  correct:

  import { Writable } from 'bare-stream'

  All core stream classes (Readable, Writable, Transform) are exported directly from the top-level 'bare-stream' package. Avoid importing from internal paths unless explicitly documented, as they are subject to change.
• Transform
  wrong:

  const { Transform } = require('bare-stream'); // Typo or wrong destructuring

  correct:

  import { Transform } from 'bare-stream'

  When using CommonJS, ensure correct destructuring. For TypeScript, import directly from the package to leverage type definitions effectively.

Quickstart

This example demonstrates creating a basic streaming pipeline using `bare-stream`. It shows a `Readable` stream generating data, a `Transform` stream processing it, and a `Writable` stream consuming and logging the final output, including basic error handling.

import { Readable, Writable, Transform } from 'bare-stream';

class MyGenerator extends Readable {
  constructor(limit) {
    super();
    this.index = 0;
    this.limit = limit;
  }

  _read(size) {
    if (this.index < this.limit) {
      const chunk = `Data chunk ${this.index++}\n`;
      this.push(Buffer.from(chunk));
    } else {
      this.push(null); // Signal end of stream
    }
  }
}

class MyProcessor extends Transform {
  _transform(chunk, encoding, callback) {
    // Convert to uppercase and add a prefix
    this.push(Buffer.from(`PROCESSED: ${chunk.toString().toUpperCase()}`));
    callback();
  }
}

class MyConsumer extends Writable {
  _write(chunk, encoding, callback) {
    console.log(chunk.toString().trim());
    callback();
  }
}

const generator = new MyGenerator(3);
const processor = new MyProcessor();
const consumer = new MyConsumer();

generator.pipe(processor).pipe(consumer);

// Error handling is crucial for streams
generator.on('error', (err) => console.error('Generator error:', err));
processor.on('error', (err) => console.error('Processor error:', err));
consumer.on('error', (err) => console.error('Consumer error:', err));
consumer.on('finish', () => console.log('All data processed.'));