@jeange/roaring-wasm

A high-performance TypeScript/JavaScript library for Roaring Bitmap, powered by Rust and WebAssembly.

Features

• 🚀 High Performance: Powered by Rust's roaring crate, compiled to WebAssembly
• 📦 Zero Dependencies: Pure WASM, no native modules required
• 🎯 TypeScript First: Full TypeScript support with complete type definitions
• 🌐 Browser Ready: Works in all modern browsers
• 🔄 Full API Coverage: Exposes all common Roaring Bitmap operations

Installation

npm install @jeange/roaring-wasm
# or
yarn add @jeange/roaring-wasm
# or
pnpm add @jeange/roaring-wasm

Quick Start

import { RoaringBitmap32 } from '@jeange/roaring-wasm';

// Create a new bitmap
const bitmap = new RoaringBitmap32();

// Add values
bitmap.add(1);
bitmap.add(2);
bitmap.add(3);

// Check membership
console.log(bitmap.contains(2)); // true
console.log(bitmap.contains(5)); // false

// Get cardinality (number of elements)
console.log(bitmap.size()); // 3

// Set operations
const bitmap2 = new RoaringBitmap32();
bitmap2.add(2);
bitmap2.add(4);

const union = bitmap.or(bitmap2);
const intersection = bitmap.and(bitmap2);
const difference = bitmap.xor(bitmap2);

API Reference

Constructor

new RoaringBitmap32()

Creates a new empty Roaring Bitmap.

new RoaringBitmap32(values: number[])

Creates a new Roaring Bitmap from an array of values.

Basic Operations

add(value: number): boolean

Adds a value to the bitmap. Returns true if the value was not already present.

remove(value: number): boolean

Removes a value from the bitmap. Returns true if the value was present.

contains(value: number): boolean

Checks if a value is present in the bitmap.

size(): number

Returns the number of elements in the bitmap (cardinality).

isEmpty(): boolean

Returns true if the bitmap is empty.

Bulk Operations

addMany(values: number[]): void

Adds multiple values to the bitmap.

removeMany(values: number[]): void

Removes multiple values from the bitmap.

toArray(): number[]

Returns all values in the bitmap as a sorted array.

Set Operations

and(other: RoaringBitmap32): RoaringBitmap32

Returns a new bitmap containing elements present in both bitmaps (intersection).

or(other: RoaringBitmap32): RoaringBitmap32

Returns a new bitmap containing elements present in either bitmap (union).

xor(other: RoaringBitmap32): RoaringBitmap32

Returns a new bitmap containing elements present in exactly one of the bitmaps.

andNot(other: RoaringBitmap32): RoaringBitmap32

Returns a new bitmap containing elements present in this bitmap but not in the other.

In-Place Set Operations

andInPlace(other: RoaringBitmap32): void

In-place intersection.

orInPlace(other: RoaringBitmap32): void

In-place union.

xorInPlace(other: RoaringBitmap32): void

In-place symmetric difference.

Serialization

serialize(): Uint8Array

Serializes the bitmap to a byte array.

static deserialize(data: Uint8Array): RoaringBitmap32

Deserializes a bitmap from a byte array.

Iteration

min(): number | null

Returns the minimum value in the bitmap, or null if empty.

max(): number | null

Returns the maximum value in the bitmap, or null if empty.

[Symbol.iterator](): Iterator<number>

Makes the bitmap iterable with for...of loops.

Performance

Roaring Bitmaps are significantly faster and more memory-efficient than standard bitmaps or sets for:

• Sparse data (few integers set)
• Clustered data (integers close together)
• Set operations (AND, OR, XOR)

Browser Support

Supports all modern browsers with WebAssembly enabled:

• Chrome 57+
• Firefox 52+
• Safari 11+
• Edge 16+

Building from Source

Prerequisites

• Rust (https://rustup.rs/)
• wasm-pack (cargo install wasm-pack)
• Node.js 16+

Build Steps

# Clone the repository
git clone https://github.com/yourusername/roaring-wasm.git
cd roaring-wasm

# Install dependencies
npm install

# Build WASM module
npm run build:wasm

# Build TypeScript
npm run build

# Run tests
npm test

License

MIT License

Acknowledgments

• roaring-rs - The Rust Roaring Bitmap implementation
• wasm-pack - Tool for building WASM packages

References

• Roaring Bitmaps - Official Roaring Bitmap website
• Better bitmap performance with Roaring bitmaps - Original paper