fast-boolean-array 1.1.2 → 1.3.1

package/README.md

@@ -1,8 +1,10 @@
 # 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.
+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.
 
-View detailed benchmark results below.
+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. Each bit represents a boolean, and you can quickly access or modify a specific boolean using bitwise operations, making it both fast and memory-efficient.
+
+For detailed benchmark results, see below.
 
 ## Features
 
@@ -15,6 +17,7 @@ View detailed benchmark results below.
 ## Installation
 
 Install the package via npm:
+
 ```bash
 npm install fast-boolean-array
 ```
@@ -26,21 +29,21 @@ 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);
-
-// 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(0)); // Output: true
+console.log(booleans.get(1)); // Output: false
+
+booleans.set(3, false); // will throw as the array is only 3 in size
 console.log(booleans.get(1)); // Output: false
 ```
 
@@ -49,12 +52,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 +67,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 +94,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 +191,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/dist/index.cjs

@@ -30,20 +30,59 @@ var FastBooleanArray = class {
     this.size = size;
     this.buffer = new Uint8Array(Math.ceil(size / 8));
   }
-  set(input, value) {
+  /**
+   * Sets a boolean value at the specified index.
+   * @param {number} index - The index to set the boolean value at.
+   * @param {number} value - The boolean value to set the `index`.
+   * @returns {boolean} The boolean value that was set.
+   */
+  set(index, value) {
     if (value) {
-      this.buffer[input >> 3] |= 1 << (input & 7);
+      this.buffer[index >> 3] |= 1 << (index & 7);
+      return true;
     } else {
-      this.buffer[input >> 3] &= ~(1 << (input & 7));
+      this.buffer[index >> 3] &= ~(1 << (index & 7));
+      return false;
     }
   }
-  get(input) {
-    return (this.buffer[input >> 3] & 1 << input % 8) !== 0;
+  /**
+   * like `set` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).
+   * @param {number} index - The index to set the boolean value at.
+   * @param {number} value - The boolean value to set the `index`.
+   * @returns {boolean} The boolean value that was set.
+   * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+   */
+  setSafe(index, value) {
+    if (index < 0 || index >= this.size) {
+      throw new RangeError("Index out of bounds");
+    }
+    return this.set(index, value);
+  }
+  /**
+   * Gets a boolean value at the specified index.
+   * @param {number} index - The index to get the boolean value of.
+   * @returns {boolean} The boolean value that was set.
+   * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+   */
+  get(index) {
+    return (this.buffer[index >> 3] & 1 << index % 8) !== 0;
+  }
+  /**
+   * like `get` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).
+   * @param {number} index - The index to get the boolean value of.
+   * @returns {boolean} The boolean value that was set.
+   * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+   */
+  getSafe(index) {
+    if (index < 0 || index >= this.size) {
+      throw new RangeError("Index out of bounds");
+    }
+    return this.get(index);
   }
   get length() {
     return this.size;
   }
-  set length(value) {
+  set length(_value) {
     throw new Error("Setting the length on BooleanArray's is not supported");
   }
 };

package/dist/index.cjs.map

@@ -1 +1 @@
-{"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":[]}
+{"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\t/**\r\n\t * Sets a boolean value at the specified index.\r\n\t * @param {number} index - The index to set the boolean value at.\r\n\t * @param {number} value - The boolean value to set the `index`.\r\n\t * @returns {boolean} The boolean value that was set.\r\n\t */\r\n\tset(index: number, value: any) {\r\n\t\tif (value) {\r\n\t\t\tthis.buffer[index >> 3] |= 1 << (index & 7); // Set bit\r\n\t\t\treturn true;\r\n\t\t} else {\r\n\t\t\tthis.buffer[index >> 3] &= ~(1 << (index & 7)); // Clear bit\r\n\t\t\treturn false;\r\n\t\t}\r\n\t}\r\n\r\n\t/**\r\n\t * like `set` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).\r\n\t * @param {number} index - The index to set the boolean value at.\r\n\t * @param {number} value - The boolean value to set the `index`.\r\n\t * @returns {boolean} The boolean value that was set.\r\n\t * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).\r\n\t */\r\n\tsetSafe(index: number, value: any) {\r\n\t\tif (index < 0 || index >= this.size) {\r\n\t\t\tthrow new RangeError('Index out of bounds');\r\n\t\t}\r\n\t\treturn this.set(index, value);\r\n\t}\r\n\r\n\t/**\r\n\t * Gets a boolean value at the specified index.\r\n\t * @param {number} index - The index to get the boolean value of.\r\n\t * @returns {boolean} The boolean value that was set.\r\n\t * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).\r\n\t */\r\n\tget(index: number) {\r\n\t\treturn (this.buffer[index >> 3] & (1 << index % 8)) !== 0; // Check bit\r\n\t}\r\n\r\n\t/**\r\n\t * like `get` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).\r\n\t * @param {number} index - The index to get the boolean value of.\r\n\t * @returns {boolean} The boolean value that was set.\r\n\t * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).\r\n\t */\r\n\tgetSafe(index: number) {\r\n\t\tif (index < 0 || index >= this.size) {\r\n\t\t\tthrow new RangeError('Index out of bounds');\r\n\t\t}\r\n\t\treturn this.get(index);\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;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,OAAe,OAAY;AAC9B,QAAI,OAAO;AACV,WAAK,OAAO,SAAS,CAAC,KAAK,MAAM,QAAQ;AACzC,aAAO;AAAA,IACR,OAAO;AACN,WAAK,OAAO,SAAS,CAAC,KAAK,EAAE,MAAM,QAAQ;AAC3C,aAAO;AAAA,IACR;AAAA,EACD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,QAAQ,OAAe,OAAY;AAClC,QAAI,QAAQ,KAAK,SAAS,KAAK,MAAM;AACpC,YAAM,IAAI,WAAW,qBAAqB;AAAA,IAC3C;AACA,WAAO,KAAK,IAAI,OAAO,KAAK;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,OAAe;AAClB,YAAQ,KAAK,OAAO,SAAS,CAAC,IAAK,KAAK,QAAQ,OAAQ;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,QAAQ,OAAe;AACtB,QAAI,QAAQ,KAAK,SAAS,KAAK,MAAM;AACpC,YAAM,IAAI,WAAW,qBAAqB;AAAA,IAC3C;AACA,WAAO,KAAK,IAAI,KAAK;AAAA,EACtB;AAAA,EAEA,IAAI,SAAS;AACZ,WAAO,KAAK;AAAA,EACb;AAAA,EAEA,IAAI,OAAO,QAAgB;AAC1B,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACxE;AACD;","names":[]}

package/dist/index.d.cts

@@ -2,10 +2,37 @@ declare class FastBooleanArray {
     size: number;
     private buffer;
     constructor(size: number);
-    set(input: number, value: boolean): void;
-    get(input: number): boolean;
+    /**
+     * Sets a boolean value at the specified index.
+     * @param {number} index - The index to set the boolean value at.
+     * @param {number} value - The boolean value to set the `index`.
+     * @returns {boolean} The boolean value that was set.
+     */
+    set(index: number, value: any): boolean;
+    /**
+     * like `set` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).
+     * @param {number} index - The index to set the boolean value at.
+     * @param {number} value - The boolean value to set the `index`.
+     * @returns {boolean} The boolean value that was set.
+     * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+     */
+    setSafe(index: number, value: any): boolean;
+    /**
+     * Gets a boolean value at the specified index.
+     * @param {number} index - The index to get the boolean value of.
+     * @returns {boolean} The boolean value that was set.
+     * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+     */
+    get(index: number): boolean;
+    /**
+     * like `get` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).
+     * @param {number} index - The index to get the boolean value of.
+     * @returns {boolean} The boolean value that was set.
+     * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+     */
+    getSafe(index: number): boolean;
     get length(): number;
-    set length(value: number);
+    set length(_value: number);
 }
 
 export { FastBooleanArray as default };

package/dist/index.d.ts

@@ -2,10 +2,37 @@ declare class FastBooleanArray {
     size: number;
     private buffer;
     constructor(size: number);
-    set(input: number, value: boolean): void;
-    get(input: number): boolean;
+    /**
+     * Sets a boolean value at the specified index.
+     * @param {number} index - The index to set the boolean value at.
+     * @param {number} value - The boolean value to set the `index`.
+     * @returns {boolean} The boolean value that was set.
+     */
+    set(index: number, value: any): boolean;
+    /**
+     * like `set` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).
+     * @param {number} index - The index to set the boolean value at.
+     * @param {number} value - The boolean value to set the `index`.
+     * @returns {boolean} The boolean value that was set.
+     * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+     */
+    setSafe(index: number, value: any): boolean;
+    /**
+     * Gets a boolean value at the specified index.
+     * @param {number} index - The index to get the boolean value of.
+     * @returns {boolean} The boolean value that was set.
+     * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+     */
+    get(index: number): boolean;
+    /**
+     * like `get` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).
+     * @param {number} index - The index to get the boolean value of.
+     * @returns {boolean} The boolean value that was set.
+     * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+     */
+    getSafe(index: number): boolean;
     get length(): number;
-    set length(value: number);
+    set length(_value: number);
 }
 
 export { FastBooleanArray as default };

package/dist/index.js

@@ -6,20 +6,59 @@ var FastBooleanArray = class {
     this.size = size;
     this.buffer = new Uint8Array(Math.ceil(size / 8));
   }
-  set(input, value) {
+  /**
+   * Sets a boolean value at the specified index.
+   * @param {number} index - The index to set the boolean value at.
+   * @param {number} value - The boolean value to set the `index`.
+   * @returns {boolean} The boolean value that was set.
+   */
+  set(index, value) {
     if (value) {
-      this.buffer[input >> 3] |= 1 << (input & 7);
+      this.buffer[index >> 3] |= 1 << (index & 7);
+      return true;
     } else {
-      this.buffer[input >> 3] &= ~(1 << (input & 7));
+      this.buffer[index >> 3] &= ~(1 << (index & 7));
+      return false;
     }
   }
-  get(input) {
-    return (this.buffer[input >> 3] & 1 << input % 8) !== 0;
+  /**
+   * like `set` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).
+   * @param {number} index - The index to set the boolean value at.
+   * @param {number} value - The boolean value to set the `index`.
+   * @returns {boolean} The boolean value that was set.
+   * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+   */
+  setSafe(index, value) {
+    if (index < 0 || index >= this.size) {
+      throw new RangeError("Index out of bounds");
+    }
+    return this.set(index, value);
+  }
+  /**
+   * Gets a boolean value at the specified index.
+   * @param {number} index - The index to get the boolean value of.
+   * @returns {boolean} The boolean value that was set.
+   * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+   */
+  get(index) {
+    return (this.buffer[index >> 3] & 1 << index % 8) !== 0;
+  }
+  /**
+   * like `get` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).
+   * @param {number} index - The index to get the boolean value of.
+   * @returns {boolean} The boolean value that was set.
+   * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+   */
+  getSafe(index) {
+    if (index < 0 || index >= this.size) {
+      throw new RangeError("Index out of bounds");
+    }
+    return this.get(index);
   }
   get length() {
     return this.size;
   }
-  set length(value) {
+  set length(_value) {
     throw new Error("Setting the length on BooleanArray's is not supported");
   }
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"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":[]}
+{"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\t/**\r\n\t * Sets a boolean value at the specified index.\r\n\t * @param {number} index - The index to set the boolean value at.\r\n\t * @param {number} value - The boolean value to set the `index`.\r\n\t * @returns {boolean} The boolean value that was set.\r\n\t */\r\n\tset(index: number, value: any) {\r\n\t\tif (value) {\r\n\t\t\tthis.buffer[index >> 3] |= 1 << (index & 7); // Set bit\r\n\t\t\treturn true;\r\n\t\t} else {\r\n\t\t\tthis.buffer[index >> 3] &= ~(1 << (index & 7)); // Clear bit\r\n\t\t\treturn false;\r\n\t\t}\r\n\t}\r\n\r\n\t/**\r\n\t * like `set` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).\r\n\t * @param {number} index - The index to set the boolean value at.\r\n\t * @param {number} value - The boolean value to set the `index`.\r\n\t * @returns {boolean} The boolean value that was set.\r\n\t * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).\r\n\t */\r\n\tsetSafe(index: number, value: any) {\r\n\t\tif (index < 0 || index >= this.size) {\r\n\t\t\tthrow new RangeError('Index out of bounds');\r\n\t\t}\r\n\t\treturn this.set(index, value);\r\n\t}\r\n\r\n\t/**\r\n\t * Gets a boolean value at the specified index.\r\n\t * @param {number} index - The index to get the boolean value of.\r\n\t * @returns {boolean} The boolean value that was set.\r\n\t * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).\r\n\t */\r\n\tget(index: number) {\r\n\t\treturn (this.buffer[index >> 3] & (1 << index % 8)) !== 0; // Check bit\r\n\t}\r\n\r\n\t/**\r\n\t * like `get` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).\r\n\t * @param {number} index - The index to get the boolean value of.\r\n\t * @returns {boolean} The boolean value that was set.\r\n\t * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).\r\n\t */\r\n\tgetSafe(index: number) {\r\n\t\tif (index < 0 || index >= this.size) {\r\n\t\t\tthrow new RangeError('Index out of bounds');\r\n\t\t}\r\n\t\treturn this.get(index);\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;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,OAAe,OAAY;AAC9B,QAAI,OAAO;AACV,WAAK,OAAO,SAAS,CAAC,KAAK,MAAM,QAAQ;AACzC,aAAO;AAAA,IACR,OAAO;AACN,WAAK,OAAO,SAAS,CAAC,KAAK,EAAE,MAAM,QAAQ;AAC3C,aAAO;AAAA,IACR;AAAA,EACD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,QAAQ,OAAe,OAAY;AAClC,QAAI,QAAQ,KAAK,SAAS,KAAK,MAAM;AACpC,YAAM,IAAI,WAAW,qBAAqB;AAAA,IAC3C;AACA,WAAO,KAAK,IAAI,OAAO,KAAK;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAI,OAAe;AAClB,YAAQ,KAAK,OAAO,SAAS,CAAC,IAAK,KAAK,QAAQ,OAAQ;AAAA,EACzD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,QAAQ,OAAe;AACtB,QAAI,QAAQ,KAAK,SAAS,KAAK,MAAM;AACpC,YAAM,IAAI,WAAW,qBAAqB;AAAA,IAC3C;AACA,WAAO,KAAK,IAAI,KAAK;AAAA,EACtB;AAAA,EAEA,IAAI,SAAS;AACZ,WAAO,KAAK;AAAA,EACb;AAAA,EAEA,IAAI,OAAO,QAAgB;AAC1B,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACxE;AACD;","names":[]}

package/package.json

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

package/src/index.ts

@@ -7,23 +7,64 @@ export default class FastBooleanArray {
 		this.buffer = new Uint8Array(Math.ceil(size / 8)); // Allocate memory
 	}
 
-	set(input: number, value: boolean) {
+	/**
+	 * Sets a boolean value at the specified index.
+	 * @param {number} index - The index to set the boolean value at.
+	 * @param {number} value - The boolean value to set the `index`.
+	 * @returns {boolean} The boolean value that was set.
+	 */
+	set(index: number, value: any) {
 		if (value) {
-			this.buffer[input >> 3] |= 1 << (input & 7); // Set bit
+			this.buffer[index >> 3] |= 1 << (index & 7); // Set bit
+			return true;
 		} else {
-			this.buffer[input >> 3] &= ~(1 << (input & 7)); // Clear bit
+			this.buffer[index >> 3] &= ~(1 << (index & 7)); // Clear bit
+			return false;
 		}
 	}
 
-	get(input: number) {
-		return (this.buffer[input >> 3] & (1 << input % 8)) !== 0; // Check bit
+	/**
+	 * like `set` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).
+	 * @param {number} index - The index to set the boolean value at.
+	 * @param {number} value - The boolean value to set the `index`.
+	 * @returns {boolean} The boolean value that was set.
+	 * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+	 */
+	setSafe(index: number, value: any) {
+		if (index < 0 || index >= this.size) {
+			throw new RangeError('Index out of bounds');
+		}
+		return this.set(index, value);
+	}
+
+	/**
+	 * Gets a boolean value at the specified index.
+	 * @param {number} index - The index to get the boolean value of.
+	 * @returns {boolean} The boolean value that was set.
+	 * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+	 */
+	get(index: number) {
+		return (this.buffer[index >> 3] & (1 << index % 8)) !== 0; // Check bit
+	}
+
+	/**
+	 * like `get` but throws if the index is out of bounds (less than 0 or greater than or equal to the array size).
+	 * @param {number} index - The index to get the boolean value of.
+	 * @returns {boolean} The boolean value that was set.
+	 * @throws {RangeError} If the index is out of bounds (less than 0 or greater than or equal to the array size).
+	 */
+	getSafe(index: number) {
+		if (index < 0 || index >= this.size) {
+			throw new RangeError('Index out of bounds');
+		}
+		return this.get(index);
 	}
 
 	get length() {
 		return this.size;
 	}
 
-	set length(value: number) {
+	set length(_value: number) {
 		throw new Error("Setting the length on BooleanArray's is not supported");
 	}
 }

package/test.js

@@ -0,0 +1,6 @@
+import BooleanArray from './dist/index.js';
+
+const array = new BooleanArray(1);
+
+const store = array.set(0, true);
+console.log(array.get(0), store);

package/bench.js

@@ -1,96 +0,0 @@
-import BooleanArray from './dist/index.js';
-import { performance } from 'node:perf_hooks';
-import { serialize } from 'v8';
-
-function getMemoryUsageOfReference(ref) {
-	const serialized = serialize(ref); // Convert the reference to a Buffer
-	return serialized.length; // The size of the serialized Buffer in bytes
-}
-
-function testVanillaArraySet(amount, analyzeMemory = true) {
-	const vanillaArray = [];
-	const startTime = performance.now();
-	for (let i = 0; i < amount; i++) {
-		vanillaArray[i] = true;
-	}
-	const endTime = performance.now();
-	const usedMemory = analyzeMemory ? getMemoryUsageOfReference(vanillaArray) : 0;
-	return { vanillaArray, usedMemory, startTime, endTime };
-}
-testVanillaArraySet._name = 'Set Vanilla array     ';
-
-function testBooleanArraySet(amount, analyzeMemory = true) {
-	const theBooleanArray = new BooleanArray(amount);
-	const startTime = performance.now();
-	for (let i = 0; i < amount; i++) {
-		theBooleanArray.set(i, true);
-	}
-	const endTime = performance.now();
-	const usedMemory = analyzeMemory ? getMemoryUsageOfReference(theBooleanArray) : 0;
-	return { theBooleanArray, usedMemory, startTime, endTime };
-}
-testBooleanArraySet._name = 'Set Fast Boolean Array';
-
-function testVanillaArrayGet(amount) {
-	const { vanillaArray } = testVanillaArraySet(amount, false);
-	const startTime = performance.now();
-	for (let i = 0; i < amount; i++) {
-		vanillaArray[i];
-	}
-	const endTime = performance.now();
-	return {
-		usedMemory: 0,
-		startTime,
-		endTime
-	};
-}
-testVanillaArrayGet._name = 'Get Vanilla array     ';
-
-function testBooleanArrayGet(amount) {
-	const { theBooleanArray } = testBooleanArraySet(amount, false);
-	const startTime = performance.now();
-	for (let i = 0; i < amount; i++) {
-		theBooleanArray.get(i, true);
-	}
-	const endTime = performance.now();
-	return {
-		usedMemory: 0,
-		startTime,
-		endTime
-	};
-}
-testBooleanArrayGet._name = 'Get Fast Boolean Array';
-
-function performanceTest(test, amount) {
-	const runs = 1000; // Number of times to run the test
-	let totalTime = 0;
-	let totalMemory = 0;
-
-	for (let i = 0; i < runs; i++) {
-		const { startTime, endTime, usedMemory } = test(amount);
-
-		totalTime += endTime - startTime;
-		totalMemory += usedMemory;
-	}
-
-	const averageTime = (totalTime / runs).toFixed(8);
-	const averageMemory = totalMemory / runs;
-
-	console.log(
-		`${test._name}: ${averageTime} ms | ${test.name.includes('Set') ? averageMemory + ' Bytes' : 'N/A'} | ${amount} indexes`
-	);
-}
-
-// Run tests
-console.clear();
-[1, 100, 1_000, 10_000, 100_000, 1_000_000, 10_000_000].forEach(async (amount) => {
-	console.log('');
-	[testVanillaArraySet, testBooleanArraySet, testVanillaArrayGet, testBooleanArrayGet].forEach(
-		(test) => {
-			performanceTest(test, amount);
-		}
-	);
-	await new Promise((resolve) => {
-		setTimeout(resolve, 5_000); // Let garbadge collection do its thing for more accurate memory logging
-	});
-});