WebAssembly port of Roaring Bitmaps for NodeJS. It is interoperable with other implementations via the Roaring format.
Roaring bitmaps are compressed bitmaps. They can be hundreds of times faster.
This project was born to use Roaring WASM in AWS Lambdas without the need to compile a node-gyp module. AWS Lambda supports node 8.10 and supports WASM.
npm install --save roaring-wasmTry it live - https://npm.runkit.com/roaring-wasm
Code sample:
// npm install --save roaring-wasm
// create this file as demo.js
// type node demo.js or nodejs demo.js depending on your system
var roaring = require("roaring-wasm");
var bitmap1 = new roaring.RoaringBitmap32()
bitmap1.addMany([1, 2, 3, 4, 5, 100, 1000])
console.log("bitmap1.toSet():",bitmap1.toSet())
var bitmap2 = new roaring.RoaringBitmap32()
bitmap2.addMany([3, 4, 1000])
console.log("bitmap2.toSet():",bitmap1.toSet())
var bitmap3 = new roaring.RoaringBitmap32()
console.log("bitmap1.cardinality():", bitmap1.cardinality())
console.log("bitmap2.contains(3):",bitmap2.contains(3))
bitmap3.add(111)
bitmap3.add(544)
bitmap3.orInPlace(bitmap1)
bitmap1.optimize()
console.log(bitmap3.toString())
console.log("bitmap3.toArray():",bitmap3.toArray())
console.log("bitmap3.maximum():",bitmap3.maximum())
console.log("bitmap3.rank(100):",bitmap3.rank(100))
bitmap1.dispose()
bitmap2.dispose()
bitmap3.dispose()This package - https://www.npmjs.com/package/roaring-wasm
Source code and build tools for this package - https://github.com/SalvatorePreviti/roaring-wasm
Roaring Bitmaps - http://roaringbitmap.org/
Portable Roaring bitmaps in C - https://github.com/RoaringBitmap/CRoaring
emscripten - https://github.com/kripken/emscripten/wiki
AWS Lambda - https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html
-
This package is provided as open source software using Apache License.
-
CRoaring is provided as open source software using Apache License.
-
RoaringBitmap32
- xorCardinality
- deserialize
- deserialize
- serializeArrayToNewBuffer
- deserializeToArray
- deserializeToSet
- isDisposed
- dispose
- throwIfDisposed
- cardinality
- isEmpty
- add
- addChecked
- addMany
- remove
- removeChecked
- maximum
- minimum
- contains
- isSubset
- isStrictSubset
- toRoaringUint32Array
- toArray
- toSet
- toUint32Array
- equals
- flipRange
- optimize
- select
- andCardinality
- orCardinality
- andNotCardinality
- andInPlace
- orInPlace
- xorInPlace
- andNotInPlace
- rank
- intersects
- jaccardIndex
- getSerializationSizeInBytes
- serializeToRoaringUint8Array
- serializeToUint8Array
- serializeToNodeBuffer
- RoaringUint32Array
- RoaringUint8Array
A Roaring Bitmap that supports 32 bit unsigned integers.
The roaring bitmap allocates in WASM memory, remember to dispose the RoaringBitmap32 when not needed anymore to release WASM memory.
Computes the size of the symmetric difference (xor) between two bitmaps. Both bitmaps are unchanged.
-
otherRoaringBitmap32
Returns number Cardinality of the symmetric difference (xor) of two bitmaps.
Creates a new roaring bitmap deserializing it from a buffer
The roaring bitmap allocates in WASM memory, remember to dispose the RoaringBitmap32 when not needed anymore to release WASM memory.
-
buffer(RoaringUint8Array | Uint8Array | Iterable<number>) The buffer to deserialize -
portableboolean If true, deserialization is compatible with the Java and Go versions of the library. If false, deserialization is compatible with the C version of the library. Default is false. (optional, defaultfalse) -
frozen(optional, defaultfalse)
Returns RoaringBitmap32 The reulting bitmap. Remember to dispose the instance when finished using it.
Reads a bitmap from a serialized version. Throws an error if deserialization failed.
-
buffer(RoaringUint8Array | Uint8Array | Iterable<number>) -
portableboolean If true, deserialization is compatible with the Java and Go versions of the library. If false, deserialization is compatible with the C version of the library. Default is false. (optional, defaultfalse) -
frozen(optional, defaultfalse)
Returns void
Utility function that serializes an array of uint32 to a new NodeJS buffer. The returned buffer is automatically garbage collected.
-
values(RoaringUint32Array | Iterable<number>) -
portableboolean If true, serialization is compatible with the Java and Go versions of the library. If false, serialization is compatible with the C version of the library. Default is false. (optional, defaultfalse)
Returns Buffer The NodeJS buffer containing the serialized data.
Utility function that deserializes a RoaringBitmap32 serialized in a buffer to an Array of values. The array can be very big, be careful when you use this function.
-
buffer(RoaringUint8Array | Uint8Array | Iterable<number>) The buffer to deserialize. -
portableboolean If true, deserialization is compatible with the Java and Go versions of the library. If false, deserialization is compatible with the C version of the library. Default is false. (optional, defaultfalse)
Returns Array<number> All the values in the bitmap.
Utility function that deserializes a RoaringBitmap32 serialized in a buffer to a Set of values. The array can be very big, be careful when you use this function.
-
buffer(RoaringUint8Array | Uint8Array | Iterable<number>) The buffer to deserialize. -
portableboolean If true, deserialization is compatible with the Java and Go versions of the library. If false, deserialization is compatible with the C version of the library. Default is false. (optional, defaultfalse)
Returns Array<number> All the values in the bitmap.
Returns true if this instance was disposed.
Type: boolean
Disposes this object freeing all WASM memory associated to it. Is safe to call this method more than once.
Returns boolean True if disposed during this call, false if not.
Throws an exception if this object was disposed before.
Returns (void | never)
Get the cardinality of the bitmap (number of elements).
Returns number Number of elements in this bitmap.
Returns true if the bitmap has no elements.
Returns boolean True if the bitmap is empty.
Adds a 32 bit unsigned integer value. Values are unique, this function does nothing if the value already exists.
-
valuenumber 32 bit unsigned integer to add in the set.
Adds a 32 bit unsigned integer value checking if the bitmap changes. Use add() if you don't need to know if something changed. Values are unique, this function does nothing and returns false if the value already exists.
-
valuenumber 32 bit unsigned integer to add in the set.
Returns boolean True if the bitmap changed, false if not.
Adds multiple values. Using this is faster than calling add() multiple times. Inserting ordered or partially ordered arrays is faster.
-
values(RoaringUint32Array | Iterable<number>) The values to add.
Removes a value from the set. If the value does not exists, this function does nothing.
-
valuenumber The value to remove.
Removes a value from the set checking if the bitmap changes. Use remove() if you don't need to know if something changed. If the value does not exists, this function does nothing and returns false.
-
valuenumber 32 bit unsigned integer to remove from the set.
Returns boolean True if the bitmap changed, false if not.
Gets the maximum value stored in the bitmap. If the bitmap is empty, returns 0.
Returns number The maximum 32 bit unsigned integer or 0 if empty.
Gets the minimum value stored in the bitmap. If the bitmap is empty, returns 0xFFFFFFFF
Returns number The minimum 32 bit unsigned integer or 0xFFFFFFFF if empty.
Checks whether the given value is contained in the set.
-
valuenumber The value to look for.
Returns boolean True if value exists in the set, false if not.
Returns true if the bitmap is subset of the other.
-
otherRoaringBitmap32 the other bitmap
Returns boolean
Returns true if this bitmap is strict subset of the other.
-
otherRoaringBitmap32 The other bitmap
Returns boolean True if this bitmap is a strict subset of other
Converts the bitmap to an array. The array may be very big, use this function with caution. The returned RoaringUint32Array is allocated in WASM memory and not garbage collected, it need to be freed manually calling dispose().
Returns RoaringUint32Array The RoaringUint32Array. Remember to manually dispose to free the memory.
Converts the bitmap to a JS array. The resulting array may be very big, use this function with caution.
Returns Array<number> The array containing all values in the bitmap.
Converts the bitmap to a JS Set. The resulting set may be very big, use this function with caution.
Returns Set<number> The set containing all values in the bitmap.
Converts the bitmap to a JS Uint32Array. The resulting array may be very big, use this function with caution.
Returns Uint32Array The array containing all values in the bitmap.
Checks wether two roaring bitmap contains the same data.
-
otherRoaringBitmap32
Returns boolean True if the bitmaps contains the same data, false if not.
Negates in place the bitmap within a specified interval. Areas outside the range are passed through unchanged.
Optimizes the bitmap releasing unused memory and compressing containers. Returns true if something changed.
Returns boolean True if something changed.
If the size of the roaring bitmap is strictly greater than rank, then this function returns the element of given rank. Otherwise, it returns NaN.
-
ranknumber Element rank
Returns number element or NaN
Computes the size of the intersection between two bitmaps. Both bitmaps are unchanged.
-
otherRoaringBitmap32
Returns number Cardinality of the intersection between two bitmaps.
Computes the size of the union of two bitmaps. Both bitmaps are unchanged.
-
otherRoaringBitmap32
Returns number Cardinality of the union of two bitmaps.
Computes the size of the difference (andnot) of two bitmaps. Both bitmaps are unchanged.
-
otherRoaringBitmap32
Returns number Cardinality of the difference (andnot) of two bitmaps.
Intersects this bitmap with another. Removes the elements from this bitmap that don't exists in the other. Stores the result in this bitmap. The provided bitmap is not modified.
-
otherRoaringBitmap32
Adds the element of the other bitmap into this bitmap. Stores the result in this bitmap. The provided bitmap is not modified.
-
otherRoaringBitmap32
Computes the difference between two bitmaps. Stores the result in this bitmap. The provided bitmap is not modified.
-
otherRoaringBitmap32
Compute the difference between this and the provided bitmap, writing the result in the current bitmap. The provided bitmap is not modified.
-
otherRoaringBitmap32
Returns the number of integers that are smaller or equal to the given value.
-
valuenumber The value to rank
Returns number The number of values smaller than the given value
Check whether the two bitmaps intersect (have at least one element in common).
-
otherRoaringBitmap32 The other bitmap.
Returns boolean True if the two bitmaps intersects, false if not.
Computes the Jaccard index between two bitmaps. (Also known as the Tanimoto distance, or the Jaccard similarity coefficient) See https://en.wikipedia.org/wiki/Jaccard_index
The Jaccard index is undefined if both bitmaps are empty.
other
Returns number The Jaccard index
How many bytes are required to serialize this bitmap.
-
portableboolean If true, deserialization is compatible with the Java and Go versions of the library. If false, deserialization is compatible with the C version of the library. Default is false. (optional, defaultfalse)
Serializes a bitmap to a byte buffer allocated in WASM memory.
The returned RoaringUint8Array is allocated in WASM memory and not garbage collected, it need to be freed manually calling dispose().
-
portableboolean If true, serialization is compatible with the Java and Go versions of the library. If false, serialization is compatible with the C version of the library. Default is false. (optional, defaultfalse)
Returns RoaringUint8Array The RoaringUint8Array. Remember to manually dispose to free the memory.
Serializes a bitmap to a typed Uint8Array. The returned array is automatically garbage collected and there is no need to be disposed manually.
-
portableboolean If true, serialization is compatible with the Java and Go versions of the library. If false, serialization is compatible with the C version of the library. Default is false. (optional, defaultfalse)
Returns Uint8Array The Uint8Array that contains the serialized bitmap
Serializes a bitmap to a NodeJS buffer. The returned buffer is automatically garbage collected and there is no need to be disposed manually.
-
portableboolean If true, serialization is compatible with the Java and Go versions of the library. If false, serialization is compatible with the C version of the library. Default is false. (optional, defaultfalse)
Returns Buffer The NodeJS Buffer that contains the serialized bitmap
Array of unsigned 32 bit integers allocted directly in roaring library WASM memory. Note: Memory is not garbage collected, you are responsible to free the allocated memory calling "dispose" method.
The type of typed array used by this class. For RoaringUint32Array is Uint32Array.
The type of typed array used by this class. For RoaringUint32Array is Uint32Array.
The size in bytes of each element in the array. For RoaringUint32Array is always 4
Type: number
The size in bytes of each element in the array. For RoaringUint32Array is always 4
Type: number
The ArrayBuffer instance referenced by the array. Note that the buffer may become invalid if the WASM allocated memory grows. When the WASM grows the preallocated memory this property will return the new allocated buffer. Use the returned buffer for short periods of time.
Type: ArrayBuffer
Returns true if this object was deallocated.
Type: boolean
The length in bytes of the array. For RoaringUint32Array it is equal to this.length * 4
Type: number
The full WASM heap in hich this array is allocated. Note that the buffer may become invalid if the WASM allocated memory grows. When the WASM grows the preallocated memory this property will return the new allocated buffer. Use the returned array for short periods of time.
Type: TypedArray
Frees the allocated memory. Is safe to call this method more than once.
Returns boolean True if memory gets freed during this call, false if not.
Throws an error if the memory was freed.
Returns (void | never)
Writes the given array at the specified position
-
arrayA typed or untyped array of values to set. -
offsetThe index in the current array at which the values are to be written.
Gets a new JS typed array instance that shares the memory used by this buffer. Note that the buffer may point to an outdated WASM memory if the WASM allocated memory grows while using the returned buffer. Use the returned array for short periods of time.
Returns Uint32Array A new typed array that shares the memory with this array.
Gets a new NodeJS Buffer instance that shares the memory used by this buffer. Note that the buffer may point to an outdated WASM memory if the WASM allocated memory grows while using the returned buffer. Use the returned array for short periods of time.
Returns Buffer A new instance of NodeJS Buffer
Copies the content of this buffer to a typed array. The returned array is garbage collected and don't need to be disposed manually.
Returns TypedArray A new typed array that contains a copy of this buffer
Copies the content of this buffer to a NodeJS Buffer. The returned buffer is garbage collected and don't need to be disposed manually.
Returns Buffer A new instance of NodeJS Buffer that contains a copy of this buffer
Copies the content of this typed array into a new JS array of numbers and returns it.
Returns Array<number> A new array.
Copies the content of this typed array into a new JS Set and returns it.
Returns Array<number> A new array.
Returns a string representation of an array.
Iterator that iterates through all values in the array.
Returns IterableIterator<number>
Array of bytes allocted directly in roaring library WASM memory. Note: Memory is not garbage collected, you are responsible to free the allocated memory calling "dispose" method.
The type of typed array used by this class. For RoaringUint8Array is Uint8Array.
The type of typed array used by this class. For RoaringUint8Array is Uint8Array.
The size in bytes of each element in the array. For RoaringUint8Array is always 1
Type: number
The size in bytes of each element in the array. For RoaringUint8Array is always 1
Type: number
The ArrayBuffer instance referenced by the array. Note that the buffer may become invalid if the WASM allocated memory grows. When the WASM grows the preallocated memory this property will return the new allocated buffer. Use the returned buffer for short periods of time.
Type: ArrayBuffer
Returns true if this object was deallocated.
Type: boolean
The length in bytes of the array. For RoaringUint8Array it is equal to this.length
Type: number
The full WASM heap in hich this array is allocated. Note that the buffer may become invalid if the WASM allocated memory grows. When the WASM grows the preallocated memory this property will return the new allocated buffer. Use the returned array for short periods of time.
Type: TypedArray
Frees the allocated memory. Is safe to call this method more than once.
Returns boolean True if memory gets freed during this call, false if not.
Throws an error if the memory was freed.
Returns (void | never)
Writes the given array at the specified position
-
arrayA typed or untyped array of values to set. -
offsetThe index in the current array at which the values are to be written.
Gets a new JS typed array instance that shares the memory used by this buffer. Note that the buffer may point to an outdated WASM memory if the WASM allocated memory grows while using the returned buffer. Use the returned array for short periods of time.
Returns Uint8Array A new typed array that shares the memory with this array.
Gets a new NodeJS Buffer instance that shares the memory used by this buffer. Note that the buffer may point to an outdated WASM memory if the WASM allocated memory grows while using the returned buffer. Use the returned array for short periods of time.
Returns Buffer A new instance of NodeJS Buffer
Copies the content of this buffer to a typed array. The returned array is garbage collected and don't need to be disposed manually.
Returns TypedArray A new typed array that contains a copy of this buffer
Copies the content of this buffer to a NodeJS Buffer. The returned buffer is garbage collected and don't need to be disposed manually.
Returns Buffer A new instance of NodeJS Buffer that contains a copy of this buffer
Copies the content of this typed array into a standard JS array of numbers and returns it.
Returns Array<number> A new array.
Returns a string representation of an array.
Iterator that iterates through all values in the array.
Returns IterableIterator<number>