@thi.ng/bitstream 2.2.67 → 2.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-08-10T15:03:07Z
+- **Last updated**: 2024-08-19T13:45:57Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,14 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/bitstream@2.3.0) (2024-08-19)
+
+#### 🚀 Features
+
+- add support for unsafe reads in BitInputStream ([5edd4dd](https://github.com/thi-ng/umbrella/commit/5edd4dd))
+  - add optional arg to disable bounds checking in all read methods
+  - update readme
+
 ### [2.2.61](https://github.com/thi-ng/umbrella/tree/@thi.ng/bitstream@2.2.61) (2024-06-21)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 198 standalone projects, maintained as part
+> This is one of 199 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -67,7 +67,7 @@ For Node.js REPL:
 const bit = await import("@thi.ng/bitstream");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.33 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.35 KB
 
 ## Dependencies
 
@@ -131,7 +131,11 @@ auto-configured input stream can also be obtained via `output.reader()`.
 The class too implements the ES6 Iterator API for **bitwise** read
 access, as well as a `read()` method to read bitfields.
 
-**Note**: Attempting to read beyond capacity will throw an EOF error.
+**Note**: By default, attempting to read beyond capacity will throw an EOF
+error. However, all available read methods in `BitInputStream` support an
+optional argument to disable bounds checking (by passing `false` as extra arg).
+These unsafe reads will result in undefined behavior once read past EOF — use
+with caution!
 
 Using `input.seek(pos)`, the read position can be repositioned within
 stream limits.

package/input.d.ts

@@ -10,12 +10,12 @@ export declare class BitInputStream {
     get length(): number;
     get position(): number;
     seek(pos: number): BitInputStream;
-    read(wordSize?: number): number;
-    readFields(fields: number[]): number[];
-    readWords(n: number, wordSize?: number): number[];
-    readStruct(fields: [string, number][]): any;
-    readBit(): number;
-    protected _read(wordSize: number): number;
+    read(wordSize?: number, safe?: boolean): number;
+    readFields(fields: number[], safe?: boolean): number[];
+    readWords(n: number, wordSize?: number, safe?: boolean): number[];
+    readStruct(fields: [string, number][], safe?: boolean): any;
+    readBit(safe?: boolean): number;
+    protected _read(wordSize: number, safe?: boolean): number;
     protected checkLimit(requested: number): void;
 }
 //# sourceMappingURL=input.d.ts.map

package/input.js

@@ -1,6 +1,6 @@
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { illegalState } from "@thi.ng/errors/illegal-state";
-const U32 = Math.pow(2, 32);
+const U32 = 4294967296;
 class BitInputStream {
   buffer;
   start;
@@ -42,42 +42,42 @@ class BitInputStream {
     this.bitPos = pos;
     return this;
   }
-  read(wordSize = 1) {
+  read(wordSize = 1, safe = true) {
     if (wordSize > 32) {
-      return this.read(wordSize - 32) * U32 + this.read(32);
+      return this.read(wordSize - 32, safe) * U32 + this.read(32, safe);
     } else if (wordSize > 8) {
       let out = 0;
       let n = wordSize & -8;
       let msb = wordSize - n;
       if (msb > 0) {
-        out = this._read(msb);
+        out = this._read(msb, safe);
       }
       while (n > 0) {
-        out = (out << 8 | this._read(8)) >>> 0;
+        out = (out << 8 | this._read(8, safe)) >>> 0;
         n -= 8;
       }
       return out;
     } else {
-      return this._read(wordSize);
+      return this._read(wordSize, safe);
     }
   }
-  readFields(fields) {
-    return fields.map((word) => this.read(word));
+  readFields(fields, safe = true) {
+    return fields.map((word) => this.read(word, safe));
   }
-  readWords(n, wordSize = 8) {
+  readWords(n, wordSize = 8, safe = true) {
     let out = [];
     while (n-- > 0) {
-      out.push(this.read(wordSize));
+      out.push(this.read(wordSize, safe));
     }
     return out;
   }
-  readStruct(fields) {
+  readStruct(fields, safe = true) {
     return fields.reduce((acc, [id, word]) => {
-      return acc[id] = this.read(word), acc;
+      return acc[id] = this.read(word, safe), acc;
     }, {});
   }
-  readBit() {
-    this.checkLimit(1);
+  readBit(safe = true) {
+    safe && this.checkLimit(1);
     this.bit--;
     this.bitPos++;
     let out = this.buffer[this.pos] >>> this.bit & 1;
@@ -87,8 +87,8 @@ class BitInputStream {
     }
     return out;
   }
-  _read(wordSize) {
-    this.checkLimit(wordSize);
+  _read(wordSize, safe = true) {
+    safe && this.checkLimit(wordSize);
     let l = this.bit - wordSize, out;
     if (l >= 0) {
       this.bit = l;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/bitstream",
-  "version": "2.2.67",
+  "version": "2.3.0",
   "description": "ES6 iterator based read/write bit streams with support for variable word widths",
   "type": "module",
   "module": "./index.js",
@@ -36,7 +36,7 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/errors": "^2.5.14"
+    "@thi.ng/errors": "^2.5.15"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.47.5",
@@ -81,5 +81,5 @@
       "rle-pack"
     ]
   },
-  "gitHead": "ec78f98d015e4d214a0b840e72e497407807daf3\n"
+  "gitHead": "bfbc227cf5ca2d3c2984b3d4713eebd6225cbd54\n"
 }