# it-reader

> Read an exact number of bytes from a binary (async) iterable

Latest version **7.0.0** (published 2026-05-07) · Apache-2.0 OR MIT license · 0 weekly downloads

## Install

```sh
npm install it-reader
pnpm add it-reader
yarn add it-reader
bun add it-reader
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 7.0.0 |
| Published | 2026-05-07 |
| First published | 2019-08-07 |
| Weekly downloads | 0 |
| License | Apache-2.0 OR MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 55.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Author | Alan Shaw |
| Maintainers | achingbrain, alanshaw |
| Keywords | async, binary, buffer, it, iterable, iterator, read, stream |

## Links

- npm: https://www.npmjs.com/package/it-reader
- Repository: https://github.com/alanshaw/it-reader
- Homepage: https://github.com/alanshaw/it-reader#readme
- Issues: https://github.com/alanshaw/it-reader/issues
- npm.io page: https://npm.io/package/it-reader

## Dependencies (2)

- [uint8arraylist](https://npm.io/package/uint8arraylist.md) ^3.0.1
- [it-stream-types](https://npm.io/package/it-stream-types.md) ^2.0.1

## Alternatives

- [byte-size](https://npm.io/package/byte-size.md) — 2.1M weekly downloads
- [speed-limiter](https://npm.io/package/speed-limiter.md) — 16.0K weekly downloads
- [@powersync/node](https://npm.io/package/@powersync/node.md) — 10.9K weekly downloads
- [@ledgerhq/coin-cardano](https://npm.io/package/@ledgerhq/coin-cardano.md) — 1.0K weekly downloads
- [@jayesol/jayeson.lib.streamfinder](https://npm.io/package/@jayesol/jayeson.lib.streamfinder.md) — 1.0K weekly downloads

## Recent versions

- 7.0.0 (latest) — 2026-05-07
- 6.0.5 — 2026-05-07
- 6.0.4 — 2023-04-19
- 6.0.3 — 2023-04-18
- 6.0.2 — 2022-12-22
- 6.0.1 — 2022-07-28
- 6.0.0 — 2022-07-28
- 5.0.2 — 2022-07-28
- 5.0.1 — 2022-03-08
- 5.0.0 — 2022-02-16
- 4.0.2 — 2022-01-13
- 4.0.1 — 2022-01-13
- 4.0.0 — 2022-01-13
- 3.0.0 — 2021-04-08
- 2.1.0 — 2020-01-06
- … 2 more at https://npm.io/package/it-reader/versions

## README

# it-reader <!-- omit in toc -->

[![codecov](https://img.shields.io/codecov/c/github/alanshaw/it-reader.svg?style=flat-square)](https://codecov.io/gh/alanshaw/it-reader)
[![CI](https://img.shields.io/github/actions/workflow/status/alanshaw/it-reader/js-test-and-release.yml?branch=master\&style=flat-square)](https://github.com/alanshaw/it-reader/actions/workflows/js-test-and-release.yml?query=branch%3Amaster)

> Read an exact number of bytes from a binary (async) iterable

## Table of contents <!-- omit in toc -->

- [Install](#install)
  - [Browser `<script>` tag](#browser-script-tag)
- [Usage](#usage)
- [API](#api)
  - [`reader(source)`](#readersource)
    - [Parameters](#parameters)
    - [Returns](#returns)
- [Contribute](#contribute)
- [API Docs](#api-docs)
- [License](#license)
- [Contribution](#contribution)

## Install

```console
$ npm i it-reader
```

### Browser `<script>` tag

Loading this module through a script tag will make it's exports available as `ItReader` in the global namespace.

```html
<script src="https://unpkg.com/it-reader/dist/index.min.js"></script>
```

## Usage

```js
import { reader } from 'it-reader'

const stream = reader(source) // source is any iterable or async iterable
const { value, done } = await stream.next(8)

// NOTE: value is a BufferList (https://npm.im/bl)
console.log(value.toString())

// Now read 16 more bytes:
await stream.next(16)

// or...
// Consume the rest of the stream

for await (const chunk of stream) {
  console.log(chunk.toString())
}
```

## API

```js
import { reader } from 'it-reader'
```

### `reader(source)`

Create and return a new reader.

#### Parameters

- `source` (`Iterable`) - An [iterable or async iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) that yields [`Buffer`](https://npm.im/buffer) or [`BufferList`](https://npm.im/bl) objects.

#### Returns

An [async iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol) that yields [`BufferList`](https://npm.im/bl) objects.

The iterator's `next` method takes an *optional* parameter - the number of bytes to read from the `source`.

If the number of bytes to read are not specified, the iterator will yield any bytes remaining in the internal buffer or the next available chunk.

If the number of bytes to read exceeds the number of bytes available in the source the iterator will throw and error with a `code` property set to `'ERR_UNDER_READ'` and a `buffer` property (the bytes read so far, if any), which is a [`BufferList`](https://npm.im/bl) instance.

## Contribute

Feel free to dive in! [Open an issue](https://github.com/alanshaw/it-reader/issues/new) or submit PRs.

## API Docs

- <https://alanshaw.github.io/it-reader>

## License

Licensed under either of

- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

---
_Source: https://npm.io/package/it-reader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._