Fast Boolean Array !Build
In JavaScript, when working with large arrays of boolean values, a common challenge is efficiently indexing and retrieving these values. Using a regular JavaScript array to store booleans is straightforward, but it is memory-inefficient. While booleans are conceptually 1-bit values, JavaScript engines, like V8 (in Chrome and Node.js), allocate 1 byte (8 bits) per boolean for optimization purposes. This can waste a significant amount of memory when dealing with large arrays.
Fast Boolean Array solves this issue by utilizing bit manipulation to store booleans in a compact format. It uses a Uint8Array and stores each boolean as a single bit within the 8 bits of each byte. This allows you to index and retrieve boolean values by integers (e.g., the 0th boolean, 1st boolean, etc.) while only using a fraction of the memory.
For detailed benchmark results, see below.
Features
-
Memory Efficiency: Stores booleans in bits rather than bytes, drastically reducing memory usage.
-
Fast Set Performance: Up to 10x faster sets for fast data re-mapping.
-
Familiar API:
Map and
Set like API for minimal learning curve. Intuitive helper functions, and works in
for.. of.
-
Array like interface: call
.accessLikeArray() to access it like an array
someArray[index] (beware of the performance penalty caused by the Proxy)!
---
Usage example:
Here's how to use the Fast Boolean Array:
``
javascript
import BooleanArray from "fast-boolean-array";
// const BooleanArray = require('fast-boolean-array'); commonjs works too.
// Create a new BooleanArray with the desired length
const booleans = new BooleanArray(2);
// Set a value at a specific index
booleans.set(0, true);
booleans.set(1, false);
// Retrieve a value at a specific index
console.log(booleans.get(0)); // Output: true
console.log(booleans.get(1)); // Output: false
booleans.set(3, true); // will not throw, but returns false as the boolean is not found
console.log(booleans.get(3)); // Output: false
booleans.setSafe(3, true); // will throw RangeError because the array has a length of 2
`
---
Installation
Install the package:
`
bash
npm install fast-boolean-array
pnpm install fast-boolean-array
`
---
API
$3
Creates a new boolean array of the given size. All values are initialized to false
.
- Parameters:
- size
(number): The number of booleans the array should hold.
$3
Sets the boolean value at the specified index.
- Parameters:
- index
(number): The position in the array to set the value.
- value
(boolean): The value to set (true
or false
).
$3
Gets the boolean value at the specified index.
- Parameters:
- index
(number): The position in the array to retrieve the value.
- Returns:
- boolean`: The value at the given index.
---
Performance Breakdown
Our benchmark compares the performance of our Fast Boolean Array library against Vanilla JavaScript arrays in terms of get and set operations across varying numbers of Booleans. The results below reflect an updated benchmark algorithm that performs 1,000 runs for each x amount of Booleans to better simulate real-world scenarios.
Performance Breakdown
$3
| Test | Time (ms) | Memory (Bytes) | Booleans |
| ---------------------- | ---------- | -------------- | -------- |
| Set Vanilla Array | 0.00236000 | 8 | 1 |
| Set Fast Boolean Array | 0.00423000 | 6 | 1 |
| Get Vanilla Array | 0.00053000 | N/A | 1 |
| Get Fast Boolean Array | 0.00291000 | N/A | 1 |
As useless as having just 1 boolean stored in an array might be, For
1 boolean, the
Fast Boolean Array is
1.8x slower for
Set and
5.5x slower for
Get operations. Memory usage is nearly identical, with a small advantage for the
Fast Boolean Array in terms of bytes.
---
$3
| Test | Time (ms) | Memory (Bytes) | Booleans |
| ---------------------- | ---------- | -------------- | -------- |
| Set Vanilla Array | 0.00332000 | 107 | 100 |
| Set Fast Boolean Array | 0.00824000 | 18 | 100 |
| Get Vanilla Array | 0.00149000 | N/A | 100 |
| Get Fast Boolean Array | 0.00581000 | N/A | 100 |
Observation: For
100 booleans,
Fast Boolean Array is
2.5x slower in
Set operations but
3.9x more memory efficient. However,
Fast Boolean Array's'
Get operation is
3.9x slower . compared to the
Vanilla Array.
---
$3
| Test | Time (ms) | Memory (Bytes) | Booleans |
| ---------------------- | ---------- | -------------- | -------- |
| Set Vanilla Array | 0.09599000 | 1009 | 1000 |
| Set Fast Boolean Array | 0.04467000 | 130 | 1000 |
| Get Vanilla Array | 0.01261000 | N/A | 1000 |
| Get Fast Boolean Array | 0.05476000 | N/A | 1000 |
For
1,000 booleans,
Fast Boolean Array is
2.1x faster for
Set operations and uses
7.7x less memory. However,
Fast Boolean Array's'
Get operation is
4.3x slower . compared to the
Vanilla Array.
---
$3
| Test | Time (ms) | Memory (Bytes) | Booleans |
| ---------------------- | ---------- | -------------- | -------- |
| Set Vanilla Array | 0.30075000 | 10009 | 10000 |
| Set Fast Boolean Array | 0.04225000 | 1256 | 10000 |
| Get Vanilla Array | 0.06054000 | N/A | 10000 |
| Get Fast Boolean Array | 0.12325000 | N/A | 10000 |
Observation: For
10,000 booleans,
Fast Boolean Array is
7.1x faster in
Set operations and uses
8x less memory. However,
Fast Boolean Array's'
Get operation is
2x slower . compared to the
Vanilla Array.
---
$3
| Test | Time (ms) | Memory (Bytes) | Booleans |
| ---------------------- | ---------- | -------------- | -------- |
| Set Vanilla Array | 1.67949000 | 100011 | 100000 |
| Set Fast Boolean Array | 0.15400000 | 12506 | 100000 |
| Get Vanilla Array | 0.04920000 | N/A | 100000 |
| Get Fast Boolean Array | 0.07523000 | N/A | 100000 |
For
100,000 booleans,
Fast Boolean Array is
10.9x faster in
Set operations and uses
8x less memory. However,
Fast Boolean Array's'
Get operation is
1.5x slower .
---
$3
| Test | Time (ms) | Memory (Bytes) | Booleans |
| ---------------------- | ----------- | -------------- | -------- |
| Set Vanilla Array | 20.07889000 | 1000011 | 1000000 |
| Set Fast Boolean Array | 3.42817000 | 125007 | 1000000 |
| Get Vanilla Array | 0.49531000 | N/A | 1000000 |
| Get Fast Boolean Array | 0.74617000 | N/A | 1000000 |
For
1,000,000 booleans, the
Fast Boolean Array is
5.9x faster for
Set operations and uses
8x less memory. However,
Fast Boolean Array's'
Get operation is
1.5x slower .
---
$3
| Test | Time (ms) | Memory (Bytes) | Booleans |
| ---------------------- | ------------ | -------------- | -------- |
| Set Vanilla Array | 266.65778000 | 10000013 | 10000000 |
| Set Fast Boolean Array | 35.53492000 | 1250007 | 10000000 |
| Get Vanilla Array | 4.90792000 | N/A | 10000000 |
| Get Fast Boolean Array | 7.57038000 | N/A | 10000000 |
For
10,000,000 booleans,
Fast Boolean Array is
7.5x faster for
Set operations and uses
8x less memory. However,
Fast Boolean Array's'
Get operation is
1.5x slower .
---
$3
- The
Fast Boolean Array is significantly more efficient in terms of memory usage and
Set operation speeds, particularly as the number of booleans increases.
- For example, as stated previously, at
10,000,000 booleans, it is
7.5x faster in
Set operations and uses
8x less memory.
- The
Get operation, however, tends to be slower on a
Fast Boolean Array, with it being up to
1.5x slower compared to the regular vanilla
boolean[] in larger datasets.
If memory efficiency and
Set performance are priorities, the
Fast Boolean Array is clearly advantageous, but if
Get performance is more important, the
Vanilla Array may still offer better results for certain use cases.
We are still working on improving the performance of the toArray function, but you can already use it today to convert back to a vanilla array, though generating one from scratch is currently more effecient.
---
Contributing
Contributions are welcome! If you'd like to report a bug, suggest a feature, or submit a pull request, please visit the
GitHub repository.
---
License
This project is licensed under the MIT License. See the
LICENSE file for details.
---
Acknowledgements
Thank you to the open-source community for inspiration and support!