Merge pull request #209 from msgpack/clarify_empty_input

[doc] clarify the edge cases where the input buffer is empty

.eslintrc.js

@@ -15,7 +15,8 @@ module.exports = {
     "prettier",
   ],
   plugins: [
-    "@typescript-eslint",
+    "@typescript-eslint/eslint-plugin",
+    "eslint-plugin-tsdoc"
   ],
   parser: "@typescript-eslint/parser",
   parserOptions: {
@@ -38,6 +39,8 @@ module.exports = {
     "import/no-cycle": "error",
     "import/no-default-export": "warn",
 
+    "tsdoc/syntax": "warn",
+
     "@typescript-eslint/await-thenable": "warn",
     "@typescript-eslint/array-type": ["warn", { default: "generic" }],
     "@typescript-eslint/naming-convention": [

.vscode/settings.json

@@ -4,5 +4,8 @@
   "editor.tabSize": 2,
   "editor.codeActionsOnSave": {
     "source.fixAll.eslint": true
-  }
+  },
+  "cSpell.words": [
+    "tsdoc"
+  ]
 }

package.json

@@ -67,6 +67,7 @@
     "eslint": "latest",
     "eslint-config-prettier": "latest",
     "eslint-plugin-import": "latest",
+    "eslint-plugin-tsdoc": "latest",
     "ieee754": "latest",
     "karma": "latest",
     "karma-chrome-launcher": "latest",

src/Decoder.ts

@@ -118,8 +118,8 @@ export class Decoder<ContextType = undefined> {
   }
 
   /**
-   * @throws {DecodeError}
-   * @throws {RangeError}
+   * @throws {@link DecodeError}
+   * @throws {@link RangeError}
    */
   public decode(buffer: ArrayLike<number> | BufferSource): unknown {
     this.reinitializeState();

src/decode.ts

@@ -47,6 +47,9 @@ export const defaultDecodeOptions: DecodeOptions = {};
  *
  * This is a synchronous decoding function.
  * See other variants for asynchronous decoding: {@link decodeAsync()}, {@link decodeStream()}, or {@link decodeArrayStream()}.
+ *
+ * @throws {@link RangeError} if the buffer is incomplete, including the case where the buffer is empty.
+ * @throws {@link DecodeError} if the buffer contains invalid data.
  */
 export function decode<ContextType = undefined>(
   buffer: ArrayLike<number> | BufferSource,
@@ -67,6 +70,9 @@ export function decode<ContextType = undefined>(
 /**
  * It decodes multiple MessagePack objects in a buffer.
  * This is corresponding to {@link decodeMultiStream()}.
+ *
+ * @throws {@link RangeError} if the buffer is incomplete, including the case where the buffer is empty.
+ * @throws {@link DecodeError} if the buffer contains invalid data.
  */
 export function decodeMulti<ContextType = undefined>(
   buffer: ArrayLike<number> | BufferSource,

src/decodeAsync.ts

@@ -5,7 +5,11 @@ import type { ReadableStreamLike } from "./utils/stream";
 import type { DecodeOptions } from "./decode";
 import type { SplitUndefined } from "./context";
 
-export async function decodeAsync<ContextType>(
+/**
+ * @throws {@link RangeError} if the buffer is incomplete, including the case where the buffer is empty.
+ * @throws {@link DecodeError} if the buffer contains invalid data.
+ */
+ export async function decodeAsync<ContextType>(
   streamLike: ReadableStreamLike<ArrayLike<number> | BufferSource>,
   options: DecodeOptions<SplitUndefined<ContextType>> = defaultDecodeOptions as any,
 ): Promise<unknown> {
@@ -23,7 +27,11 @@ export async function decodeAsync<ContextType>(
   return decoder.decodeAsync(stream);
 }
 
-export function decodeArrayStream<ContextType>(
+/**
+ * @throws {@link RangeError} if the buffer is incomplete, including the case where the buffer is empty.
+ * @throws {@link DecodeError} if the buffer contains invalid data.
+ */
+ export function decodeArrayStream<ContextType>(
   streamLike: ReadableStreamLike<ArrayLike<number> | BufferSource>,
   options: DecodeOptions<SplitUndefined<ContextType>> = defaultDecodeOptions as any,
 ): AsyncGenerator<unknown, void, unknown> {
@@ -42,6 +50,10 @@ export function decodeArrayStream<ContextType>(
   return decoder.decodeArrayStream(stream);
 }
 
+/**
+ * @throws {@link RangeError} if the buffer is incomplete, including the case where the buffer is empty.
+ * @throws {@link DecodeError} if the buffer contains invalid data.
+ */
 export function decodeMultiStream<ContextType>(
   streamLike: ReadableStreamLike<ArrayLike<number> | BufferSource>,
   options: DecodeOptions<SplitUndefined<ContextType>> = defaultDecodeOptions as any,

test/edge-cases.test.ts

@@ -1,7 +1,7 @@
 // kind of hand-written fuzzing data
 // any errors should not break Encoder/Decoder instance states
 import assert from "assert";
-import { encode, decode, Encoder, Decoder } from "../src";
+import { encode, decodeAsync, decode, Encoder, Decoder } from "../src";
 import { DataViewIndexOutOfBoundsError } from "../src/Decoder";
 
 function testEncoder(encoder: Encoder): void {
@@ -147,4 +147,22 @@ describe("edge cases", () => {
       testDecoder(decoder);
     });
   });
+
+  context("try to decode an empty input", () => {
+    it("throws RangeError (synchronous)", () => {
+      assert.throws(() => {
+        decode([]);
+      }, RangeError);
+    });
+
+    it("throws RangeError (asynchronous)", async () => {
+      const createStream = async function* () {
+        yield [];
+      };
+
+      assert.rejects(async () => {
+        await decodeAsync(createStream());
+      }, RangeError);
+    });
+  });
 });