fast-boolean-array 1.1.2 → 1.2.1

package/README.md

@@ -15,6 +15,7 @@ View detailed benchmark results below.
 ## Installation
 
 Install the package via npm:
+
 ```bash
 npm install fast-boolean-array
 ```
@@ -26,21 +27,22 @@ npm install fast-boolean-array
 Here's how to use the Fast Boolean Array:
 
 ```javascript
-const BooleanArray = require('fast-boolean-array');
+import BooleanArray from 'fast-boolean-array';
+// const BooleanArray = require('fast-boolean-array'); works too
 
 // Create a new BooleanArray with the desired size
-const booleans = new BooleanArray(10);
+const booleans = new BooleanArray(2);
 
 // Set a value at a specific index
 booleans.set(0, true);
+booleans.set(1, false);
 
-// Get the value at a specific index
+// Retrieve it
 console.log(booleans.get(0)); // Output: true
+console.log(booleans.get(1)); // Output: false
 
-// Set another value
-booleans.set(1, false);
 
-// Retrieve it
+booleans.set(3, false); // will throw as the array is only 3 in size
 console.log(booleans.get(1)); // Output: false
 ```
 
@@ -49,12 +51,14 @@ 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:**
@@ -62,9 +66,11 @@ Sets the boolean value at the specified index.
   - `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:**
@@ -87,76 +93,84 @@ Our benchmark compares the performance of our Fast Boolean Array library against
 ## 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         |
+
+| 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         |
+
+| 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         |
+
+| 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         |
+
+| 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         |
+
+| 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         |
+
+| 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         |
+
+| 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.
 
 ---
@@ -176,4 +190,3 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
 ## Acknowledgements
 
 Thank you to the open-source community for inspiration and support!
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fast-boolean-array",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "homepage": "https://github.com/UltraCakeBakery/FastBooleanArray",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -7,15 +7,30 @@ export default class FastBooleanArray {
 		this.buffer = new Uint8Array(Math.ceil(size / 8)); // Allocate memory
 	}
 
+	/**
+	 * Set a boolean at a specific index
+	 * @throws {RangeError} if `input` is less than `0` or more than the array `size`
+	 */
 	set(input: number, value: boolean) {
+		if (input < 0 || input >= this.size) {
+			throw new RangeError('Index out of bounds');
+		}
 		if (value) {
 			this.buffer[input >> 3] |= 1 << (input & 7); // Set bit
 		} else {
 			this.buffer[input >> 3] &= ~(1 << (input & 7)); // Clear bit
 		}
+		return value;
 	}
 
+	/**
+	 * Set a boolean at a specific index
+	 * @throws {RangeError} if `input` is less than `0` or more than the array `size`
+	 */
 	get(input: number) {
+		if (input < 0 || input >= this.size) {
+			throw new RangeError('Index out of bounds');
+		}
 		return (this.buffer[input >> 3] & (1 << input % 8)) !== 0; // Check bit
 	}
 

package/dist/index.cjs

@@ -1,50 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  default: () => FastBooleanArray
-});
-module.exports = __toCommonJS(src_exports);
-var FastBooleanArray = class {
-  size;
-  buffer;
-  constructor(size) {
-    this.size = size;
-    this.buffer = new Uint8Array(Math.ceil(size / 8));
-  }
-  set(input, value) {
-    if (value) {
-      this.buffer[input >> 3] |= 1 << (input & 7);
-    } else {
-      this.buffer[input >> 3] &= ~(1 << (input & 7));
-    }
-  }
-  get(input) {
-    return (this.buffer[input >> 3] & 1 << input % 8) !== 0;
-  }
-  get length() {
-    return this.size;
-  }
-  set length(value) {
-    throw new Error("Setting the length on BooleanArray's is not supported");
-  }
-};
-//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"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

@@ -1,11 +0,0 @@
-declare class FastBooleanArray {
-    size: number;
-    private buffer;
-    constructor(size: number);
-    set(input: number, value: boolean): void;
-    get(input: number): boolean;
-    get length(): number;
-    set length(value: number);
-}
-
-export { FastBooleanArray as default };

package/dist/index.d.ts

@@ -1,11 +0,0 @@
-declare class FastBooleanArray {
-    size: number;
-    private buffer;
-    constructor(size: number);
-    set(input: number, value: boolean): void;
-    get(input: number): boolean;
-    get length(): number;
-    set length(value: number);
-}
-
-export { FastBooleanArray as default };

package/dist/index.js

@@ -1,29 +0,0 @@
-// src/index.ts
-var FastBooleanArray = class {
-  size;
-  buffer;
-  constructor(size) {
-    this.size = size;
-    this.buffer = new Uint8Array(Math.ceil(size / 8));
-  }
-  set(input, value) {
-    if (value) {
-      this.buffer[input >> 3] |= 1 << (input & 7);
-    } else {
-      this.buffer[input >> 3] &= ~(1 << (input & 7));
-    }
-  }
-  get(input) {
-    return (this.buffer[input >> 3] & 1 << input % 8) !== 0;
-  }
-  get length() {
-    return this.size;
-  }
-  set length(value) {
-    throw new Error("Setting the length on BooleanArray's is not supported");
-  }
-};
-export {
-  FastBooleanArray as default
-};
-//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +0,0 @@
-{"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":[]}