pkg: add Struct static types that can be extended.

bcoin-org · Oct 1, 2024 · 45467c7 · 45467c7
1 parent 5200d35
commit 45467c7
Show file tree

Hide file tree

Showing 4 changed files with 109 additions and 18 deletions.
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -1,19 +1,9 @@
 {
   "env": {
-    "es6": true,
+    "es2022": true,
     "node": true
   },
   "extends": "eslint:recommended",
-  "globals": {
-    "Atomics": "readable",
-    "BigInt": "readable",
-    "BigInt64Array": "readable",
-    "BigUint64Array": "readable",
-    "queueMicrotask": "readable",
-    "SharedArrayBuffer": "readable",
-    "TextEncoder": "readable",
-    "TextDecoder": "readable"
-  },
   "overrides": [
     {
       "files": ["*.mjs"],
@@ -44,9 +34,8 @@
       }
     }
   ],
-  "parser": "babel-eslint",
   "parserOptions": {
-    "ecmaVersion": 10,
+    "ecmaVersion": 13,
     "ecmaFeatures": {
       "globalReturn": true
     },

diff --git a/lib/bufio.js b/lib/bufio.js
@@ -23,16 +23,32 @@ exports.BufferWriter = BufferWriter;
 exports.StaticWriter = StaticWriter;
 exports.Struct = Struct;
 
+/**
+ * @param {Buffer} data
+ * @param {Boolean} [zeroCopy]
+ * @returns {BufferReader}
+ */
+
 exports.read = function read(data, zeroCopy) {
   return new BufferReader(data, zeroCopy);
 };
 
+/**
+ * @param {Number} [size]
+ * @returns {BufferWriter|StaticWriter}
+ */
+
 exports.write = function write(size) {
   return size != null
     ? new StaticWriter(size)
     : new BufferWriter();
 };
 
+/**
+ * @param {Number} size
+ * @returns {StaticWriter}
+ */
+
 exports.pool = function pool(size) {
   return StaticWriter.pool(size);
 };

diff --git a/lib/reader.js b/lib/reader.js
@@ -946,7 +946,7 @@ class BufferReader {
   /**
    * Read a string.
    * @param {Number} size
-   * @param {BufferEncoding} enc - Any buffer-supported encoding.
+   * @param {BufferEncoding?} [enc] - Any buffer-supported encoding.
    * @returns {String}
    */
 
@@ -968,7 +968,7 @@ class BufferReader {
 
   /**
    * Read a 32-byte hash.
-   * @param {BufferEncoding} enc - `"hex"` or `null`.
+   * @param {BufferEncoding} [enc] - `"hex"` or `null`.
    * @returns {Buffer|String}
    */
 

diff --git a/lib/struct.js b/lib/struct.js
@@ -129,10 +129,11 @@ class Struct {
   }
 
   /**
+   * @param {*} [extra]
    * @returns {*}
    */
 
-  format() {
+  format(extra) {
     return this.getJSON();
   }
 
@@ -239,34 +240,98 @@ class Struct {
    * Static API
    */
 
+  /**
+   * @template {Struct} T
+   * @this {new (...args: any[]) => T}
+   * @param {BufferReader} br
+   * @param {*} [extra]
+   * @returns {T}
+   */
+
   static read(br, extra) {
     return new this().read(br, extra);
   }
 
+  /**
+   * @template {Struct} T
+   * @this {new (...args: any[]) => T}
+   * @param {Buffer} data
+   * @param {*} [extra]
+   * @returns {T}
+   */
+
   static decode(data, extra) {
     return new this().decode(data, extra);
   }
 
+  /**
+   * @template {Struct} T
+   * @this {new (...args: any[]) => T}
+   * @param {String} str
+   * @param {*} [extra]
+   * @returns {T}
+   */
+
   static fromHex(str, extra) {
     return new this().fromHex(str, extra);
   }
 
+  /**
+   * @template {Struct} T
+   * @this {new (...args: any[]) => T}
+   * @param {String} str
+   * @param {*} [extra]
+   * @returns {T}
+   */
+
   static fromBase64(str, extra) {
     return new this().fromBase64(str, extra);
   }
 
+  /**
+   * @template {Struct} T
+   * @this {new (...args: any[]) => T}
+   * @param {String} str
+   * @param {*} [extra]
+   * @returns {T}
+   */
+
   static fromString(str, extra) {
     return new this().fromString(str, extra);
   }
 
+  /**
+   * @template {Struct} T
+   * @this {new (...args: any[]) => T}
+   * @param {Object} json
+   * @param {*} [extra]
+   * @returns {T}
+   */
+
   static fromJSON(json, extra) {
     return new this().fromJSON(json, extra);
   }
 
+  /**
+   * @template {Struct} T
+   * @this {new (...args: any[]) => T}
+   * @param {Object} options
+   * @param {*} [extra]
+   * @returns {T}
+   */
+
   static fromOptions(options, extra) {
     return new this().fromOptions(options, extra);
   }
 
+  /**
+   * @template {Struct} T
+   * @this {new (...args: any[]) => T}
+   * @param {Object} options
+   * @param {*} [extra]
+   * @returns {T}
+   */
+
   static from(options, extra) {
     return new this().from(options, extra);
   }
@@ -318,19 +383,40 @@ class Struct {
    * Static Aliases
    */
 
+  /**
+   * @template {Struct} T
+   * @this {new (...args: any[]) => T}
+   * @param {BufferReader} br
+   * @param {*} [extra]
+   * @returns {T}
+   */
+
   static fromReader(br, extra) {
-    return this.read(br, extra);
+    return new this().read(br, extra);
   }
 
+  /**
+   * @template {Struct} T
+   * @this {new (...args: any[]) => T}
+   * @param {Buffer} data
+   * @param {*} [extra]
+   * @returns {T}
+   */
+
   static fromRaw(data, extra) {
-    return this.decode(data, extra);
+    return new this().decode(data, extra);
   }
 }
 
 /*
  * Helpers
  */
 
+/**
+ * @param {Number} size
+ * @returns {Number}
+ */
+
 function size64(size) {
   const expect = ((4 * size / 3) + 3) & ~3;
   return expect >>> 0;