@thi.ng/bitstream 2.1.7 → 2.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-06-09T16:14:01Z
+- **Last updated**: 2022-07-06T11:33:31Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,13 @@ 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.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/bitstream@2.2.0) (2022-07-06)
+
+#### 🚀 Features
+
+- add barebones bitReader/Writer() ([e17dff9](https://github.com/thi-ng/umbrella/commit/e17dff9))
+  - update pkg & readme
+
 ## [2.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/bitstream@2.1.0) (2021-11-17)
 
 #### 🚀 Features

package/README.md

@@ -17,6 +17,7 @@ This project is part of the
 - [API](#api)
   - [BitOutputStream](#bitoutputstream)
   - [BitInputStream](#bitinputstream)
+  - [Barebones alternatives](#barebones-alternatives)
 - [Authors](#authors)
 - [License](#license)
 
@@ -58,7 +59,7 @@ node --experimental-repl-await
 > const bitstream = await import("@thi.ng/bitstream");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.10 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.31 KB
 
 ## Dependencies
 
@@ -164,6 +165,36 @@ input.read(7)
 In addition to the generic `read()` method, there's also the slightly
 faster `readBit()` for reading single bits.
 
+### Barebones alternatives
+
+For use cases requiring only word sizes <=8 bits and none of the advanced features provided by the above implementations, the package also provides functional barebones alternatives in the form of [`bitWriter()`](https://docs.thi.ng/umbrella/bitstream/modules.html#bitWriter) and [`bitReader()`](https://docs.thi.ng/umbrella/bitstream/modules.html#bitReader):
+
+```ts
+import { bitReader, bitWriter } from "@thi.ng/bistream";
+
+const writer = bitWriter();
+// write single bit
+writer.write(1);
+
+// write unsigned value (up to 8 bits)
+writer.write(31, 5);
+
+// retrieve buffer
+const bytes = writer.bytes();
+// Uint8Array(1) [ 252 ]
+
+// create reader from byte buffer
+const reader = bitReader(bytes);
+
+// read single bit
+reader();
+// 1
+
+// read n-bit unsigned value
+reader(5);
+// 31
+```
+
 ## Authors
 
 Karsten Schmidt

package/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./input.js";
 export * from "./output.js";
+export * from "./simple.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,2 +1,3 @@
 export * from "./input.js";
 export * from "./output.js";
+export * from "./simple.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/bitstream",
-  "version": "2.1.7",
+  "version": "2.2.0",
   "description": "ES6 iterator based read/write bit streams with support for variable word widths",
   "type": "module",
   "module": "./index.js",
@@ -70,6 +70,9 @@
     },
     "./output": {
       "default": "./output.js"
+    },
+    "./simple": {
+      "default": "./simple.js"
     }
   },
   "thi.ng": {
@@ -78,5 +81,5 @@
       "rle-pack"
     ]
   },
-  "gitHead": "9e516d30a1a537e027a6b3d78bf9121bc5831d31\n"
+  "gitHead": "2cb03180092d0e3e76f28096e7555e87ff7161bb\n"
 }

package/simple.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Barebones alternative to {@link BitOutputStream} for word sizes <= 8 and with
+ * minimal API surface. The returned object only exposes 2 functions:
+ *
+ * - `write(x, size)` - writes a single value of given bit size (default: 1 bit)
+ * - `bytes()` - retrieve all bytes written so far
+ *
+ * @remarks
+ * The internal backing buffer automatically resizes on demand. The optionally
+ * provided `capacity` is only the initial buffer size.
+ *
+ * @param capacity - initial capacity
+ */
+export declare const bitWriter: (capacity?: number) => {
+    write: (x: number, n?: number) => void;
+    bytes: () => Uint8Array;
+};
+/**
+ * Barebones alternative to {@link BitInputStream} for word sizes <= 8 and with
+ * minimal API surface and WITHOUT bounds checking of any form! The returned
+ * function reads `n` bits from the originally provided buffer.
+ *
+ * @param buf
+ */
+export declare const bitReader: (buf: Uint8Array | number[]) => (n?: number) => number;
+//# sourceMappingURL=simple.d.ts.map

package/simple.js

@@ -0,0 +1,79 @@
+/**
+ * Barebones alternative to {@link BitOutputStream} for word sizes <= 8 and with
+ * minimal API surface. The returned object only exposes 2 functions:
+ *
+ * - `write(x, size)` - writes a single value of given bit size (default: 1 bit)
+ * - `bytes()` - retrieve all bytes written so far
+ *
+ * @remarks
+ * The internal backing buffer automatically resizes on demand. The optionally
+ * provided `capacity` is only the initial buffer size.
+ *
+ * @param capacity - initial capacity
+ */
+export const bitWriter = (capacity = 16) => {
+    let buf = new Uint8Array(capacity);
+    let pos = 0;
+    let bit = 8;
+    const ensure = () => {
+        if (++pos === buf.length) {
+            let b = new Uint8Array(buf.length << 1);
+            b.set(buf);
+            buf = b;
+        }
+    };
+    return {
+        write: (x, n = 1) => {
+            x &= (1 << n) - 1;
+            let b = bit - n;
+            let m = bit < 8 ? ~((1 << bit) - 1) : 0;
+            if (b >= 0) {
+                m |= (1 << b) - 1;
+                buf[pos] = (buf[pos] & m) | ((x << b) & ~m);
+                if (b === 0) {
+                    ensure();
+                    bit = 8;
+                }
+                else {
+                    bit = b;
+                }
+            }
+            else {
+                bit = 8 + b;
+                buf[pos] = (buf[pos] & m) | ((x >>> -b) & ~m);
+                ensure();
+                buf[pos] = (buf[pos] & ((1 << bit) - 1)) | ((x << bit) & 0xff);
+            }
+        },
+        bytes: () => buf.slice(0, pos + (bit & 7 ? 1 : 0)),
+    };
+};
+/**
+ * Barebones alternative to {@link BitInputStream} for word sizes <= 8 and with
+ * minimal API surface and WITHOUT bounds checking of any form! The returned
+ * function reads `n` bits from the originally provided buffer.
+ *
+ * @param buf
+ */
+export const bitReader = (buf) => {
+    let p = 0;
+    let b = 8;
+    return (n = 1) => {
+        let l = b - n;
+        let out;
+        if (l >= 0) {
+            b = l;
+            out = (buf[p] >>> l) & ((1 << n) - 1);
+            if (!l) {
+                p++;
+                b = 8;
+            }
+        }
+        else {
+            out = (buf[p++] & ((1 << b) - 1)) << -l;
+            b = 8 + l;
+            out = out | (buf[p] >>> b);
+        }
+        return out;
+    };
+};