@thi.ng/rle-pack 3.1.117 → 3.2.0

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 213 standalone projects, maintained as part
+> This is one of 214 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -15,7 +15,10 @@
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
-  - [Encoding format](#encoding-format)
+  - [Simple RLE](#simple-rle)
+  - [Binary encoding](#binary-encoding)
+    - [Encoding format](#encoding-format)
+    - [Code example](#code-example)
 - [Status](#status)
 - [Related packages](#related-packages)
 - [Installation](#installation)
@@ -26,6 +29,31 @@
 
 ## About
 
+The package provides two approaches for [Run-length
+encoding/decoding](https://en.wikipedia.org/wiki/Run-length_encoding):
+
+### Simple RLE
+
+The naive approach operates on arrays of arbitrary values and supports
+user-defined predicates to determine if a consecutive input values are equal
+(i.e. repeated). By default uses `===` strict comparison.
+
+```ts tangle:export/readme-simple.ts
+import { encodeSimple, decodeSimple } from "@thi.ng/rle-pack";
+
+const src = [..."aaaaaabbbbaaaxyxxx"];
+
+const encoded = encodeSimple(src);
+console.log(encoded);
+// ["a", 6, "b", 4, "a", 3, "x", 1, "y", 1, "x", 3]
+
+const decoded = decodeSimple(encoded);
+console.log(decoded);
+// ["a", "a", "a", "a", "a", "a", "b", "b", "b", "b", "a", "a", "a", "x", "y", "x", "x", "x"]
+```
+
+### Binary encoding
+
 Binary [run-length
 encoding](https://en.wikipedia.org/wiki/Run-length_encoding)
 packer/unpacker with support for customizable input word sizes (1 - 32
@@ -36,7 +64,7 @@ lengths is 16 bits (i.e. 65536 repetitions). If a value is repeated more
 often than that, the remainder will be encoded using additional RLE
 chunks...
 
-### Encoding format
+#### Encoding format
 
 ![data layout](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/rle/rle-layout.png)
 
@@ -54,6 +82,31 @@ Then per value:
   then split into chunks...)
 - n bits - value(s)
 
+#### Code example
+
+```ts tangle:export/readme-binary.ts
+import { encodeBinary, decodeBinary } from "@thi.ng/rle-pack";
+
+// prepare dummy data
+const src = new Uint8Array(1024);
+src.set([1,1,1,1,1,2,2,2,2,3,3,3,4,4,5,4,4,3,3,3,2,2,2,2,1,1,1,1,1], 512);
+
+// pack data
+const packed = encodeBinary(src, src.length);
+console.log(packed.length);
+// 30 => 2.93% of original
+
+// pack with custom word size (3 bits, i.e. our value range is only 0-7)
+// and use custom repeat group sizes suitable for our data
+const alt = encodeBinary(src, src.length, 3, [1, 2, 3, 9]);
+console.log(alt.length);
+// 20 => 1.95% of original, 66% of default config
+
+// unpack
+const unpacked = decodeBinary(alt);
+console.log(unpacked.length);
+```
+
 ## Status
 
 **STABLE** - used in production
@@ -92,39 +145,20 @@ For Node.js REPL:
 const rle = await import("@thi.ng/rle-pack");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 636 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 802 bytes
 
 ## Dependencies
 
+- [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/bitstream](https://github.com/thi-ng/umbrella/tree/develop/packages/bitstream)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 
+Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
+
 ## API
 
 [Generated API docs](https://docs.thi.ng/umbrella/rle-pack/)
 
-```ts
-import { encode, decode } from "@thi.ng/rle-pack";
-
-// prepare dummy data
-src = new Uint8Array(1024);
-src.set([1,1,1,1,1,2,2,2,2,3,3,3,4,4,5,4,4,3,3,3,2,2,2,2,1,1,1,1,1], 512);
-
-// pack data
-packed = encode(src, src.length);
-packed.length
-// 30 => 2.93% of original
-
-// pack with custom word size (3 bits, i.e. our value range is only 0-7)
-// and use custom repeat group sizes suitable for our data
-alt = encode(src, src.length, 3, [1, 2, 3, 9]);
-alt.length
-// 20 => 1.95% of original, 66% of default config
-
-// unpack
-unpacked = new Uint8Array(decode(alt));
-```
-
 ## Authors
 
 - [Karsten Schmidt](https://thi.ng)

package/binary.d.ts

@@ -0,0 +1,17 @@
+export type RLESizes = [number, number, number, number];
+/**
+ * Compresses input using dynamically sized RLE compression and returns
+ * result as `Uint8Array`.
+ *
+ * @param src -
+ * @param num - number of input words
+ * @param wordSize - in bits, range 1 - 32
+ * @param rleSizes - run-length group sizes (in bits, max. 16)
+ */
+export declare const encodeBinary: (src: Iterable<number>, num: number, wordSize?: number, rleSizes?: RLESizes) => Uint8Array<ArrayBuffer>;
+export declare const decodeBinary: (src: Uint8Array) => Uint8Array<ArrayBuffer> | Uint16Array<ArrayBuffer> | Uint32Array<ArrayBuffer>;
+/** @deprecated renamed to {@link encodeBinary} */
+export declare const encode: (src: Iterable<number>, num: number, wordSize?: number, rleSizes?: RLESizes) => Uint8Array<ArrayBuffer>;
+/** @deprecated renamed to {@link decodeBinary} */
+export declare const decode: (src: Uint8Array) => Uint8Array<ArrayBuffer> | Uint16Array<ArrayBuffer> | Uint32Array<ArrayBuffer>;
+//# sourceMappingURL=binary.d.ts.map

package/binary.js

@@ -0,0 +1,102 @@
+import { BitInputStream } from "@thi.ng/bitstream/input";
+import { BitOutputStream } from "@thi.ng/bitstream/output";
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
+const encodeBinary = (src, num, wordSize = 8, rleSizes = [3, 4, 8, 16]) => {
+  (wordSize < 1 || wordSize > 32) && illegalArgs("word size (1-32 bits only)");
+  const out = new BitOutputStream(Math.ceil(num * wordSize / 8) + 4 + 2 + 1).write(num, 32).write(wordSize - 1, 5);
+  rleSizes.forEach((x) => {
+    (x < 1 || x > 16) && illegalArgs("RLE repeat size (1-16 bits only)");
+    out.write(x - 1, 4);
+  });
+  const [rle0, rle1, rle2, rle3] = rleSizes.map((x) => 1 << x);
+  const chunk = [];
+  const n1 = num - 1;
+  let val;
+  let tail = true;
+  let n = 0;
+  let i = 0;
+  const writeRLE = () => {
+    const t = n < rle0 ? 0 : n < rle1 ? 1 : n < rle2 ? 2 : 3;
+    out.writeBit(1);
+    out.write(t, 2);
+    out.write(n, rleSizes[t]);
+    out.write(val, wordSize);
+    n = 0;
+  };
+  const writeChunk = () => {
+    const m = chunk.length - 1;
+    const t = m < rle0 ? 0 : m < rle1 ? 1 : m < rle2 ? 2 : 3;
+    out.writeBit(0);
+    out.write(t, 2);
+    out.write(m, rleSizes[t]);
+    out.writeWords(chunk, wordSize);
+    chunk.length = 0;
+  };
+  for (const x of src) {
+    if (val === void 0) {
+      val = x;
+    } else if (x !== val) {
+      if (n > 0) {
+        writeRLE();
+      } else {
+        chunk.push(val);
+        if (chunk.length === rle3) {
+          writeChunk();
+        }
+      }
+      val = x;
+    } else {
+      if (chunk.length) {
+        writeChunk();
+      }
+      if (++n === rle3) {
+        n--;
+        writeRLE();
+        tail = i < n1;
+      }
+    }
+    if (i === n1) {
+      break;
+    }
+    i++;
+  }
+  if (chunk.length) {
+    chunk.push(val);
+    writeChunk();
+  } else if (tail) {
+    writeRLE();
+  }
+  return out.bytes();
+};
+const decodeBinary = (src) => {
+  const input = new BitInputStream(src);
+  const num = input.read(32);
+  const wordSize = input.read(5) + 1;
+  const rleSizes = [0, 0, 0, 0].map(() => input.read(4) + 1);
+  const out = __arrayForWordSize(wordSize, num);
+  let x, j;
+  for (let i = 0; i < num; ) {
+    x = input.readBit();
+    j = i + 1 + input.read(rleSizes[input.read(2)]);
+    if (x) {
+      out.fill(input.read(wordSize), i, j);
+      i = j;
+    } else {
+      for (; i < j; i++) {
+        out[i] = input.read(wordSize);
+      }
+    }
+  }
+  return out;
+};
+const __arrayForWordSize = (ws, n) => {
+  return new (ws < 9 ? Uint8Array : ws < 17 ? Uint16Array : Uint32Array)(n);
+};
+const encode = encodeBinary;
+const decode = decodeBinary;
+export {
+  decode,
+  decodeBinary,
+  encode,
+  encodeBinary
+};

package/index.d.ts

@@ -1,13 +1,3 @@
-export type RLESizes = [number, number, number, number];
-/**
- * Compresses input using dynamically sized RLE compression and returns
- * result as `Uint8Array`.
- *
- * @param src -
- * @param num - number of input words
- * @param wordSize - in bits, range 1 - 32
- * @param rleSizes - run-length group sizes (in bits, max. 16)
- */
-export declare const encode: (src: Iterable<number>, num: number, wordSize?: number, rleSizes?: RLESizes) => Uint8Array<ArrayBuffer>;
-export declare const decode: (src: Uint8Array) => Uint8Array<ArrayBuffer> | Uint16Array<ArrayBuffer> | Uint32Array<ArrayBuffer>;
+export * from "./binary.js";
+export * from "./simple.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,98 +1,2 @@
-import { BitInputStream } from "@thi.ng/bitstream/input";
-import { BitOutputStream } from "@thi.ng/bitstream/output";
-import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
-const encode = (src, num, wordSize = 8, rleSizes = [3, 4, 8, 16]) => {
-  (wordSize < 1 || wordSize > 32) && illegalArgs("word size (1-32 bits only)");
-  const out = new BitOutputStream(Math.ceil(num * wordSize / 8) + 4 + 2 + 1).write(num, 32).write(wordSize - 1, 5);
-  rleSizes.forEach((x) => {
-    (x < 1 || x > 16) && illegalArgs("RLE repeat size (1-16 bits only)");
-    out.write(x - 1, 4);
-  });
-  const [rle0, rle1, rle2, rle3] = rleSizes.map((x) => 1 << x);
-  const chunk = [];
-  const n1 = num - 1;
-  let val;
-  let tail = true;
-  let n = 0;
-  let i = 0;
-  const writeRLE = () => {
-    const t = n < rle0 ? 0 : n < rle1 ? 1 : n < rle2 ? 2 : 3;
-    out.writeBit(1);
-    out.write(t, 2);
-    out.write(n, rleSizes[t]);
-    out.write(val, wordSize);
-    n = 0;
-  };
-  const writeChunk = () => {
-    const m = chunk.length - 1;
-    const t = m < rle0 ? 0 : m < rle1 ? 1 : m < rle2 ? 2 : 3;
-    out.writeBit(0);
-    out.write(t, 2);
-    out.write(m, rleSizes[t]);
-    out.writeWords(chunk, wordSize);
-    chunk.length = 0;
-  };
-  for (const x of src) {
-    if (val === void 0) {
-      val = x;
-    } else if (x !== val) {
-      if (n > 0) {
-        writeRLE();
-      } else {
-        chunk.push(val);
-        if (chunk.length === rle3) {
-          writeChunk();
-        }
-      }
-      val = x;
-    } else {
-      if (chunk.length) {
-        writeChunk();
-      }
-      if (++n === rle3) {
-        n--;
-        writeRLE();
-        tail = i < n1;
-      }
-    }
-    if (i === n1) {
-      break;
-    }
-    i++;
-  }
-  if (chunk.length) {
-    chunk.push(val);
-    writeChunk();
-  } else if (tail) {
-    writeRLE();
-  }
-  return out.bytes();
-};
-const decode = (src) => {
-  const input = new BitInputStream(src);
-  const num = input.read(32);
-  const wordSize = input.read(5) + 1;
-  const rleSizes = [0, 0, 0, 0].map(() => input.read(4) + 1);
-  const out = __arrayForWordSize(wordSize, num);
-  let x, j;
-  for (let i = 0; i < num; ) {
-    x = input.readBit();
-    j = i + 1 + input.read(rleSizes[input.read(2)]);
-    if (x) {
-      out.fill(input.read(wordSize), i, j);
-      i = j;
-    } else {
-      for (; i < j; i++) {
-        out[i] = input.read(wordSize);
-      }
-    }
-  }
-  return out;
-};
-const __arrayForWordSize = (ws, n) => {
-  return new (ws < 9 ? Uint8Array : ws < 17 ? Uint16Array : Uint32Array)(n);
-};
-export {
-  decode,
-  encode
-};
+export * from "./binary.js";
+export * from "./simple.js";

package/package.json

@@ -1,14 +1,15 @@
 {
 	"name": "@thi.ng/rle-pack",
-	"version": "3.1.117",
-	"description": "Binary run-length encoding packer w/ flexible repeat bit widths",
+	"version": "3.2.0",
+	"description": "Binary run-length encoding packer w/ flexible repeat bit widths and a naive RLE encoder/decoder for arrays of arbitrary typed values",
 	"type": "module",
 	"module": "./index.js",
 	"typings": "./index.d.ts",
 	"sideEffects": false,
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/thi-ng/umbrella.git"
+		"url": "git+https://github.com/thi-ng/umbrella.git",
+		"directory": "packages/rle-pack"
 	},
 	"homepage": "https://thi.ng/rle-pack",
 	"funding": [
@@ -39,8 +40,9 @@
 		"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
 	},
 	"dependencies": {
-		"@thi.ng/bitstream": "^2.4.39",
-		"@thi.ng/errors": "^2.6.2"
+		"@thi.ng/api": "^8.12.14",
+		"@thi.ng/bitstream": "^2.4.41",
+		"@thi.ng/errors": "^2.6.3"
 	},
 	"devDependencies": {
 		"esbuild": "^0.27.2",
@@ -69,6 +71,12 @@
 	"exports": {
 		".": {
 			"default": "./index.js"
+		},
+		"./binary": {
+			"default": "./binary.js"
+		},
+		"./simple": {
+			"default": "./simple.js"
 		}
 	},
 	"thi.ng": {
@@ -80,5 +88,5 @@
 		],
 		"year": 2017
 	},
-	"gitHead": "828ec2e9ffde7307231b03cff46598c0915b1857\n"
+	"gitHead": "b90a2f41eb0b3c89391bbb7cfff940192f23a83c\n"
 }

package/simple.d.ts

@@ -0,0 +1,33 @@
+import type { Predicate2 } from "@thi.ng/api";
+/**
+ * Performs basic RLE encoding on the given `src` array(like) input, using the
+ * optional `equiv` predicate to determine if the current value is a repetition
+ * of an earlier one (i.e consecutive values are considered repetitions as long
+ * as that predicate returns true). The default predicate is using `===` for
+ * comparison. Returns RLE result array of `[value1, count1, value2, count2...]`
+ *
+ * @example
+ * ```ts tangle:../export/encode-simple.ts
+ * import { encodeSimple } from "@thi.ng/rle-pack";
+ *
+ * const src = [..."aaaaaabbbbaaaxyxxx"];
+ *
+ * console.log(src);
+ * // ["a", "a", "a", "a", "a", "a", "b", "b", "b", "b", "a", "a", "a", "x", "y", "x", "x", "x"]
+ *
+ * console.log(encodeSimple(src));
+ * // ["a", 6, "b", 4, "a", 3, "x", 1, "y", 1, "x", 3]
+ * ```
+ *
+ * @param src
+ * @param equiv
+ */
+export declare const encodeSimple: <T = any>(src: ArrayLike<T>, equiv?: Predicate2<T>) => any[];
+/**
+ * Reverse op of {@link encodeSimple}. Takes an RLE array and returns restored
+ * original version. Throws an error if `src.length` is not even.
+ *
+ * @param src
+ */
+export declare const decodeSimple: (src: any[]) => any[];
+//# sourceMappingURL=simple.d.ts.map

package/simple.js

@@ -0,0 +1,32 @@
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
+const encodeSimple = (src, equiv = (a, b) => a === b) => {
+  const result = [];
+  const n = src.length;
+  if (!n) return result;
+  let val = src[0];
+  let start = 0;
+  for (let i = 1; i < n; i++) {
+    if (!equiv(src[i], val)) {
+      result.push(val, i - start);
+      val = src[i];
+      start = i;
+    }
+  }
+  result.push(val, n - start);
+  return result;
+};
+const decodeSimple = (src) => {
+  const n = src.length;
+  if (n & 1) illegalArgs(`input length must be even`);
+  const result = [];
+  for (let i = 0; i < n; i += 2) {
+    const val = src[i];
+    const count = src[i + 1];
+    for (let j = 0; j < count; j++) result.push(val);
+  }
+  return result;
+};
+export {
+  decodeSimple,
+  encodeSimple
+};