Skip to content

feat: add ArrayBuffer output support #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ChALkeR merged 1 commit into from
Mar 4, 2026
Merged

feat: add ArrayBuffer output support #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 3 additions & 8 deletions array.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,12 +45,7 @@ export type Uint32ArrayBuffer = ReturnType<typeof Uint32Array.from>;
/**
* Output format for typed array conversions
*/
export type OutputFormat = 'uint8' | 'buffer';

/**
* Output format for typed array copy conversions
*/
export type OutputCopyFormat = 'uint8' | 'arraybuffer' | 'buffer';
export type OutputFormat = 'uint8' | 'arraybuffer' | 'buffer';

/**
* Create a view of a TypedArray in the specified format (`'uint8'` or `'buffer'`)
Expand All @@ -68,7 +63,7 @@ export type OutputCopyFormat = 'uint8' | 'arraybuffer' | 'buffer';
*/
export function typedView(arr: ArrayBufferView, format: 'uint8'): Uint8Array;
export function typedView(arr: ArrayBufferView, format: 'buffer'): Buffer;
export function typedView(arr: ArrayBufferView, format: OutputFormat): Uint8Array | Buffer;
export function typedView(arr: ArrayBufferView, format: 'uint8' | 'buffer'): Uint8Array | Buffer;

/**
* Create a copy of TypedArray underlying bytes in the specified format (`'uint8'`, `'buffer'`, or `'arraybuffer'`)
Expand All @@ -91,4 +86,4 @@ export function typedView(arr: ArrayBufferView, format: OutputFormat): Uint8Arra
export function typedCopyBytes(arr: ArrayBufferView, format: 'uint8'): Uint8Array;
export function typedCopyBytes(arr: ArrayBufferView, format: 'arraybuffer'): ArrayBuffer;
export function typedCopyBytes(arr: ArrayBufferView, format: 'buffer'): Buffer;
export function typedCopyBytes(arr: ArrayBufferView, format: OutputCopyFormat): Uint8Array | ArrayBuffer | Buffer;
export function typedCopyBytes(arr: ArrayBufferView, format: OutputFormat): Uint8Array | ArrayBuffer | Buffer;
9 changes: 6 additions & 3 deletions base32.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,9 @@ export function toBase32crockford(arr: Uint8Array, options?: ToBase32Options): s
* @returns The decoded bytes
*/
export function fromBase32(string: string, options?: FromBase32Options & { format?: 'uint8' }): Uint8ArrayBuffer;
export function fromBase32(string: string, options: FromBase32Options & { format: 'arraybuffer' }): ArrayBuffer;
export function fromBase32(string: string, options: FromBase32Options & { format: 'buffer' }): Buffer;
export function fromBase32(string: string, options?: FromBase32Options): Uint8ArrayBuffer | Buffer;
export function fromBase32(string: string, options?: FromBase32Options): Uint8ArrayBuffer | ArrayBuffer | Buffer;

/**
* Decode a base32hex string to bytes
Expand All @@ -90,8 +91,9 @@ export function fromBase32(string: string, options?: FromBase32Options): Uint8Ar
* @returns The decoded bytes
*/
export function fromBase32hex(string: string, options?: FromBase32Options & { format?: 'uint8' }): Uint8ArrayBuffer;
export function fromBase32hex(string: string, options: FromBase32Options & { format: 'arraybuffer' }): ArrayBuffer;
export function fromBase32hex(string: string, options: FromBase32Options & { format: 'buffer' }): Buffer;
export function fromBase32hex(string: string, options?: FromBase32Options): Uint8ArrayBuffer | Buffer;
export function fromBase32hex(string: string, options?: FromBase32Options): Uint8ArrayBuffer | ArrayBuffer | Buffer;

/**
* Decode a Crockford base32 string to bytes
Expand All @@ -105,5 +107,6 @@ export function fromBase32hex(string: string, options?: FromBase32Options): Uint
* @returns The decoded bytes
*/
export function fromBase32crockford(string: string, options?: FromBase32Options & { format?: 'uint8' }): Uint8ArrayBuffer;
export function fromBase32crockford(string: string, options: FromBase32Options & { format: 'arraybuffer' }): ArrayBuffer;
export function fromBase32crockford(string: string, options: FromBase32Options & { format: 'buffer' }): Buffer;
export function fromBase32crockford(string: string, options?: FromBase32Options): Uint8ArrayBuffer | Buffer;
export function fromBase32crockford(string: string, options?: FromBase32Options): Uint8ArrayBuffer | ArrayBuffer | Buffer;
6 changes: 4 additions & 2 deletions base58.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,9 @@ export function toBase58(arr: Uint8Array): string;
* @returns The decoded bytes
*/
export function fromBase58(string: string, format?: 'uint8'): Uint8ArrayBuffer;
export function fromBase58(string: string, format: 'arraybuffer'): ArrayBuffer;
export function fromBase58(string: string, format: 'buffer'): Buffer;
export function fromBase58(string: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
export function fromBase58(string: string, format?: OutputFormat): Uint8ArrayBuffer | ArrayBuffer | Buffer;

/**
* Encode a `Uint8Array` to a base58 string using XRP alphabet
Expand All @@ -58,5 +59,6 @@ export function toBase58xrp(arr: Uint8Array): string;
* @returns The decoded bytes
*/
export function fromBase58xrp(string: string, format?: 'uint8'): Uint8ArrayBuffer;
export function fromBase58xrp(string: string, format: 'arraybuffer'): ArrayBuffer;
export function fromBase58xrp(string: string, format: 'buffer'): Buffer;
export function fromBase58xrp(string: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
export function fromBase58xrp(string: string, format?: OutputFormat): Uint8ArrayBuffer | ArrayBuffer | Buffer;
12 changes: 8 additions & 4 deletions base58check.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,9 @@ export interface Base58CheckAsync {
* @returns A Promise that resolves to the decoded bytes
*/
decode(string: string, format?: 'uint8'): Promise<Uint8ArrayBuffer>;
decode(string: string, format: 'arraybuffer'): Promise<ArrayBuffer>;
decode(string: string, format: 'buffer'): Promise<Buffer>;
decode(string: string, format?: OutputFormat): Promise<Uint8ArrayBuffer | Buffer>;
decode(string: string, format?: OutputFormat): Promise<Uint8ArrayBuffer | ArrayBuffer | Buffer>;
}

/**
Expand All @@ -70,8 +71,9 @@ export interface Base58CheckSync extends Base58CheckAsync {
* @returns The decoded bytes
*/
decodeSync(string: string, format?: 'uint8'): Uint8ArrayBuffer;
decodeSync(string: string, format: 'arraybuffer'): ArrayBuffer;
decodeSync(string: string, format: 'buffer'): Buffer;
decodeSync(string: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
decodeSync(string: string, format?: OutputFormat): Uint8ArrayBuffer | ArrayBuffer | Buffer;
}

/**
Expand Down Expand Up @@ -104,8 +106,9 @@ export function toBase58check(arr: Uint8Array): Promise<string>;
* @returns A Promise that resolves to the decoded bytes
*/
export function fromBase58check(string: string, format?: 'uint8'): Promise<Uint8ArrayBuffer>;
export function fromBase58check(string: string, format: 'arraybuffer'): Promise<ArrayBuffer>;
export function fromBase58check(string: string, format: 'buffer'): Promise<Buffer>;
export function fromBase58check(string: string, format?: OutputFormat): Promise<Uint8ArrayBuffer | Buffer>;
export function fromBase58check(string: string, format?: OutputFormat): Promise<Uint8ArrayBuffer | ArrayBuffer | Buffer>;

/**
* Encode bytes to base58check string synchronously
Expand All @@ -127,5 +130,6 @@ export function toBase58checkSync(arr: Uint8Array): string;
* @returns The decoded bytes
*/
export function fromBase58checkSync(string: string, format?: 'uint8'): Uint8ArrayBuffer;
export function fromBase58checkSync(string: string, format: 'arraybuffer'): ArrayBuffer;
export function fromBase58checkSync(string: string, format: 'buffer'): Buffer;
export function fromBase58checkSync(string: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
export function fromBase58checkSync(string: string, format?: OutputFormat): Uint8ArrayBuffer | ArrayBuffer | Buffer;
9 changes: 6 additions & 3 deletions base64.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,8 +69,9 @@ export function toBase64url(arr: Uint8Array, options?: ToBase64Options): string;
* @returns The decoded bytes
*/
export function fromBase64(string: string, options?: FromBase64Options & { format?: 'uint8' }): Uint8ArrayBuffer;
export function fromBase64(string: string, options: FromBase64Options & { format: 'arraybuffer' }): ArrayBuffer;
export function fromBase64(string: string, options: FromBase64Options & { format: 'buffer' }): Buffer;
export function fromBase64(string: string, options?: FromBase64Options): Uint8ArrayBuffer | Buffer;
export function fromBase64(string: string, options?: FromBase64Options): Uint8ArrayBuffer | ArrayBuffer | Buffer;

/**
* Decode a base64url string to bytes
Expand All @@ -82,8 +83,9 @@ export function fromBase64(string: string, options?: FromBase64Options): Uint8Ar
* @returns The decoded bytes
*/
export function fromBase64url(string: string, options?: FromBase64Options & { format?: 'uint8' }): Uint8ArrayBuffer;
export function fromBase64url(string: string, options: FromBase64Options & { format: 'arraybuffer' }): ArrayBuffer;
export function fromBase64url(string: string, options: FromBase64Options & { format: 'buffer' }): Buffer;
export function fromBase64url(string: string, options?: FromBase64Options): Uint8ArrayBuffer | Buffer;
export function fromBase64url(string: string, options?: FromBase64Options): Uint8ArrayBuffer | ArrayBuffer | Buffer;

/**
* Decode either base64 or base64url string to bytes
Expand All @@ -95,5 +97,6 @@ export function fromBase64url(string: string, options?: FromBase64Options): Uint
* @returns The decoded bytes
*/
export function fromBase64any(string: string, options?: FromBase64Options & { format?: 'uint8' }): Uint8ArrayBuffer;
export function fromBase64any(string: string, options: FromBase64Options & { format: 'arraybuffer' }): ArrayBuffer;
export function fromBase64any(string: string, options: FromBase64Options & { format: 'buffer' }): Buffer;
export function fromBase64url(string: string, options?: FromBase64Options): Uint8ArrayBuffer | Buffer;
export function fromBase64url(string: string, options?: FromBase64Options): Uint8ArrayBuffer | ArrayBuffer | Buffer;
3 changes: 2 additions & 1 deletion bigint.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,9 @@ export interface FromBigIntOptions {
* @returns The converted bytes in big-endian format
*/
export function fromBigInt(bigint: bigint, options: { length: number; format?: 'uint8' }): Uint8ArrayBuffer;
export function fromBigInt(bigint: bigint, options: { length: number; format: 'arraybuffer' }): ArrayBuffer;
export function fromBigInt(bigint: bigint, options: { length: number; format: 'buffer' }): Buffer;
export function fromBigInt(bigint: bigint, options: FromBigIntOptions): Uint8ArrayBuffer | Buffer;
export function fromBigInt(bigint: bigint, options: FromBigIntOptions): Uint8ArrayBuffer | ArrayBuffer | Buffer;

/**
* Convert a Uint8Array or Buffer to a BigInt
Expand Down
5 changes: 5 additions & 0 deletions fallback/_utils.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ export function fromUint8(arr, format) {
case 'uint8':
if (arr.constructor !== Uint8Array) throw new Error('Unexpected')
return arr
case 'arraybuffer':
if (arr.byteLength !== arr.buffer.byteLength) throw new Error('Unexpected')
return arr.buffer
case 'buffer':
if (arr.length <= 64) return Buffer.from(arr)
return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength)
Expand All @@ -43,6 +46,8 @@ export function fromBuffer(arr, format) {
}

return new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength)
case 'arraybuffer':
return fromBuffer(arr, 'uint8').buffer
case 'buffer':
if (arr.constructor !== Buffer) throw new Error('Unexpected')
return arr
Expand Down
3 changes: 2 additions & 1 deletion hex.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,5 +31,6 @@ export function toHex(arr: Uint8Array): string;
* @returns The decoded bytes
*/
export function fromHex(string: string, format?: 'uint8'): Uint8ArrayBuffer;
export function fromHex(string: string, format: 'arraybuffer'): ArrayBuffer;
export function fromHex(string: string, format: 'buffer'): Buffer;
export function fromHex(string: string, format?: OutputFormat): Uint8ArrayBuffer | Buffer;
export function fromHex(string: string, format?: OutputFormat): Uint8ArrayBuffer | ArrayBuffer | Buffer;
17 changes: 14 additions & 3 deletions tests/base32.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,9 @@ const pool = raw.map((uint8) => {
const hex = buffer.toString('hex')
const shared = new Uint8Array(new SharedArrayBuffer(uint8.length))
shared.set(uint8)
return { uint8, shared, buffer, hex, base32, base32padded, base32hex, base32hexPadded }
const ab = uint8.buffer
if (ab.byteLength !== uint8.byteLength) throw new Error('Unexpected pooled Uint8Array')
return { uint8, ab, shared, buffer, hex, base32, base32padded, base32hex, base32hexPadded }
})

describe('toBase32', () => {
Expand Down Expand Up @@ -110,7 +112,7 @@ describe('fromBase32', () => {
t.assert.throws(() => fromBase32hex(input.toUpperCase()))
t.assert.throws(() => fromBase32(input.toLowerCase()))
t.assert.throws(() => fromBase32hex(input.toLowerCase()))
for (const format of ['uint8', 'buffer', 'hex']) {
for (const format of ['uint8', 'buffer', 'arraybuffer', 'hex']) {
t.assert.throws(() => fromBase32(input, { format }))
t.assert.throws(() => fromBase32hex(input, { format }))
}
Expand Down Expand Up @@ -145,9 +147,18 @@ describe('fromBase32', () => {
})

test('buffer', (t) => {
for (const { base32, base32hex, buffer } of pool) {
for (const { base32, base32padded, base32hex, buffer } of pool) {
t.assert.deepStrictEqual(fromBase32(base32, { format: 'buffer' }), buffer)
t.assert.deepStrictEqual(fromBase32(base32padded, { format: 'buffer' }), buffer)
t.assert.deepStrictEqual(fromBase32hex(base32hex, { format: 'buffer' }), buffer)
}
})

test('arraybuffer', (t) => {
for (const { base32, base32padded, base32hex, ab } of pool) {
t.assert.deepStrictEqual(fromBase32(base32, { format: 'arraybuffer' }), ab)
t.assert.deepStrictEqual(fromBase32(base32padded, { format: 'arraybuffer' }), ab)
t.assert.deepStrictEqual(fromBase32hex(base32hex, { format: 'arraybuffer' }), ab)
}
})
})
6 changes: 5 additions & 1 deletion tests/base58.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,18 +134,22 @@ test('sizes roundtrip, static data + types', (t) => {
const zerosBase58 = toBase58(zeros)
t.assert.deepStrictEqual(fromBase58(zerosBase58), zeros, `[0] x${size}`)
t.assert.deepStrictEqual(fromBase58(zerosBase58, 'buffer'), Buffer.from(zeros))
t.assert.deepStrictEqual(fromBase58(zerosBase58, 'arraybuffer'), zeros.buffer)
const ones = new Uint8Array(size).fill(1)
const onesBase58 = toBase58(ones)
t.assert.deepStrictEqual(fromBase58(onesBase58), ones, `[1] x${size}`)
t.assert.deepStrictEqual(fromBase58(onesBase58, 'buffer'), Buffer.from(ones))
t.assert.deepStrictEqual(fromBase58(onesBase58, 'arraybuffer'), ones.buffer)
const mid = new Uint8Array(size).fill(42)
const midBase58 = toBase58(mid)
t.assert.deepStrictEqual(fromBase58(midBase58), mid, `[42] x${size}`)
t.assert.deepStrictEqual(fromBase58(midBase58, 'buffer'), Buffer.from(mid))
t.assert.deepStrictEqual(fromBase58(midBase58, 'arraybuffer'), mid.buffer)
const max = new Uint8Array(size).fill(255)
const maxBase58 = toBase58(max)
t.assert.deepStrictEqual(fromBase58(maxBase58), max, `[255] x${size}`)
t.assert.deepStrictEqual(fromBase58(maxBase58, 'buffer'), Buffer.from(max))
t.assert.deepStrictEqual(fromBase58(maxBase58, 'arraybuffer'), max.buffer)
}
})

Expand Down Expand Up @@ -191,7 +195,7 @@ test('fromBase58 returns non-pooled Uint8Array instances', (t) => {
t.assert.ok(tracked.length > 1000)

for (const u8 of tracked) {
if (Buffer.isBuffer(u8)) continue
if (Buffer.isBuffer(u8) || u8 instanceof ArrayBuffer) continue
t.assert.strictEqual(u8.byteLength, u8.buffer.byteLength)
}
})
6 changes: 5 additions & 1 deletion tests/base58check.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,18 +47,22 @@ test('sizes roundtrip, static data + types', (t) => {
const zerosBase58check = toBase58checkSync(zeros)
t.assert.deepStrictEqual(fromBase58checkSync(zerosBase58check), zeros, `[0] x${size}`)
t.assert.deepStrictEqual(fromBase58checkSync(zerosBase58check, 'buffer'), Buffer.from(zeros))
t.assert.deepStrictEqual(fromBase58checkSync(zerosBase58check, 'arraybuffer'), zeros.buffer)
const ones = new Uint8Array(size).fill(1)
const onesBase58check = toBase58checkSync(ones)
t.assert.deepStrictEqual(fromBase58checkSync(onesBase58check), ones, `[1] x${size}`)
t.assert.deepStrictEqual(fromBase58checkSync(onesBase58check, 'buffer'), Buffer.from(ones))
t.assert.deepStrictEqual(fromBase58checkSync(onesBase58check, 'arraybuffer'), ones.buffer)
const mid = new Uint8Array(size).fill(42)
const midBase58check = toBase58checkSync(mid)
t.assert.deepStrictEqual(fromBase58checkSync(midBase58check), mid, `[42] x${size}`)
t.assert.deepStrictEqual(fromBase58checkSync(midBase58check, 'buffer'), Buffer.from(mid))
t.assert.deepStrictEqual(fromBase58checkSync(midBase58check, 'arraybuffer'), mid.buffer)
const max = new Uint8Array(size).fill(255)
const maxBase58check = toBase58checkSync(max)
t.assert.deepStrictEqual(fromBase58checkSync(maxBase58check), max, `[255] x${size}`)
t.assert.deepStrictEqual(fromBase58checkSync(maxBase58check, 'buffer'), Buffer.from(max))
t.assert.deepStrictEqual(fromBase58checkSync(maxBase58check, 'arraybuffer'), max.buffer)
}
})

Expand Down Expand Up @@ -104,7 +108,7 @@ test('fromBase58check returns non-pooled Uint8Array instances', (t) => {
t.assert.ok(tracked.length > 1000)

for (const u8 of tracked) {
if (Buffer.isBuffer(u8)) continue
if (Buffer.isBuffer(u8) || u8 instanceof ArrayBuffer) continue
t.assert.strictEqual(u8.byteLength, u8.buffer.byteLength)
}
})
13 changes: 11 additions & 2 deletions tests/base64.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,9 @@ const pool = raw.map((uint8) => {
const hex = buffer.toString('hex')
const shared = new Uint8Array(new SharedArrayBuffer(uint8.length))
shared.set(uint8)
return { uint8, shared, buffer, hex, base64, base64nopad, base64url, base64urlPadded }
const ab = uint8.buffer
if (ab.byteLength !== uint8.byteLength) throw new Error('Unexpected pooled Uint8Array')
return { uint8, ab, shared, buffer, hex, base64, base64nopad, base64url, base64urlPadded }
})

describe('toBase64', () => {
Expand Down Expand Up @@ -114,7 +116,7 @@ describe('fromBase64', () => {
]) {
t.assert.throws(() => fromBase64(input))
t.assert.throws(() => fromBase64url(input))
for (const format of ['uint8', 'buffer', 'hex']) {
for (const format of ['uint8', 'arraybuffer', 'buffer', 'hex']) {
t.assert.throws(() => fromBase64(input, { format }))
t.assert.throws(() => fromBase64url(input, { format }))
}
Expand Down Expand Up @@ -162,6 +164,13 @@ describe('fromBase64', () => {
}
})

test('arraybuffer', (t) => {
for (const { base64, base64url, ab } of pool) {
t.assert.deepStrictEqual(fromBase64(base64, { format: 'arraybuffer' }), ab)
t.assert.deepStrictEqual(fromBase64url(base64url, { format: 'arraybuffer' }), ab)
}
})

test('fallback', (t) => {
for (const { base64, base64nopad, base64url, base64urlPadded, uint8 } of pool) {
t.assert.deepStrictEqual(js.fromBase64(base64, false), uint8)
Expand Down
Loading