@wtasnorg/node-lib 0.0.10 → 0.0.11

package/src/base58.js

@@ -0,0 +1,155 @@
+/**
+ * Base58 encoding/decoding with multiple charset variants.
+ * Base58 excludes visually ambiguous characters (0, O, I, l).
+ * @module base58
+ */
+/**
+ * Available Base58 charset variants.
+ * - `bitcoin`: Bitcoin/IPFS alphabet (default)
+ * - `flickr`: Flickr short URLs (swaps case)
+ * - `ripple`: Ripple addresses
+ */
+const Base58Charset = ["bitcoin", "flickr", "ripple"];
+/**
+ * Charset alphabets for Base58 variants.
+ */
+const CHARSETS = {
+    bitcoin: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz",
+    flickr: "123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ",
+    ripple: "rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz"
+};
+/**
+ * Build a reverse lookup table for decoding.
+ * @param alphabet - The 58-character alphabet string.
+ * @returns Map of character to index.
+ */
+function buildDecodeTable(alphabet) {
+    const table = new Map();
+    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 = {
+    bitcoin: buildDecodeTable(CHARSETS.bitcoin),
+    flickr: buildDecodeTable(CHARSETS.flickr),
+    ripple: buildDecodeTable(CHARSETS.ripple)
+};
+/**
+ * Encode a string to Base58.
+ *
+ * @example
+ * ```typescript
+ * import { encode58 } from "./base58.js";
+ *
+ * encode58("Hello World");
+ * // => "JxF12TrwUP45BMd"
+ *
+ * encode58("Hello World", "flickr");
+ * // => "jXf12sRWto45bmD"
+ * ```
+ *
+ * @param input - The string to encode.
+ * @param charset - The charset variant to use (default: "bitcoin").
+ * @returns The Base58 encoded string.
+ */
+function encode58(input, charset = "bitcoin") {
+    if (input === "") {
+        return "";
+    }
+    const alphabet = CHARSETS[charset];
+    const bytes = new TextEncoder().encode(input);
+    // Count leading zeros
+    let leadingZeros = 0;
+    for (const byte of bytes) {
+        if (byte === 0) {
+            leadingZeros++;
+        }
+        else {
+            break;
+        }
+    }
+    // Convert bytes to a big integer
+    let num = 0n;
+    for (const byte of bytes) {
+        num = num * 256n + BigInt(byte);
+    }
+    // Convert to Base58
+    let result = "";
+    while (num > 0n) {
+        const remainder = Number(num % 58n);
+        num = num / 58n;
+        result = alphabet[remainder] + result;
+    }
+    // Add leading '1's for leading zero bytes
+    const leadChar = alphabet[0];
+    for (let i = 0; i < leadingZeros; i++) {
+        result = leadChar + result;
+    }
+    return result;
+}
+/**
+ * Decode a Base58 string.
+ *
+ * @example
+ * ```typescript
+ * import { decode58 } from "./base58.js";
+ *
+ * decode58("JxF12TrwUP45BMd");
+ * // => "Hello World"
+ *
+ * decode58("jXf12sRWto45bmD", "flickr");
+ * // => "Hello World"
+ * ```
+ *
+ * @param input - The Base58 encoded string.
+ * @param charset - The charset variant to use (default: "bitcoin").
+ * @returns The decoded string.
+ * @throws Error if the input contains invalid characters.
+ */
+function decode58(input, charset = "bitcoin") {
+    if (input === "") {
+        return "";
+    }
+    const alphabet = CHARSETS[charset];
+    const decodeTable = DECODE_TABLES[charset];
+    const leadChar = alphabet[0];
+    // Count leading '1's (or equivalent)
+    let leadingOnes = 0;
+    for (const char of input) {
+        if (char === leadChar) {
+            leadingOnes++;
+        }
+        else {
+            break;
+        }
+    }
+    // Convert from Base58 to big integer
+    let num = 0n;
+    for (const char of input) {
+        const value = decodeTable.get(char);
+        if (value === undefined) {
+            throw new Error(`Invalid Base58 character: ${char}`);
+        }
+        num = num * 58n + BigInt(value);
+    }
+    // Convert big integer to bytes
+    const bytes = [];
+    while (num > 0n) {
+        bytes.unshift(Number(num % 256n));
+        num = num / 256n;
+    }
+    // Add leading zeros
+    for (let i = 0; i < leadingOnes; i++) {
+        bytes.unshift(0);
+    }
+    return new TextDecoder().decode(new Uint8Array(bytes));
+}
+export { encode58, decode58, Base58Charset };
+//# sourceMappingURL=base58.js.map

package/src/base58.test.d.ts

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

package/src/base58.test.js

@@ -0,0 +1,108 @@
+import { describe, it } from "node:test";
+import { strictEqual, throws } from "node:assert";
+import { encode58, decode58, Base58Charset } from "./base58.js";
+describe("Base58 encode58", () => {
+    it("encodes empty string", () => {
+        strictEqual(encode58(""), "");
+    });
+    it("encodes 'Hello World' with bitcoin charset", () => {
+        strictEqual(encode58("Hello World"), "JxF12TrwUP45BMd");
+    });
+    it("encodes single character", () => {
+        // Verify round-trip rather than hardcoded value
+        const encoded = encode58("A");
+        strictEqual(encoded.length > 0, true);
+        strictEqual(decode58(encoded), "A");
+    });
+    it("encodes 'abc'", () => {
+        strictEqual(encode58("abc"), "ZiCa");
+    });
+    it("encodes with flickr charset", () => {
+        const bitcoin = encode58("Hello World", "bitcoin");
+        const flickr = encode58("Hello World", "flickr");
+        // Flickr swaps case
+        strictEqual(bitcoin !== flickr, true);
+    });
+    it("encodes with ripple charset", () => {
+        const bitcoin = encode58("Hello World", "bitcoin");
+        const ripple = encode58("Hello World", "ripple");
+        strictEqual(bitcoin !== ripple, true);
+    });
+    it("encodes UTF-8 characters", () => {
+        const input = "こんにちは";
+        const encoded = encode58(input);
+        const decoded = decode58(encoded);
+        strictEqual(decoded, input);
+    });
+    it("preserves leading zero bytes", () => {
+        const input = "\x00\x00Hello";
+        const encoded = encode58(input);
+        const decoded = decode58(encoded);
+        strictEqual(decoded, input);
+    });
+});
+describe("Base58 decode58", () => {
+    it("decodes empty string", () => {
+        strictEqual(decode58(""), "");
+    });
+    it("decodes 'JxF12TrwUP45BMd' to 'Hello World'", () => {
+        strictEqual(decode58("JxF12TrwUP45BMd"), "Hello World");
+    });
+    it("decodes single character", () => {
+        const encoded = encode58("A");
+        strictEqual(decode58(encoded), "A");
+    });
+    it("decodes 'ZiCa' to 'abc'", () => {
+        strictEqual(decode58("ZiCa"), "abc");
+    });
+    it("throws on invalid character (0)", () => {
+        throws(() => decode58("0invalid"), /Invalid Base58 character/);
+    });
+    it("throws on invalid character (O)", () => {
+        throws(() => decode58("OOO"), /Invalid Base58 character/);
+    });
+    it("throws on invalid character (I)", () => {
+        throws(() => decode58("III"), /Invalid Base58 character/);
+    });
+    it("throws on invalid character (l)", () => {
+        throws(() => decode58("lll"), /Invalid Base58 character/);
+    });
+});
+describe("Base58 round-trip", () => {
+    const testCases = [
+        "",
+        "a",
+        "ab",
+        "abc",
+        "abcd",
+        "Hello, World!",
+        "The quick brown fox jumps over the lazy dog",
+        "こんにちは世界",
+        "🎉🚀✨",
+        "\x00\x00\x00abc"
+    ];
+    for (const charset of Base58Charset) {
+        describe(`charset: ${charset}`, () => {
+            for (const input of testCases) {
+                it(`round-trips: ${JSON.stringify(input)}`, () => {
+                    const encoded = encode58(input, charset);
+                    const decoded = decode58(encoded, charset);
+                    strictEqual(decoded, input);
+                });
+            }
+        });
+    }
+});
+describe("Base58Charset", () => {
+    it("exports array with three charsets", () => {
+        strictEqual(Base58Charset.length, 3);
+        strictEqual(Base58Charset[0], "bitcoin");
+        strictEqual(Base58Charset[1], "flickr");
+        strictEqual(Base58Charset[2], "ripple");
+    });
+    it("charset type works correctly", () => {
+        const cs = "flickr";
+        strictEqual(encode58("test", cs), encode58("test", "flickr"));
+    });
+});
+//# sourceMappingURL=base58.test.js.map

package/src/base58.test.ts

@@ -0,0 +1,128 @@
+import { describe, it } from "node:test";
+import { strictEqual, throws } from "node:assert";
+import { encode58, decode58, Base58Charset } from "./base58.js";
+import type { Base58CharsetType } from "./base58.js";
+
+describe("Base58 encode58", () => {
+    it("encodes empty string", () => {
+        strictEqual(encode58(""), "");
+    });
+
+    it("encodes 'Hello World' with bitcoin charset", () => {
+        strictEqual(encode58("Hello World"), "JxF12TrwUP45BMd");
+    });
+
+    it("encodes single character", () => {
+        // Verify round-trip rather than hardcoded value
+        const encoded = encode58("A");
+        strictEqual(encoded.length > 0, true);
+        strictEqual(decode58(encoded), "A");
+    });
+
+    it("encodes 'abc'", () => {
+        strictEqual(encode58("abc"), "ZiCa");
+    });
+
+    it("encodes with flickr charset", () => {
+        const bitcoin = encode58("Hello World", "bitcoin");
+        const flickr = encode58("Hello World", "flickr");
+        // Flickr swaps case
+        strictEqual(bitcoin !== flickr, true);
+    });
+
+    it("encodes with ripple charset", () => {
+        const bitcoin = encode58("Hello World", "bitcoin");
+        const ripple = encode58("Hello World", "ripple");
+        strictEqual(bitcoin !== ripple, true);
+    });
+
+    it("encodes UTF-8 characters", () => {
+        const input = "こんにちは";
+        const encoded = encode58(input);
+        const decoded = decode58(encoded);
+        strictEqual(decoded, input);
+    });
+
+    it("preserves leading zero bytes", () => {
+        const input = "\x00\x00Hello";
+        const encoded = encode58(input);
+        const decoded = decode58(encoded);
+        strictEqual(decoded, input);
+    });
+});
+
+describe("Base58 decode58", () => {
+    it("decodes empty string", () => {
+        strictEqual(decode58(""), "");
+    });
+
+    it("decodes 'JxF12TrwUP45BMd' to 'Hello World'", () => {
+        strictEqual(decode58("JxF12TrwUP45BMd"), "Hello World");
+    });
+
+    it("decodes single character", () => {
+        const encoded = encode58("A");
+        strictEqual(decode58(encoded), "A");
+    });
+
+    it("decodes 'ZiCa' to 'abc'", () => {
+        strictEqual(decode58("ZiCa"), "abc");
+    });
+
+    it("throws on invalid character (0)", () => {
+        throws(() => decode58("0invalid"), /Invalid Base58 character/);
+    });
+
+    it("throws on invalid character (O)", () => {
+        throws(() => decode58("OOO"), /Invalid Base58 character/);
+    });
+
+    it("throws on invalid character (I)", () => {
+        throws(() => decode58("III"), /Invalid Base58 character/);
+    });
+
+    it("throws on invalid character (l)", () => {
+        throws(() => decode58("lll"), /Invalid Base58 character/);
+    });
+});
+
+describe("Base58 round-trip", () => {
+    const testCases = [
+        "",
+        "a",
+        "ab",
+        "abc",
+        "abcd",
+        "Hello, World!",
+        "The quick brown fox jumps over the lazy dog",
+        "こんにちは世界",
+        "🎉🚀✨",
+        "\x00\x00\x00abc"
+    ];
+
+    for (const charset of Base58Charset) {
+        describe(`charset: ${charset}`, () => {
+            for (const input of testCases) {
+                it(`round-trips: ${JSON.stringify(input)}`, () => {
+                    const encoded = encode58(input, charset);
+                    const decoded = decode58(encoded, charset);
+                    strictEqual(decoded, input);
+                });
+            }
+        });
+    }
+});
+
+describe("Base58Charset", () => {
+    it("exports array with three charsets", () => {
+        strictEqual(Base58Charset.length, 3);
+        strictEqual(Base58Charset[0], "bitcoin");
+        strictEqual(Base58Charset[1], "flickr");
+        strictEqual(Base58Charset[2], "ripple");
+    });
+
+    it("charset type works correctly", () => {
+        const cs: Base58CharsetType = "flickr";
+        strictEqual(encode58("test", cs), encode58("test", "flickr"));
+    });
+});

package/src/base58.ts

@@ -0,0 +1,177 @@
+/**
+ * Base58 encoding/decoding with multiple charset variants.
+ * Base58 excludes visually ambiguous characters (0, O, I, l).
+ * @module base58
+ */
+
+/**
+ * Available Base58 charset variants.
+ * - `bitcoin`: Bitcoin/IPFS alphabet (default)
+ * - `flickr`: Flickr short URLs (swaps case)
+ * - `ripple`: Ripple addresses
+ */
+const Base58Charset = ["bitcoin", "flickr", "ripple"] as const;
+
+/**
+ * Base58 charset type.
+ */
+type Base58CharsetType = (typeof Base58Charset)[number];
+
+/**
+ * Charset alphabets for Base58 variants.
+ */
+const CHARSETS: Record<Base58CharsetType, string> = {
+    bitcoin: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz",
+    flickr: "123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ",
+    ripple: "rpshnaf39wBUDNEGHJKLM4PQRST7VWXYZ2bcdeCg65jkm8oFqi1tuvAxyz"
+};
+
+/**
+ * Build a reverse lookup table for decoding.
+ * @param alphabet - The 58-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<Base58CharsetType, Map<string, number>> = {
+    bitcoin: buildDecodeTable(CHARSETS.bitcoin),
+    flickr: buildDecodeTable(CHARSETS.flickr),
+    ripple: buildDecodeTable(CHARSETS.ripple)
+};
+
+/**
+ * Encode a string to Base58.
+ *
+ * @example
+ * ```typescript
+ * import { encode58 } from "./base58.js";
+ *
+ * encode58("Hello World");
+ * // => "JxF12TrwUP45BMd"
+ *
+ * encode58("Hello World", "flickr");
+ * // => "jXf12sRWto45bmD"
+ * ```
+ *
+ * @param input - The string to encode.
+ * @param charset - The charset variant to use (default: "bitcoin").
+ * @returns The Base58 encoded string.
+ */
+function encode58(input: string, charset: Base58CharsetType = "bitcoin"): string {
+    if (input === "") {
+        return "";
+    }
+
+    const alphabet = CHARSETS[charset];
+    const bytes = new TextEncoder().encode(input);
+
+    // Count leading zeros
+    let leadingZeros = 0;
+    for (const byte of bytes) {
+        if (byte === 0) {
+            leadingZeros++;
+        } else {
+            break;
+        }
+    }
+
+    // Convert bytes to a big integer
+    let num = 0n;
+    for (const byte of bytes) {
+        num = num * 256n + BigInt(byte);
+    }
+
+    // Convert to Base58
+    let result = "";
+    while (num > 0n) {
+        const remainder = Number(num % 58n);
+        num = num / 58n;
+        result = alphabet[remainder] + result;
+    }
+
+    // Add leading '1's for leading zero bytes
+    const leadChar = alphabet[0];
+    for (let i = 0; i < leadingZeros; i++) {
+        result = leadChar + result;
+    }
+
+    return result;
+}
+
+/**
+ * Decode a Base58 string.
+ *
+ * @example
+ * ```typescript
+ * import { decode58 } from "./base58.js";
+ *
+ * decode58("JxF12TrwUP45BMd");
+ * // => "Hello World"
+ *
+ * decode58("jXf12sRWto45bmD", "flickr");
+ * // => "Hello World"
+ * ```
+ *
+ * @param input - The Base58 encoded string.
+ * @param charset - The charset variant to use (default: "bitcoin").
+ * @returns The decoded string.
+ * @throws Error if the input contains invalid characters.
+ */
+function decode58(input: string, charset: Base58CharsetType = "bitcoin"): string {
+    if (input === "") {
+        return "";
+    }
+
+    const alphabet = CHARSETS[charset];
+    const decodeTable = DECODE_TABLES[charset];
+    const leadChar = alphabet[0];
+
+    // Count leading '1's (or equivalent)
+    let leadingOnes = 0;
+    for (const char of input) {
+        if (char === leadChar) {
+            leadingOnes++;
+        } else {
+            break;
+        }
+    }
+
+    // Convert from Base58 to big integer
+    let num = 0n;
+    for (const char of input) {
+        const value = decodeTable.get(char);
+        if (value === undefined) {
+            throw new Error(`Invalid Base58 character: ${char}`);
+        }
+        num = num * 58n + BigInt(value);
+    }
+
+    // Convert big integer to bytes
+    const bytes: number[] = [];
+    while (num > 0n) {
+        bytes.unshift(Number(num % 256n));
+        num = num / 256n;
+    }
+
+    // Add leading zeros
+    for (let i = 0; i < leadingOnes; i++) {
+        bytes.unshift(0);
+    }
+
+    return new TextDecoder().decode(new Uint8Array(bytes));
+}
+
+export { encode58, decode58, Base58Charset };
+export type { Base58CharsetType };

package/src/base85.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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
+ */
+declare const Base85Charset: readonly ["ascii85", "z85", "rfc1924"];
+/**
+ * Base85 charset type.
+ */
+type Base85CharsetType = (typeof Base85Charset)[number];
+/**
+ * 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.
+ */
+declare function encode85(input: string, charset?: Base85CharsetType): string;
+/**
+ * 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.
+ */
+declare function decode85(input: string, charset?: Base85CharsetType): string;
+export { encode85, decode85, Base85Charset };
+export type { Base85CharsetType };
+//# sourceMappingURL=base85.d.ts.map