fast-boolean-array 1.1.0 → 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jack van der Bilt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# Fast Boolean Array
+
+In JavaScript, you sometimes need an array of booleans for a specific size. Using a regular JavaScript array works, but it can waste over 8x the memory. This is because JavaScript engines, like V8 (in Chrome and Node.js), represent all primitive types in a uniform way for optimization reasons. While a boolean is conceptually a 1-bit value, JavaScript engines typically allocate 1 byte (8 bits) per boolean value in memory. **Fast Boolean Array** solves this inefficiency by leveraging bit manipulation to store booleans in a compact format. It does bit manipulation on a uInt8Array, storing every boolean as a specific bit on each 8 bit int, fast and efficiently.
+
+View detailed benchmark results below.
+
+## Features
+
+- **Memory Efficiency**: Stores booleans in bits rather than bytes, drastically reducing memory usage.
+- **Simple API**: Intuitive methods for setting and getting values.
+- **Performance**: Optimized for use in scenarios where memory constraints are critical.
+
+---
+
+## Installation
+
+Install the package via npm:
+```bash
+npm install fast-boolean-array
+```
+
+---
+
+## Usage
+
+Here's how to use the Fast Boolean Array:
+
+```javascript
+const BooleanArray = require('fast-boolean-array');
+
+// Create a new BooleanArray with the desired size
+const booleans = new BooleanArray(10);
+
+// Set a value at a specific index
+booleans.set(0, true);
+
+// Get the value at a specific index
+console.log(booleans.get(0)); // Output: true
+
+// Set another value
+booleans.set(1, false);
+
+// Retrieve it
+console.log(booleans.get(1)); // Output: false
+```
+
+---
+
+## API
+
+### `new BooleanArray(size)`
+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.
+
+### `set(index, value)`
+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`).
+
+### `get(index)`
+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.
+
+---
+
+## Why Use Fast Boolean Array?
+
+- **Efficient Memory Usage**: Ideal for applications handling large boolean arrays, such as data compression or state tracking.
+- **Easy to Use**: Familiar `Map` and `Set` like API for minimal learning curve.
+- **Scalable**: Suitable for high-performance, memory-sensitive projects.
+
+---
+
+# Fast Boolean Array vs Vanilla JavaScript Array Performance
+
+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
+
+### 1 Boolean
+| Test                     | Time (ms) | Memory (MB) |
+|--------------------------|-----------|-------------|
+| Set Vanilla Array        | 0.00      | 0.00        |
+| Set Fast Boolean Array   | 0.00      | 0.00        |
+| Get Vanilla Array        | 0.00      | N/A         |
+| Get Fast Boolean Array   | 0.00      | N/A         |
+
+**Observation:** At 1 boolean, both arrays remain equal in terms of performance and memory usage. Differences in performance are effectively immessurable, and one can assume practically identical.
+
+### 100 Booleans
+| Test                     | Time (ms) | Memory (MB) |
+|--------------------------|-----------|-------------|
+| Set Vanilla Array        | 0.00      | 0.00        |
+| Set Fast Boolean Array   | 0.00      | 0.00        |
+| Get Vanilla Array        | 0.00      | N/A         |
+| Get Fast Boolean Array   | 0.00      | N/A         |
+
+**Observation:** At 100 booleans, both arrays remain equal in terms of performance and memory usage. Differences in performance are effectively immessurable, and one can assume practically identical.
+
+### 1,000 Booleans
+| Test                     | Time (ms) | Memory (MB) |
+|--------------------------|-----------|-------------|
+| Set Vanilla Array        | 0.01      | 0.00        |
+| Set Fast Boolean Array   | 0.00      | 0.00        |
+| Get Vanilla Array        | 0.00      | N/A         |
+| Get Fast Boolean Array   | 0.00      | N/A         |
+
+**Observation:** At 1,000 booleans, the Fast Boolean Array is **10x** faster in set operations and uses **8x** less memory as expected. We have not yet been able to messure in actual bytes.
+
+### 10,000 Booleans
+| Test                     | Time (ms) | Memory (MB) |
+|--------------------------|-----------|-------------|
+| Set Vanilla Array        | 0.06      | 0.01        |
+| Set Fast Boolean Array   | 0.02      | 0.00        |
+| Get Vanilla Array        | 0.01      | N/A         |
+| Get Fast Boolean Array   | 0.01      | N/A         |
+
+**Observation:** For 10,000 booleans, Fast Boolean Array is **3x** faster in set operations and uses **8x** less memory as expected.
+
+### 100,000 Booleans
+| Test                     | Time (ms) | Memory (MB) |
+|--------------------------|-----------|-------------|
+| Set Vanilla Array        | 1.37      | 0.10        |
+| Set Fast Boolean Array   | 0.21      | 0.01        |
+| Get Vanilla Array        | 0.05      | N/A         |
+| Get Fast Boolean Array   | 0.07      | N/A         |
+
+**Observation:** At 100,000 booleans, Fast Boolean Array is approximately **6.5x** faster in set operations and uses **8x** less memory as expected.
+
+### 1,000,000 Booleans
+| Test                     | Time (ms) | Memory (MB) |
+|--------------------------|-----------|-------------|
+| Set Vanilla Array        | 19.62     | 0.95        |
+| Set Fast Boolean Array   | 2.02      | 0.12        |
+| Get Vanilla Array        | 0.48      | N/A         |
+| Get Fast Boolean Array   | 0.71      | N/A         |
+
+**Observation:** For 1,000,000 booleans, Fast Boolean Array is nearly **10x** faster in set operations and uses **8x** less memory as expected.
+
+### 10,000,000 Booleans
+| Test                     | Time (ms) | Memory (MB) |
+|--------------------------|-----------|-------------|
+| Set Vanilla Array        | 259.10    | 9.54        |
+| Set Fast Boolean Array   | 21.57     | 1.19        |
+| Get Vanilla Array        | 4.90      | N/A         |
+| Get Fast Boolean Array   | 7.21      | N/A         |
+
+**Observation:** At 10,000,000 booleans, Fast Boolean Array is about **12x** faster in set operations and uses nearly **8x** less memory as expected compared to Vanilla.
+
+## Summary
+This updated benchmark confirms that the Fast Boolean Array library excels in scenarios involving large datasets, offering substantial improvements in set operation performance and memory efficiency. The sweet spot remains around 100,000 indexes, where the library achieves its most pronounced gains (6.5x faster and much lower memory usage) over Vanilla JavaScript arrays.
+
+---
+
+## 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](https://github.com/yourusername/fast-boolean-array).
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+## Acknowledgements
+
+Thank you to the open-source community for inspiration and support!
+

package/bench.js

@@ -1,4 +1,4 @@
-import BooleanArray from 'boolean-array';
+import BooleanArray from './dist/index.js';
 import { performance } from 'node:perf_hooks';
 import { serialize } from 'v8';
 

package/dist/index.cjs

@@ -20,7 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  FastBooleanArray: () => FastBooleanArray
+  default: () => FastBooleanArray
 });
 module.exports = __toCommonJS(src_exports);
 var FastBooleanArray = class {
@@ -47,8 +47,4 @@ var FastBooleanArray = class {
     throw new Error("Setting the length on BooleanArray's is not supported");
   }
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  FastBooleanArray
-});
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export class FastBooleanArray {\r\n\tpublic size: number;\r\n\tprivate buffer: Uint8Array;\r\n\r\n\tconstructor(size: number) {\r\n\t\tthis.size = size;\r\n\t\tthis.buffer = new Uint8Array(Math.ceil(size / 8)); // Allocate memory\r\n\t}\r\n\r\n\tset(input: number, value: boolean) {\r\n\t\tif (value) {\r\n\t\t\tthis.buffer[input >> 3] |= 1 << (input & 7); // Set bit\r\n\t\t} else {\r\n\t\t\tthis.buffer[input >> 3] &= ~(1 << (input & 7)); // Clear bit\r\n\t\t}\r\n\t}\r\n\r\n\tget(input: number) {\r\n\t\treturn (this.buffer[input >> 3] & (1 << input % 8)) !== 0; // Check bit\r\n\t}\r\n\r\n\tget length() {\r\n\t\treturn this.size;\r\n\t}\r\n\r\n\tset length(value: number) {\r\n\t\tthrow new Error(\"Setting the length on BooleanArray's is not supported\");\r\n\t}\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,mBAAN,MAAuB;AAAA,EACtB;AAAA,EACC;AAAA,EAER,YAAY,MAAc;AACzB,SAAK,OAAO;AACZ,SAAK,SAAS,IAAI,WAAW,KAAK,KAAK,OAAO,CAAC,CAAC;AAAA,EACjD;AAAA,EAEA,IAAI,OAAe,OAAgB;AAClC,QAAI,OAAO;AACV,WAAK,OAAO,SAAS,CAAC,KAAK,MAAM,QAAQ;AAAA,IAC1C,OAAO;AACN,WAAK,OAAO,SAAS,CAAC,KAAK,EAAE,MAAM,QAAQ;AAAA,IAC5C;AAAA,EACD;AAAA,EAEA,IAAI,OAAe;AAClB,YAAQ,KAAK,OAAO,SAAS,CAAC,IAAK,KAAK,QAAQ,OAAQ;AAAA,EACzD;AAAA,EAEA,IAAI,SAAS;AACZ,WAAO,KAAK;AAAA,EACb;AAAA,EAEA,IAAI,OAAO,OAAe;AACzB,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACxE;AACD;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export default class FastBooleanArray {\r\n\tpublic size: number;\r\n\tprivate buffer: Uint8Array;\r\n\r\n\tconstructor(size: number) {\r\n\t\tthis.size = size;\r\n\t\tthis.buffer = new Uint8Array(Math.ceil(size / 8)); // Allocate memory\r\n\t}\r\n\r\n\tset(input: number, value: boolean) {\r\n\t\tif (value) {\r\n\t\t\tthis.buffer[input >> 3] |= 1 << (input & 7); // Set bit\r\n\t\t} else {\r\n\t\t\tthis.buffer[input >> 3] &= ~(1 << (input & 7)); // Clear bit\r\n\t\t}\r\n\t}\r\n\r\n\tget(input: number) {\r\n\t\treturn (this.buffer[input >> 3] & (1 << input % 8)) !== 0; // Check bit\r\n\t}\r\n\r\n\tget length() {\r\n\t\treturn this.size;\r\n\t}\r\n\r\n\tset length(value: number) {\r\n\t\tthrow new Error(\"Setting the length on BooleanArray's is not supported\");\r\n\t}\r\n}\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAqB,mBAArB,MAAsC;AAAA,EAC9B;AAAA,EACC;AAAA,EAER,YAAY,MAAc;AACzB,SAAK,OAAO;AACZ,SAAK,SAAS,IAAI,WAAW,KAAK,KAAK,OAAO,CAAC,CAAC;AAAA,EACjD;AAAA,EAEA,IAAI,OAAe,OAAgB;AAClC,QAAI,OAAO;AACV,WAAK,OAAO,SAAS,CAAC,KAAK,MAAM,QAAQ;AAAA,IAC1C,OAAO;AACN,WAAK,OAAO,SAAS,CAAC,KAAK,EAAE,MAAM,QAAQ;AAAA,IAC5C;AAAA,EACD;AAAA,EAEA,IAAI,OAAe;AAClB,YAAQ,KAAK,OAAO,SAAS,CAAC,IAAK,KAAK,QAAQ,OAAQ;AAAA,EACzD;AAAA,EAEA,IAAI,SAAS;AACZ,WAAO,KAAK;AAAA,EACb;AAAA,EAEA,IAAI,OAAO,OAAe;AACzB,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACxE;AACD;","names":[]}

package/dist/index.d.cts

@@ -8,4 +8,4 @@ declare class FastBooleanArray {
     set length(value: number);
 }
 
-export { FastBooleanArray };
+export { FastBooleanArray as default };

package/dist/index.d.ts

@@ -8,4 +8,4 @@ declare class FastBooleanArray {
     set length(value: number);
 }
 
-export { FastBooleanArray };
+export { FastBooleanArray as default };

package/dist/index.js

@@ -24,6 +24,6 @@ var FastBooleanArray = class {
   }
 };
 export {
-  FastBooleanArray
+  FastBooleanArray as default
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export class FastBooleanArray {\r\n\tpublic size: number;\r\n\tprivate buffer: Uint8Array;\r\n\r\n\tconstructor(size: number) {\r\n\t\tthis.size = size;\r\n\t\tthis.buffer = new Uint8Array(Math.ceil(size / 8)); // Allocate memory\r\n\t}\r\n\r\n\tset(input: number, value: boolean) {\r\n\t\tif (value) {\r\n\t\t\tthis.buffer[input >> 3] |= 1 << (input & 7); // Set bit\r\n\t\t} else {\r\n\t\t\tthis.buffer[input >> 3] &= ~(1 << (input & 7)); // Clear bit\r\n\t\t}\r\n\t}\r\n\r\n\tget(input: number) {\r\n\t\treturn (this.buffer[input >> 3] & (1 << input % 8)) !== 0; // Check bit\r\n\t}\r\n\r\n\tget length() {\r\n\t\treturn this.size;\r\n\t}\r\n\r\n\tset length(value: number) {\r\n\t\tthrow new Error(\"Setting the length on BooleanArray's is not supported\");\r\n\t}\r\n}\r\n"],"mappings":";AAAO,IAAM,mBAAN,MAAuB;AAAA,EACtB;AAAA,EACC;AAAA,EAER,YAAY,MAAc;AACzB,SAAK,OAAO;AACZ,SAAK,SAAS,IAAI,WAAW,KAAK,KAAK,OAAO,CAAC,CAAC;AAAA,EACjD;AAAA,EAEA,IAAI,OAAe,OAAgB;AAClC,QAAI,OAAO;AACV,WAAK,OAAO,SAAS,CAAC,KAAK,MAAM,QAAQ;AAAA,IAC1C,OAAO;AACN,WAAK,OAAO,SAAS,CAAC,KAAK,EAAE,MAAM,QAAQ;AAAA,IAC5C;AAAA,EACD;AAAA,EAEA,IAAI,OAAe;AAClB,YAAQ,KAAK,OAAO,SAAS,CAAC,IAAK,KAAK,QAAQ,OAAQ;AAAA,EACzD;AAAA,EAEA,IAAI,SAAS;AACZ,WAAO,KAAK;AAAA,EACb;AAAA,EAEA,IAAI,OAAO,OAAe;AACzB,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACxE;AACD;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export default class FastBooleanArray {\r\n\tpublic size: number;\r\n\tprivate buffer: Uint8Array;\r\n\r\n\tconstructor(size: number) {\r\n\t\tthis.size = size;\r\n\t\tthis.buffer = new Uint8Array(Math.ceil(size / 8)); // Allocate memory\r\n\t}\r\n\r\n\tset(input: number, value: boolean) {\r\n\t\tif (value) {\r\n\t\t\tthis.buffer[input >> 3] |= 1 << (input & 7); // Set bit\r\n\t\t} else {\r\n\t\t\tthis.buffer[input >> 3] &= ~(1 << (input & 7)); // Clear bit\r\n\t\t}\r\n\t}\r\n\r\n\tget(input: number) {\r\n\t\treturn (this.buffer[input >> 3] & (1 << input % 8)) !== 0; // Check bit\r\n\t}\r\n\r\n\tget length() {\r\n\t\treturn this.size;\r\n\t}\r\n\r\n\tset length(value: number) {\r\n\t\tthrow new Error(\"Setting the length on BooleanArray's is not supported\");\r\n\t}\r\n}\r\n"],"mappings":";AAAA,IAAqB,mBAArB,MAAsC;AAAA,EAC9B;AAAA,EACC;AAAA,EAER,YAAY,MAAc;AACzB,SAAK,OAAO;AACZ,SAAK,SAAS,IAAI,WAAW,KAAK,KAAK,OAAO,CAAC,CAAC;AAAA,EACjD;AAAA,EAEA,IAAI,OAAe,OAAgB;AAClC,QAAI,OAAO;AACV,WAAK,OAAO,SAAS,CAAC,KAAK,MAAM,QAAQ;AAAA,IAC1C,OAAO;AACN,WAAK,OAAO,SAAS,CAAC,KAAK,EAAE,MAAM,QAAQ;AAAA,IAC5C;AAAA,EACD;AAAA,EAEA,IAAI,OAAe;AAClB,YAAQ,KAAK,OAAO,SAAS,CAAC,IAAK,KAAK,QAAQ,OAAQ;AAAA,EACzD;AAAA,EAEA,IAAI,SAAS;AACZ,WAAO,KAAK;AAAA,EACb;AAAA,EAEA,IAAI,OAAO,OAAe;AACzB,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACxE;AACD;","names":[]}

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "fast-boolean-array",
-  "version": "1.1.0",
+  "version": "1.1.2",
+  "homepage": "https://github.com/UltraCakeBakery/FastBooleanArray",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UltraCakeBakery/FastBooleanArray.git"
+  },
+  "bugs": {
+    "url": "https://github.com/UltraCakeBakery/FastBooleanArray/issues",
+    "email": "fast-boolean-array@managing.software"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -16,6 +25,8 @@
     }
   },
   "scripts": {
+    "check": "npm run check:types",
+    "check:types": "npx --yes @arethetypeswrong/cli --pack .",
     "build": "tsup src/index.ts --dts --format cjs,esm --clean --sourcemap"
   },
   "keywords": [
@@ -25,10 +36,13 @@
     "efficient",
     "map"
   ],
-  "author": "Jack van der Bilt",
+  "author": "Jack van der Bil  <jack@managing.software> (https://jackvanderbilt.nl)",
   "license": "MIT",
   "description": "",
-  "dependencies": {
+  "engines": {
+    "node": ">=0.10.3"
+  },
+  "devDependencies": {
     "tsup": "^8.3.5"
   }
 }

package/src/index.ts

@@ -1,4 +1,4 @@
-export class FastBooleanArray {
+export default class FastBooleanArray {
 	public size: number;
 	private buffer: Uint8Array;