Merge pull request #155 from msgpack/buffer-source

fix: make decodeAsync(), decodeStream(), and decodeArrayStream() to take BufferSource

Author: gfx

README.md

@@ -45,11 +45,11 @@ deepStrictEqual(decode(encoded), object);
 - [API](#api)
   - [`encode(data: unknown, options?: EncodeOptions): Uint8Array`](#encodedata-unknown-options-encodeoptions-uint8array)
     - [`EncodeOptions`](#encodeoptions)
-  - [`decode(buffer: ArrayLike<number> | ArrayBuffer, options?: DecodeOptions): unknown`](#decodebuffer-arraylikenumber--arraybuffer-options-decodeoptions-unknown)
+  - [`decode(buffer: ArrayLike<number> | BufferSource, options?: DecodeOptions): unknown`](#decodebuffer-arraylikenumber--buffersource-options-decodeoptions-unknown)
     - [`DecodeOptions`](#decodeoptions)
-  - [`decodeAsync(stream: AsyncIterable<ArrayLike<number>> | ReadableStream<ArrayLike<number>>, options?: DecodeAsyncOptions): Promise<unknown>`](#decodeasyncstream-asynciterablearraylikenumber--readablestreamarraylikenumber-options-decodeasyncoptions-promiseunknown)
-  - [`decodeArrayStream(stream: AsyncIterable<ArrayLike<number>> | ReadableStream<ArrayLike<number>>, options?: DecodeAsyncOptions): AsyncIterable<unknown>`](#decodearraystreamstream-asynciterablearraylikenumber--readablestreamarraylikenumber-options-decodeasyncoptions-asynciterableunknown)
-  - [`decodeStream(stream: AsyncIterable<ArrayLike<number>> | ReadableStream<ArrayLike<number>>, options?: DecodeAsyncOptions): AsyncIterable<unknown>`](#decodestreamstream-asynciterablearraylikenumber--readablestreamarraylikenumber-options-decodeasyncoptions-asynciterableunknown)
+  - [`decodeAsync(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecodeAsyncOptions): Promise<unknown>`](#decodeasyncstream-readablestreamlikearraylikenumber--buffersource-options-decodeasyncoptions-promiseunknown)
+  - [`decodeArrayStream(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecodeAsyncOptions): AsyncIterable<unknown>`](#decodearraystreamstream-readablestreamlikearraylikenumber--buffersource-options-decodeasyncoptions-asynciterableunknown)
+  - [`decodeStream(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecodeAsyncOptions): AsyncIterable<unknown>`](#decodestreamstream-readablestreamlikearraylikenumber--buffersource-options-decodeasyncoptions-asynciterableunknown)
   - [Reusing Encoder and Decoder instances](#reusing-encoder-and-decoder-instances)
 - [Extension Types](#extension-types)
     - [ExtensionCodec context](#extensioncodec-context)
@@ -123,11 +123,11 @@ forceIntegerToFloat | boolean | false
 ignoreUndefined | boolean | false
 context | user-defined | -
 
-### `decode(buffer: ArrayLike<number> | ArrayBuffer, options?: DecodeOptions): unknown`
+### `decode(buffer: ArrayLike<number> | BufferSource, options?: DecodeOptions): unknown`
 
 It decodes `buffer` encoded in MessagePack, and returns a decoded object as `unknown`.
 
-`buffer` must be an array of bytes, which is typically `Uint8Array` or `ArrayBuffer`, but `Array<number>` is okay.
+`buffer` must be an array of bytes, which is typically `Uint8Array` or `ArrayBuffer`. `BufferSource` is defined as `ArrayBuffer | ArrayBufferView`.
 
 for example:
 
@@ -145,7 +145,7 @@ NodeJS `Buffer` is also acceptable because it is a subclass of `Uint8Array`.
 
 Name|Type|Default
 ----|----|----
-extensionCodec | ExtensionCodec | `ExtensinCodec.defaultCodec`
+extensionCodec | ExtensionCodec | `ExtensionCodec.defaultCodec`
 maxStrLength | number | `4_294_967_295` (UINT32_MAX)
 maxBinLength | number | `4_294_967_295` (UINT32_MAX)
 maxArrayLength | number | `4_294_967_295` (UINT32_MAX)
@@ -155,9 +155,9 @@ context | user-defined | -
 
 You can use `max${Type}Length` to limit the length of each type decoded.
 
-### `decodeAsync(stream: AsyncIterable<ArrayLike<number>> | ReadableStream<ArrayLike<number>>, options?: DecodeAsyncOptions): Promise<unknown>`
+### `decodeAsync(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecodeAsyncOptions): Promise<unknown>`
 
-It decodes `stream` in an async iterable of byte arrays, and returns decoded object as `uknown` type, wrapped in `Promise`. This function works asyncronously.
+It decodes `stream`, where `ReadableStreamLike<T>` is defined as `ReadableStream<T> | AsyncIterable<T>`, in an async iterable of byte arrays, and returns decoded object as `unknown` type, wrapped in `Promise`. This function works asynchronously.
 
 `DecodeAsyncOptions` is the same as `DecodeOptions` for `decode()`.
 
@@ -176,7 +176,7 @@ if (contentType && contentType.startsWith(MSGPACK_TYPE) && response.body != null
 } else { /* handle errors */ }
 ```
 
-### `decodeArrayStream(stream: AsyncIterable<ArrayLike<number>> | ReadableStream<ArrayLike<number>>, options?: DecodeAsyncOptions): AsyncIterable<unknown>`
+### `decodeArrayStream(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecodeAsyncOptions): AsyncIterable<unknown>`
 
 It is alike to `decodeAsync()`, but only accepts an array of items as the input `stream`, and emits the decoded item one by one.
 
@@ -196,7 +196,7 @@ for await (const item of decodeArrayStream(stream)) {
 ```
 
 
-### `decodeStream(stream: AsyncIterable<ArrayLike<number>> | ReadableStream<ArrayLike<number>>, options?: DecodeAsyncOptions): AsyncIterable<unknown>`
+### `decodeStream(stream: ReadableStreamLike<ArrayLike<number> | BufferSource>, options?: DecodeAsyncOptions): AsyncIterable<unknown>`
 
 It is alike to `decodeAsync()` and `decodeArrayStream()`, but the input `stream` consists of independent MessagePack items.
 

src/Decoder.ts

@@ -85,13 +85,13 @@ export class Decoder<ContextType> {
     this.headByte = HEAD_BYTE_REQUIRED;
   }
 
-  private setBuffer(buffer: ArrayLike<number> | ArrayBuffer): void {
+  private setBuffer(buffer: ArrayLike<number> | BufferSource): void {
     this.bytes = ensureUint8Array(buffer);
     this.view = createDataView(this.bytes);
     this.pos = 0;
   }
 
-  private appendBuffer(buffer: ArrayLike<number>) {
+  private appendBuffer(buffer: ArrayLike<number> | BufferSource) {
     if (this.headByte === HEAD_BYTE_REQUIRED && !this.hasRemaining()) {
       this.setBuffer(buffer);
     } else {
@@ -114,7 +114,7 @@ export class Decoder<ContextType> {
     return new RangeError(`Extra ${view.byteLength - pos} of ${view.byteLength} byte(s) found at buffer[${posToShow}]`);
   }
 
-  public decode(buffer: ArrayLike<number> | ArrayBuffer): unknown {
+  public decode(buffer: ArrayLike<number> | BufferSource): unknown {
     this.reinitializeState();
     this.setBuffer(buffer);
 
@@ -125,7 +125,7 @@ export class Decoder<ContextType> {
     return object;
   }
 
-  public async decodeAsync(stream: AsyncIterable<ArrayLike<number>>): Promise<unknown> {
+  public async decodeAsync(stream: AsyncIterable<ArrayLike<number> | BufferSource>): Promise<unknown> {
     let decoded = false;
     let object: unknown;
     for await (const buffer of stream) {
@@ -160,15 +160,15 @@ export class Decoder<ContextType> {
     );
   }
 
-  public decodeArrayStream(stream: AsyncIterable<ArrayLike<number>>) {
+  public decodeArrayStream(stream: AsyncIterable<ArrayLike<number> | BufferSource>) {
     return this.decodeMultiAsync(stream, true);
   }
 
-  public decodeStream(stream: AsyncIterable<ArrayLike<number>>) {
+  public decodeStream(stream: AsyncIterable<ArrayLike<number> | BufferSource>) {
     return this.decodeMultiAsync(stream, false);
   }
 
-  private async *decodeMultiAsync(stream: AsyncIterable<ArrayLike<number>>, isArray: boolean) {
+  private async *decodeMultiAsync(stream: AsyncIterable<ArrayLike<number> | BufferSource>, isArray: boolean) {
     let isArrayHeaderRequired = isArray;
     let arrayItemsLeft = -1;
 

src/decode.ts

@@ -43,7 +43,7 @@ export const defaultDecodeOptions: DecodeOptions = {};
  * This is a synchronous decoding function. See other variants for asynchronous decoding: `decodeAsync()`, `decodeStream()`, `decodeArrayStream()`.
  */
 export function decode<ContextType = undefined>(
-  buffer: ArrayLike<number> | ArrayBuffer,
+  buffer: ArrayLike<number> | BufferSource,
   options: DecodeOptions<SplitUndefined<ContextType>> = defaultDecodeOptions as any,
 ): unknown {
   const decoder = new Decoder(

src/decodeAsync.ts

@@ -1,10 +1,12 @@
 import { Decoder } from "./Decoder";
-import { defaultDecodeOptions, DecodeOptions } from "./decode";
-import { ensureAsyncIterable, ReadableStreamLike } from "./utils/stream";
-import { SplitUndefined } from "./context";
+import { ensureAsyncIterable } from "./utils/stream";
+import { defaultDecodeOptions } from "./decode";
+import type { ReadableStreamLike } from "./utils/stream";
+import type { DecodeOptions } from "./decode";
+import type { SplitUndefined } from "./context";
 
 export async function decodeAsync<ContextType>(
-  streamLike: ReadableStreamLike<ArrayLike<number>>,
+  streamLike: ReadableStreamLike<ArrayLike<number> | BufferSource>,
   options: DecodeOptions<SplitUndefined<ContextType>> = defaultDecodeOptions as any,
 ): Promise<unknown> {
   const stream = ensureAsyncIterable(streamLike);
@@ -22,7 +24,7 @@ export async function decodeAsync<ContextType>(
 }
 
 export function decodeArrayStream<ContextType>(
-  streamLike: ReadableStreamLike<ArrayLike<number>>,
+  streamLike: ReadableStreamLike<ArrayLike<number> | BufferSource>,
   options: DecodeOptions<SplitUndefined<ContextType>> = defaultDecodeOptions as any,
 ) {
   const stream = ensureAsyncIterable(streamLike);
@@ -41,7 +43,7 @@ export function decodeArrayStream<ContextType>(
 }
 
 export function decodeStream<ContextType>(
-  streamLike: ReadableStreamLike<ArrayLike<number>>,
+  streamLike: ReadableStreamLike<ArrayLike<number> | BufferSource>,
   options: DecodeOptions<SplitUndefined<ContextType>> = defaultDecodeOptions as any,
 ) {
   const stream = ensureAsyncIterable(streamLike);

test/decodeAsync.test.ts

@@ -107,4 +107,17 @@ describe("decodeAsync", () => {
     };
     assert.deepStrictEqual(await decodeAsync(createStream()), object);
   });
+
+  it("decodes BufferSource", async () => {
+    // https://developer.mozilla.org/en-US/docs/Web/API/BufferSource
+    const createStream = async function* () {
+      yield [0x81] as ArrayLike<number>; // fixmap size=1
+      yield encode("foo") as BufferSource;
+      yield encode("bar") as BufferSource;
+    };
+
+    // createStream() returns AsyncGenerator<ArrayLike<number> | BufferSource, ...>
+    const object = await decodeAsync(createStream());
+    assert.deepStrictEqual(object, { "foo": "bar" });
+  });
 });