feat: support decoding ArrayBuffers

[achingbrain]

When using fetch to download something over HTTP, it only makes an ArrayBuffer available, not a Uint8Array.

TextDecoder supports decoding ArrayBuffers, and the raw codec already turns passed ArrayBuffers into Uint8Arrays so this is just a type change.

Instead of:

const res = await fetch('...')
const obj = json.decode(new Uint8Array(await res.arrayBuffer()))

we can do:

const res = await fetch('...')
const obj = json.decode(await res.arrayBuffer())

[SgtPooki]

just confirming that this is exported from index.ts:

js-multiformats/src/index.ts

Line 210 in aa9c730

export * from './interface.js'

and

js-multiformats/src/interface.ts

Lines 1 to 5 in aa9c730

	export * from './bases/interface.js'
	export * from './hashes/interface.js'
	export * from './codecs/interface.js'
	export * from './link/interface.js'
	export * from './block/interface.js'

[SgtPooki]

We are exporting this type twice from two separate files.

1. src/blocks/interface -> src/codecs/interface -> src/interface
2. src/blocks/interface -> src/interface

Do we need a central location or will TS handle that well?

[achingbrain]

TS handles it fine, but it makes linking to a canonical documentation location in generated TypeDocs a little more fiddly.

Ref: TypeStrong/typedoc#2125 and https://github.com/ipfs/aegir/blob/master/src/docs/type-indexer-plugin.js#L121-L128.

[SgtPooki]

do we want to update https://github.com/ipld/js-dag-json/blob/1e797391539237ab1738dbf60fe9d0a92278d88d/src/index.js#L249 and others as well?

[rvagg]

seems ok to me, the | makes it less elegant but I can't think of how you'd reduce that without making it really gnarly

[Gozala]

I personally prefer to keep interface as simple as possible and add all the sugar in the layers above that way not each implementation has to deal with the variability it’s just becomes only concern of the layer above which will handle across all codecs.

That said I don’t want to stand in the way of this if there’s a consensus around it.

P.S.: uint8array was chosen over array buffer because you can reference slice within buffer and you can’t do same with later without copying

[achingbrain]

the | makes it less elegant

You could make ByteView a union type, but that'd be a breaking change that doesn't seem worth the pain to me.

I personally prefer to keep interface as simple as possible and add all the sugar in the layers above

I agree with the design principle but here there is no layer above. The IPLD specs say to use these modules, yet we then force users to create extra Uint8Arrays which are superfluous since raw coerces the input to Uint8Array anyway, and json passes the input off to JSON.parse which supports both ArrayBuffers and Uint8Arrays.

uint8array was chosen over array buffer because you can reference slice within buffer and you can’t do same with later without copying

Not all codecs will need this but if they do it's simple enough to wrap the ArrayBuffer in a Uint8Array and use .subarray internally. The DX to require all users to do this seems arbitrary when it's potentially unnecessary.

That said I don’t want to stand in the way of this if there’s a consensus around it.

🙏

[github-actions]

🎉 This PR is included in version 13.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀