https://github.com/borewit/read-next-line
Utility for reading lines from a `ReadableStream` in JavaScript
https://github.com/borewit/read-next-line
bom esm line promise read stream stream-api streamreadable text utf-16
Last synced: 4 months ago
JSON representation
Utility for reading lines from a `ReadableStream` in JavaScript
- Host: GitHub
- URL: https://github.com/borewit/read-next-line
- Owner: Borewit
- Created: 2025-01-13T19:58:20.000Z (12 months ago)
- Default Branch: master
- Last Pushed: 2025-04-07T06:51:32.000Z (9 months ago)
- Last Synced: 2025-06-09T09:15:37.693Z (7 months ago)
- Topics: bom, esm, line, promise, read, stream, stream-api, streamreadable, text, utf-16
- Language: JavaScript
- Homepage:
- Size: 269 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://github.com/Borewit/read-next-line/actions/workflows/nodejs-ci.yml)
[](https://npmjs.org/package/read-next-line)
[](https://npmcharts.com/compare/read-next-line)
# `read-next-line`
Is s a lightweight, efficient utility for reading lines from a [ReadableStream](https://developer.mozilla.org/docs/Web/API/ReadableStream) in JavaScript.
The primary goal of this module is to enable memory-efficient line-by-line processing of large data streams,
such as logs, files, or real-time data feeds.
## Features
- **Line-based processing**: Reads lines directly from any [ReadableStream](https://developer.mozilla.org/docs/Web/API/ReadableStream).
- **Memory efficiency**: Keeps memory usage low by processing one line at a time.
- **Browser compatibility**: Works seamlessly with modern web browsers.
- **Node.js compatibility**: Works seamlessly with [Node.js Web Streams API](https://nodejs.org/api/webstreams.html#web-streams-api).
- Supports the following **text encoding**:
- UTF-8 (default)
- UTF-8 with the BOM field set
- UTF-16LE with the BOM field is set
- UTF-16BE with the BOM field is set
- Supports different [line endings](https://en.wikipedia.org/wiki/Newline):
| Type | Abbreviation | Escape sequence |
|---------------------|--------------|-----------------|
| Windows | `CR LF` | `\r\n` |
| Unix | `LF` | `\n` |
| Acorn BBC / RISC OS | `LF CR` | `\n\r` |
| classic Mac OS | `CR` | `\r` |
## Installation
Install the package via npm:
```bash
npm install read-next-line
```
## Compatibility
**read-next-line** is a hybrid JavaScript module, supporting:
- ECMAScript Module (ESM)
- CommonJS backwards compatibility support
Designed to work with Works seamlessly with either:
- [Node.js Readable streams](https://nodejs.org/api/stream.html#readable-streams)
- [Node.js Web Streams API](https://nodejs.org/api/webstreams.html#web-streams-api)
- [Streams-API](https://developer.mozilla.org/docs/Web/API/Streams_API) in the browser
Compatible with modern web browsers or Node.js ≥ 18.
## Usage
Import and use `StreamLineReader` in your project:
In ESM projects or any TypeScript project use:
```js
import {ReadNextLine} from 'read-next-line';
```
In CommonJS projects use:
```js
const {ReadNextLine} = require('read-next-line');
```
Using **read-next-line** to read lines of text of a binary [ReadableStream](https://developer.mozilla.org/docs/Web/API/ReadableStream) or [Node.js Readable streams](https://nodejs.org/api/stream.html#readable-streams):
```js
async function processStream(stream) {
const reader = new ReadNextLine(stream);
let line;
while ((line = await reader.readLine()) !== null) {
console.log(line); // Process each line as needed
}
}
```
You may as well use the `LineSplitter` which is a [`TransformStream`](https://developer.mozilla.org/docs/Web/API/TransformStream),
converting a binary stream into stream of lines (strings).
```js
import {LineSplitter} from 'read-next-line';
const lineStream = webStream.pipeThrough(lineSplitter);
const lineReader = lineStream.getReader();
```
### Parsing a Blob/File
To process a file input, wrap the file's stream with `ReadNextLine`:
```js
async function proccessTextFile(blob) {
const reader = new ReadNextLine(blob.stream());
try {
let line;
do {
line = await reader.readLine();
console.log(line);
}
while (line !== null);
} finally {
reader.release();
}
}
const file = document.querySelector('#fileInput').files[0];
proccessTextFile(file);
```
Online example can be found here: https://playcode.io/2226348
## API
### `StreamLineReader` Class
#### Constructor
```ts
new StreamLineReader(stream: ReadableStream);
```
- **stream**: The `ReadableStream` to process.
#### Methods
- **`readLine(): Promise`**
- Reads the next line from the stream. Returns `null` if the stream ends.
- **`release(): void`**
- Release the internal [Reader](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultReader/releaseLock).
## License
This project is licensed under the MIT License. Feel free to use, modify, and distribute as needed.