refactor(api): fix typescript typings

api/crypto.js

@@ -16,6 +16,10 @@ import { Buffer } from './buffer.js'
 
 import * as exports from './crypto.js'
 
+/**
+ * @typedef {Uint8Array|Int8Array} TypedArray
+ */
+
 /**
  * WebCrypto API
  * @see {https://developer.mozilla.org/en-US/docs/Web/API/Crypto}

api/dgram.js

@@ -1163,6 +1163,9 @@ export class Socket extends EventEmitter {
  * @ignore
  */
 export class SocketError extends InternalError {
+  /**
+   * @type {string}
+   */
   get code () { return this.constructor.name }
 }
 

api/diagnostics/channels.js

@@ -39,14 +39,22 @@ export function normalizeName (group, name) {
  * A general interface for diagnostic channels that can be subscribed to.
  */
 export class Channel {
-  subscribers = new Array(MIN_CHANNEL_SUBSCRIBER_SIZE)
+  #subscribers = new Array(MIN_CHANNEL_SUBSCRIBER_SIZE)
   #subscribed = 0
 
   constructor (name) {
     this.name = name
     this.group = null
   }
 
+  /**
+   * Computed subscribers for all channels in this group.
+   * @type {Array<function>}
+   */
+  get subscribers () {
+    return this.#subscribers
+  }
+
   /**
    * Accessor for determining if channel has subscribers. This
    * is always `false` for `Channel instances and `true` for `ActiveChannel`
@@ -67,8 +75,9 @@ export class Channel {
    * Iterator interface
    * @ignore
    */
+  // @ts-ignore
   get [Symbol.iterator] () {
-    return this.subscribers
+    return /** @type {Array} */(this.subscribers)
   }
 
   /**
@@ -94,7 +103,11 @@ export class Channel {
    * Adds an `onMessage` subscription callback to the channel.
    * @return {boolean}
    */
-  subscribe (onMessage) {
+  subscribe (_, onMessage) {
+    if (typeof _ === 'function') {
+      onMessage = _
+    }
+
     if (typeof onMessage !== 'function') {
       throw new TypeError(
         `Expecting 'onMessage' to be a function. Got: ${typeof onMessage}`
@@ -120,7 +133,11 @@ export class Channel {
    * @param {function} onMessage
    * @return {boolean}
    */
-  unsubscribe (onMessage) {
+  unsubscribe (_, onMessage) {
+    if (typeof _ === 'function') {
+      onMessage = _
+    }
+
     if (typeof onMessage !== 'function') {
       throw new TypeError(
         `Expecting 'onMessage' to be a function. Got: ${typeof onMessage}`
@@ -255,6 +272,7 @@ export class ChannelGroup extends Channel {
 
   /**
    * Computed subscribers for all channels in this group.
+   * @type {Array<function>}
    */
   get subscribers () {
     return this.channels
@@ -280,8 +298,9 @@ export class ChannelGroup extends Channel {
    * Iterator iterface.
    * @ignore
    */
+  // @ts-ignore
   get [Symbol.iterator] () {
-    return this.channels
+    return /** @type {Array} */(this.channels)
   }
 
   /**

api/diagnostics/metric.js

@@ -2,7 +2,7 @@ import { isArrayLike, format } from '../util.js'
 
 export class Metric {
   init () {}
-  update () {}
+  update (value) {}
   destroy () {}
 
   toJSON () {

api/dns/index.js

@@ -52,20 +52,20 @@ const dc = diagnostics.channels.group('dns', [
  *
  * @see {@link https://nodejs.org/api/dns.html#dns_dns_lookup_hostname_options_callback}
  * @param {string} hostname - The host name to resolve.
- * @param {Object=} opts - An options object.
- * @param {number|string} [opts.family=0] - The record family. Must be 4, 6, or 0. For backward compatibility reasons,'IPv4' and 'IPv6' are interpreted as 4 and 6 respectively. The value 0 indicates that IPv4 and IPv6 addresses are both returned. Default: 0.
+ * @param {object?|function} [options] - An options object.
+ * @param {number|string} [options.family=0] - The record family. Must be 4, 6, or 0. For backward compatibility reasons,'IPv4' and 'IPv6' are interpreted as 4 and 6 respectively. The value 0 indicates that IPv4 and IPv6 addresses are both returned. Default: 0.
  * @param {function} cb - The function to call after the method is complete.
  * @returns {void}
  */
-export function lookup (hostname, opts, cb) {
+export function lookup (hostname, options = {}, cb) {
   if (typeof hostname !== 'string') {
     const err = new TypeError(`The "hostname" argument must be of type string. Received type ${typeof hostname} (${hostname})`)
     err.code = 'ERR_INVALID_ARG_TYPE'
     throw err
   }
 
-  if (typeof opts === 'function') {
-    cb = opts
+  if (typeof options === 'function') {
+    cb = options
   }
 
   if (typeof cb !== 'function') {
@@ -74,16 +74,16 @@ export function lookup (hostname, opts, cb) {
     throw err
   }
 
-  if (typeof opts === 'number') {
-    opts = { family: opts }
+  if (typeof options === 'number') {
+    options = { family: options }
   }
 
-  if (typeof opts !== 'object') {
-    opts = {}
+  if (typeof options !== 'object') {
+    options = {}
   }
 
-  dc.channel('lookup.start').publish({ hostname, family: opts.family, sync: true })
-  const { err, data } = ipc.sendSync('dns.lookup', { ...opts, id: rand64(), hostname })
+  dc.channel('lookup.start').publish({ hostname, family: options.family, sync: true })
+  const { err, data } = ipc.sendSync('dns.lookup', { ...options, id: rand64(), hostname })
 
   if (err) {
     const e = new Error(`getaddrinfo EAI_AGAIN ${hostname}`)
@@ -96,8 +96,8 @@ export function lookup (hostname, opts, cb) {
     return
   }
 
-  dc.channel('lookup.end').publish({ hostname, family: opts.family, sync: true })
-  dc.channel('lookup').publish({ hostname, family: opts.family, sync: true })
+  dc.channel('lookup.end').publish({ hostname, family: options.family, sync: true })
+  dc.channel('lookup').publish({ hostname, family: options.family, sync: true })
   cb(null, data?.address ?? null, data?.family ?? null)
 }
 

api/errors.js

@@ -246,10 +246,16 @@ export class InternalError extends Error {
     return 'InternalError'
   }
 
+  /**
+   * @type {number|string}
+   */
   get code () {
     return this[kInternalErrorCode] || 'INTERNAL_ERR'
   }
 
+  /**
+   * @param {number|string}
+   */
   set code (code) {
     this[kInternalErrorCode] = code
   }

api/events.js

@@ -216,7 +216,15 @@ EventEmitter.prototype.addListener = function addListener (type, listener) {
   return _addListener(this, type, listener, false)
 }
 
-EventEmitter.prototype.on = EventEmitter.prototype.addListener
+/**
+ * @instance
+ * @method on
+ * @memberOf EventEmitter
+ * @type {function(any, any): any}
+ */
+EventEmitter.prototype.on = function on (type, listener) {
+  return this.addListener(type, listener)
+}
 
 EventEmitter.prototype.prependListener =
     function prependListener (type, listener) {
@@ -296,7 +304,9 @@ EventEmitter.prototype.removeListener =
       return this
     }
 
-EventEmitter.prototype.off = EventEmitter.prototype.removeListener
+EventEmitter.prototype.off = function off (type, listener) {
+  return this.removeListener(type, listener)
+}
 
 EventEmitter.prototype.removeAllListeners =
     function removeAllListeners (type) {
@@ -376,7 +386,10 @@ EventEmitter.listenerCount = function (emitter, type) {
   }
 }
 
-EventEmitter.prototype.listenerCount = listenerCount
+EventEmitter.prototype.listenerCount = function (type) {
+  return listenerCount.call(this, type)
+}
+
 function listenerCount (type) {
   const events = this._events
 

api/extension.js

@@ -147,7 +147,7 @@ export class Extension extends EventTarget {
 /**
  * Load an extension by name.
  * @param {string} name
- * @param {objects?} [options]
+ * @param {object?} [options]
  * @return {Promise<Extension>}
  */
 export async function load (name, options = {}) {

api/fs/handle.js

@@ -24,6 +24,10 @@ import gc from '../gc.js'
 
 import * as exports from './handle.js'
 
+/**
+ * @typedef {Uint8Array|Int8Array} TypedArray
+ */
+
 const dc = diagnostics.channels.group('fs', [
   'handle',
   'handle.open',