@atproto/lex-data 0.0.2 → 0.0.4

package/src/uint8array-from-base64.ts

@@ -1,5 +1,6 @@
 import { fromString } from 'uint8arrays/from-string'
 import { NodeJSBuffer } from './lib/nodejs-buffer.js'
+import { Base64Alphabet } from './uint8array-base64.js'
 
 const Buffer = NodeJSBuffer
 
@@ -21,14 +22,23 @@ declare global {
 
 export const fromBase64Native =
   typeof Uint8Array.fromBase64 === 'function'
-    ? function fromBase64Native(b64: string): Uint8Array {
-        return Uint8Array.fromBase64!(b64, { lastChunkHandling: 'loose' })
+    ? function fromBase64Native(
+        b64: string,
+        alphabet: Base64Alphabet = 'base64',
+      ): Uint8Array {
+        return Uint8Array.fromBase64!(b64, {
+          alphabet,
+          lastChunkHandling: 'loose',
+        })
       }
     : null
 
 export const fromBase64Node = Buffer
-  ? function fromBase64Node(b64: string): Uint8Array {
-      const bytes = Buffer.from(b64, 'base64')
+  ? function fromBase64Node(
+      b64: string,
+      alphabet: Base64Alphabet = 'base64',
+    ): Uint8Array {
+      const bytes = Buffer.from(b64, alphabet)
       verifyBase64ForBytes(b64, bytes)
       // Convert to Uint8Array because even though Buffer is a sub class of
       // Uint8Array, it serializes differently to Uint8Array (e.g. in JSON) and
@@ -37,8 +47,11 @@ export const fromBase64Node = Buffer
     }
   : null
 
-export function fromBase64Ponyfill(b64: string): Uint8Array {
-  const bytes = fromString(b64, 'base64')
+export function fromBase64Ponyfill(
+  b64: string,
+  alphabet: Base64Alphabet = 'base64',
+): Uint8Array {
+  const bytes = fromString(b64, b64.endsWith('=') ? `${alphabet}pad` : alphabet)
   verifyBase64ForBytes(b64, bytes)
   return bytes
 }

package/src/uint8array-to-base64.test.ts

@@ -0,0 +1,170 @@
+import 'core-js/modules/es.uint8-array.from-base64.js'
+import 'core-js/modules/es.uint8-array.to-base64.js'
+import assert from 'node:assert'
+import {
+  toBase64Native,
+  toBase64Node,
+  toBase64Ponyfill,
+} from './uint8array-to-base64.js'
+
+for (const toBase64 of [
+  toBase64Native,
+  toBase64Node,
+  toBase64Ponyfill,
+] as const) {
+  // Tests should run in NodeJS where implementations are either available or
+  // polyfilled (see core-js imports above).
+  assert(toBase64 !== null, 'toBase64 implementation should not be null')
+
+  describe(toBase64.name, () => {
+    describe('basic encoding', () => {
+      it('encodes empty Uint8Array', () => {
+        const encoded = toBase64(new Uint8Array(0))
+        expect(typeof encoded).toBe('string')
+        expect(encoded).toBe('')
+      })
+
+      it('encodes 10MB', () => {
+        const bytes = Buffer.allocUnsafe(10_000_000).fill('🐩')
+        const encoded = toBase64(bytes)
+        expect(typeof encoded).toBe('string')
+        // Verify by decoding back
+        const decoded = Buffer.from(encoded, 'base64')
+        expect(decoded.equals(bytes)).toBe(true)
+      })
+    })
+
+    describe('base64 alphabet (default)', () => {
+      for (const string of [
+        '',
+        '\0\0',
+        '\0\0\0',
+        '\0\0\0\0',
+        '__',
+        'é',
+        'àç',
+        '\0éàç',
+        '```\x1b',
+        'aaa',
+        'Hello, World!',
+        '😀😃😄😁😆😅😂🤣😊😇',
+        '👩‍💻👨‍💻👩‍🔬👨‍🔬👩‍🚀👨‍🚀',
+        '🌍🌎🌏🌐🪐🌟✨⚡🔥💧',
+      ] as const) {
+        const buffer = Buffer.from(string, 'utf8')
+        const expected = buffer.toString('base64').replace(/=+$/, '')
+
+        it(`encodes ${JSON.stringify(string)} as ${JSON.stringify(expected)}`, () => {
+          const encoded = toBase64(buffer)
+          expect(encoded).toBe(expected)
+        })
+      }
+    })
+
+    describe('base64url alphabet', () => {
+      for (const string of [
+        '',
+        '\0\0',
+        '\0\0\0',
+        '\0\0\0\0',
+        '__',
+        'é',
+        'àç',
+        '\0éàç',
+        '```\x1b',
+        'aaa',
+        'Hello, World!',
+        '😀😃😄😁😆😅😂🤣😊😇',
+        '👩‍💻👨‍💻👩‍🔬👨‍🔬👩‍🚀👨‍🚀',
+        '🌍🌎🌏🌐🪐🌟✨⚡🔥💧',
+      ] as const) {
+        const buffer = Buffer.from(string, 'utf8')
+        const expected = buffer.toString('base64url')
+
+        it(`encodes ${JSON.stringify(string)} as ${JSON.stringify(expected)}`, () => {
+          const encoded = toBase64(buffer, 'base64url')
+          expect(encoded).toBe(expected)
+        })
+      }
+    })
+
+    describe('base64 vs base64url character differences', () => {
+      // Test data that produces + and / in standard base64
+      // These should become - and _ in base64url
+      it('uses + and / for base64 alphabet', () => {
+        // 0xfb, 0xff, 0xbf produces "+/+/" in base64
+        const bytes = new Uint8Array([0xfb, 0xff, 0xbf])
+        const encoded = toBase64(bytes)
+        expect(encoded).toContain('+')
+        expect(encoded).toContain('/')
+        expect(encoded).not.toContain('-')
+        expect(encoded).not.toContain('_')
+      })
+
+      it('uses - and _ for base64url alphabet', () => {
+        // Same bytes should use - and _ in base64url
+        const bytes = new Uint8Array([0xfb, 0xff, 0xbf])
+        const encoded = toBase64(bytes, 'base64url')
+        expect(encoded).toContain('-')
+        expect(encoded).toContain('_')
+        expect(encoded).not.toContain('+')
+        expect(encoded).not.toContain('/')
+      })
+    })
+
+    describe('padding behavior', () => {
+      it('omits padding by default for 1-byte input', () => {
+        // 1 byte -> 2 base64 chars + 2 padding
+        const bytes = new Uint8Array([0x4d]) // 'M' -> 'TQ=='
+        const encoded = toBase64(bytes)
+        expect(encoded).toBe('TQ')
+        expect(encoded).not.toContain('=')
+      })
+
+      it('omits padding by default for 2-byte input', () => {
+        // 2 bytes -> 3 base64 chars + 1 padding
+        const bytes = new Uint8Array([0x4d, 0x61]) // 'Ma' -> 'TWE='
+        const encoded = toBase64(bytes)
+        expect(encoded).toBe('TWE')
+        expect(encoded).not.toContain('=')
+      })
+
+      it('no padding needed for 3-byte input', () => {
+        // 3 bytes -> 4 base64 chars, no padding needed
+        const bytes = new Uint8Array([0x4d, 0x61, 0x6e]) // 'Man' -> 'TWFu'
+        const encoded = toBase64(bytes)
+        expect(encoded).toBe('TWFu')
+      })
+
+      it('includes double padding when omitPadding: false for 1-byte input', () => {
+        const bytes = new Uint8Array([0x4d]) // 'M' -> 'TQ=='
+        const encoded = toBase64(bytes)
+        expect(encoded).toBe('TQ')
+      })
+
+      it('includes single padding when omitPadding: false for 2-byte input', () => {
+        const bytes = new Uint8Array([0x4d, 0x61]) // 'Ma' -> 'TWE='
+        const encoded = toBase64(bytes)
+        expect(encoded).toBe('TWE')
+      })
+    })
+
+    describe('Uint8Array subarray handling', () => {
+      it('correctly encodes a subarray', () => {
+        const fullArray = new Uint8Array([0x00, 0x4d, 0x61, 0x6e, 0x00])
+        const subarray = fullArray.subarray(1, 4) // 'Man'
+        const encoded = toBase64(subarray)
+        expect(encoded).toBe('TWFu')
+      })
+
+      it('correctly encodes a subarray with offset', () => {
+        const buffer = new ArrayBuffer(10)
+        const fullView = new Uint8Array(buffer)
+        fullView.set([0x00, 0x00, 0x4d, 0x61, 0x6e, 0x00, 0x00])
+        const subarray = new Uint8Array(buffer, 2, 3) // 'Man' at offset 2
+        const encoded = toBase64(subarray)
+        expect(encoded).toBe('TWFu')
+      })
+    })
+  })
+}

package/src/uint8array-to-base64.ts

@@ -1,5 +1,6 @@
 import { toString } from 'uint8arrays/to-string'
 import { NodeJSBuffer } from './lib/nodejs-buffer.js'
+import { Base64Alphabet } from './uint8array-base64.js'
 
 const Buffer = NodeJSBuffer
 
@@ -18,16 +19,22 @@ declare global {
 
 export const toBase64Native =
   typeof Uint8Array.prototype.toBase64 === 'function'
-    ? function toBase64Native(bytes: Uint8Array): string {
-        return bytes.toBase64!({ omitPadding: true })
+    ? function toBase64Native(
+        bytes: Uint8Array,
+        alphabet: Base64Alphabet = 'base64',
+      ): string {
+        return bytes.toBase64!({ alphabet, omitPadding: true })
       }
     : null
 
 export const toBase64Node = Buffer
-  ? function toBase64Node(bytes: Uint8Array): string {
-      const b64 = (
-        bytes instanceof Buffer ? bytes : Buffer.from(bytes)
-      ).toString('base64')
+  ? function toBase64Node(
+      bytes: Uint8Array,
+      alphabet: Base64Alphabet = 'base64',
+    ): string {
+      const buffer = bytes instanceof Buffer ? bytes : Buffer.from(bytes)
+      const b64 = buffer.toString(alphabet)
+
       // @NOTE We strip padding for strict compatibility with
       // uint8arrays.toString behavior. Tests failing because of the presence of
       // padding are not really synonymous with an actual error and we might
@@ -40,6 +47,9 @@ export const toBase64Node = Buffer
     }
   : null
 
-export function toBase64Ponyfill(bytes: Uint8Array): string {
-  return toString(bytes, 'base64')
+export function toBase64Ponyfill(
+  bytes: Uint8Array,
+  alphabet: Base64Alphabet = 'base64',
+): string {
+  return toString(bytes, alphabet)
 }

package/src/uint8array.ts

@@ -1,3 +1,4 @@
+import { Base64Alphabet } from './uint8array-base64.js'
 import {
   fromBase64Native,
   fromBase64Node,
@@ -9,6 +10,8 @@ import {
   toBase64Ponyfill,
 } from './uint8array-to-base64.js'
 
+export type { Base64Alphabet }
+
 // @TODO drop dependency on uint8arrays package once Uint8Array.fromBase64 /
 // Uint8Array.prototype.toBase64 is widely supported, and mark fromBase64 /
 // toBase64 as deprecated. We can also drop NodeJS specific implementations
@@ -19,17 +22,22 @@ import {
  *
  * @returns The base64 encoded string
  */
-export const toBase64: (bytes: Uint8Array) => string =
-  toBase64Native ?? toBase64Node ?? toBase64Ponyfill
+export const toBase64: (
+  bytes: Uint8Array,
+  alphabet?: Base64Alphabet,
+) => string = toBase64Native ?? toBase64Node ?? toBase64Ponyfill
 
 /**
- * Decodes a base64 string into a Uint8Array.
+ * Decodes a base64 string into a Uint8Array. This function supports both padded
+ * and unpadded base64 strings.
  *
  * @returns The decoded {@link Uint8Array}
  * @throws If the input is not a valid base64 string
  */
-export const fromBase64: (b64: string) => Uint8Array =
-  fromBase64Native ?? fromBase64Node ?? fromBase64Ponyfill
+export const fromBase64: (
+  b64: string,
+  alphabet?: Base64Alphabet,
+) => Uint8Array = fromBase64Native ?? fromBase64Node ?? fromBase64Ponyfill
 
 if (toBase64 === toBase64Ponyfill || fromBase64 === fromBase64Ponyfill) {
   /*#__PURE__*/

package/tsconfig.tests.json

@@ -1,6 +1,6 @@
 {
   "extends": "../../../tsconfig/tests.json",
-  "include": ["./tests", "./src/**.test.ts"],
+  "include": ["./tests", "./src/**/*.test.ts"],
   "compilerOptions": {
     "noImplicitAny": true,
     "rootDir": "./",