Level Read Stream

Common errors

• TypeError: db.iterator is not a function

  cause Attempting to use `level-read-stream` v2.x with an `abstract-level` v1.x compatible database instance.
  fix Upgrade your database package (e.g., `level`, `memdown`) to a version that implements `abstract-level` v2 or higher.

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/level-read-stream/index.js from ... not supported.

  cause Attempting to use `require()` to import `level-read-stream` in an environment configured for pure ESM, or when `level-read-stream` itself becomes pure ESM in a future major version (not currently true for v2).
  fix Change your import statement to `import { EntryStream } from 'level-read-stream';` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

• TypeError: EntryStream is not a constructor

  cause Incorrect import statement when using CommonJS, attempting `const EntryStream = require('level-read-stream')` instead of destructuring.
  fix Use `const { EntryStream } = require('level-read-stream');` to correctly destructure the named export.

• TS2307: Cannot find module '@types/readable-stream' or its corresponding type declarations.

  cause Missing TypeScript type definitions for the `readable-stream` package when using `level-read-stream` in a TypeScript project.
  fix Install the types package: `npm install --save-dev @types/readable-stream`.

Warnings

• breaking Version 2.0.0 drops support for `abstract-level` v1. Users must upgrade their underlying `abstract-level` implementation to `>=2.0.0`.
  Fix: Ensure your database package (e.g., `level`, `memdown`) is updated to a version compatible with `abstract-level@2`.
• breaking Version 2.0.0 updated its internal `readable-stream` dependency from v3 to v4. While largely compatible, this might introduce subtle behavioral changes or require adjustments if your project relies on specific `readable-stream` v3 internals.
  Fix: Review your stream pipeline for compatibility with `readable-stream` v4 behavior, especially if you have custom `_read` or `_write` implementations.
• gotcha For TypeScript users, in addition to installing `level-read-stream`, you must also install `@types/readable-stream` to get proper type definitions for Node.js's stream API.
  Fix: Run `npm install --save-dev @types/readable-stream`.
• gotcha If migrating from older `levelup` or `level <= 7` versions, consult the `UPGRADING.md` file in the package's GitHub repository for specific migration steps and considerations.
  Fix: Refer to `https://github.com/Level/read-stream/blob/main/UPGRADING.md` for detailed instructions.
• gotcha While `EntryStream` provides a stream interface, for consuming database entries using `for await...of` syntax, it is generally recommended to directly use `db.iterator()` as it offers a more idiomatic async iteration pattern.
  Fix: Consider `for await (const entry of db.iterator(options))` instead of piping `EntryStream` for simple async iteration.

Install

• npm install level-read-stream npm
• yarn add level-read-stream yarn
• pnpm add level-read-stream pnpm

Imports

• EntryStream
  wrong:

  const EntryStream = require('level-read-stream').EntryStream

  correct:

  import { EntryStream } from 'level-read-stream'

  For ESM projects, use named import. CommonJS `require` still works but destructuring is crucial.
• KeyStream
  wrong:

  import KeyStream from 'level-read-stream'

  correct:

  import { KeyStream } from 'level-read-stream'

  All stream classes are named exports. Default import will not work.
• ValueStream
  wrong:

  const { ValueStream } = require('level-read-stream')

  correct:

  import { ValueStream } from 'level-read-stream'

  When using CommonJS, ensure you destructure the specific stream class from the `require` call.

Quickstart

This example demonstrates how to create an `EntryStream` to read key-value pairs from an `abstract-level` database, filter by a starting key (`gte: 'b'`), and pipe the results to a writable stream for processing, logging each entry.

import { EntryStream } from 'level-read-stream';
import { Writable, pipeline } from 'readable-stream';
import { Level } from 'level'; // Assuming 'level' or similar abstract-level implementation

async function runExample() {
  const db = new Level('./mydb');

  await db.put('a', '1');
  await db.put('b', '2');
  await db.put('c', '3');

  const src = new EntryStream(db, { gte: 'b' });

  const dst = new Writable({
    objectMode: true,
    write(entry, _, next) {
      console.log('Entry: %s: %s', entry.key, entry.value);
      next();
    }
  });

  // Using pipeline with a callback for error handling and stream completion
  pipeline(src, dst, (err) => {
    if (err) {
      console.error('Pipeline failed.', err);
    } else {
      console.log('Pipeline succeeded.');
    }
    db.close(); // Close the database after stream operations
  });
}

runExample().catch(console.error);