chore: GitHub actions warning cleanup (#819)

* invalid JSDoc tag name "jest-environment" * idl jsdoc warnings * Missing JSDoc @param "s" description * leb128 cleanup and strict arraybuffer type enforcement * npm audit * changelog fixes #811
dfinity · Jan 11, 2024 · eb3fa49 · eb3fa49
1 parent e46045b
commit eb3fa49
Show file tree

Hide file tree

Showing 7 changed files with 51 additions and 19 deletions.
diff --git a/docs/generated/changelog.html b/docs/generated/changelog.html
@@ -12,6 +12,7 @@ <h1>Agent-JS Changelog</h1>
     <section>
       <h2>Version x.x.x</h2>
       <ul>
+        <li>chore: cleans up github actions linting warnings</li>
         <li>feat: replaces `secp256k1` npm package with `@noble/curves`</li>
         <li>feat: enhances `.from` methods on public key classes to support unknown types, including PublicKey instances, ArrayBuffer-like objects, DER encoded public keys, and hex strings. Also introduces a new `bufFromBufLike` util</li>
         <li>feat: introduces partial identities from public keys for authentication flows</li>

diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/candid/src/idl.test.ts b/packages/candid/src/idl.test.ts
@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-/**
+/*
  * @jest-environment node
  */
 import * as IDL from './idl';

diff --git a/packages/candid/src/idl.ts b/packages/candid/src/idl.ts
@@ -1531,9 +1531,9 @@ export class ServiceClass extends ConstructType<PrincipalId> {
 }
 
 /**
- *
- * @param x
- * @returns {string}
+ * Takes an unknown value and returns a string representation of it.
+ * @param x - unknown value
+ * @returns {string} string representation of the value
  */
 function toReadableString(x: unknown): string {
   const str = JSON.stringify(x, (_key, value) =>
@@ -1547,9 +1547,9 @@ function toReadableString(x: unknown): string {
 
 /**
  * Encode a array of values
- * @param argTypes
- * @param args
- * @returns {Buffer} serialised value
+ * @param argTypes - array of Types
+ * @param args - array of values
+ * @returns {ArrayBuffer} serialised value
  */
 export function encode(argTypes: Array<Type<any>>, args: any[]): ArrayBuffer {
   if (args.length < argTypes.length) {

diff --git a/packages/candid/src/utils/buffer.ts b/packages/candid/src/utils/buffer.ts
@@ -50,13 +50,13 @@ export class PipeArrayBuffer {
    * @param length an optional amount of bytes to use for the length.
    */
   constructor(buffer?: ArrayBuffer, length = buffer?.byteLength || 0) {
-    this._buffer = buffer || new ArrayBuffer(0);
+    this._buffer = bufFromBufLike(buffer || new ArrayBuffer(0));
     this._view = new Uint8Array(this._buffer, 0, length);
   }
 
   get buffer(): ArrayBuffer {
     // Return a copy of the buffer.
-    return this._view.slice();
+    return bufFromBufLike(this._view.slice());
   }
 
   get byteLength(): number {
@@ -121,3 +121,32 @@ export class PipeArrayBuffer {
     this._view = v;
   }
 }
+
+/**
+ * Returns a true ArrayBuffer from a Uint8Array, as Uint8Array.buffer is unsafe.
+ * @param {Uint8Array} arr Uint8Array to convert
+ * @returns ArrayBuffer
+ */
+export function uint8ToBuf(arr: Uint8Array): ArrayBuffer {
+  return new DataView(arr.buffer, arr.byteOffset, arr.byteLength).buffer;
+}
+
+/**
+ * Returns a true ArrayBuffer from an ArrayBufferLike object.
+ * @param bufLike a buffer-like object
+ * @returns ArrayBuffer
+ */
+export function bufFromBufLike(
+  bufLike: ArrayBuffer | Uint8Array | DataView | ArrayBufferView | ArrayBufferLike,
+): ArrayBuffer {
+  if (bufLike instanceof Uint8Array) {
+    return uint8ToBuf(bufLike);
+  }
+  if (bufLike instanceof ArrayBuffer) {
+    return bufLike;
+  }
+  if ('buffer' in bufLike) {
+    return bufLike.buffer;
+  }
+  return new Uint8Array(bufLike);
+}
diff --git a/packages/candid/src/utils/hash.ts b/packages/candid/src/utils/hash.ts
@@ -1,7 +1,8 @@
 /**
  * Hashes a string to a number. Algorithm can be found here:
  * https://caml.inria.fr/pub/papers/garrigue-polymorphic_variants-ml98.pdf
- * @param s
+ * @param s - string to hash
+ * @returns number representing hashed string
  */
 function idlHash(s: string): number {
   const utf8encoder = new TextEncoder();

diff --git a/packages/candid/src/utils/leb128.ts b/packages/candid/src/utils/leb128.ts
@@ -26,7 +26,7 @@ export function safeRead(pipe: Pipe, num: number): ArrayBuffer {
 }
 
 /**
- * @param pipe
+ * @param pipe - PipeArrayBuffer simulating buffer-pipe api
  */
 export function safeReadUint8(pipe: Pipe): number {
   const byte = pipe.readUint8();
@@ -169,8 +169,9 @@ export function writeUIntLE(value: bigint | number, byteLength: number): ArrayBu
 
 /**
  *
- * @param value
- * @param byteLength
+ * @param value - bigint or number
+ * @param byteLength - number
+ * @returns ArrayBuffer
  */
 export function writeIntLE(value: bigint | number, byteLength: number): ArrayBuffer {
   value = BigInt(value);