@wtasnorg/node-lib 0.0.10 → 0.0.12

package/src/base85.test.ts

@@ -0,0 +1,125 @@
+import { describe, it } from "node:test";
+import { strictEqual, throws } from "node:assert";
+import { encode85, decode85, Base85Charset } from "./base85.js";
+import type { Base85CharsetType } from "./base85.js";
+
+describe("Base85 encode85", () => {
+    it("encodes empty string", () => {
+        strictEqual(encode85(""), "");
+    });
+
+    it("encodes 'Hello' with ascii85 charset", () => {
+        const encoded = encode85("Hello");
+        strictEqual(encoded.length > 0, true);
+    });
+
+    it("encodes single character", () => {
+        const encoded = encode85("A");
+        strictEqual(encoded.length, 2);
+    });
+
+    it("encodes 4 characters (full block)", () => {
+        const encoded = encode85("test");
+        strictEqual(encoded.length, 5);
+    });
+
+    it("encodes 5 characters (4 + 1)", () => {
+        const encoded = encode85("tests");
+        strictEqual(encoded.length, 7);
+    });
+
+    it("encodes with z85 charset", () => {
+        const ascii85 = encode85("test", "ascii85");
+        const z85 = encode85("test", "z85");
+        strictEqual(ascii85 !== z85, true);
+    });
+
+    it("encodes with rfc1924 charset", () => {
+        const ascii85 = encode85("test", "ascii85");
+        const rfc1924 = encode85("test", "rfc1924");
+        strictEqual(ascii85 !== rfc1924, true);
+    });
+
+    it("encodes UTF-8 characters", () => {
+        const input = "こんにちは";
+        const encoded = encode85(input);
+        const decoded = decode85(encoded);
+        strictEqual(decoded, input);
+    });
+});
+
+describe("Base85 decode85", () => {
+    it("decodes empty string", () => {
+        strictEqual(decode85(""), "");
+    });
+
+    it("decodes encoded 'Hello'", () => {
+        const encoded = encode85("Hello");
+        strictEqual(decode85(encoded), "Hello");
+    });
+
+    it("decodes single character encoded", () => {
+        const encoded = encode85("A");
+        strictEqual(decode85(encoded), "A");
+    });
+
+    it("decodes 4-char block correctly", () => {
+        const encoded = encode85("test");
+        strictEqual(decode85(encoded), "test");
+    });
+
+    it("throws on invalid character", () => {
+        // Use a character not in ascii85 alphabet
+        throws(() => decode85("\x7F"), /Invalid Base85 character/);
+    });
+});
+
+describe("Base85 round-trip", () => {
+    const testCases = [
+        "",
+        "a",
+        "ab",
+        "abc",
+        "abcd",
+        "abcde",
+        "Hello, World!",
+        "The quick brown fox jumps over the lazy dog",
+        "こんにちは世界",
+        "🎉🚀✨",
+        "1234567890"
+    ];
+
+    for (const charset of Base85Charset) {
+        describe(`charset: ${charset}`, () => {
+            for (const input of testCases) {
+                it(`round-trips: ${JSON.stringify(input)}`, () => {
+                    const encoded = encode85(input, charset);
+                    const decoded = decode85(encoded, charset);
+                    strictEqual(decoded, input);
+                });
+            }
+        });
+    }
+});
+
+describe("Base85Charset", () => {
+    it("exports array with three charsets", () => {
+        strictEqual(Base85Charset.length, 3);
+        strictEqual(Base85Charset[0], "ascii85");
+        strictEqual(Base85Charset[1], "z85");
+        strictEqual(Base85Charset[2], "rfc1924");
+    });
+
+    it("charset type works correctly", () => {
+        const cs: Base85CharsetType = "z85";
+        strictEqual(encode85("test", cs), encode85("test", "z85"));
+    });
+
+    it("each charset has exactly 85 characters", () => {
+        // This is a compile-time guarantee, but let's verify at runtime too
+        for (const charset of Base85Charset) {
+            const encoded = encode85("test", charset);
+            strictEqual(encoded.length > 0, true);
+        }
+    });
+});

package/src/base85.ts

@@ -0,0 +1,199 @@
+/**
+ * Base85 encoding/decoding with multiple charset variants.
+ * Base85 provides ~25% better efficiency than Base64 (4:5 vs 3:4 ratio).
+ * @module base85
+ */
+
+/**
+ * Available Base85 charset variants.
+ * - `ascii85`: Adobe Ascii85 (btoa format)
+ * - `z85`: ZeroMQ Base85 (no quotes or backslash)
+ * - `rfc1924`: RFC 1924 IPv6 encoding
+ */
+const Base85Charset = ["ascii85", "z85", "rfc1924"] as const;
+
+/**
+ * Base85 charset type.
+ */
+type Base85CharsetType = (typeof Base85Charset)[number];
+
+/**
+ * Charset alphabets for Base85 variants.
+ * Each has exactly 85 printable ASCII characters.
+ */
+const CHARSETS: Record<Base85CharsetType, string> = {
+    ascii85: "!\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstu",
+    z85: "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.-:+=^!/*?&<>()[]{}@%$#",
+    rfc1924: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!#$%&()*+-;<=>?@^_`{|}~"
+};
+
+/**
+ * Build a reverse lookup table for decoding.
+ * @param alphabet - The 85-character alphabet string.
+ * @returns Map of character to index.
+ */
+function buildDecodeTable(alphabet: string): Map<string, number> {
+    const table = new Map<string, number>();
+    for (let i = 0; i < alphabet.length; i++) {
+        const char = alphabet[i];
+        if (char !== undefined) {
+            table.set(char, i);
+        }
+    }
+    return table;
+}
+
+/**
+ * Pre-built decode tables for each charset.
+ */
+const DECODE_TABLES: Record<Base85CharsetType, Map<string, number>> = {
+    ascii85: buildDecodeTable(CHARSETS.ascii85),
+    z85: buildDecodeTable(CHARSETS.z85),
+    rfc1924: buildDecodeTable(CHARSETS.rfc1924)
+};
+
+/**
+ * Encode a string to Base85.
+ *
+ * @example
+ * ```typescript
+ * import { encode85 } from "./base85.js";
+ *
+ * encode85("Hello");
+ * // => "87cURDZ"
+ *
+ * encode85("test", "z85");
+ * // => "wrx.P"
+ * ```
+ *
+ * @param input - The string to encode.
+ * @param charset - The charset variant to use (default: "ascii85").
+ * @returns The Base85 encoded string.
+ */
+function encode85(input: string, charset: Base85CharsetType = "ascii85"): string {
+    if (input === "") {
+        return "";
+    }
+
+    const alphabet = CHARSETS[charset];
+    const bytes = new TextEncoder().encode(input);
+    let result = "";
+
+    // Process 4 bytes at a time
+    for (let i = 0; i < bytes.length; i += 4) {
+        const chunkSize = Math.min(4, bytes.length - i);
+
+        // Pack up to 4 bytes into a value using multiplication to avoid
+        // 32-bit signed integer overflow from bitwise operations
+        let value = 0;
+        for (let j = 0; j < chunkSize; j++) {
+            value = value * 256 + (bytes[i + j] ?? 0);
+        }
+        // Pad with zeros for incomplete chunks
+        for (let j = chunkSize; j < 4; j++) {
+            value = value * 256;
+        }
+
+        // Convert to 5 base-85 digits
+        const encoded: string[] = [];
+        for (let j = 0; j < 5; j++) {
+            encoded.unshift(alphabet[value % 85] ?? "");
+            value = Math.floor(value / 85);
+        }
+
+        // For the last chunk, only output as many characters as needed
+        // (chunkSize bytes -> chunkSize + 1 characters)
+        if (i + 4 > bytes.length) {
+            result += encoded.slice(0, chunkSize + 1).join("");
+        } else {
+            result += encoded.join("");
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Decode a Base85 string.
+ *
+ * @example
+ * ```typescript
+ * import { decode85 } from "./base85.js";
+ *
+ * decode85("87cURDZ");
+ * // => "Hello"
+ *
+ * decode85("wrx.P", "z85");
+ * // => "test"
+ * ```
+ *
+ * @param input - The Base85 encoded string.
+ * @param charset - The charset variant to use (default: "ascii85").
+ * @returns The decoded string.
+ * @throws Error if the input contains invalid characters.
+ */
+function decode85(input: string, charset: Base85CharsetType = "ascii85"): string {
+    if (input === "") {
+        return "";
+    }
+
+    const decodeTable = DECODE_TABLES[charset];
+    const bytes: number[] = [];
+    const inputLen = input.length;
+
+    // Calculate expected output length
+    // Full groups of 5 chars -> 4 bytes each
+    // Partial group: n chars -> n-1 bytes
+    const fullGroups = Math.floor(inputLen / 5);
+    const remainder = inputLen % 5;
+    const totalBytes = fullGroups * 4 + (remainder > 0 ? remainder - 1 : 0);
+
+    // Process 5 characters at a time
+    let byteCount = 0;
+    for (let i = 0; i < inputLen; i += 5) {
+        const chunkSize = Math.min(5, inputLen - i);
+
+        // Decode up to 5 characters into a 32-bit value
+        let value = 0;
+        for (let j = 0; j < chunkSize; j++) {
+            const char = input[i + j];
+            if (char === undefined) {
+                break;
+            }
+            const digit = decodeTable.get(char);
+            if (digit === undefined) {
+                throw new Error(`Invalid Base85 character: ${char}`);
+            }
+            value = value * 85 + digit;
+        }
+
+        // Pad with 84 (highest digit) for incomplete chunks
+        for (let j = chunkSize; j < 5; j++) {
+            value = value * 85 + 84;
+        }
+
+        // Calculate how many bytes this chunk should produce
+        const bytesToExtract = chunkSize === 5 ? 4 : chunkSize - 1;
+
+        // Extract bytes from high to low
+        const extracted: number[] = [];
+        for (let j = 0; j < 4; j++) {
+            extracted.unshift(value & 0xff);
+            value = value >>> 8;
+        }
+
+        // Only push the bytes we need
+        for (let j = 0; j < bytesToExtract && byteCount < totalBytes; j++) {
+            const byte = extracted[j];
+            if (byte !== undefined) {
+                bytes.push(byte);
+                byteCount++;
+            }
+        }
+    }
+
+    return new TextDecoder().decode(new Uint8Array(bytes));
+}
+
+export { encode85, decode85, Base85Charset };
+export type { Base85CharsetType };

package/src/bits.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Count set bits in an unsigned 32-bit representation of a number.
+ *
+ * @param {number} value - Number interpreted as uint32.
+ * @returns {number} Number of set bits (0-32).
+ */
+declare function popcount32(value: number): number;
+/**
+ * Count set bits in the low 64 bits of a number or bigint.
+ *
+ * @param {number | bigint} value - Input value. For `number`, it must be a non-negative safe integer.
+ * @returns {number} Number of set bits (0-64).
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+declare function popcount64(value: number | bigint): number;
+/**
+ * Count set bits in a non-negative integer.
+ *
+ * @param {number | bigint} value - Input value.
+ * @returns {number} Number of set bits.
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+declare function countOnes(value: number | bigint): number;
+/**
+ * Count zero bits within a fixed width, considering only low-order `width` bits.
+ *
+ * @param {number | bigint} value - Input value.
+ * @param {number} width - Bit width to inspect.
+ * @returns {number} Number of zero bits in the selected width.
+ * @throws {RangeError} If `value` is negative/unsafe or `width` is negative/unsafe.
+ */
+declare function countZeroesWithWidth(value: number | bigint, width: number): number;
+/**
+ * Count zero bits from LSB up to and including the highest set bit.
+ * For zero input, returns 0.
+ *
+ * @param {number | bigint} value - Input value.
+ * @returns {number} Zero count up to the left-most set bit.
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+declare function countZeroes(value: number | bigint): number;
+export { popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes };
+//# sourceMappingURL=bits.d.ts.map

package/src/bits.js

@@ -0,0 +1,117 @@
+const UINT64_MASK = (1n << 64n) - 1n;
+/**
+ *
+ * @param {number | bigint} value
+ * @param {string} fnName
+ * @returns {bigint}
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ * @example
+ * toNonNegativeBigInt(42, "exampleFunction"); // returns 42n
+ * toNonNegativeBigInt(-1, "exampleFunction"); // throws RangeError
+ */
+function toNonNegativeBigInt(value, fnName) {
+    if (typeof value === "bigint") {
+        if (value < 0n) {
+            throw new RangeError(`${fnName}: value must be non-negative`);
+        }
+        return value;
+    }
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${fnName}: value must be a non-negative safe integer`);
+    }
+    return BigInt(value);
+}
+/**
+ * Count set bits in a bigint.
+ *
+ * @param {bigint} value - Input value.
+ * @returns {number} Number of set bits.
+ * @example
+ * popcountBigInt(0b1011n); // returns 3
+ */
+function popcountBigInt(value) {
+    let count = 0;
+    let bits = value;
+    while (bits !== 0n) {
+        bits &= bits - 1n;
+        count += 1;
+    }
+    return count;
+}
+/**
+ * Count set bits in an unsigned 32-bit representation of a number.
+ *
+ * @param {number} value - Number interpreted as uint32.
+ * @returns {number} Number of set bits (0-32).
+ */
+function popcount32(value) {
+    let bits = value >>> 0;
+    bits -= (bits >>> 1) & 0x55555555;
+    bits = (bits & 0x33333333) + ((bits >>> 2) & 0x33333333);
+    bits = (bits + (bits >>> 4)) & 0x0f0f0f0f;
+    bits += bits >>> 8;
+    bits += bits >>> 16;
+    return bits & 0x3f;
+}
+/**
+ * Count set bits in the low 64 bits of a number or bigint.
+ *
+ * @param {number | bigint} value - Input value. For `number`, it must be a non-negative safe integer.
+ * @returns {number} Number of set bits (0-64).
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+function popcount64(value) {
+    const bits64 = toNonNegativeBigInt(value, "popcount64") & UINT64_MASK;
+    return popcountBigInt(bits64);
+}
+/**
+ * Count set bits in a non-negative integer.
+ *
+ * @param {number | bigint} value - Input value.
+ * @returns {number} Number of set bits.
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+function countOnes(value) {
+    const bits = toNonNegativeBigInt(value, "countOnes");
+    return popcountBigInt(bits);
+}
+/**
+ * Count zero bits within a fixed width, considering only low-order `width` bits.
+ *
+ * @param {number | bigint} value - Input value.
+ * @param {number} width - Bit width to inspect.
+ * @returns {number} Number of zero bits in the selected width.
+ * @throws {RangeError} If `value` is negative/unsafe or `width` is negative/unsafe.
+ */
+function countZeroesWithWidth(value, width) {
+    if (!Number.isSafeInteger(width) || width < 0) {
+        throw new RangeError("countZeroesWithWidth: width must be a non-negative safe integer");
+    }
+    if (width === 0) {
+        return 0;
+    }
+    const bits = toNonNegativeBigInt(value, "countZeroesWithWidth");
+    const widthBigInt = BigInt(width);
+    const mask = (1n << widthBigInt) - 1n;
+    const ones = popcountBigInt(bits & mask);
+    return width - ones;
+}
+/**
+ * Count zero bits from LSB up to and including the highest set bit.
+ * For zero input, returns 0.
+ *
+ * @param {number | bigint} value - Input value.
+ * @returns {number} Zero count up to the left-most set bit.
+ * @throws {RangeError} If `value` is negative or an unsafe integer.
+ */
+function countZeroes(value) {
+    const bits = toNonNegativeBigInt(value, "countZeroes");
+    if (bits === 0n) {
+        return 0;
+    }
+    const width = bits.toString(2).length;
+    const ones = popcountBigInt(bits);
+    return width - ones;
+}
+export { popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes };
+//# sourceMappingURL=bits.js.map

package/src/bits.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bits.test.d.ts.map

package/src/bits.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from "node:test";
+import { strictEqual, throws } from "node:assert";
+import { popcount32, popcount64, countOnes, countZeroesWithWidth, countZeroes } from "./bits.js";
+describe("popcount32", () => {
+    it("counts set bits for simple values", () => {
+        strictEqual(popcount32(0), 0);
+        strictEqual(popcount32(1), 1);
+        strictEqual(popcount32(0b10110100), 4);
+    });
+    it("uses uint32 semantics", () => {
+        strictEqual(popcount32(-1), 32);
+        strictEqual(popcount32(0xffffffff), 32);
+    });
+});
+describe("popcount64", () => {
+    it("counts set bits for bigint values", () => {
+        strictEqual(popcount64(0n), 0);
+        strictEqual(popcount64((1n << 64n) - 1n), 64);
+        strictEqual(popcount64(41n), 3);
+    });
+    it("counts only low 64 bits", () => {
+        const value = (1n << 65n) | 1n;
+        strictEqual(popcount64(value), 1);
+    });
+    it("throws for invalid number input", () => {
+        throws(() => popcount64(-1), /must be a non-negative safe integer/);
+        throws(() => popcount64(Number.MAX_SAFE_INTEGER + 1), /must be a non-negative safe integer/);
+    });
+});
+describe("countOnes", () => {
+    it("counts set bits for number and bigint", () => {
+        strictEqual(countOnes(0), 0);
+        strictEqual(countOnes(255), 8);
+        strictEqual(countOnes(65537n), 2);
+    });
+});
+describe("countZeroesWithWidth", () => {
+    it("counts zero bits for a chosen width", () => {
+        strictEqual(countZeroesWithWidth(0b10100, 5), 3);
+        strictEqual(countZeroesWithWidth(0b10100, 8), 6);
+        strictEqual(countZeroesWithWidth(0, 8), 8);
+        strictEqual(countZeroesWithWidth(123, 0), 0);
+    });
+    it("throws for invalid width", () => {
+        throws(() => countZeroesWithWidth(1, -1), /width must be a non-negative safe integer/);
+        throws(() => countZeroesWithWidth(1, Number.MAX_SAFE_INTEGER + 1), /width must be a non-negative safe integer/);
+    });
+});
+describe("countZeroes", () => {
+    it("counts zero bits only up to highest set bit", () => {
+        strictEqual(countZeroes(0), 0);
+        strictEqual(countZeroes(1), 0);
+        strictEqual(countZeroes(0b10100), 3);
+        strictEqual(countZeroes(0b1000), 3);
+        strictEqual(countZeroes(0b1111), 0);
+    });
+    it("throws for invalid inputs", () => {
+        throws(() => countZeroes(-1), /must be a non-negative safe integer/);
+        throws(() => countOnes(-1n), /must be non-negative/);
+    });
+});
+//# sourceMappingURL=bits.test.js.map

package/src/bits.test.ts

@@ -0,0 +1,77 @@
+import { describe, it } from "node:test";
+import { strictEqual, throws } from "node:assert";
+import {
+    popcount32,
+    popcount64,
+    countOnes,
+    countZeroesWithWidth,
+    countZeroes
+} from "./bits.js";
+
+describe("popcount32", () => {
+    it("counts set bits for simple values", () => {
+        strictEqual(popcount32(0), 0);
+        strictEqual(popcount32(1), 1);
+        strictEqual(popcount32(0b10110100), 4);
+    });
+
+    it("uses uint32 semantics", () => {
+        strictEqual(popcount32(-1), 32);
+        strictEqual(popcount32(0xffffffff), 32);
+    });
+});
+
+describe("popcount64", () => {
+    it("counts set bits for bigint values", () => {
+        strictEqual(popcount64(0n), 0);
+        strictEqual(popcount64((1n << 64n) - 1n), 64);
+        strictEqual(popcount64(0b101001n), 3);
+    });
+
+    it("counts only low 64 bits", () => {
+        const value = (1n << 65n) | 1n;
+        strictEqual(popcount64(value), 1);
+    });
+
+    it("throws for invalid number input", () => {
+        throws(() => popcount64(-1), /must be a non-negative safe integer/);
+        throws(() => popcount64(Number.MAX_SAFE_INTEGER + 1), /must be a non-negative safe integer/);
+    });
+});
+
+describe("countOnes", () => {
+    it("counts set bits for number and bigint", () => {
+        strictEqual(countOnes(0), 0);
+        strictEqual(countOnes(255), 8);
+        strictEqual(countOnes(0b10000000000000001n), 2);
+    });
+});
+
+describe("countZeroesWithWidth", () => {
+    it("counts zero bits for a chosen width", () => {
+        strictEqual(countZeroesWithWidth(0b10100, 5), 3);
+        strictEqual(countZeroesWithWidth(0b10100, 8), 6);
+        strictEqual(countZeroesWithWidth(0, 8), 8);
+        strictEqual(countZeroesWithWidth(123, 0), 0);
+    });
+
+    it("throws for invalid width", () => {
+        throws(() => countZeroesWithWidth(1, -1), /width must be a non-negative safe integer/);
+        throws(() => countZeroesWithWidth(1, Number.MAX_SAFE_INTEGER + 1), /width must be a non-negative safe integer/);
+    });
+});
+
+describe("countZeroes", () => {
+    it("counts zero bits only up to highest set bit", () => {
+        strictEqual(countZeroes(0), 0);
+        strictEqual(countZeroes(1), 0);
+        strictEqual(countZeroes(0b10100), 3);
+        strictEqual(countZeroes(0b1000), 3);
+        strictEqual(countZeroes(0b1111), 0);
+    });
+
+    it("throws for invalid inputs", () => {
+        throws(() => countZeroes(-1), /must be a non-negative safe integer/);
+        throws(() => countOnes(-1n), /must be non-negative/);
+    });
+});