From 00d97b9730f3d83e865d0f3ee33cba6290ba20ed Mon Sep 17 00:00:00 2001
From: Janaka66 <60848415+Janaka66@users.noreply.github.com>
Date: Mon, 23 Feb 2026 23:59:55 +0530
Subject: [PATCH] docs(utils): add missing JSDoc comments (#7427)

Co-authored-by: Jay <jasonsaayman@gmail.com>
---
 lib/utils.js | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/lib/utils.js b/lib/utils.js
index 0ef9c0b5..13bb0116 100644
--- a/lib/utils.js
+++ b/lib/utils.js
@@ -324,6 +324,14 @@ function forEach(obj, fn, { allOwnKeys = false } = {}) {
   }
 }
 
+/**
+ * Finds a key in an object, case-insensitive, returning the actual key name.
+ * Returns null if the object is a Buffer or if no match is found.
+ *
+ * @param {Object} obj - The object to search.
+ * @param {string} key - The key to find (case-insensitive).
+ * @returns {?string} The actual key name if found, otherwise null.
+ */
 function findKey(obj, key) {
   if (isBuffer(obj)) {
     return null;
@@ -667,6 +675,14 @@ const freezeMethods = (obj) => {
   });
 };
 
+/**
+ * Converts an array or a delimited string into an object set with values as keys and true as values.
+ * Useful for fast membership checks.
+ *
+ * @param {Array|string} arrayOrString - The array or string to convert.
+ * @param {string} delimiter - The delimiter to use if input is a string.
+ * @returns {Object} An object with keys from the array or string, values set to true.
+ */
 const toObjectSet = (arrayOrString, delimiter) => {
   const obj = {};
 
@@ -703,6 +719,12 @@ function isSpecCompliantForm(thing) {
   );
 }
 
+/**
+ * Recursively converts an object to a JSON-compatible object, handling circular references and Buffers.
+ *
+ * @param {Object} obj - The object to convert.
+ * @returns {Object} The JSON-compatible object.
+ */
 const toJSONObject = (obj) => {
   const stack = new Array(10);
 
@@ -738,8 +760,20 @@ const toJSONObject = (obj) => {
   return visit(obj, 0);
 };
 
+/**
+ * Determines if a value is an async function.
+ *
+ * @param {*} thing - The value to test.
+ * @returns {boolean} True if value is an async function, otherwise false.
+ */
 const isAsyncFn = kindOfTest('AsyncFunction');
 
+/**
+ * Determines if a value is thenable (has then and catch methods).
+ *
+ * @param {*} thing - The value to test.
+ * @returns {boolean} True if value is thenable, otherwise false.
+ */
 const isThenable = (thing) =>
   thing &&
   (isObject(thing) || isFunction(thing)) &&
@@ -749,6 +783,14 @@ const isThenable = (thing) =>
 // original code
 // https://github.com/DigitalBrainJS/AxiosPromise/blob/16deab13710ec09779922131f3fa5954320f83ab/lib/utils.js#L11-L34
 
+/**
+ * Provides a cross-platform setImmediate implementation.
+ * Uses native setImmediate if available, otherwise falls back to postMessage or setTimeout.
+ *
+ * @param {boolean} setImmediateSupported - Whether setImmediate is supported.
+ * @param {boolean} postMessageSupported - Whether postMessage is supported.
+ * @returns {Function} A function to schedule a callback asynchronously.
+ */
 const _setImmediate = ((setImmediateSupported, postMessageSupported) => {
   if (setImmediateSupported) {
     return setImmediate;
@@ -774,6 +816,12 @@ const _setImmediate = ((setImmediateSupported, postMessageSupported) => {
     : (cb) => setTimeout(cb);
 })(typeof setImmediate === 'function', isFunction(_global.postMessage));
 
+/**
+ * Schedules a microtask or asynchronous callback as soon as possible.
+ * Uses queueMicrotask if available, otherwise falls back to process.nextTick or _setImmediate.
+ *
+ * @type {Function}
+ */
 const asap =
   typeof queueMicrotask !== 'undefined'
     ? queueMicrotask.bind(_global)