# @codedread/bitjs

> Binary Tools for JavaScript

Latest version **1.2.6** (published 2026-03-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @codedread/bitjs
pnpm add @codedread/bitjs
yarn add @codedread/bitjs
bun add @codedread/bitjs
```

## Health

**Score 60/100 (C)** — status: stable.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.6 |
| Published | 2026-03-19 |
| First published | 2020-04-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 701.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 86 |
| Author | Jeff Schiller |
| Maintainers | codedread |
| Keywords | binary, javascript, archive, file, image, pkzip, zip, rar, tar, gzip, unzip, unrar, untar, gunzip, gif, jpeg, png, webp, codecs, mp4, avc, webm |

## Links

- npm: https://www.npmjs.com/package/@codedread/bitjs
- Repository: https://github.com/codedread/bitjs
- Issues: https://github.com/codedread/bitjs/issues
- npm.io page: https://npm.io/package/@codedread/bitjs

## Alternatives

- [lodash.startswith](https://npm.io/package/lodash.startswith.md) — 769.7K weekly downloads
- [@tarojs/service](https://npm.io/package/@tarojs/service.md) — 33.9K weekly downloads
- [io.extendreality.tilia.indicators.spatialtargets.unity](https://npm.io/package/io.extendreality.tilia.indicators.spatialtargets.unity.md) — 131 weekly downloads
- [@rtarojs/taro](https://npm.io/package/@rtarojs/taro.md) — 90 weekly downloads
- [node-branch-io](https://npm.io/package/node-branch-io.md) — 50 weekly downloads

## Recent versions

- 1.2.6 (latest) — 2026-03-19
- 1.2.5 — 2025-10-05
- 1.2.3 — 2024-02-05
- 1.2.2 — 2024-01-27
- 1.2.1 — 2024-01-19
- 1.2.0 — 2024-01-15
- 1.1.7 — 2023-12-17
- 1.1.6 — 2023-10-26
- 1.1.5 — 2023-10-22
- 1.1.4 — 2023-10-20
- 1.1.3 — 2023-10-16
- 1.1.2 — 2023-09-30
- 1.1.1 — 2023-06-21
- 1.1.0 — 2023-05-28
- 1.0.11 — 2023-02-16
- … 11 more at https://npm.io/package/@codedread/bitjs/versions

## README

[![Node.js CI](https://github.com/codedread/bitjs/actions/workflows/node.js.yml/badge.svg)](https://github.com/codedread/bitjs/actions/workflows/node.js.yml)

# bitjs: Binary Tools for JavaScript

## Introduction

A set of dependency-free JavaScript modules to work with binary data in JS (using
[Typed Arrays](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)).
Includes:

  * bitjs/archive: Decompressing files (unzip, unrar, untar, gunzip) in JavaScript, implemented as
    Web Workers where supported, and allowing progressive unarchiving while streaming.
  * bitjs/codecs: Get the codec info of media containers in a ISO RFC6381 MIME type string.
  * bitjs/file: Detect the type of file from its binary signature.
  * bitjs/image: Parsing GIF, JPEG, PNG. Conversion of WebP to PNG or JPEG.
  * bitjs/io: Low-level classes for interpreting binary data (BitStream, ByteStream). For example,
    reading or peeking at N bits at a time.

## Installation

Install it using your favourite package manager, the package is registered under `@codedread/bitjs`.
```bash
npm install @codedread/bitjs
```
or
```bash
yarn add @codedread/bitjs
```

### CommonJS/ESM in Node

This module is an ES Module. If your project uses CommonJS modules, it's a little trickier to use.
One example of this is if a TypeScript project compiles to CommonJS, it will try to turn imports
into require() statements, which will break. The fix for this (unfortunately) is to update your
tsconfig.json:

```json
 "moduleResolution": "Node16",
```

and use a Dynamic Import:

```javascript
const { getFullMIMEString } = await import('@codedread/bitjs');
```

## Packages

### bitjs.archive

This package includes objects for decompressing and compressing binary data in popular archive
formats (zip, rar, tar, gzip). Here is a simple example of unrar:

#### Decompressing

```javascript
import { Unrarrer } from './bitjs/archive/decompress.js';
const unrar = new Unrarrer(rarFileArrayBuffer);
unrar.addEventListener('extract', (e) => {
  const {filename, fileData} = e.unarchivedFile;
  console.log(`Extracted ${filename} (${fileData.byteLength} bytes)`);
  // Do something with fileData...
});
unrar.addEventListener('finish', () => console.log('Done'));
unrar.start();
```

More details and examples are located on [the API page](./docs/bitjs.archive.md).

### bitjs.codecs

This package includes code for dealing with media files (audio/video). It is useful for deriving
ISO RFC6381 MIME type strings, including the codec information. Currently supports a limited subset
of MP4 and WEBM.

How to use:
  * First, install ffprobe (ffmpeg) on your system.
  * Then:
```javascript

import { getFullMIMEString } from 'bitjs/codecs/codecs.js';
/**
 * @typedef {import('bitjs/codecs/codecs.js').ProbeInfo} ProbeInfo
 */

const cmd = 'ffprobe -show_format -show_streams -print_format json -v quiet foo.mp4';
exec(cmd, (error, stdout) => {
  /** @type {ProbeInfo} */
  const info = JSON.parse(stdout);
  // 'video/mp4; codecs="avc1.4D4028, mp4a.40.2"'
  const contentType = getFullMIMEString(info);
  ...
});
```

### bitjs.file

This package includes code for dealing with files.  It includes a sniffer which detects the type of
file, given an ArrayBuffer.

```javascript
import { findMimeType } from './bitjs/file/sniffer.js';
const mimeType = findMimeType(someArrayBuffer);
```

### bitjs.image

This package includes code for dealing with image files.  It includes low-level, event-based
parsers for GIF, JPEG, and PNG images.

It also includes a module for converting WebP images into
alternative raster graphics formats (PNG/JPG), though this latter module is deprecated, now that
WebP images are well-supported in all browsers.

#### GIF Parser
```javascript
import { GifParser } from './bitjs/image/parsers/gif.js'

const parser = new GifParser(someArrayBuffer);
parser.onApplicationExtension(evt => {
  const appId = evt.detail.applicationIdentifier;
  const appAuthCode = new TextDecoder().decode(evt.detail.applicationAuthenticationCode);
  if (appId === 'XMP Data' && appAuthCode === 'XMP') {
    /** @type {Uint8Array} */
    const appData = evt.detail.applicationData;
    // Do something with appData (parse the XMP).
  }
});
parser.start();
```

#### JPEG Parser
```javascript
import { JpegParser } from './bitjs/image/parsers/jpeg.js'
import { ExifTagNumber } from './bitjs/image/parsers/exif.js';

const parser = new JpegParser(someArrayBuffer)
    .onApp1Exif(evt => console.log(evt.detail.get(ExifTagNumber.IMAGE_DESCRIPTION).stringValue));
await parser.start();
```

#### PNG Parser
```javascript
import { PngParser } from './bitjs/image/parsers/png.js'
import { ExifTagNumber } from './bitjs/image/parsers/exif.js';

const parser = new PngParser(someArrayBuffer);
    .onExifProfile(evt => console.log(evt.detail.get(ExifTagNumber.IMAGE_DESCRIPTION).stringValue))
    .onTextualData(evt => console.dir(evt.detail));
await parser.start();
```

#### WebP Converter
```javascript
import { convertWebPtoPNG, convertWebPtoJPG } from './bitjs/image/webp-shim/webp-shim.js';
// convertWebPtoPNG() takes in an ArrayBuffer containing the bytes of a WebP
// image and returns a Promise that resolves with an ArrayBuffer containing the
// bytes of an equivalent PNG image.
convertWebPtoPNG(webpBuffer).then(pngBuf => {
  const pngUrl = URL.createObjectURL(new Blob([pngBuf], {type: 'image/png'}));
  someImgElement.setAttribute(src, pngUrl);
});
```

### bitjs.io

This package includes stream objects for reading and writing binary data at the bit and byte level:
BitStream, ByteStream.

```javascript
import { BitStream } from './bitjs/io/bitstream.js';
const bstream = new BitStream(someArrayBuffer, true /** most-significant-bit-to-least */ );
const crc = bstream.readBits(12); // Read in 12 bits as CRC. Advance pointer.
const flagbits = bstream.peekBits(6); // Look ahead at next 6 bits. Do not advance pointer.
```

More details and examples are located on [the API page](./docs/bitjs.io.md).

## Reference

* [UnRar](http://codedread.github.io/bitjs/docs/unrar.html): A work-in-progress description of the
RAR file format.

## History

This project grew out of another project of mine, [kthoom](https://github.com/codedread/kthoom) (a
comic book reader implemented in the browser). This repository was automatically exported from
[my original repository on GoogleCode](https://code.google.com/p/bitjs) and has undergone
considerable changes and improvements since then.

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