Merge pull request #153 from msgpack/example-decode-stream

add tests and examples to decode multi-value MessagePack binaries with decodeStream()

Author: gfx

README.md

@@ -57,7 +57,7 @@ deepStrictEqual(decode(encoded), object);
 - [Decoding a Blob](#decoding-a-blob)
 - [MessagePack Specification](#messagepack-specification)
   - [MessagePack Mapping Table](#messagepack-mapping-table)
-- [Prerequsites](#prerequsites)
+- [Prerequisites](#prerequisites)
   - [ECMA-262](#ecma-262)
   - [NodeJS](#nodejs)
   - [TypeScript](#typescript)
@@ -215,6 +215,22 @@ for await (const item of decodeStream(stream)) {
 }
 ```
 
+If you have a multi-values MessagePack binary, you can use `decodeStream()`, but you need to convert it to a stream or an async generator like this:
+
+```typescript
+// A function that generates an AsyncGenerator
+const createStream = async function* (): AsyncGenerator<Uint8Array> {
+  yield encoded;
+};
+
+const result: Array<unknown> = [];
+
+// Decodes it with for-await
+for await (const item of decodeStream(createStream())) {
+  result.push(item);
+}
+```
+
 ### Reusing Encoder and Decoder instances
 
 `Encoder` and `Decoder` classes is provided for better performance:
@@ -461,7 +477,7 @@ Date|timestamp ext family|Date (*4)
 * *3 In handling `Object`, it is regarded as `Record<string, unknown>` in terms of TypeScript
 * *4 MessagePack timestamps may have nanoseconds, which will lost when it is decoded into JavaScript `Date`. This behavior can be overridden by registering `-1` for the extension codec.
 
-## Prerequsites
+## Prerequisites
 
 This is a universal JavaScript library that supports major browsers and NodeJS.
 

test/decodeStream.test.ts

@@ -2,7 +2,7 @@ import assert from "assert";
 import { encode, decodeStream } from "@msgpack/msgpack";
 
 describe("decodeStream", () => {
-  it("decodes stream (array8)", async () => {
+  it("decodes stream", async () => {
     const items = [
       "foo",
       10,
@@ -12,7 +12,7 @@ describe("decodeStream", () => {
       [1, 2, 3],
     ];
 
-    const createStream = async function* () {
+    const createStream = async function* (): AsyncGenerator<Uint8Array> {
       for (const item of items) {
         yield encode(item);
       }
@@ -26,4 +26,35 @@ describe("decodeStream", () => {
 
     assert.deepStrictEqual(result, items);
   });
+
+  it("decodes stream with a single binary", async () => {
+    const items = [
+      "foo",
+      10,
+      {
+        name: "bar",
+      },
+      [1, 2, 3],
+    ];
+
+    const encodedItems = items.map((item) => encode(item));
+    const encoded = new Uint8Array(encodedItems.reduce((p, c) => p + c.byteLength, 0));
+    let offset = 0;
+    for (const encodedItem of encodedItems) {
+      encoded.set(encodedItem, offset);
+      offset += encodedItem.byteLength;
+    }
+
+    const createStream = async function* (): AsyncGenerator<Uint8Array> {
+      yield encoded;
+    };
+
+    const result: Array<unknown> = [];
+
+    for await (const item of decodeStream(createStream())) {
+      result.push(item);
+    }
+
+    assert.deepStrictEqual(result, items);
+  });
 });