Open History to see the last commit
1/**
2 * Cross-runtime base64 helpers.
3 *
4 * Both `arrayBufferToBase64` and `base64ToArrayBuffer` prefer the new native
5 * `Uint8Array.toBase64()` / `Uint8Array.fromBase64()` methods (TC39 base64
6 * proposal, Stage 3) when available — they are significantly faster and more
7 * memory-efficient than the byte-walking fallback. The fallbacks use Node's
8 * `Buffer` when present, then `atob`/`btoa` for browser / edge runtimes.
9 */
10
11interface Uint8ArrayWithBase64 {
12 fromBase64?: (input: string) => Uint8Array
13}
14
15interface Uint8ArrayInstanceWithBase64 {
16 toBase64?: () => string
17}
18
19/**
20 * Encode an `ArrayBuffer` as a base64 string.
21 *
22 * Note: callers should be cautious about feeding large buffers (more than a
23 * few megabytes) on serverless / Workers runtimes — converting big media to
24 * base64 multiplies its memory footprint by ~1.33× and frequently OOMs the
25 * isolate.
26 */
27export function arrayBufferToBase64(buffer: ArrayBuffer): string {
28 const bytes = new Uint8Array(buffer)
29
30 const fast = (bytes as Uint8ArrayInstanceWithBase64).toBase64
31 if (typeof fast === 'function') {
32 return fast.call(bytes)
33 }
34
35 if (typeof Buffer !== 'undefined' && typeof Buffer.from === 'function') {
36 return Buffer.from(buffer).toString('base64')
37 }
38
39 if (typeof btoa === 'function') {
40 let binary = ''
41 // 32KB chunks keep us well under V8's argument-count limits for
42 // String.fromCharCode.apply on large buffers.
43 const chunkSize = 0x8000
44 for (let i = 0; i < bytes.length; i += chunkSize) {
45 const chunk = bytes.subarray(i, i + chunkSize)
46 binary += String.fromCharCode.apply(
47 null,
48 // oxlint-disable-next-line eslint-js/no-restricted-syntax -- TS lib types String.fromCharCode.apply as Array<number> but runtime accepts any ArrayLike
49 chunk as unknown as Array<number>,
50 )
51 }
52 return btoa(binary)
53 }
54
55 throw new Error('No base64 encoder available in this environment.')
56}
57
58/**
59 * Decode a base64 string into a `Uint8Array`.
60 */
61export function base64ToUint8Array(base64: string): Uint8Array {
62 return new Uint8Array(base64ToArrayBuffer(base64))
63}
64
65/**
66 * Decode a base64 string into an `ArrayBuffer`.
67 */
68export function base64ToArrayBuffer(base64: string): ArrayBuffer {
69 // oxlint-disable-next-line eslint-js/no-restricted-syntax -- feature-detecting Uint8Array.fromBase64 Stage-3 proposal not yet in lib.es types
70 const fast = (Uint8Array as unknown as Uint8ArrayWithBase64).fromBase64
71 if (typeof fast === 'function') {
72 return fast(base64).buffer as ArrayBuffer
73 }
74
75 if (typeof atob === 'function') {
76 const binary = atob(base64)
77 const bytes = new Uint8Array(binary.length)
78 for (let i = 0; i < binary.length; i++) {
79 bytes[i] = binary.charCodeAt(i)
80 }
81 return bytes.buffer
82 }
83
84 if (typeof Buffer !== 'undefined' && typeof Buffer.from === 'function') {
85 const buf = Buffer.from(base64, 'base64')
86 return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength)
87 }
88
89 throw new Error('No base64 decoder available in this environment.')
90}