@oazmi/superbuild 0.1.0

package/esm/deps/jsr.io/@oazmi/kitchensink/0.10.0/src/eightpack.d.ts

@@ -0,0 +1,168 @@
+/** utility functions for packing and unpacking bytes (8-bits) of primitive javascript objects.
+ * > and hence the name of the module (*8(bit)pack*).
+ *
+ * @module
+*/
+import type { NumericArrayType, NumericType, VarNumericArrayType, VarNumericType } from "./typedefs.js";
+/** binary primitive types.
+ * - {@link NumericType} various binary representations of number
+ * - {@link NumericArrayType} various binary representations of array of numbers. requires defining array length (number of items) during decoding as `args[0]`
+ * - `"bytes"` a `Uint8Array`, which requires defining a bytesize length during decoding as `args[0]`
+ * - `"str"` a string, which requires defining a bytesize length during decoding as `args[0]`
+ * - `"cstr"` a null-terminated (`"\u0000"`) string. the null termination byte character is automatically added when encoding
+ * - `"bool"` a boolean occupying a single byte
+*/
+export type PrimitiveType = PrimitiveArrayType | NumericType | VarNumericType | "cstr" | "bool";
+/** primitive types that typically require length information to be decoded. */
+export type PrimitiveArrayType = NumericArrayType | VarNumericArrayType | "bytes" | "str";
+/** all unpack functions return their decoded outputs in a 2-tuple array;
+ * the first element being the decoded value `V`, and the second being the number of bytes this data occupied.
+*/
+export type Decoded<V, ByteSize extends number = number> = [value: V, bytesize: ByteSize];
+/** primitive javascript types. */
+export type JSPrimitive = string | boolean | number | bigint | number[] | Uint8Array;
+/** packing function signature for {@link JSPrimitive} types. */
+export type EncodeFunc<T extends JSPrimitive, ARGS extends any[] = []> = (value: T, ...args: ARGS) => Uint8Array;
+/** unpacking function signature for {@link JSPrimitive} types. */
+export type DecodeFunc<T extends JSPrimitive, ARGS extends any[] = []> = (buffer: Uint8Array, offset: number, ...args: ARGS) => Decoded<T>;
+/** an instance of `TextEncoder`. (i.e. `new TextEncoder()`, that uses `utf8` encoding). */
+export declare const textEncoder: TextEncoder;
+/** an instance of `TextDecoder`. (i.e. `new TextDecoder()`, that uses `utf8` encoding). */
+export declare const textDecoder: TextDecoder;
+/** read `type` of value from buffer `buf`, starting at position `offset`. */
+export declare const readFrom: (buf: Uint8Array, offset: number, type: PrimitiveType, ...args: any[]) => [value: JSPrimitive, new_offset: number];
+/** write `type` of `value` to buffer `buf`, starting at position `offset`. */
+export declare const writeTo: (buf: Uint8Array, offset: number, type: PrimitiveType, value: JSPrimitive, ...args: any[]) => [buf: typeof buf, new_offset: number];
+/** encode a sequential array of primitive items.
+ * to invert/decode the transformation, use {@link unpackSeq}.
+ *
+ * under the hood, this function uses {@link pack} for encoding each item.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * assertEquals(
+ * 	packSeq(["u4b", 0x12AB98], ["str", "hello"], ["bool", false]),
+ * 	Uint8Array.of(0x00, 0x12, 0xAB, 0x98, 104, 101, 108, 108, 111, 0),
+ * )
+ * ```
+*/
+export declare const packSeq: (...items: Parameters<typeof pack>[]) => any;
+/** decodes as a sequential array of items, provided that you pair the values with their `PrimitiveType`s.
+ * this is the inverse of {@link packSeq}.
+ *
+ * under the hood, this function uses {@link unpack} for decoding each item.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * assertEquals(
+ * 	unpackSeq(
+ * 		Uint8Array.of(0x00, 0x12, 0xAB, 0x98, 104, 101, 108, 108, 111, 0), // byte buffer
+ * 		0,          // starting index
+ * 		["u4b"],    // first decoded item should be a 4-byte unsigned integer in big-endian byte-order.
+ * 		["str", 5], // the second item should be a string consisting of 5 bytes (5 characters in this case).
+ * 		["bool"],   // the last item should be a 1-byte boolean.
+ * 	), [
+ * 		[0x12AB98, "hello", false], // decoded items
+ * 		10,                         // bytes decoded
+ * 	],
+ * )
+ * ```
+*/
+export declare const unpackSeq: (buf: Uint8Array, offset: number, ...items: [type: PrimitiveType, ...args: any[]][]) => Decoded<JSPrimitive[]>;
+/** a primitive value encoder/packer for a given `type` (see {@link PrimitiveType}).
+ * to invert/decode the transformation, use {@link unpack}.
+ *
+ * under the hood, this function calls one of the following primitive value encoders, based on the `type` that you provide:
+ * - {@link encode_bool}, {@link encode_cstr}, {@link encode_str}, {@link encode_bytes},
+ *   {@link encode_number}, {@link encode_number_array}, {@link encode_varint}, {@link encode_varint_array}
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * // aliasing for brevity
+ * const u8 = Uint8Array, eq = assertEquals
+ *
+ * eq(pack("bool" , true),           u8.of(1))
+ * eq(pack("cstr" , "hello"),        u8.of(104, 101, 108, 108, 111, 0))
+ * eq(pack("str"  , "hello"),        u8.of(104, 101, 108, 108, 111))
+ * eq(pack("bytes", u8.of(1, 2, 3)), u8.of(1, 2, 3))
+ * // NOTE: if your device's native endian is not little-endian, then the test below will fail.
+ * eq(pack("f8l[]", [1.1, 2.2, 3**45.67]), new u8(Float64Array.of(1.1, 2.2, 3**45.67).buffer))
+ * ```
+*/
+export declare const pack: (type: PrimitiveType, value: JSPrimitive, ...args: any[]) => ReturnType<EncodeFunc<JSPrimitive>>;
+/** a buffer decoder/unpacker for a primitive value of a certain `type` (see {@link PrimitiveType}).
+ * this is the inverse of {@link pack}.
+ *
+ * under the hood, this function calls one of the following primitive value decoders, based on the `type` that you provide:
+ * - {@link decode_bool}, {@link decode_cstr}, {@link decode_str}, {@link decode_bytes},
+ *   {@link decode_number}, {@link decode_number_array}, {@link decode_varint}, {@link decode_varint_array}
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * // aliasing for brevity
+ * const u8 = Uint8Array, eq = assertEquals
+ *
+ * eq(unpack(
+ * 	"bool",         // type of value to decode
+ * 	u8.of(1, 0, 1), // buffer to decode from
+ * 	1,              // the index to begin decoding from
+ * ), [
+ * 	false, // returned decoded value
+ * 	1,     // number of bytes traversed while decoding (i.e. byte size of the decoded object)
+ * ])
+ *
+ * eq(unpack("cstr" , u8.of(97, 98, 99, 0, 100, 101), 0),    ["abc"      , 4])
+ * eq(unpack("str"  , u8.of(97, 98, 99, 0, 100, 101), 0),    ["abc\x00de", 6])
+ * eq(unpack("str"  , u8.of(97, 98, 99, 0, 100, 101), 0, 4), ["abc\x00"  , 4])
+ * eq(unpack("bytes", u8.of(0, 1, 2, 3, 4, 5, 6), 2, 4),     [u8.of(2, 3, 4, 5), 4])
+ * eq(unpack("i2b[]", u8.of(0, 1, 2, 3, 4, 5), 2),           [[0x0203, 0x0405] , 4])
+ * eq(unpack("i2b[]", u8.of(0, 1, 2, 3, 4, 5), 0, 2),        [[0x0001, 0x0203] , 4])
+ * ```
+*/
+export declare const unpack: (type: PrimitiveType, buf: Uint8Array, offset: number, ...args: any[]) => ReturnType<DecodeFunc<JSPrimitive>>;
+/** pack a `boolean` as 1-byte of data. */
+export declare const encode_bool: EncodeFunc<boolean>;
+/** unpack a `boolean` from 1-byte of data. */
+export declare const decode_bool: DecodeFunc<boolean>;
+/** pack a `string` as an array of characters, terminated by the `"\x00"` (or `"\u0000"`) charbyte.
+ * this is the traditional c-programming language convention for strings.
+*/
+export declare const encode_cstr: EncodeFunc<string>;
+/** unpack a `string` as an array of characters that's terminated by `"\x00"` (or `"\u0000"`) charbyte.
+ * this is the traditional c-programming language convention for strings.
+*/
+export declare const decode_cstr: DecodeFunc<string>;
+/** pack a `string` as an array of characters. */
+export declare const encode_str: EncodeFunc<string>;
+/** unpack a `string` as an array of characters.
+ * you must provide the `bytesize` of the string being decoded,
+ * otherwise the decoder will unpack till the end of the buffer.
+*/
+export declare const decode_str: DecodeFunc<string, [bytesize?: number]>;
+/** pack a `Uint8Array` array of bytes as is. (ie: don't perform any operation). */
+export declare const encode_bytes: EncodeFunc<Uint8Array>;
+/** unpack a `Uint8Array` array of bytes.
+ * you must provide the `bytesize` of the bytes being decoded,
+ * otherwise the decoder will unpack till the end of the buffer.
+*/
+export declare const decode_bytes: DecodeFunc<Uint8Array, [bytesize?: number]>;
+/** pack a numeric array (`number[]`) in the provided {@link NumericArrayType} byte representation. */
+export declare const encode_number_array: EncodeFunc<number[], [type: NumericArrayType]>;
+/** unpack a numeric array (`number[]`) that is encoded in one of {@link NumericArrayType} byte representation.
+ * you must provide the `array_length` of the array being decoded,
+ * otherwise the decoder will unpack till the end of the buffer.
+*/
+export declare const decode_number_array: DecodeFunc<number[], [type: NumericArrayType, array_length?: number]>;
+/** pack a `number` in the provided {@link NumericType} byte representation. */
+export declare const encode_number: EncodeFunc<number, [type: NumericType]>;
+/** unpack a `number` in the provided {@link NumericType} byte representation. */
+export declare const decode_number: DecodeFunc<number, [type: NumericType]>;
+//# sourceMappingURL=eightpack.d.ts.map

package/esm/deps/jsr.io/@oazmi/kitchensink/0.10.0/src/eightpack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eightpack.d.ts","sourceRoot":"","sources":["../../../../../../../src/deps/jsr.io/@oazmi/kitchensink/0.10.0/src/eightpack.ts"],"names":[],"mappings":"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"}

package/esm/deps/jsr.io/@oazmi/kitchensink/0.10.0/src/eightpack.js

@@ -0,0 +1,236 @@
+/** utility functions for packing and unpacking bytes (8-bits) of primitive javascript objects.
+ * > and hence the name of the module (*8(bit)pack*).
+ *
+ * @module
+*/
+import { array_from, number_parseInt } from "./alias.js";
+import { decode_varint, decode_varint_array, encode_varint, encode_varint_array } from "./eightpack_varint.js";
+import { concatBytes, env_is_little_endian, swapEndiannessFast, typed_array_constructor_of } from "./typedbuffer.js";
+/** an instance of `TextEncoder`. (i.e. `new TextEncoder()`, that uses `utf8` encoding). */
+export const textEncoder = /*@__PURE__*/ new TextEncoder();
+/** an instance of `TextDecoder`. (i.e. `new TextDecoder()`, that uses `utf8` encoding). */
+export const textDecoder = /*@__PURE__*/ new TextDecoder();
+/** read `type` of value from buffer `buf`, starting at position `offset`. */
+export const readFrom = (buf, offset, type, ...args) => {
+    const [value, bytesize] = unpack(type, buf, offset, ...args);
+    return [value, offset + bytesize];
+};
+/** write `type` of `value` to buffer `buf`, starting at position `offset`. */
+export const writeTo = (buf, offset, type, value, ...args) => {
+    const value_buf = pack(type, value, ...args);
+    buf.set(value_buf, offset);
+    return [buf, offset + value_buf.length];
+};
+/** encode a sequential array of primitive items.
+ * to invert/decode the transformation, use {@link unpackSeq}.
+ *
+ * under the hood, this function uses {@link pack} for encoding each item.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * assertEquals(
+ * 	packSeq(["u4b", 0x12AB98], ["str", "hello"], ["bool", false]),
+ * 	Uint8Array.of(0x00, 0x12, 0xAB, 0x98, 104, 101, 108, 108, 111, 0),
+ * )
+ * ```
+*/
+export const packSeq = (...items) => {
+    const bufs = [];
+    for (const item of items) {
+        bufs.push(pack(...item));
+    }
+    return concatBytes(...bufs);
+};
+/** decodes as a sequential array of items, provided that you pair the values with their `PrimitiveType`s.
+ * this is the inverse of {@link packSeq}.
+ *
+ * under the hood, this function uses {@link unpack} for decoding each item.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * assertEquals(
+ * 	unpackSeq(
+ * 		Uint8Array.of(0x00, 0x12, 0xAB, 0x98, 104, 101, 108, 108, 111, 0), // byte buffer
+ * 		0,          // starting index
+ * 		["u4b"],    // first decoded item should be a 4-byte unsigned integer in big-endian byte-order.
+ * 		["str", 5], // the second item should be a string consisting of 5 bytes (5 characters in this case).
+ * 		["bool"],   // the last item should be a 1-byte boolean.
+ * 	), [
+ * 		[0x12AB98, "hello", false], // decoded items
+ * 		10,                         // bytes decoded
+ * 	],
+ * )
+ * ```
+*/
+export const unpackSeq = (buf, offset, ...items) => {
+    const values = [];
+    let total_bytesize = 0;
+    for (const [type, ...args] of items) {
+        const [value, bytesize] = unpack(type, buf, offset + total_bytesize, ...args);
+        values.push(value);
+        total_bytesize += bytesize;
+    }
+    return [values, total_bytesize];
+};
+/** a primitive value encoder/packer for a given `type` (see {@link PrimitiveType}).
+ * to invert/decode the transformation, use {@link unpack}.
+ *
+ * under the hood, this function calls one of the following primitive value encoders, based on the `type` that you provide:
+ * - {@link encode_bool}, {@link encode_cstr}, {@link encode_str}, {@link encode_bytes},
+ *   {@link encode_number}, {@link encode_number_array}, {@link encode_varint}, {@link encode_varint_array}
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * // aliasing for brevity
+ * const u8 = Uint8Array, eq = assertEquals
+ *
+ * eq(pack("bool" , true),           u8.of(1))
+ * eq(pack("cstr" , "hello"),        u8.of(104, 101, 108, 108, 111, 0))
+ * eq(pack("str"  , "hello"),        u8.of(104, 101, 108, 108, 111))
+ * eq(pack("bytes", u8.of(1, 2, 3)), u8.of(1, 2, 3))
+ * // NOTE: if your device's native endian is not little-endian, then the test below will fail.
+ * eq(pack("f8l[]", [1.1, 2.2, 3**45.67]), new u8(Float64Array.of(1.1, 2.2, 3**45.67).buffer))
+ * ```
+*/
+export const pack = (type, value, ...args) => {
+    switch (type) {
+        case "bool": return encode_bool(value);
+        case "cstr": return encode_cstr(value);
+        case "str": return encode_str(value);
+        case "bytes": return encode_bytes(value);
+        default: {
+            if (type[1] === "v") {
+                return type.endsWith("[]") ?
+                    encode_varint_array(value, type) :
+                    encode_varint(value, type);
+            }
+            else {
+                return type.endsWith("[]") ?
+                    encode_number_array(value, type) :
+                    encode_number(value, type);
+            }
+        }
+    }
+};
+/** a buffer decoder/unpacker for a primitive value of a certain `type` (see {@link PrimitiveType}).
+ * this is the inverse of {@link pack}.
+ *
+ * under the hood, this function calls one of the following primitive value decoders, based on the `type` that you provide:
+ * - {@link decode_bool}, {@link decode_cstr}, {@link decode_str}, {@link decode_bytes},
+ *   {@link decode_number}, {@link decode_number_array}, {@link decode_varint}, {@link decode_varint_array}
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * // aliasing for brevity
+ * const u8 = Uint8Array, eq = assertEquals
+ *
+ * eq(unpack(
+ * 	"bool",         // type of value to decode
+ * 	u8.of(1, 0, 1), // buffer to decode from
+ * 	1,              // the index to begin decoding from
+ * ), [
+ * 	false, // returned decoded value
+ * 	1,     // number of bytes traversed while decoding (i.e. byte size of the decoded object)
+ * ])
+ *
+ * eq(unpack("cstr" , u8.of(97, 98, 99, 0, 100, 101), 0),    ["abc"      , 4])
+ * eq(unpack("str"  , u8.of(97, 98, 99, 0, 100, 101), 0),    ["abc\x00de", 6])
+ * eq(unpack("str"  , u8.of(97, 98, 99, 0, 100, 101), 0, 4), ["abc\x00"  , 4])
+ * eq(unpack("bytes", u8.of(0, 1, 2, 3, 4, 5, 6), 2, 4),     [u8.of(2, 3, 4, 5), 4])
+ * eq(unpack("i2b[]", u8.of(0, 1, 2, 3, 4, 5), 2),           [[0x0203, 0x0405] , 4])
+ * eq(unpack("i2b[]", u8.of(0, 1, 2, 3, 4, 5), 0, 2),        [[0x0001, 0x0203] , 4])
+ * ```
+*/
+export const unpack = (type, buf, offset, ...args) => {
+    switch (type) {
+        case "bool": return decode_bool(buf, offset);
+        case "cstr": return decode_cstr(buf, offset);
+        case "str": return decode_str(buf, offset, ...args);
+        case "bytes": return decode_bytes(buf, offset, ...args);
+        default: {
+            if (type[1] === "v") {
+                return type.endsWith("[]") ?
+                    decode_varint_array(buf, offset, type, ...args) :
+                    decode_varint(buf, offset, type);
+            }
+            else {
+                return type.endsWith("[]") ?
+                    decode_number_array(buf, offset, type, ...args) :
+                    decode_number(buf, offset, type);
+            }
+        }
+    }
+};
+/** pack a `boolean` as 1-byte of data. */
+export const encode_bool = (value) => { return Uint8Array.of(value ? 1 : 0); };
+/** unpack a `boolean` from 1-byte of data. */
+export const decode_bool = (buf, offset = 0) => { return [buf[offset] >= 1 ? true : false, 1]; };
+/** pack a `string` as an array of characters, terminated by the `"\x00"` (or `"\u0000"`) charbyte.
+ * this is the traditional c-programming language convention for strings.
+*/
+export const encode_cstr = (value) => { return textEncoder.encode(value + "\x00"); };
+/** unpack a `string` as an array of characters that's terminated by `"\x00"` (or `"\u0000"`) charbyte.
+ * this is the traditional c-programming language convention for strings.
+*/
+export const decode_cstr = (buf, offset = 0) => {
+    const offset_end = buf.indexOf(0x00, offset), txt_arr = buf.subarray(offset, offset_end), value = textDecoder.decode(txt_arr);
+    return [value, txt_arr.length + 1];
+};
+/** pack a `string` as an array of characters. */
+export const encode_str = (value) => { return textEncoder.encode(value); };
+/** unpack a `string` as an array of characters.
+ * you must provide the `bytesize` of the string being decoded,
+ * otherwise the decoder will unpack till the end of the buffer.
+*/
+export const decode_str = (buf, offset = 0, bytesize) => {
+    const offset_end = bytesize === undefined ? undefined : offset + bytesize, txt_arr = buf.subarray(offset, offset_end), value = textDecoder.decode(txt_arr);
+    return [value, txt_arr.length];
+};
+/** pack a `Uint8Array` array of bytes as is. (ie: don't perform any operation). */
+export const encode_bytes = (value) => { return value; };
+/** unpack a `Uint8Array` array of bytes.
+ * you must provide the `bytesize` of the bytes being decoded,
+ * otherwise the decoder will unpack till the end of the buffer.
+*/
+export const decode_bytes = (buf, offset = 0, bytesize) => {
+    const offset_end = bytesize === undefined ? undefined : offset + bytesize, value = buf.slice(offset, offset_end);
+    return [value, value.length];
+};
+/** pack a numeric array (`number[]`) in the provided {@link NumericArrayType} byte representation. */
+export const encode_number_array = (value, type) => {
+    const [t, s, e] = type, typed_arr_constructor = typed_array_constructor_of(type), bytesize = number_parseInt(s), is_native_endian = (e === "l" && env_is_little_endian) || (e === "b" && !env_is_little_endian) || bytesize === 1 ? true : false, typed_arr = typed_arr_constructor.from(value);
+    if (typed_arr instanceof Uint8Array) {
+        return typed_arr;
+    }
+    const buf = new Uint8Array(typed_arr.buffer);
+    if (is_native_endian) {
+        return buf;
+    }
+    else
+        return swapEndiannessFast(buf, bytesize);
+};
+/** unpack a numeric array (`number[]`) that is encoded in one of {@link NumericArrayType} byte representation.
+ * you must provide the `array_length` of the array being decoded,
+ * otherwise the decoder will unpack till the end of the buffer.
+*/
+export const decode_number_array = (buf, offset = 0, type, array_length) => {
+    const [t, s, e] = type, bytesize = number_parseInt(s), is_native_endian = (e === "l" && env_is_little_endian) || (e === "b" && !env_is_little_endian) || bytesize === 1 ? true : false, bytelength = array_length ? bytesize * array_length : undefined, array_buf = buf.subarray(offset, bytelength ? offset + bytelength : undefined), array_bytesize = array_buf.byteLength, typed_arr_constructor = typed_array_constructor_of(type), array_buf_endian_corrected = is_native_endian ? array_buf : swapEndiannessFast(array_buf, bytesize), 
+    // ANNOYANCE: below, we have to do `as ArrayBuffer` due to the introduction of `SharedArrayBuffer`.
+    typed_arr = new typed_arr_constructor(array_buf_endian_corrected.buffer, array_buf_endian_corrected.byteOffset, (array_bytesize / bytesize) | 0);
+    return [array_from(typed_arr), array_bytesize];
+};
+/** pack a `number` in the provided {@link NumericType} byte representation. */
+export const encode_number = (value, type) => { return encode_number_array([value,], type); };
+/** unpack a `number` in the provided {@link NumericType} byte representation. */
+export const decode_number = (buf, offset = 0, type) => {
+    const [value_arr, bytesize] = decode_number_array(buf, offset, type, 1);
+    return [value_arr[0], bytesize];
+};

package/esm/deps/jsr.io/@oazmi/kitchensink/0.10.0/src/eightpack_varint.d.ts

@@ -0,0 +1,90 @@
+/** submodule for {@link "eightpack"} that adds the ability to encode and decode variable byte-sized integers.
+ *
+ * this part of the library has been separated from  {@link "eightpack"} because of the unlikeyhood of being used.
+ *
+ * - `uvar` stands for an unsigned variable-sized integer.
+ * - `ivar` stands for a signed variable-sized integer.
+ *
+ * ## Purpose
+ *
+ * these variable-sized encodings are especially useful for encoding the length of other variables in their header (i.e. at the beginning of their sequence).
+ *
+ * ## How the encoding works
+ *
+ * ### Unsigned integer case
+ *
+ * - the byte form of a `uvar` occupies a variable number of bytes to accommodate the unsigned integer that it is holding.
+ * - for each byte, it uses the first bit of the octet (`0bXYYYYYYY`) to signal whether the integer carries on to the next byte (X == 1) or not (X == 0).
+ * - the remaining 7 bits in each byte are used for base-7 big-endian encoding of the numeric value of the integer (`YYYYYYY`).
+ * - you can read more about it on [wikipedia](https://en.wikipedia.org/wiki/Variable-length_quantity).
+ *
+ * the following table lists the first few bounds of this encoding:
+ *
+ * | decimal          | unsigned big endian binary                  | unsigned variable binary         |
+ * |------------------|---------------------------------------------|----------------------------------|
+ * | 0                | 0b00000000 0b00000000 0b00000000 0b00000000 | 0b00000000                       |
+ * | 127 = 2^7 - 1    | 0b00000000 0b00000000 0b00000000 0b01111111 | 0b01111111                       |
+ * | 128 = 2^7        | 0b00000000 0b00000000 0b00000000 0b10000000 | 0b10000001 0b00000000            |
+ * | 16383 = 2^14 - 1 | 0b00000000 0b00000000 0b00111111 0b11111111 | 0b11111111 0b01111111            |
+ * | 16384 = 2^14     | 0b00000000 0b00000000 0b01000000 0b00000000 | 0b10000001 0b10000000 0b00000000 |
+ *
+ * ### Signed integer case
+ *
+ * - the `ivar` encoding is similar to the `uvar` encoding, with the exception that in the first byte,
+ *   the second-major bit `Z` of the octet (0b0ZYYYYYY) signals whether the number is positive (Z == 0), or negative (Z == 1).
+ *
+ * the following table lists the first few bounds of this encoding:
+ *
+ * | decimal             | signed big endian binary                    | signed variable binary           |
+ * |---------------------|---------------------------------------------|----------------------------------|
+ * |  0                  | 0b00000000 0b00000000 0b00000000 0b00000000 | 0b00000000 or 0b01000000         |
+ * |  63 =   2^6 - 1     | 0b00000000 0b00000000 0b00000000 0b00111111 | 0b00111111                       |
+ * | -63 = -(2^6 - 1)    | 0b00000000 0b00000000 0b00000000 0b11000001 | 0b01111111                       |
+ * |  8191 =   2^13 - 1  | 0b00000000 0b00000000 0b00011111 0b11111111 | 0b10111111 0b01111111            |
+ * | -8191 = -(2^13 - 1) | 0b00000000 0b00000000 0b11100000 0b00000001 | 0b11111111 0b01111111            |
+ *
+ * @module
+*/
+import type { DecodeFunc, EncodeFunc } from "./eightpack.js";
+import type { VarNumericArrayType, VarNumericType } from "./typedefs.js";
+/** encode a `number` as a variable sized integer (signed or unsigned) in binary. */
+export declare const encode_varint: EncodeFunc<number, [type: VarNumericType]>;
+/** encode an array of `number`s as variable sized integers (signed or unsigned) in binary. */
+export declare const encode_varint_array: EncodeFunc<number[], [type: VarNumericArrayType]>;
+/** decode an byte buffer as a variable sized integer of the given `type` (signed or unsigned). */
+export declare const decode_varint: DecodeFunc<number, [type: VarNumericType]>;
+/** decode an byte buffer as an array of variable sized integers of the given `type` (signed or unsigned) and `array_length`. */
+export declare const decode_varint_array: DecodeFunc<number[], [type: VarNumericArrayType, array_length?: number]>;
+/** byte encoder for an array of unsigned-integers.
+ * use {@link decode_uvar_array} for decoding the result.
+*/
+export declare const encode_uvar_array: EncodeFunc<number[]>;
+/** byte buffer decoder for an array of unsigned-integers of the given (optional) `array_length`.
+ * use {@link encode_uvar_array} for encoding first.
+*/
+export declare const decode_uvar_array: DecodeFunc<number[], [array_length?: number]>;
+/** byte encoder for an array of signed-integers.
+ * use {@link decode_ivar_array} for decoding the result.
+*/
+export declare const encode_ivar_array: EncodeFunc<number[]>;
+/** byte buffer decoder for an array of signed-integers of the given (optional) `array_length`.
+ * use {@link encode_ivar_array} for encoding first.
+*/
+export declare const decode_ivar_array: DecodeFunc<number[], [array_length?: number]>;
+/** a single variable-sized unsigned-integer byte encoder.
+ * use {@link decode_uvar} for decoding the result.
+*/
+export declare const encode_uvar: EncodeFunc<number>;
+/** a single variable-sized unsigned-integers decoder.
+ * use {@link encode_uvar} for encoding first.
+*/
+export declare const decode_uvar: DecodeFunc<number>;
+/** a single variable-sized signed-integer byte encoder.
+ * use {@link decode_ivar} for decoding the result.
+*/
+export declare const encode_ivar: EncodeFunc<number>;
+/** a single variable-sized signed-integers decoder.
+ * use {@link encode_ivar} for encoding first.
+*/
+export declare const decode_ivar: DecodeFunc<number>;
+//# sourceMappingURL=eightpack_varint.d.ts.map

package/esm/deps/jsr.io/@oazmi/kitchensink/0.10.0/src/eightpack_varint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eightpack_varint.d.ts","sourceRoot":"","sources":["../../../../../../../src/deps/jsr.io/@oazmi/kitchensink/0.10.0/src/eightpack_varint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8CE;AAEF,OAAO,KAAK,EAAW,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAGxE,oFAAoF;AACpF,eAAO,MAAM,aAAa,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,cAAc,CAAC,CAA0F,CAAA;AAE/J,8FAA8F;AAC9F,eAAO,MAAM,mBAAmB,EAAE,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAIjF,CAAA;AAED,kGAAkG;AAClG,eAAO,MAAM,aAAa,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,cAAc,CAAC,CAGpE,CAAA;AAED,gIAAgI;AAChI,eAAO,MAAM,mBAAmB,EAAE,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,EAAE,mBAAmB,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,CAIxG,CAAA;AAED;;EAEE;AACF,eAAO,MAAM,iBAAiB,EAAE,UAAU,CAAC,MAAM,EAAE,CAgBlD,CAAA;AAED;;EAEE;AACF,eAAO,MAAM,iBAAiB,EAAE,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,CAmB3E,CAAA;AAED;;EAEE;AACF,eAAO,MAAM,iBAAiB,EAAE,UAAU,CAAC,MAAM,EAAE,CAmBlD,CAAA;AAED;;EAEE;AACF,eAAO,MAAM,iBAAiB,EAAE,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,CA2B3E,CAAA;AAED;;EAEE;AACF,eAAO,MAAM,WAAW,EAAE,UAAU,CAAC,MAAM,CAAqD,CAAA;AAgBhG;;EAEE;AACF,eAAO,MAAM,WAAW,EAAE,UAAU,CAAC,MAAM,CAG1C,CAAA;AAkBD;;EAEE;AACF,eAAO,MAAM,WAAW,EAAE,UAAU,CAAC,MAAM,CAAqD,CAAA;AAmBhG;;EAEE;AACF,eAAO,MAAM,WAAW,EAAE,UAAU,CAAC,MAAM,CAG1C,CAAA"}