@thi.ng/leb128 3.0.87 → 3.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-11T12:32:44Z
+- **Last updated**: 2024-04-20T14:42:45Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,16 @@ 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.
 
+## [3.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/leb128@3.1.0) (2024-04-20)
+
+#### 🚀 Features
+
+- update docs, add encode[SU]LEB128Into() fns ([44f927b](https://github.com/thi-ng/umbrella/commit/44f927b))
+  - update/fix doc strings
+  - retroactively document new functions by @jtenner's PR ([#460](https://github.com/thi-ng/umbrella/issues/460))
+    - add encodeSLEB128Into()
+    - add encodeULEB128Into()
+
 ### [3.0.47](https://github.com/thi-ng/umbrella/tree/@thi.ng/leb128@3.0.47) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -39,6 +39,10 @@ environments. The source code of the actual implementation (written in
 All public functions throw an error if the WASM module could not be
 initialized.
 
+The `encodeSLEB128Into()` and `encodeULEB128Into()` functions will check the
+bounds of the target array to ensure all bytes can be written and will
+throw an error if the result would go out of bounds.
+
 References:
 
 - https://en.wikipedia.org/wiki/LEB128
@@ -74,10 +78,10 @@ import * as leb from "@thi.ng/leb128";
 Browser ESM import:
 
 ```html
-<script type="module" src="https://cdn.skypack.dev/@thi.ng/leb128"></script>
+<script type="module" src="https://esm.run/@thi.ng/leb128"></script>
 ```
 
-[Skypack documentation](https://docs.skypack.dev/)
+[JSDelivr documentation](https://www.jsdelivr.com/)
 
 For Node.js REPL:
 
@@ -85,7 +89,7 @@ For Node.js REPL:
 const leb = await import("@thi.ng/leb128");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 880 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 968 bytes
 
 ## Dependencies
 
@@ -97,23 +101,37 @@ Package sizes (brotli'd, pre-treeshake): ESM: 880 bytes
 
 [Generated API docs](https://docs.thi.ng/umbrella/leb128/)
 
-```ts
+```ts tangle:export/readme1.ts
 import * as leb from "@thi.ng/leb128";
 
 // if WASM is unavailable, the encode/decode functions will throw an error
-enc = leb.encodeULEB128(Number.MAX_SAFE_INTEGER);
+let encoded = leb.encodeULEB128(Number.MAX_SAFE_INTEGER);
+
+console.log(encoded);
 // Uint8Array [ 255, 255, 255, 255, 255, 255, 255, 15 ]
 
 // decoding returns tuple of [value (bigint), bytes consumed]
-leb.decodeULEB128(enc);
+console.log(leb.decodeULEB128(encoded));
 // [ 9007199254740991n, 8 ]
 
 // encode signed int
-enc = leb.encodeSLEB128(Number.MIN_SAFE_INTEGER)
+encoded = leb.encodeSLEB128(Number.MIN_SAFE_INTEGER);
+
+console.log(encoded)
 // Uint8Array [ 129, 128, 128, 128, 128, 128, 128, 112 ]
 
-leb.decodeSLEB128(enc)
+console.log(leb.decodeSLEB128(encoded));
 // [ -9007199254740991n, 8 ]
+
+// when writing into an existing buffer, there needs to be enough bytes to write the value
+const target = new Uint8Array(10);
+const count = leb.encodeULEB128Into(target, Number.MAX_SAFE_INTEGER);
+
+console.log(target);
+// Uint8Array [ 255, 255, 255, 255, 255, 255, 255, 15, 0, 0 ]
+
+console.log(count);
+// 8
 ```
 
 ## Building the binary
@@ -142,14 +160,15 @@ yarn test
 
 ## Authors
 
-- [Karsten Schmidt](https://thi.ng)
+- [Karsten Schmidt](https://thi.ng) (Main author)
+- [jtenner](https://github.com/jtenner)
 
 If this project contributes to an academic publication, please cite it as:
 
 ```bibtex
 @misc{thing-leb128,
   title = "@thi.ng/leb128",
-  author = "Karsten Schmidt",
+  author = "Karsten Schmidt and others",
   note = "https://thi.ng/leb128",
   year = 2019
 }

package/binary.d.ts

@@ -1,5 +1,5 @@
 /**
- * Generated @ 2022-12-02T12:00:53Z
+ * Generated @ 2024-04-13T13:45:31Z
  *
  * @internal
  */

package/index.d.ts

@@ -1,33 +1,59 @@
 /**
- * Encodes signed integer `x` into LEB128 varint format and returns
- * encoded bytes.
+ * Encodes signed integer `x` into LEB128 varint format and returns encoded
+ * bytes. Values will be coerced to i64 range prior to encoding.
  *
  * @param x -
  */
 export declare const encodeSLEB128: (x: bigint | number) => Uint8Array;
 /**
- * Takes Uint8Array with LEB128 encoded signed varint and an optional
- * start index to decode from. Returns 2-tuple of decoded value and
- * number of bytes consumed. Consumes up to 10 bytes from `src`.
+ * Takes an `Uint8Array` with LEB128 encoded signed varint and an optional start
+ * index to decode from. Returns 2-tuple of decoded value and number of bytes
+ * consumed. Consumes up to 10 bytes from `src`.
  *
  * @param src -
  * @param idx -
  */
 export declare const decodeSLEB128: (src: Uint8Array, idx?: number) => [bigint, number];
 /**
- * Encodes unsigned integer `x` into LEB128 varint format and returns
- * encoded bytes. Values < 0 will be encoded as zero.
+ * Takes a destination `Uint8Array`, a signed integer `x`, and an optional
+ * index/position to encode an LEB128 formatted byte sequence into the
+ * destination. Returns the number of bytes written.
+ *
+ * @remarks
+ * Also see {@link encodeSLEB128}.
+ *
+ * @param dst -
+ * @param x -
+ * @param pos -
+ */
+export declare const encodeSLEB128Into: (dst: Uint8Array, x: bigint | number, pos?: number) => number;
+/**
+ * Encodes unsigned integer `x` into LEB128 varint format and returns encoded
+ * bytes. Values will be coerced to u64 range prior to encoding.
  *
  * @param x -
  */
 export declare const encodeULEB128: (x: bigint | number) => Uint8Array;
 /**
- * Takes Uint8Array with LEB128 encoded unsigned varint and an optional
- * start index to decode from. Returns 2-tuple of decoded value and
- * number of bytes consumed. Consumes up to 10 bytes from `src`.
+ * Takes an `Uint8Array` with LEB128 encoded unsigned varint and an optional
+ * start index to decode from. Returns 2-tuple of decoded value and number of
+ * bytes consumed. Consumes up to 10 bytes from `src`.
  *
  * @param src -
  * @param idx -
  */
 export declare const decodeULEB128: (src: Uint8Array, idx?: number) => [bigint, number];
+/**
+ * Takes a destination Uint8Array, an unsigned integer `x`, and an optional
+ * position to encode an LEB128 formatted byte sequence into the destination.
+ * Returns the number of bytes written.
+ *
+ * @remarks
+ * Also see {@link encodeULEB128}.
+ *
+ * @param dst -
+ * @param x -
+ * @param pos -
+ */
+export declare const encodeULEB128Into: (dst: Uint8Array, x: bigint | number, pos?: number) => number;
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,5 +1,6 @@
 import { hasWASM } from "@thi.ng/checks/has-wasm";
 import { unsupported } from "@thi.ng/errors/unsupported";
+import { ensureIndex } from "@thi.ng/errors/out-of-bounds";
 import { base64Decode } from "@thi.ng/transducers-binary/base64";
 import { BINARY } from "./binary.js";
 let wasm;
@@ -17,6 +18,14 @@ const encode = (op, signed) => (x) => {
   const value = signed ? BigInt.asIntN(64, BigInt(x)) : BigInt.asUintN(64, BigInt(x));
   return U8.slice(0, wasm[op](value));
 };
+const encodeInto = (op, signed) => (dst, x, pos = 0) => {
+  ensureWASM();
+  const value = signed ? BigInt.asIntN(64, BigInt(x)) : BigInt.asUintN(64, BigInt(x));
+  const size = wasm[op](value);
+  ensureIndex(pos, 0, dst.length - size + 1);
+  dst.set(U8.subarray(0, size), pos);
+  return size;
+};
 const decode = (op, signed) => (src, idx = 0) => {
   ensureWASM();
   U8.set(src.subarray(idx, Math.min(idx + 10, src.length)), 0);
@@ -28,11 +37,15 @@ const decode = (op, signed) => (src, idx = 0) => {
 };
 const encodeSLEB128 = encode("leb128EncodeI64", true);
 const decodeSLEB128 = decode("leb128DecodeI64", true);
+const encodeSLEB128Into = encodeInto("leb128EncodeI64", true);
 const encodeULEB128 = encode("leb128EncodeU64", false);
 const decodeULEB128 = decode("leb128DecodeU64", false);
+const encodeULEB128Into = encodeInto("leb128EncodeU64", true);
 export {
   decodeSLEB128,
   decodeULEB128,
   encodeSLEB128,
-  encodeULEB128
+  encodeSLEB128Into,
+  encodeULEB128,
+  encodeULEB128Into
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/leb128",
-  "version": "3.0.87",
+  "version": "3.1.0",
   "description": "WASM based LEB128 encoder / decoder (signed & unsigned)",
   "type": "module",
   "module": "./index.js",
@@ -22,6 +22,9 @@
     }
   ],
   "author": "Karsten Schmidt (https://thi.ng)",
+  "contributors": [
+    "jtenner (https://github.com/jtenner)"
+  ],
   "license": "Apache-2.0",
   "scripts": {
     "build": "yarn build:esbuild && yarn build:decl",
@@ -37,9 +40,9 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/checks": "^3.6.1",
-    "@thi.ng/errors": "^2.5.4",
-    "@thi.ng/transducers-binary": "^2.1.116"
+    "@thi.ng/checks": "^3.6.2",
+    "@thi.ng/errors": "^2.5.5",
+    "@thi.ng/transducers-binary": "^2.1.117"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.43.0",
@@ -82,5 +85,5 @@
     "alias": "leb",
     "year": 2019
   },
-  "gitHead": "18a0c063a7b33d790e5bc2486c106f45f663ac28\n"
+  "gitHead": "8339d05ecc857e529c7325a9839c0063b89e728d\n"
 }