feat(encoding/unstable): add format option to encodeBase64 and decodeBase64

_tools/check_docs.ts

@@ -48,6 +48,7 @@ const ENTRY_POINTS = [
   "../datetime/mod.ts",
   "../dotenv/mod.ts",
   "../encoding/mod.ts",
+  "../encoding/unstable_base64.ts",
   "../encoding/unstable_base64_stream.ts",
   "../encoding/unstable_base32hex_stream.ts",
   "../encoding/unstable_base32_stream.ts",

encoding/_common64.ts

@@ -0,0 +1,122 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+
+import type { Uint8Array_ } from "./_types.ts";
+export type { Uint8Array_ };
+
+/**
+ * Calculate the output size needed to encode a given input size for
+ * {@linkcode encodeRawBase64}.
+ *
+ * @param originalSize The size of the input buffer.
+ * @returns The size of the output buffer.
+ *
+ * @example Basic Usage
+ * ```ts
+ * import { assertEquals } from "@std/assert";
+ * import { calcMax } from "@std/encoding/unstable-base64";
+ *
+ * assertEquals(calcMax(1), 4);
+ * ```
+ */
+export function calcMax(originalSize: number): number {
+  return ((originalSize + 2) / 3 | 0) * 4;
+}
+
+export function encode(
+  buffer: Uint8Array_,
+  i: number,
+  o: number,
+  alphabet: Uint8Array,
+  padding: number,
+): number {
+  i += 2;
+  for (; i < buffer.length; i += 3) {
+    const x = (buffer[i - 2]! << 16) | (buffer[i - 1]! << 8) | buffer[i]!;
+    buffer[o++] = alphabet[x >> 18]!;
+    buffer[o++] = alphabet[x >> 12 & 0x3F]!;
+    buffer[o++] = alphabet[x >> 6 & 0x3F]!;
+    buffer[o++] = alphabet[x & 0x3F]!;
+  }
+  switch (i) {
+    case buffer.length + 1: {
+      const x = buffer[i - 2]! << 16;
+      buffer[o++] = alphabet[x >> 18]!;
+      buffer[o++] = alphabet[x >> 12 & 0x3F]!;
+      buffer[o++] = padding;
+      buffer[o++] = padding;
+      break;
+    }
+    case buffer.length: {
+      const x = (buffer[i - 2]! << 16) | (buffer[i - 1]! << 8);
+      buffer[o++] = alphabet[x >> 18]!;
+      buffer[o++] = alphabet[x >> 12 & 0x3F]!;
+      buffer[o++] = alphabet[x >> 6 & 0x3F]!;
+      buffer[o++] = padding;
+      break;
+    }
+  }
+  return o;
+}
+
+export function decode(
+  buffer: Uint8Array_,
+  i: number,
+  o: number,
+  alphabet: Uint8Array,
+  padding: number,
+): number {
+  for (let x = buffer.length - 2; x < buffer.length; ++x) {
+    if (buffer[x] === padding) {
+      for (let y = x + 1; y < buffer.length; ++y) {
+        if (buffer[y] !== padding) {
+          throw new TypeError(
+            `Invalid Character (${String.fromCharCode(buffer[y]!)})`,
+          );
+        }
+      }
+      buffer = buffer.subarray(0, x);
+      break;
+    }
+  }
+  if ((buffer.length - o) % 4 === 1) {
+    throw new TypeError(
+      `Invalid Character (${String.fromCharCode(buffer[buffer.length - 1]!)})`,
+    );
+  }
+
+  i += 3;
+  for (; i < buffer.length; i += 4) {
+    const x = (getByte(buffer[i - 3]!, alphabet) << 18) |
+      (getByte(buffer[i - 2]!, alphabet) << 12) |
+      (getByte(buffer[i - 1]!, alphabet) << 6) |
+      getByte(buffer[i]!, alphabet);
+    buffer[o++] = x >> 16;
+    buffer[o++] = x >> 8 & 0xFF;
+    buffer[o++] = x & 0xFF;
+  }
+  switch (i) {
+    case buffer.length + 1: {
+      const x = (getByte(buffer[i - 3]!, alphabet) << 18) |
+        (getByte(buffer[i - 2]!, alphabet) << 12);
+      buffer[o++] = x >> 16;
+      break;
+    }
+    case buffer.length: {
+      const x = (getByte(buffer[i - 3]!, alphabet) << 18) |
+        (getByte(buffer[i - 2]!, alphabet) << 12) |
+        (getByte(buffer[i - 1]!, alphabet) << 6);
+      buffer[o++] = x >> 16;
+      buffer[o++] = x >> 8 & 0xFF;
+      break;
+    }
+  }
+  return o;
+}
+
+function getByte(char: number, alphabet: Uint8Array): number {
+  const byte = alphabet[char]!;
+  if (byte === 64) { // alphabet.Base64.length
+    throw new TypeError(`Invalid Character (${String.fromCharCode(char)})`);
+  }
+  return byte;
+}

encoding/_common_detach.ts

@@ -0,0 +1,20 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+
+import type { Uint8Array_ } from "./_types.ts";
+export type { Uint8Array_ };
+
+export function detach(
+  buffer: Uint8Array_,
+  maxSize: number,
+): [Uint8Array_, number] {
+  const originalSize = buffer.length;
+  if (buffer.byteOffset) {
+    const b = new Uint8Array(buffer.buffer);
+    b.set(buffer);
+    buffer = b.subarray(0, originalSize);
+  }
+  // deno-lint-ignore no-explicit-any
+  buffer = new Uint8Array((buffer.buffer as any).transfer(maxSize));
+  buffer.set(buffer.subarray(0, originalSize), maxSize - originalSize);
+  return [buffer, maxSize - originalSize];
+}

encoding/deno.json

@@ -11,6 +11,7 @@
     "./unstable-base32hex-stream": "./unstable_base32hex_stream.ts",
     "./base58": "./base58.ts",
     "./base64": "./base64.ts",
+    "./unstable-base64": "./unstable_base64.ts",
     "./unstable-base64-stream": "./unstable_base64_stream.ts",
     "./base64url": "./base64url.ts",
     "./unstable-base64url-stream": "./unstable_base64url_stream.ts",