@litert/base32 1.0.0

package/src/lib/base32-js.ts

@@ -0,0 +1,268 @@
+/**
+ * Copyright 2025 Angus.Fenying <fenying@litert.org>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+const BASE32_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+
+const BITS_TO_CHARS = Buffer.from(BASE32_CHARS);
+
+const CHARS_TO_BITS: Record<string, number> = {};
+
+for (let i = 0; i < BASE32_CHARS.length; i++) {
+
+    CHARS_TO_BITS[BASE32_CHARS[i]] = i;
+}
+
+export const PADDING = '='.charCodeAt(0);
+
+/**
+ * Encode a `Buffer` to a BASE32-encoded string.
+ *
+ * @param data  The `Buffer` to be encoded.
+ *
+ * @returns     The BASE32 encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc4648#section-6
+ */
+export function bufferToBase32(data: Buffer): string {
+
+    const ret: Buffer = Buffer.alloc(Math.ceil(data.length / 5) * 8);
+
+    for (let i = 0, j = 0; i < data.length; i += 5) {
+
+        switch (data.length - i) {
+            case 1:
+
+                /**
+                 * 11111 111|00 00000 0|0000 0000|0 00000 00|000 00000
+                 */
+                ret[j++] = BITS_TO_CHARS[data[i] >> 3];
+                ret[j++] = BITS_TO_CHARS[(data[i] & 0x07) << 2];
+                ret[j++] = PADDING;
+                ret[j++] = PADDING;
+                ret[j++] = PADDING;
+                ret[j++] = PADDING;
+                ret[j++] = PADDING;
+                ret[j++] = PADDING;
+                break;
+            case 2:
+
+                /**
+                 * 11111 111|11 11111 1|0000 0000|0 00000 00|000 00000
+                 */
+                ret[j++] = BITS_TO_CHARS[data[i] >> 3];
+                ret[j++] = BITS_TO_CHARS[((data[i] & 0x07) << 2) | (data[i + 1] >> 6)];
+                ret[j++] = BITS_TO_CHARS[(data[i + 1] >> 1) & 0x1F];
+                ret[j++] = BITS_TO_CHARS[(data[i + 1] & 0x01) << 4];
+                ret[j++] = PADDING;
+                ret[j++] = PADDING;
+                ret[j++] = PADDING;
+                ret[j++] = PADDING;
+                break;
+            case 3:
+
+                /**
+                 * 11111 111|11 11111 1|1111 1111|0 00000 00|000 00000
+                 */
+                ret[j++] = BITS_TO_CHARS[data[i] >> 3];
+                ret[j++] = BITS_TO_CHARS[((data[i] & 0x07) << 2) | (data[i + 1] >> 6)];
+                ret[j++] = BITS_TO_CHARS[(data[i + 1] >> 1) & 0x1F];
+                ret[j++] = BITS_TO_CHARS[((data[i + 1] & 0x01) << 4) | (data[i + 2] >> 4)];
+                ret[j++] = BITS_TO_CHARS[(data[i + 2] & 0x0F) << 1];
+                ret[j++] = PADDING;
+                ret[j++] = PADDING;
+                ret[j++] = PADDING;
+                break;
+            case 4:
+
+                /**
+                 * 11111 111|11 11111 1|1111 1111|1 11111 11|000 00000
+                 */
+                ret[j++] = BITS_TO_CHARS[data[i] >> 3];
+                ret[j++] = BITS_TO_CHARS[((data[i] & 0x07) << 2) | (data[i + 1] >> 6)];
+                ret[j++] = BITS_TO_CHARS[(data[i + 1] >> 1) & 0x1F];
+                ret[j++] = BITS_TO_CHARS[((data[i + 1] & 0x01) << 4) | (data[i + 2] >> 4)];
+                ret[j++] = BITS_TO_CHARS[((data[i + 2] & 0x0F) << 1) | (data[i + 3] >> 7)];
+                ret[j++] = BITS_TO_CHARS[(data[i + 3] >> 2) & 0x1F];
+                ret[j++] = BITS_TO_CHARS[(data[i + 3] & 0x03) << 3];
+                ret[j++] = PADDING;
+                break;
+            default: // >= 5
+                /**
+                 * 11111 111|11 11111 1|1111 1111|1 11111 11|111 11111
+                 */
+                ret[j++] = BITS_TO_CHARS[data[i] >> 3];
+                ret[j++] = BITS_TO_CHARS[((data[i] & 0x07) << 2) | (data[i + 1] >> 6)];
+                ret[j++] = BITS_TO_CHARS[(data[i + 1] >> 1) & 0x1F];
+                ret[j++] = BITS_TO_CHARS[((data[i + 1] & 0x01) << 4) | (data[i + 2] >> 4)];
+                ret[j++] = BITS_TO_CHARS[((data[i + 2] & 0x0F) << 1) | (data[i + 3] >> 7)];
+                ret[j++] = BITS_TO_CHARS[(data[i + 3] >> 2) & 0x1F];
+                ret[j++] = BITS_TO_CHARS[((data[i + 3] & 0x03) << 3) | (data[i + 4] >> 5)];
+                ret[j++] = BITS_TO_CHARS[data[i + 4] & 0x1F];
+                break;
+        }
+    }
+
+    return ret.toString();
+}
+
+/**
+ * Decode a BASE32-encoded string into a `Buffer`.
+ *
+ * @param input  The BASE32-encoded string to be decoded.
+ *
+ * @returns        The decoded `Buffer`.
+ *
+ * @throws `RangeError` if the input is not a valid BASE32-encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc4648#section-6
+ */
+export function bufferFromBase32(input: string): Buffer {
+
+    if (input.length & 0x7) {
+
+        throw new RangeError('Unrecognizable base32 input.');
+    }
+
+    const ret: Buffer = Buffer.allocUnsafe(input.length / 8 * 5);
+
+    for (let i = 0, j = 0; i < input.length; i += 8) {
+
+        let padFrom = 0;
+
+        if (input[i + 7] === '=') {
+
+            if (input[i + 8] !== undefined) {
+
+                throw new RangeError('Unrecognizable base32 input.');
+            }
+
+            padFrom = input.indexOf('=', i) - i;
+        }
+
+        switch (padFrom) {
+            case 0: // no padding
+
+                /**
+                 * 11111 111|11 11111 1|1111 1111|1 11111 11|111 11111
+                 */
+                ret[j++] = (CHARS_TO_BITS[input[i]] << 3) | (CHARS_TO_BITS[input[i + 1]] >> 2);
+                ret[j++] = ((CHARS_TO_BITS[input[i + 1]] & 0x03) << 6)
+                     | (CHARS_TO_BITS[input[i + 2]] << 1)
+                     | (CHARS_TO_BITS[input[i + 3]] >> 4);
+                ret[j++] = ((CHARS_TO_BITS[input[i + 3]] & 0x0F) << 4)
+                     | (CHARS_TO_BITS[input[i + 4]] >> 1);
+                ret[j++] = ((CHARS_TO_BITS[input[i + 4]] & 0x01) << 7)
+                     | (CHARS_TO_BITS[input[i + 5]] << 2)
+                     | (CHARS_TO_BITS[input[i + 6]] >> 3);
+                ret[j++] = ((CHARS_TO_BITS[input[i + 6]] & 0x07) << 5)
+                     | CHARS_TO_BITS[input[i + 7]];
+                break;
+
+            case 7: // 1 padding
+
+                /**
+                 * 11111 111|11 11111 1|1111 1111|1 11111 11|000 00000
+                 */
+                ret[j++] = (CHARS_TO_BITS[input[i]] << 3) | (CHARS_TO_BITS[input[i + 1]] >> 2);
+                ret[j++] = ((CHARS_TO_BITS[input[i + 1]] & 0x03) << 6)
+                     | (CHARS_TO_BITS[input[i + 2]] << 1)
+                     | (CHARS_TO_BITS[input[i + 3]] >> 4);
+                ret[j++] = ((CHARS_TO_BITS[input[i + 3]] & 0x0F) << 4)
+                     | (CHARS_TO_BITS[input[i + 4]] >> 1);
+                ret[j++] = ((CHARS_TO_BITS[input[i + 4]] & 0x01) << 7)
+                     | (CHARS_TO_BITS[input[i + 5]] << 2)
+                     | (CHARS_TO_BITS[input[i + 6]] >> 3);
+
+                return ret.subarray(0, -1);
+
+            case 5: // 3 padding
+
+                /**
+                 * 11111 111|11 11111 1|1111 1111|0 00000 00|000 00000
+                 */
+                ret[j++] = (CHARS_TO_BITS[input[i]] << 3) | (CHARS_TO_BITS[input[i + 1]] >> 2);
+                ret[j++] = ((CHARS_TO_BITS[input[i + 1]] & 0x03) << 6)
+                     | (CHARS_TO_BITS[input[i + 2]] << 1)
+                     | (CHARS_TO_BITS[input[i + 3]] >> 4);
+                ret[j++] = ((CHARS_TO_BITS[input[i + 3]] & 0x0F) << 4)
+                     | (CHARS_TO_BITS[input[i + 4]] >> 1);
+
+                return ret.subarray(0, -2);
+
+            case 4: // 4 padding
+
+                /**
+                 * 11111 111|11 11111 1|0000 0000|0 00000 00|000 00000
+                 */
+                ret[j++] = (CHARS_TO_BITS[input[i]] << 3) | (CHARS_TO_BITS[input[i + 1]] >> 2);
+                ret[j++] = ((CHARS_TO_BITS[input[i + 1]] & 0x03) << 6)
+                     | (CHARS_TO_BITS[input[i + 2]] << 1)
+                     | (CHARS_TO_BITS[input[i + 3]] >> 4);
+
+                return ret.subarray(0, -3);
+
+            case 2: // 6 padding
+
+                /**
+                 * 11111 111|00 00000 0|0000 0000|0 00000 00|000 00000
+                 */
+                ret[j++] = (CHARS_TO_BITS[input[i]] << 3) | (CHARS_TO_BITS[input[i + 1]] >> 2);
+
+                return ret.subarray(0, -4);
+
+            default:
+
+                throw new RangeError('Unrecognizable base32 input.');
+        }
+    }
+
+    return ret;
+}
+
+/**
+ * Encode a UTF-8 string into a BASE32-encoded string.
+ *
+ * > This method transform the input string into a `Buffer`, and then calls `bufferToBase32`.
+ *
+ * @param data  The string to be encoded.
+ *
+ * @returns     The BASE32-encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc4648#section-6
+ */
+export function stringToBase32(data: string): string {
+
+    return bufferToBase32(Buffer.from(data));
+}
+
+/**
+ * Decode a BASE32-encoded string into a UTF-8 string.
+ *
+ * > This method calls `bufferFromBase32` to decode the input string into a `Buffer`, and then
+ * > converts it to a UTF-8 string.
+ *
+ * @param data  The BASE32-encoded string to be decoded.
+ *
+ * @returns     The decoded UTF-8 string.
+ *
+ * @throws `RangeError` if the input is not a valid BASE32-encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc4648#section-6
+ */
+export function stringFromBase32(data: string): string {
+
+    return bufferFromBase32(data).toString();
+}

package/src/lib/base32-wasm.ts

@@ -0,0 +1,179 @@
+/**
+ * Copyright 2025 Angus.Fenying <fenying@litert.org>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import * as NodeFS from 'node:fs';
+
+let wasmModule: WebAssembly.Module;
+
+interface IWasmApis {
+
+    readonly memory: WebAssembly.Memory;
+
+    initTable(): void;
+
+    getReserverMemorySize(): number;
+
+    encode(len: number): number;
+
+    decode(len: number): number;
+}
+
+/**
+ * The encoder (and also the decoder) for base32 encoding,
+ * written in WebAssembly.
+ */
+class WasmBase32Encoder {
+
+    /**
+     * Allocated pages for the WebAssembly memory.
+     * The initial value is 1, which means 64K memory is allocated.
+     *
+     * > A page in WebAssembly is 64 KiB (65536 bytes).
+     */
+    private _allocPages: number = 1;
+
+    private readonly _wasmInst: WebAssembly.Instance;
+
+    private readonly _apis: IWasmApis;
+
+    public constructor() {
+
+        wasmModule ??= new WebAssembly.Module(NodeFS.readFileSync(`${__dirname}/../wasm/base32.wasm`));
+
+        this._wasmInst = new WebAssembly.Instance(wasmModule, {});
+
+        this._apis = this._wasmInst.exports as unknown as IWasmApis;
+
+        this._apis.memory.grow(1); // Allocate 64K memory for the first time.
+
+        this._apis.initTable();
+    }
+
+    public bufferToBase32(data: Buffer): string {
+
+        const RMS = this._apis.getReserverMemorySize();
+
+        // Prepare memory for decoding: RMS + input length + expected output length.
+        // The expected output length is 8/5 of the input length.
+        // Then the most safe way is just using the 2x (10/5, 200%) as the expected output length,
+        // So, the final memory size will be: RMS + input length * 2 + input length.
+        const minMemPages = Math.ceil((RMS + data.byteLength * 3) / 65536);
+
+        if (minMemPages > this._allocPages) {
+
+            this._apis.memory.grow(minMemPages - this._allocPages);
+            this._allocPages = minMemPages;
+        }
+
+        data.copy(Buffer.from(this._apis.memory.buffer, RMS, data.byteLength));
+        const outLength = this._apis.encode(data.byteLength);
+        return Buffer.from(this._apis.memory.buffer, RMS + data.byteLength, outLength).toString('utf8');
+    }
+
+    public bufferFromBase32(input: string): Buffer {
+
+        const RMS = this._apis.getReserverMemorySize();
+        const inLength = Buffer.byteLength(input);
+
+        // Prepare memory for decoding: RMS + input length + expected output length.
+        // The expected output length is 5/8 of the input length.
+        // So, to simplify the calculation, just use the same as the expected output length,
+        // So, the final memory size will be: RMS + input length * 2.
+        const minMemPages = Math.ceil((inLength * 2 + RMS) / 65536);
+
+        if (minMemPages > this._allocPages) {
+
+            this._apis.memory.grow(minMemPages - this._allocPages);
+            this._allocPages = minMemPages;
+        }
+
+        // copy the input string to the wasm memory (starting from RMS, ending at RMS + inLength).
+        Buffer.from(this._apis.memory.buffer, RMS, inLength).write(input);
+
+        const outLength = this._apis.decode(inLength);
+        if (outLength < 0) {
+
+            throw new TypeError('Invalid input data for base32 encoding.');
+        }
+
+        // read the result from the wasm memory (starting from RMS + inLength, ending at RMS + inLength + outLength).
+        return Buffer.from(this._apis.memory.buffer, RMS + inLength, outLength);
+    }
+
+    public stringToBase32(data: string): string {
+
+        return this.bufferToBase32(Buffer.from(data));
+    }
+
+    public stringFromBase32(data: string): string {
+
+        return this.bufferFromBase32(data).toString();
+    }
+}
+
+const enc = new WasmBase32Encoder();
+
+/**
+ * Encode a UTF-8 string into a BASE32-encoded string.
+ *
+ * > This method transform the input string into a `Buffer`, and then calls `bufferToBase32`.
+ *
+ * @param data  The string to be encoded.
+ *
+ * @returns     The BASE32-encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc4648#section-6
+ */
+export const stringToBase32 = enc.stringToBase32.bind(enc);
+
+/**
+ * Decode a BASE32-encoded string into a UTF-8 string.
+ *
+ * > This method calls `bufferFromBase32` to decode the input string into a `Buffer`, and then
+ * > converts it to a UTF-8 string.
+ *
+ * @param data  The BASE32-encoded string to be decoded.
+ *
+ * @returns     The decoded UTF-8 string.
+ *
+ * @throws `RangeError` if the input is not a valid BASE32-encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc4648#section-6
+ */
+export const stringFromBase32 = enc.stringFromBase32.bind(enc);
+
+/**
+ * Encode a `Buffer` to a BASE32-encoded string.
+ *
+ * @param data  The `Buffer` to be encoded.
+ *
+ * @returns     The BASE32 encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc4648#section-6
+ */
+export const bufferToBase32 = enc.bufferToBase32.bind(enc);
+
+/**
+ * Decode a BASE32-encoded string into a `Buffer`.
+ *
+ * @param input  The BASE32-encoded string to be decoded.
+ *
+ * @returns        The decoded `Buffer`.
+ *
+ * @throws `RangeError` if the input is not a valid BASE32-encoded string.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc4648#section-6
+ */
+export const bufferFromBase32 = enc.bufferFromBase32.bind(enc);

package/src/lib/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright 2025 Angus.Fenying <fenying@litert.org>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './base32-wasm';