@wtasnorg/node-lib 0.0.8 → 0.0.9

package/src/base64.test.js

@@ -0,0 +1,106 @@
+import { describe, it } from "node:test";
+import { strictEqual, throws } from "node:assert";
+import { encode, decode, Base64Charset } from "./base64.js";
+describe("Base64 encode", () => {
+    it("encodes empty string", () => {
+        strictEqual(encode(""), "");
+    });
+    it("encodes 'Hello, World!' with standard charset", () => {
+        strictEqual(encode("Hello, World!"), "SGVsbG8sIFdvcmxkIQ==");
+    });
+    it("encodes single character", () => {
+        strictEqual(encode("A"), "QQ==");
+    });
+    it("encodes two characters (padding test)", () => {
+        strictEqual(encode("AB"), "QUI=");
+    });
+    it("encodes three characters (no padding)", () => {
+        strictEqual(encode("ABC"), "QUJD");
+    });
+    it("encodes with urlsafe charset", () => {
+        // Bytes that produce +/ in standard: 0xfb, 0xef, 0xbe -> ++/+
+        const input = "\xfb\xef\xbe";
+        const standard = encode(input, "standard");
+        const urlsafe = encode(input, "urlsafe");
+        // standard uses + and /, urlsafe uses - and _
+        strictEqual(standard.includes("+") || standard.includes("/"), true);
+        strictEqual(urlsafe.includes("+"), false);
+        strictEqual(urlsafe.includes("/"), false);
+    });
+    it("encodes with imap charset", () => {
+        // imap uses , instead of /
+        const input = "\xff\xff";
+        const standard = encode(input, "standard");
+        const imap = encode(input, "imap");
+        strictEqual(imap.includes(",") || !imap.includes("/"), true);
+        strictEqual(standard !== imap || !standard.includes("/"), true);
+    });
+    it("encodes UTF-8 characters", () => {
+        const input = "こんにちは";
+        const encoded = encode(input);
+        const decoded = decode(encoded);
+        strictEqual(decoded, input);
+    });
+});
+describe("Base64 decode", () => {
+    it("decodes empty string", () => {
+        strictEqual(decode(""), "");
+    });
+    it("decodes 'SGVsbG8sIFdvcmxkIQ==' to 'Hello, World!'", () => {
+        strictEqual(decode("SGVsbG8sIFdvcmxkIQ=="), "Hello, World!");
+    });
+    it("decodes single character padded", () => {
+        strictEqual(decode("QQ=="), "A");
+    });
+    it("decodes two characters padded", () => {
+        strictEqual(decode("QUI="), "AB");
+    });
+    it("decodes three characters (no padding)", () => {
+        strictEqual(decode("QUJD"), "ABC");
+    });
+    it("throws on invalid character", () => {
+        throws(() => decode("!!!"), /Invalid Base64 character/);
+    });
+    it("decodes without padding characters", () => {
+        strictEqual(decode("SGVsbG8sIFdvcmxkIQ"), "Hello, World!");
+    });
+});
+describe("Base64 round-trip", () => {
+    const testCases = [
+        "",
+        "a",
+        "ab",
+        "abc",
+        "abcd",
+        "Hello, World!",
+        "The quick brown fox jumps over the lazy dog",
+        "こんにちは世界",
+        "🎉🚀✨",
+        "\x00\x01\x02\xff"
+    ];
+    for (const charset of Base64Charset) {
+        describe(`charset: ${charset}`, () => {
+            for (const input of testCases) {
+                it(`round-trips: ${JSON.stringify(input)}`, () => {
+                    const encoded = encode(input, charset);
+                    const decoded = decode(encoded, charset);
+                    strictEqual(decoded, input);
+                });
+            }
+        });
+    }
+});
+describe("Base64Charset", () => {
+    it("exports array with four charsets", () => {
+        strictEqual(Base64Charset.length, 4);
+        strictEqual(Base64Charset[0], "standard");
+        strictEqual(Base64Charset[1], "urlsafe");
+        strictEqual(Base64Charset[2], "imap");
+        strictEqual(Base64Charset[3], "radix64");
+    });
+    it("charset type works correctly", () => {
+        const cs = "urlsafe";
+        strictEqual(encode("test", cs), encode("test", "urlsafe"));
+    });
+});
+//# sourceMappingURL=base64.test.js.map

package/src/base64.test.ts

@@ -0,0 +1,125 @@
+import { describe, it } from "node:test";
+import { strictEqual, throws } from "node:assert";
+import { encode, decode, Base64Charset } from "./base64.js";
+import type { Base64CharsetType } from "./base64.js";
+
+describe("Base64 encode", () => {
+    it("encodes empty string", () => {
+        strictEqual(encode(""), "");
+    });
+
+    it("encodes 'Hello, World!' with standard charset", () => {
+        strictEqual(encode("Hello, World!"), "SGVsbG8sIFdvcmxkIQ==");
+    });
+
+    it("encodes single character", () => {
+        strictEqual(encode("A"), "QQ==");
+    });
+
+    it("encodes two characters (padding test)", () => {
+        strictEqual(encode("AB"), "QUI=");
+    });
+
+    it("encodes three characters (no padding)", () => {
+        strictEqual(encode("ABC"), "QUJD");
+    });
+
+    it("encodes with urlsafe charset", () => {
+        // Bytes that produce +/ in standard: 0xfb, 0xef, 0xbe -> ++/+
+        const input = "\xfb\xef\xbe";
+        const standard = encode(input, "standard");
+        const urlsafe = encode(input, "urlsafe");
+        // standard uses + and /, urlsafe uses - and _
+        strictEqual(standard.includes("+") || standard.includes("/"), true);
+        strictEqual(urlsafe.includes("+"), false);
+        strictEqual(urlsafe.includes("/"), false);
+    });
+
+    it("encodes with imap charset", () => {
+        // imap uses , instead of /
+        const input = "\xff\xff";
+        const standard = encode(input, "standard");
+        const imap = encode(input, "imap");
+        strictEqual(imap.includes(",") || !imap.includes("/"), true);
+        strictEqual(standard !== imap || !standard.includes("/"), true);
+    });
+
+    it("encodes UTF-8 characters", () => {
+        const input = "こんにちは";
+        const encoded = encode(input);
+        const decoded = decode(encoded);
+        strictEqual(decoded, input);
+    });
+});
+
+describe("Base64 decode", () => {
+    it("decodes empty string", () => {
+        strictEqual(decode(""), "");
+    });
+
+    it("decodes 'SGVsbG8sIFdvcmxkIQ==' to 'Hello, World!'", () => {
+        strictEqual(decode("SGVsbG8sIFdvcmxkIQ=="), "Hello, World!");
+    });
+
+    it("decodes single character padded", () => {
+        strictEqual(decode("QQ=="), "A");
+    });
+
+    it("decodes two characters padded", () => {
+        strictEqual(decode("QUI="), "AB");
+    });
+
+    it("decodes three characters (no padding)", () => {
+        strictEqual(decode("QUJD"), "ABC");
+    });
+
+    it("throws on invalid character", () => {
+        throws(() => decode("!!!"), /Invalid Base64 character/);
+    });
+
+    it("decodes without padding characters", () => {
+        strictEqual(decode("SGVsbG8sIFdvcmxkIQ"), "Hello, World!");
+    });
+});
+
+describe("Base64 round-trip", () => {
+    const testCases = [
+        "",
+        "a",
+        "ab",
+        "abc",
+        "abcd",
+        "Hello, World!",
+        "The quick brown fox jumps over the lazy dog",
+        "こんにちは世界",
+        "🎉🚀✨",
+        "\x00\x01\x02\xff"
+    ];
+
+    for (const charset of Base64Charset) {
+        describe(`charset: ${charset}`, () => {
+            for (const input of testCases) {
+                it(`round-trips: ${JSON.stringify(input)}`, () => {
+                    const encoded = encode(input, charset);
+                    const decoded = decode(encoded, charset);
+                    strictEqual(decoded, input);
+                });
+            }
+        });
+    }
+});
+
+describe("Base64Charset", () => {
+    it("exports array with four charsets", () => {
+        strictEqual(Base64Charset.length, 4);
+        strictEqual(Base64Charset[0], "standard");
+        strictEqual(Base64Charset[1], "urlsafe");
+        strictEqual(Base64Charset[2], "imap");
+        strictEqual(Base64Charset[3], "radix64");
+    });
+
+    it("charset type works correctly", () => {
+        const cs: Base64CharsetType = "urlsafe";
+        strictEqual(encode("test", cs), encode("test", "urlsafe"));
+    });
+});

package/src/base64.ts

@@ -0,0 +1,163 @@
+/**
+ * Base64 encoding/decoding with multiple charset variants.
+ * @module base64
+ */
+
+/**
+ * Available Base64 charset variants.
+ * - `standard`: RFC 4648 standard alphabet (A-Z, a-z, 0-9, +, /)
+ * - `urlsafe`: URL and filename safe (A-Z, a-z, 0-9, -, _)
+ * - `imap`: Modified Base64 for IMAP mailbox names (A-Z, a-z, 0-9, +, ,)
+ * - `radix64`: Base64 variant used in OpenPGP (A-Z, a-z, 0-9, +, /)
+ */
+const Base64Charset = ["standard", "urlsafe", "imap", "radix64"] as const;
+
+/**
+ * Base64 charset type.
+ */
+type Base64CharsetType = (typeof Base64Charset)[number];
+
+/**
+ * Charset alphabets for Base64 variants.
+ */
+const CHARSETS: Record<Base64CharsetType, string> = {
+    standard: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/",
+    urlsafe: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_",
+    imap: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,",
+    radix64: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+};
+
+/**
+ * Padding character for Base64 encoding.
+ */
+const PAD = "=";
+
+/**
+ * Build a reverse lookup table for decoding.
+ * @param alphabet - The 64-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<Base64CharsetType, Map<string, number>> = {
+    standard: buildDecodeTable(CHARSETS.standard),
+    urlsafe: buildDecodeTable(CHARSETS.urlsafe),
+    imap: buildDecodeTable(CHARSETS.imap),
+    radix64: buildDecodeTable(CHARSETS.radix64)
+};
+
+/**
+ * Encode a string to Base64.
+ *
+ * @example
+ * ```typescript
+ * import { encode } from "./base64.js";
+ *
+ * encode("Hello, World!");
+ * // => "SGVsbG8sIFdvcmxkIQ=="
+ *
+ * encode("Hello, World!", "urlsafe");
+ * // => "SGVsbG8sIFdvcmxkIQ=="
+ * ```
+ *
+ * @param input - The string to encode.
+ * @param charset - The charset variant to use (default: "standard").
+ * @returns The Base64 encoded string.
+ */
+function encode(input: string, charset: Base64CharsetType = "standard"): string {
+    const alphabet = CHARSETS[charset];
+    const bytes = new TextEncoder().encode(input);
+    let result = "";
+
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i] ?? 0;
+        const b1 = i + 1 < bytes.length ? (bytes[i + 1] ?? 0) : 0;
+        const b2 = i + 2 < bytes.length ? (bytes[i + 2] ?? 0) : 0;
+
+        const triple = (b0 << 16) | (b1 << 8) | b2;
+
+        result += alphabet[(triple >> 18) & 0x3f];
+        result += alphabet[(triple >> 12) & 0x3f];
+        result += i + 1 < bytes.length ? alphabet[(triple >> 6) & 0x3f] : PAD;
+        result += i + 2 < bytes.length ? alphabet[triple & 0x3f] : PAD;
+    }
+
+    return result;
+}
+
+/**
+ * Decode a Base64 string.
+ *
+ * @example
+ * ```typescript
+ * import { decode } from "./base64.js";
+ *
+ * decode("SGVsbG8sIFdvcmxkIQ==");
+ * // => "Hello, World!"
+ *
+ * decode("SGVsbG8sIFdvcmxkIQ==", "standard");
+ * // => "Hello, World!"
+ * ```
+ *
+ * @param input - The Base64 encoded string.
+ * @param charset - The charset variant to use (default: "standard").
+ * @returns The decoded string.
+ * @throws Error if the input contains invalid characters.
+ */
+function decode(input: string, charset: Base64CharsetType = "standard"): string {
+    const decodeTable = DECODE_TABLES[charset];
+
+    // Remove padding
+    const cleanInput = input.replace(/=+$/, "");
+    const bytes: number[] = [];
+
+    for (let i = 0; i < cleanInput.length; i += 4) {
+        const c0 = cleanInput[i];
+        const c1 = cleanInput[i + 1];
+        const c2 = cleanInput[i + 2];
+        const c3 = cleanInput[i + 3];
+
+        if (c0 === undefined) {
+            break;
+        }
+
+        const v0 = decodeTable.get(c0);
+        const v1 = c1 !== undefined ? decodeTable.get(c1) : 0;
+        const v2 = c2 !== undefined ? decodeTable.get(c2) : 0;
+        const v3 = c3 !== undefined ? decodeTable.get(c3) : 0;
+
+        if (v0 === undefined) {
+            throw new Error(`Invalid Base64 character: ${c0}`);
+        }
+        if (c1 !== undefined && v1 === undefined) {
+            throw new Error(`Invalid Base64 character: ${c1}`);
+        }
+
+        const triple = ((v0 ?? 0) << 18) | ((v1 ?? 0) << 12) | ((v2 ?? 0) << 6) | (v3 ?? 0);
+
+        bytes.push((triple >> 16) & 0xff);
+        if (c2 !== undefined) {
+            bytes.push((triple >> 8) & 0xff);
+        }
+        if (c3 !== undefined) {
+            bytes.push(triple & 0xff);
+        }
+    }
+
+    return new TextDecoder().decode(new Uint8Array(bytes));
+}
+
+export { encode, decode, Base64Charset };
+export type { Base64CharsetType };

package/src/index.d.ts

@@ -4,6 +4,8 @@ import type { FindDirectoriesOptions, FileSystemDependencies } from "./find.js";
 import { createFindDirectories } from "./find.js";
 import type { UserAgentInfo } from "./user-agent.js";
 import { parseUserAgent } from "./user-agent.js";
-export { hello, pojo, createFindDirectories, parseUserAgent };
-export type { FindDirectoriesOptions, FileSystemDependencies, UserAgentInfo, };
+import type { Base64CharsetType } from "./base64.js";
+import { encode, decode, Base64Charset } from "./base64.js";
+export { hello, pojo, createFindDirectories, parseUserAgent, encode, decode, Base64Charset };
+export type { FindDirectoriesOptions, FileSystemDependencies, UserAgentInfo, Base64CharsetType };
 //# sourceMappingURL=index.d.ts.map

package/src/index.js

@@ -2,5 +2,6 @@ import { hello } from "./hello.js";
 import { pojo } from "./pojo.js";
 import { createFindDirectories } from "./find.js";
 import { parseUserAgent } from "./user-agent.js";
-export { hello, pojo, createFindDirectories, parseUserAgent };
+import { encode, decode, Base64Charset } from "./base64.js";
+export { hello, pojo, createFindDirectories, parseUserAgent, encode, decode, Base64Charset };
 //# sourceMappingURL=index.js.map

package/src/index.ts

@@ -4,16 +4,22 @@ import type { FindDirectoriesOptions, FileSystemDependencies } from "./find.js";
 import { createFindDirectories } from "./find.js";
 import type { UserAgentInfo } from "./user-agent.js";
 import { parseUserAgent } from "./user-agent.js";
+import type { Base64CharsetType } from "./base64.js";
+import { encode, decode, Base64Charset } from "./base64.js";
 
 export {
     hello,
     pojo,
     createFindDirectories,
-    parseUserAgent
+    parseUserAgent,
+    encode,
+    decode,
+    Base64Charset
 };
 
 export type {
     FindDirectoriesOptions,
     FileSystemDependencies,
     UserAgentInfo,
+    Base64CharsetType
 };