# roaring

> CRoaring official port for NodeJS

Latest version **2.7.0** (published 2025-12-19) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install roaring
pnpm add roaring
yarn add roaring
bun add roaring
```

## Health

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

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

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.7.0 |
| Published | 2025-12-19 |
| First published | 2018-05-31 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=18.20.8 |
| Dependencies | 1 |
| Unpacked size | 1.3 MB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 139 |
| Author | Salvatore Previti |
| Maintainers | salvatorepreviti |
| Keywords | CRoaring, Roaring, bitmaps |

## Links

- npm: https://www.npmjs.com/package/roaring
- Repository: https://github.com/SalvatorePreviti/roaring-node
- Homepage: https://github.com/SalvatorePreviti/roaring-node#readme
- Issues: https://github.com/SalvatorePreviti/roaring/issues
- npm.io page: https://npm.io/package/roaring

## Dependencies (1)

- [@mapbox/node-pre-gyp](https://npm.io/package/@mapbox/node-pre-gyp.md) ^2.0.3

## Recent versions

- 2.7.0 (latest) — 2025-12-19
- 2.6.0 — 2025-10-21
- 2.5.0 — 2025-10-17
- 2.4.0 — 2024-09-18
- 2.3.0 — 2024-02-29
- 2.2.0 — 2023-06-08
- 2.1.1 — 2023-05-17
- 2.1.0 — 2023-05-13
- 2.0.1 — 2023-04-25
- 2.0.0 — 2023-04-25
- 1.5.2 — 2023-03-09
- 1.4.4 — 2023-02-21
- 1.4.3 — 2023-02-12
- 1.4.2 — 2023-02-05
- 1.4.1 — 2023-02-03
- … 29 more at https://npm.io/package/roaring/versions

## README

# roaring

Official port of [Roaring Bitmaps](http://roaringbitmap.org) for NodeJS as a native addon.

It is interoperable with other implementations via the [Roaring format](https://github.com/RoaringBitmap/RoaringFormatSpec/).
It takes advantage of AVX2 or SSE4.2 instructions on 64 bit platforms that supports it.

Roaring bitmaps are compressed bitmaps. They can be hundreds of times faster.

For a precompiled binary of this package compatible with AWS Lambda NodeJS v8.10.0, use [roaring-aws](https://www.npmjs.com/package/roaring-aws).

## Supported node versions

Node 20, 22, 24, 25 are currently supported.

Node 8 and 10 support was dropped in release 2.0

Node 12 and 14 support was dropped in release 2.3

Node 16 and 21 support was dropped in release 2.6

Node 18 support was dropped in release 2.7

## Worker thread support

Directly transferring an instance without copy between worker threads is not currently supported, but you can create a frozen view on a SharedArrayBuffer using bufferAlignedAllocShared and pass it to the worker thread.

## Installation

```sh
npm install --save roaring
```

### Linux libc variants

Prebuilt binaries are now published separately for `glibc` and `musl` targets. When running on Alpine or any other musl-based distribution the installer will request the `-musl` artifact; on other Linux distributions it will request the `-glibc` build. If a matching build is not available `npm install` falls back to compiling from source, so ensure the usual build toolchain is present.

## References

- This package - <https://www.npmjs.com/package/roaring>
- Source code and build tools for this package - <https://github.com/SalvatorePreviti/roaring-node>
- Roaring Bitmaps - <http://roaringbitmap.org/>
- Portable Roaring bitmaps in C - <https://github.com/RoaringBitmap/CRoaring>
- Portable Roaring bitmaps in C (unity build) - https://github.com/lemire/CRoaringUnityBuild

# Licenses

- This package is provided as open source software using Apache License.
- CRoaring is provided as open source software using Apache License.

# API

See the [roaring module documentation](https://salvatorepreviti.github.io/roaring-node/modules.html)

See the [RoaringBitmap32 class documentation](https://salvatorepreviti.github.io/roaring-node/classes/RoaringBitmap32.html)

# Code sample:

```javascript
// npm install --save roaring
// create this file as demo.js
// type node demo.js

const RoaringBitmap32 = require("roaring/RoaringBitmap32");

const bitmap1 = new RoaringBitmap32([1, 2, 3, 4, 5]);
bitmap1.addMany([100, 1000]);
console.log("bitmap1.toArray():", bitmap1.toArray());

const bitmap2 = new RoaringBitmap32([3, 4, 1000]);
console.log("bitmap2.toArray():", bitmap2.toArray());

const bitmap3 = new RoaringBitmap32();
console.log("bitmap1.size:", bitmap1.size);
console.log("bitmap3.has(3):", bitmap3.has(3));
bitmap3.add(3);
console.log("bitmap3.has(3):", bitmap3.has(3));

bitmap3.add(111);
bitmap3.add(544);
bitmap3.orInPlace(bitmap1);
bitmap1.runOptimize();
bitmap1.shrinkToFit();
console.log("contentToString:", bitmap3.contentToString());

console.log("bitmap3.toArray():", bitmap3.toArray());
console.log("bitmap3.maximum():", bitmap3.maximum());
console.log("bitmap3.rank(100):", bitmap3.rank(100));

const iterated = [];
for (const value of bitmap3) {
  iterated.push(value);
}
console.log("iterated:", iterated);

const serialized = bitmap3.serialize(false);
console.log("serialized:", serialized.toString("base64"));
console.log(
  "deserialized:",
  RoaringBitmap32.deserialize(serialized, false).toArray()
);
```

# Other

Wanna play an open source game made by the author of this library? Try [Dante](https://github.com/SalvatorePreviti/js13k-2022)

# Development, local building

Clone the repository and install all the dependencies

```
git clone https://github.com/SalvatorePreviti/roaring-node.git

cd roaring-node

npm install
```

# To rebuild the roaring unity build updating to the latest version

```
./scripts/update-roaring.sh

npm run build

```

### To run the unit test

```
npm test
```

### To regenerate the API documentation

```
npm run doc
```

### To run the performance benchmarks

```sh
npm run benchmarks
```

It will produce a result similar to this one:

```
Platform : Darwin 17.6.0 x64
CPU      : Intel(R) Core(TM) i7-7700HQ CPU @ 2.80GHz AVX2
Cores    : 4 physical - 8 logical
Memory   : 16.00 GB
NodeJS   : v10.5.0 - V8 v6.7.288.46-node.8

* running 8 files...

• suite intersection (in place)
  65536 elements
  ✔ Set                  186.82 ops/sec  ±2.33%  66 runs  -99.98%
  ✔ FastBitSet       100,341.63 ops/sec  ±2.10%  85 runs  -87.10%
  ✔ RoaringBitmap32  777,765.97 ops/sec  ±2.14%  87 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite intersection (new)
  1048576 elements
  ✔ Set                  3.49 ops/sec   ±3.82%  13 runs  -99.89%
  ✔ FastBitSet       1,463.87 ops/sec   ±1.13%  84 runs  -55.54%
  ✔ RoaringBitmap32  3,292.51 ops/sec  ±20.89%  44 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite add
  65535 elements
  ✔ Set.add                                438.37 ops/sec  ±4.48%  68 runs  -85.21%
  ✔ RoaringBitmap32.tryAdd                 489.70 ops/sec  ±3.19%  76 runs  -83.48%
  ✔ RoaringBitmap32.add                    528.09 ops/sec  ±3.38%  76 runs  -82.18%
  ✔ RoaringBitmap32.addMany Array        1,652.62 ops/sec  ±4.20%  64 runs  -44.25%
  ✔ RoaringBitmap32.addMany Uint32Array  2,964.19 ops/sec  ±1.47%  86 runs  fastest
  ➔ Fastest is RoaringBitmap32.addMany Uint32Array

• suite iterator
  65536 elements
  ✔ Set              1,648.55 ops/sec  ±1.21%  86 runs  fastest
  ✔ RoaringBitmap32  1,239.06 ops/sec  ±1.62%  86 runs  -24.84%
  ➔ Fastest is Set

• suite intersection size
  262144 elements
  ✔ Set                   29.10 ops/sec  ±5.65%  51 runs  -99.99%
  ✔ FastBitSet        15,938.45 ops/sec  ±2.01%  86 runs  -94.09%
  ✔ RoaringBitmap32  269,502.51 ops/sec  ±2.08%  84 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite union (in place)
  65536 elements
  ✔ Set                  298.53 ops/sec  ±3.07%  65 runs  -99.97%
  ✔ FastBitSet       144,914.65 ops/sec  ±2.10%  75 runs  -83.38%
  ✔ RoaringBitmap32  871,794.31 ops/sec  ±3.85%  82 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite union size
  262144 elements
  ✔ Set                   17.69 ops/sec  ±3.40%  33 runs  -99.99%
  ✔ FastBitSet         8,481.07 ops/sec  ±1.54%  84 runs  -97.02%
  ✔ RoaringBitmap32  284,749.52 ops/sec  ±1.35%  86 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite union (new)
  1048576 elements
  ✔ Set                  1.83 ops/sec   ±6.60%   9 runs  -99.90%
  ✔ FastBitSet         744.68 ops/sec   ±1.11%  85 runs  -60.45%
  ✔ RoaringBitmap32  1,882.93 ops/sec  ±16.32%  44 runs  fastest
  ➔ Fastest is RoaringBitmap32


* completed: 53610.279ms
```

Works also on M1

````
Platform : Darwin 21.1.0 arm64
CPU      : Apple M1 Pro
Cores    : 10 physical - 10 logical
Memory   : 16.00 GB
NodeJS   : v16.13.1 - V8 v9.4.146.24-node.14

* running 8 files...

• suite union (in place)
  65536 elements
  ✔ Set                    456.60 ops/sec  ±1.88%  77 runs  -99.97%
  ✔ FastBitSet         232,794.03 ops/sec  ±0.94%  91 runs  -86.52%
  ✔ RoaringBitmap32  1,727,310.24 ops/sec  ±1.12%  95 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite intersection size
  262144 elements
  ✔ Set                   71.20 ops/sec  ±2.30%  62 runs  -99.98%
  ✔ FastBitSet        21,525.29 ops/sec  ±0.71%  97 runs  -93.72%
  ✔ RoaringBitmap32  342,892.37 ops/sec  ±0.93%  95 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite intersection (in place)
  65536 elements
  ✔ Set                    280.62 ops/sec  ±1.66%  76 runs  -99.97%
  ✔ FastBitSet         136,148.03 ops/sec  ±0.56%  96 runs  -87.11%
  ✔ RoaringBitmap32  1,055,978.14 ops/sec  ±1.16%  92 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite union size
  262144 elements
  ✔ Set                   37.95 ops/sec  ±2.33%  51 runs  -99.99%
  ✔ FastBitSet        12,111.37 ops/sec  ±0.67%  96 runs  -96.35%
  ✔ RoaringBitmap32  331,510.04 ops/sec  ±1.02%  95 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite intersection (new)
  1048576 elements
  ✔ Set                  6.54 ops/sec  ±5.41%  21 runs  -99.93%
  ✔ FastBitSet       2,087.94 ops/sec  ±5.23%  42 runs  -78.88%
  ✔ RoaringBitmap32  9,888.24 ops/sec  ±1.77%  51 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite union (new)
  1048576 elements
  ✔ Set                  3.80 ops/sec  ±7.91%  14 runs  -99.93%
  ✔ FastBitSet       1,693.77 ops/sec  ±3.90%  64 runs  -70.63%
  ✔ RoaringBitmap32  5,767.35 ops/sec  ±1.74%  51 runs  fastest
  ➔ Fastest is RoaringBitmap32

• suite iterator
  65536 elements
  ✔ Set.iterator              10,033.75 ops/sec  ±1.40%  92 runs  fastest
  ✔ Set.forEach                1,595.08 ops/sec  ±2.02%  89 runs  -84.10%
  ✔ RoaringBitmap32.iterator   2,879.57 ops/sec  ±1.06%  93 runs  -71.30%
  ✔ RoaringBitmap32.forEach    1,764.98 ops/sec  ±0.68%  97 runs  -82.41%
  ➔ Fastest is Set.iterator

• suite add
  65535 elements
  ✔ Set.add                                508.76 ops/sec  ±1.27%   86 runs  -91.37%
  ✔ RoaringBitmap32.tryAdd                 707.70 ops/sec  ±0.81%   96 runs  -87.99%
  ✔ RoaringBitmap32.add                    699.27 ops/sec  ±1.08%   90 runs  -88.13%
  ✔ RoaringBitmap32.addMany Array        4,457.70 ops/sec  ±0.54%   90 runs  -24.35%
  ✔ RoaringBitmap32.addMany Uint32Array  5,892.57 ops/sec  ±0.07%  101 runs  fastest
  ➔ Fastest is RoaringBitmap32.addMany Uint32Array


* completed: 27.170s```

````

## Branches

Branch `publish` contains the latest published stable version.

Branch `master` is the development branch that may contain code not yet published or ready for production.
If you want to contribute and submit a pull request, use the master branch.

## For collaborators

To release a new version:

- To update to the latest version of CRoaring run `./scripts/update-roaring.sh`, this will pull the CRoaring as submodule to its latest version from CRoaring dev branch.
- Ensure the version is manually increased in `package.json`
- Locally, run `npm run build` and `npm run doc` to generate the final C source and generate the doc
- Be sure `master` contains all the changes, and all is pushed.
- Merge `master` into `publish` with a pull request, this will create a new release and prebuild and publish all the binaries for the new release. This will also update the docs.
- Verify that the github action `Publish` went well and is completed. This action is triggered by any change in `publish` branch.
- Go to https://github.com/SalvatorePreviti/roaring-node/releases and verify the release is present and published
- Run manually the github action `publish to npm` via the Button in the actions page only if all the previous steps were successful

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