feat: binary encoder

Author: Bekacru

README.md

@@ -21,6 +21,7 @@ utilities provided by `@better-auth/utils`:
 | [**Hex**](#hex)   | Encode and decode data in hexadecimal format.      |
 | [**OTP**](#otp) | Generate and verify one-time passwords.            |
 
+
 ## Hash
 
 Digest provides a way to hash an input using sha family hash functions. It wraps over `crypto.digest` and provide utilities to encode output in hex or base 64.
@@ -228,61 +229,6 @@ const isValid = await ecdsa.verify(publicKey, {
 });
 ```
 
-## Base64
-
-Base64 utilities provide a simple interface to encode and decode data in base64 format.
-
-### Encoding
-
-Encode data in base64 format. Input can be a string, `ArrayBuffer`, or `TypedArray`.
-
-```ts
-import { base64 } from "@better-auth/utils/base64";
-
-const encodedData = base64.encode("Data to encode");
-```
-
-options:
-- `urlSafe` - URL-safe encoding, replacing `+` with `-` and `/` with `_`.
-- `padding` - Include padding characters (`=`) at the end of the encoded string
-
-```ts
-const encodedData = base64.encode("Data to encode", { url: true, padding: false });
-```
-
-### Decoding
-
-Decode base64-encoded data. Input can be a string or `ArrayBuffer`.
-
-```ts
-const decodedData = await base64.decode(encodedData);
-```
-
-It automatically detects if the input is URL-safe and includes padding characters.
-
-
-## Hex
-
-Hex utilities provide a simple interface to encode and decode data in hexadecimal format.
-
-### Encoding
-
-Encode data in hexadecimal format. Input can be a string, `ArrayBuffer`, or `TypedArray`.
-
-```ts
-import { hex } from "@better-auth/utils/hex";
-
-const encodedData = hex.encode("Data to encode");
-```
-
-### Decoding
-
-Decode hexadecimal-encoded data. Input can be a string or `ArrayBuffer`.
-
-```ts
-const decodedData = hex.decode(encodedData);
-```
-
 ## OTP
 
 The OTP utility provides a simple and secure way to generate and verify one-time passwords (OTPs), commonly used in multi-factor authentication (MFA) systems. It includes support for both HOTP (HMAC-based One-Time Password) and TOTP (Time-based One-Time Password) standards.
@@ -349,6 +295,90 @@ const secret = "my-super-secret-key";
 const qrCodeUrl = createOTP(secret).url("my-app", "[email protected]"); 
 ```
 
+
+## Base64
+
+Base64 utilities provide a simple interface to encode and decode data in base64 format.
+
+### Encoding
+
+Encode data in base64 format. Input can be a string, `ArrayBuffer`, or `TypedArray`.
+
+```ts
+import { base64 } from "@better-auth/utils/base64";
+
+const encodedData = base64.encode("Data to encode");
+```
+
+options:
+- `padding` - Include padding characters (`=`) at the end of the encoded string
+
+```ts
+const encodedData = base64.encode("Data to encode", { url: true, padding: false });
+```
+
+### Decoding
+
+Decode base64-encoded data. Input can be a string or `ArrayBuffer`.
+
+```ts
+const decodedData = await base64.decode(encodedData);
+```
+
+It automatically detects if the input is URL-safe and includes padding characters.
+
+### Base64Url
+
+Url safe alternative
+
+```ts
+import { base64Url } from "@better-auth/utils/base64";
+
+const encodedData = base64Url.encode("Data to encode");
+```
+
+## Hex
+
+Hex utilities provide a simple interface to encode and decode data in hexadecimal format.
+
+### Encoding
+
+Encode data in hexadecimal format. Input can be a string, `ArrayBuffer`, or `TypedArray`.
+
+```ts
+import { hex } from "@better-auth/utils/hex";
+
+const encodedData = hex.encode("Data to encode");
+```
+
+### Decoding
+
+Decode hexadecimal-encoded data. Input can be a string or `ArrayBuffer`.
+
+```ts
+const decodedData = hex.decode(encodedData);
+```
+
+## Binary
+
+A utilities provide a simple interface to encode and decode data in binary format. It uses `TextEncode` and `TextDecoder` to encode and decode data respectively.
+
+### Encoding
+
+```ts
+import { binary } from "@better-auth/util/binary"
+
+const data = binary.encode("Hello World!")
+```
+
+### Decoding
+
+```ts
+import { binary } from "@better-auth/util/binary"
+
+const data = binary.decode(new Unit8Array([[72, 101, 108, 108, 111]]))
+```
+
 ## License
 
 MIT

src/base64.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
-import { base64 } from "./base64";
+import { base64, base64Url } from "./base64";
+import { binary } from "./binary";
 
 describe("base64", () => {
 	const plainText = "Hello, World!";
@@ -9,45 +10,38 @@ describe("base64", () => {
 
 	describe("encode", () => {
 		it("encodes a string to base64 with padding", async () => {
-			const result = await base64.encode(plainText, { padding: true });
+			const result = base64.encode(plainText, { padding: true });
 			expect(result).toBe(base64Encoded);
 		});
 
 		it("encodes a string to base64 without padding", async () => {
-			const result = await base64.encode(plainText, { padding: false });
+			const result = base64.encode(plainText, { padding: false });
 			expect(result).toBe(base64Encoded.replace(/=+$/, ""));
 		});
 
 		it("encodes a string to base64 URL-safe", async () => {
-			const result = await base64.encode(plainText, {
-				urlSafe: true,
+			const result = base64Url.encode(plainText, {
 				padding: false,
 			});
 			expect(result).toBe(base64UrlEncoded);
 		});
 
 		it("encodes an ArrayBuffer to base64", async () => {
-			const result = await base64.encode(plainBuffer, { padding: true });
+			const result = base64.encode(plainBuffer, { padding: true });
 			expect(result).toBe(base64Encoded);
 		});
 	});
 
 	describe("decode", () => {
-		it("decodes a base64 string to a Uint8Array", async () => {
-			const result = await base64.decode(base64Encoded);
-			expect(result).toBe(plainText);
+		it("decodes a base64 string", async () => {
+			const encoded = Buffer.from(plainText).toString("base64");
+			const result = base64.decode(encoded);
+			expect(binary.decode(result)).toBe(plainText);
 		});
 
-		it("decodes a base64 URL-safe string to a Uint8Array", async () => {
-			const result = await base64.decode(base64UrlEncoded);
-			expect(result).toBe(plainText);
-		});
-
-		it("throws an error for invalid characters", async () => {
-			const invalidBase64 = "SGVsbG8s#";
-			await expect(base64.decode(invalidBase64)).rejects.toThrow(
-				"Invalid character",
-			);
+		it("decodes a base64 URL-safe string", async () => {
+			const result = base64.decode(base64UrlEncoded);
+			expect(binary.decode(result)).toBe(plainText);
 		});
 	});
 });

src/base64.ts

@@ -2,14 +2,6 @@
 
 import type { TypedArray } from "./type";
 
-function createDecodeMap(alphabet: string): Map<string, number> {
-	const decodeMap = new Map<string, number>();
-	for (let i = 0; i < alphabet.length; i++) {
-		decodeMap.set(alphabet[i]!, i);
-	}
-	return decodeMap;
-}
-
 function getAlphabet(urlSafe: boolean): string {
 	return urlSafe
 		? "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
@@ -25,82 +17,91 @@ function base64Encode(
 	let buffer = 0;
 	let shift = 0;
 
-	for (let i = 0; i < data.length; i++) {
-		buffer = (buffer << 8) | data[i]!;
+	for (const byte of data) {
+		buffer = (buffer << 8) | byte;
 		shift += 8;
 		while (shift >= 6) {
 			shift -= 6;
 			result += alphabet[(buffer >> shift) & 0x3f];
 		}
 	}
+
 	if (shift > 0) {
 		result += alphabet[(buffer << (6 - shift)) & 0x3f];
 	}
+
 	if (padding) {
 		const padCount = (4 - (result.length % 4)) % 4;
 		result += "=".repeat(padCount);
 	}
+
 	return result;
 }
 
 function base64Decode(data: string, alphabet: string): Uint8Array {
-	const decodeMap = createDecodeMap(alphabet);
+	const decodeMap = new Map<string, number>();
+	for (let i = 0; i < alphabet.length; i++) {
+		decodeMap.set(alphabet[i]!, i);
+	}
 	const result: number[] = [];
-	const chunkCount = Math.ceil(data.length / 4);
+	let buffer = 0;
+	let bitsCollected = 0;
 
-	for (let i = 0; i < chunkCount; i++) {
-		let padCount = 0;
-		let buffer = 0;
-		for (let j = 0; j < 4; j++) {
-			const encoded = data[i * 4 + j];
-			if (encoded === "=") {
-				padCount += 1;
-				continue;
-			}
-			if (encoded === undefined) {
-				padCount += 1;
-				continue;
-			}
-			const value = decodeMap.get(encoded) ?? null;
-			if (value === null) {
-				throw new Error(`Invalid character: ${encoded}`);
-			}
-			buffer += value << (6 * (3 - j));
-		}
-		result.push((buffer >> 16) & 0xff);
-		if (padCount < 2) {
-			result.push((buffer >> 8) & 0xff);
+	for (const char of data) {
+		if (char === "=") break;
+		const value = decodeMap.get(char);
+		if (value === undefined) {
+			throw new Error(`Invalid Base64 character: ${char}`);
 		}
-		if (padCount < 1) {
-			result.push(buffer & 0xff);
+		buffer = (buffer << 6) | value;
+		bitsCollected += 6;
+
+		if (bitsCollected >= 8) {
+			bitsCollected -= 8;
+			result.push((buffer >> bitsCollected) & 0xff);
 		}
 	}
+
 	return Uint8Array.from(result);
 }
 
 export const base64 = {
-	async encode(
+	encode(
 		data: ArrayBuffer | TypedArray | string,
-		options: {
-			urlSafe?: boolean;
-			padding?: boolean;
-		} = {},
+		options: { padding?: boolean } = {},
 	) {
-		const alphabet = getAlphabet(options.urlSafe ?? false);
-		if (typeof data === "string") {
-			const encoder = new TextEncoder();
-			data = encoder.encode(data);
+		const alphabet = getAlphabet(false);
+		const buffer =
+			typeof data === "string"
+				? new TextEncoder().encode(data)
+				: new Uint8Array(data);
+		return base64Encode(buffer, alphabet, options.padding ?? true);
+	},
+	decode(data: string | ArrayBuffer | TypedArray) {
+		if (typeof data !== "string") {
+			data = new TextDecoder().decode(data);
 		}
-		return base64Encode(
-			new Uint8Array(data),
-			alphabet,
-			options.padding ?? true,
-		);
+		const urlSafe = data.includes("-") || data.includes("_");
+		const alphabet = getAlphabet(urlSafe);
+		return base64Decode(data, alphabet);
+	},
+};
+
+export const base64Url = {
+	encode(
+		data: ArrayBuffer | TypedArray | string,
+		options: { padding?: boolean } = {},
+	) {
+		const alphabet = getAlphabet(true);
+		const buffer =
+			typeof data === "string"
+				? new TextEncoder().encode(data)
+				: new Uint8Array(data);
+		return base64Encode(buffer, alphabet, options.padding ?? true);
 	},
-	async decode(data: string) {
-		const isUrlSafe = data.includes("-") || data.includes("_");
-		const alphabet = getAlphabet(isUrlSafe);
-		const decoded = base64Decode(data, alphabet);
-		return new TextDecoder().decode(decoded);
+	decode(data: string) {
+		const urlSafe = data.includes("-") || data.includes("_");
+		const alphabet = getAlphabet(urlSafe);
+		return base64Decode(data, alphabet);
 	},
 };

src/binary.ts

@@ -0,0 +1,17 @@
+type Encoding = "utf-8" | "utf-16" | "iso-8859-1";
+
+type BinaryData = ArrayBuffer | ArrayBufferView;
+
+const decoders = new Map<Encoding, TextDecoder>();
+const encoder = new TextEncoder();
+
+export const binary = {
+	decode: (data: BinaryData, encoding: Encoding = "utf-8") => {
+		if (!decoders.has(encoding)) {
+			decoders.set(encoding, new TextDecoder(encoding));
+		}
+		const decoder = decoders.get(encoding)!;
+		return decoder.decode(data);
+	},
+	encode: encoder.encode,
+};