From c3708e3a49cd3e3fff8afdfe98f0c82d91fea1f9 Mon Sep 17 00:00:00 2001
From: uzlopak <aras.abbasi@googlemail.com>
Date: Sat, 7 Sep 2024 13:03:43 +0200
Subject: [PATCH] chore: add jsdoc for lib/web/websocket/util.js

---
 lib/web/websocket/util.js | 40 +++++++++++++++++++++++++++++++--------
 1 file changed, 32 insertions(+), 8 deletions(-)

diff --git a/lib/web/websocket/util.js b/lib/web/websocket/util.js
index 9d3890c1eb0..acad497fadf 100644
--- a/lib/web/websocket/util.js
+++ b/lib/web/websocket/util.js
@@ -50,6 +50,7 @@ function isClosed (readyState) {
  * @param {EventTarget} target
  * @param {(...args: ConstructorParameters<typeof Event>) => Event} eventFactory
  * @param {EventInit | undefined} eventInitDict
+ * @returns {void}
  */
 function fireEvent (e, target, eventFactory = (type, init) => new Event(type, init), eventInitDict = {}) {
   // 1. If eventConstructor is not given, then let eventConstructor be Event.
@@ -72,11 +73,16 @@ function fireEvent (e, target, eventFactory = (type, init) => new Event(type, in
  * @param {import('./websocket').Handler} handler
  * @param {number} type Opcode
  * @param {Buffer} data application data
+ * @returns {void}
  */
 function websocketMessageReceived (handler, type, data) {
   handler.onMessage(type, data)
 }
 
+/**
+ * @param {Buffer} buffer
+ * @returns {ArrayBuffer}
+ */
 function toArrayBuffer (buffer) {
   if (buffer.byteLength === buffer.buffer.byteLength) {
     return buffer.buffer
@@ -89,6 +95,7 @@ function toArrayBuffer (buffer) {
  * @see https://datatracker.ietf.org/doc/html/rfc2616
  * @see https://bugs.chromium.org/p/chromium/issues/detail?id=398407
  * @param {string} protocol
+ * @returns {boolean}
  */
 function isValidSubprotocol (protocol) {
   // If present, this value indicates one
@@ -135,6 +142,7 @@ function isValidSubprotocol (protocol) {
 /**
  * @see https://datatracker.ietf.org/doc/html/rfc6455#section-7-4
  * @param {number} code
+ * @returns {boolean}
  */
 function isValidStatusCode (code) {
   if (code >= 1000 && code < 1015) {
@@ -151,6 +159,7 @@ function isValidStatusCode (code) {
 /**
  * @param {import('./websocket').Handler} handler
  * @param {string|undefined} reason
+ * @returns {void}
  */
 function failWebsocketConnection (handler, reason) {
   handler.onFail(reason)
@@ -159,6 +168,7 @@ function failWebsocketConnection (handler, reason) {
 /**
  * @see https://datatracker.ietf.org/doc/html/rfc6455#section-5.5
  * @param {number} opcode
+ * @returns {boolean}
  */
 function isControlFrame (opcode) {
   return (
@@ -168,14 +178,27 @@ function isControlFrame (opcode) {
   )
 }
 
+/**
+ * @param {number} opcode
+ * @returns {boolean}
+ */
 function isContinuationFrame (opcode) {
   return opcode === opcodes.CONTINUATION
 }
 
+/**
+ * @param {number} opcode
+ * @returns {boolean}
+ */
 function isTextBinaryFrame (opcode) {
   return opcode === opcodes.TEXT || opcode === opcodes.BINARY
 }
 
+/**
+ *
+ * @param {number} opcode
+ * @returns {boolean}
+ */
 function isValidOpcode (opcode) {
   return isTextBinaryFrame(opcode) || isContinuationFrame(opcode) || isControlFrame(opcode)
 }
@@ -209,6 +232,7 @@ function parseExtensions (extensions) {
  * @see https://www.rfc-editor.org/rfc/rfc7692#section-7.1.2.2
  * @description "client-max-window-bits = 1*DIGIT"
  * @param {string} value
+ * @returns {boolean}
  */
 function isValidClientWindowBits (value) {
   for (let i = 0; i < value.length; i++) {
@@ -222,22 +246,22 @@ function isValidClientWindowBits (value) {
   return true
 }
 
-// https://nodejs.org/api/intl.html#detecting-internationalization-support
-const hasIntl = typeof process.versions.icu === 'string'
-const fatalDecoder = hasIntl ? new TextDecoder('utf-8', { fatal: true }) : undefined
-
 /**
  * Converts a Buffer to utf-8, even on platforms without icu.
- * @param {Buffer} buffer
+ * @type {(buffer: Buffer) => string}
  */
-const utf8Decode = hasIntl
-  ? fatalDecoder.decode.bind(fatalDecoder)
-  : function (buffer) {
+const utf8Decode = (() => {
+  if (typeof process.versions.icu === 'string') {
+    const fatalDecoder = new TextDecoder('utf-8', { fatal: true })
+    return fatalDecoder.decode.bind(fatalDecoder)
+  }
+  return function (buffer) {
     if (isUtf8(buffer)) {
       return buffer.toString('utf-8')
     }
     throw new TypeError('Invalid utf-8 received.')
   }
+})()
 
 module.exports = {
   isConnecting,