jsfunx 1.0.0

package/jsfunx.mjs

@@ -0,0 +1,1646 @@
+/* 
+
+Copyright (c) 2025 Khiat Mohammed Abderrezzak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Author: Khiat Mohammed Abderrezzak <khiat.dev@gmail.com>
+
+*/
+
+// JavaScript utility functions for cleaner, more readable code
+
+import { argv } from "process";
+
+import { basename } from "path";
+
+import { fileURLToPath } from "url";
+
+/** @type {string} */
+
+export const and = "and";
+
+/** @type {string} */
+
+export const or = "or";
+
+/** @type {string} */
+
+export const bigint = "bigint";
+
+/** @type {string} */
+
+export const func = "function";
+
+/** @type {string} */
+
+export const number = "number";
+
+/** @type {string} */
+
+export const object = "object";
+
+/** @type {string} */
+
+export const string = "string";
+
+/** @type {string} */
+
+export const symbol = "symbol";
+
+/** @type {string} */
+
+export const boolean = "boolean";
+
+/** @type {string} */
+
+export const undef = "undefined";
+
+/**
+ * Compares a value or a list of values against a given type (or list of types),
+ * similar to using `typeof x === y`, but in a more flexible and readable way.
+ *
+ * Supports single values or arrays, and can combine results using logical
+ * operators like `"and"` or `"or"`.
+ *
+ * @param {* | Array<*>} data - The value or array of values to check.
+ * @param {* | Array<*>} dataType - The expected type or array of expected types.
+ * @param {"and" | "or"} logic - Logic mode: `"and"` requires all matches, `"or"` allows any match.
+ * @param {boolean} match - Whether to compare type names strictly or loosely.
+ * @param {boolean} strict - If `true`, enforces strict comparison rules.
+ * @returns {boolean} `true` if the data matches the expected type(s) according to the given logic, otherwise `false`.
+ */
+
+function checkType(data, dataType, logic, match, strict) {
+  // if data or dataType is Array must be nested Array
+
+  if (!(dataType instanceof Array)) {
+    if (!(data instanceof Array)) {
+      return typeof data === dataType;
+    }
+
+    if (logic === and) {
+      for (let dt of data) {
+        // 1 step directly in all cases
+
+        if (!(typeof dt === dataType)) {
+          return false;
+        }
+
+        // or using recursion (one to one)
+        // 2 steps
+
+        // if (!checkType(dt, dataType, logic, match, strict)) {
+        //   return false;
+        // }
+      }
+
+      return true;
+    }
+
+    if (logic === or) {
+      for (let dt of data) {
+        // 1 step directly in all cases
+
+        if (typeof dt === dataType) {
+          return true;
+        }
+
+        // or using recursion (one to one)
+        // 2 steps
+
+        // if (checkType(dt, dataType, logic, match, strict)) {
+        //   return true;
+        // }
+      }
+
+      return false;
+    }
+
+    throw new TypeError("logic type undefined !");
+  }
+
+  if (!(data instanceof Array)) {
+    for (let dtype of dataType) {
+      // 1 step directly in all cases
+
+      if (typeof data === dtype) {
+        return true;
+      }
+
+      // or using recursion if (one to one) enabled
+      // 2 steps
+
+      // if (checkType(data, dtype, logic, match, strict)) {
+      //   return true;
+      // }
+    }
+
+    return false;
+  }
+
+  if (!match) {
+    if (logic === and) {
+      outerLoop: for (let dt of data) {
+        for (let dtype of dataType) {
+          if (typeof dt === dtype) {
+            continue outerLoop;
+          }
+        }
+
+        return false;
+      }
+
+      return true;
+
+      // or like this handling each case individually using recursion
+
+      // checking relationship type in this case (one to many)
+
+      // if (data.length < 2) {
+      //   // [x], [y, z] => x, [y, z] (one to many)
+
+      //   // we can call isType(data[0], dataType) in place of
+      //   // checkType(data[0], dataType, logic, match, strict) but take
+      //   // one step plus
+
+      //   // 2 steps (one to one)
+      //   if (!checkType(data[0], dataType, logic, match, strict)) {
+      //     return false;
+      //   }
+
+      //   return true;
+
+      //   // 1 step directly using (one to one)
+
+      //   // for (let dtype of dataType) {
+      //   //   if (checkType(data[0], dtype, logic, match, strict)) {
+      //   //     return true;
+      //   //   }
+
+      //   //   // the same as this
+
+      //   //   // if (typeof data[0] === dtype) {
+      //   //   //   return true;
+      //   //   // }
+      //   // }
+
+      //   // return false;
+      // }
+
+      // checking relationship type in this case (many to one)
+
+      // if (dataType.length < 2) {
+      //   // [x, y], [z] => [x, y], z (many to one)
+
+      //   // we can call isType(data, dataType[0]) in place of
+      //   // checkType(data, dataType[0], logic, match, strict) but take
+      //   // one step plus
+
+      //   // 2 steps (one to one)
+
+      //   if (!checkType(data, dataType[0], logic, match, strict)) {
+      //     return false;
+      //   }
+
+      //   // 1 step directly (one to one)
+
+      //   // for (let dt of data) {
+      //   //   if (!checkType(dt, dataType[0], logic, match, strict)) {
+      //   //     return false;
+      //   //   }
+
+      //   //   // the same as this
+
+      //   //   // if (!(typeof dt === dataType[0])) {
+      //   //   //   return false;
+      //   //   // }
+      //   // }
+
+      //   // shared return
+
+      //   return true;
+      // }
+
+      // checking relationship type in this case (many to many)
+
+      // we can embeds this in recursive (one to many) with the condition
+      // if (data.length < 2 || (data.length > 1 && dataType.length > 1)){
+      // with adding a for loop for any number of data at least one
+      // and replacing data[0] with dt from the loop and remove the next
+      // condition if (dataType.length < 2) {} because it's the last one no
+      // more conditions after it run the nested condition directly
+      // and set just one global true in the last of the two logics
+
+      // for (let dt of data) {
+      //   // [w, x], [y, z] => w, [y, z]
+      //   // [w, x], [y, z] => x, [y, z]
+      //   // (one to many) 1 step directly
+
+      //   // we can call isType(dt, dataType) in place of
+      //   // checkType(dt, dataType, logic, match, strict) but take
+      //   // one step plus
+
+      //   if (!checkType(dt, dataType, logic, match, strict)) {
+      //     return false;
+      //   }
+      // }
+
+      // return true;
+
+      // checking relationship type in this case (many to many)
+
+      // for (let dt of data) {
+      //   // [w, x], [y, z] => [w], [y, z]
+      //   // [w, x], [y, z] => [x], [y, z]
+      //   //  (one to many) 2 steps
+
+      //   // we can call isType([dt], dataType, match) in place of
+      //   // checkType([dt], dataType, logic, match, strict) but take
+      //   // one step plus
+
+      //   if (!checkType([dt], dataType, logic, match, strict)) {
+      //     return false;
+      //   }
+      // }
+
+      // return true;
+    }
+
+    if (logic === or) {
+      for (let dt of data) {
+        for (let dtype of dataType) {
+          if (typeof dt === dtype) {
+            return true;
+          }
+        }
+      }
+      return false;
+
+      // or like this handling each case individually using recursion
+
+      // checking relationship type in this case (one to many)
+
+      // if (data.length < 2) {
+      //   // [x], [y, z] => x, [y, z] (one to many)
+
+      //   // we can call isType(data[0], dataType, logic) in place of
+      //   // checkType(data[0], dataType, logic, match, strict) but take
+      //   // one step plus
+
+      //   // 2 steps (one to one)
+
+      //   if (checkType(data[0], dataType, logic, match, strict)) {
+      //     return true;
+      //   }
+
+      //   // 1 step directly using (one to one)
+
+      //   // for (let dtype of dataType) {
+      //   //   if (checkType(data[0], dtype, logic, match, strict)) {
+      //   //     return true;
+      //   //   }
+
+      //   //   // the same as this
+
+      //   //   // if (typeof data[0] === dtype) {
+      //   //   //   return true;
+      //   //   // }
+      //   // }
+
+      //   // shared return
+
+      //   return false;
+      // }
+
+      // checking relationship type in this case (many to one)
+
+      // if (dataType.length < 2) {
+      //   // [x, y], [z] => [x, y], z (many to one)
+
+      //   // we can call isType(data, dataType[0], logic) in place of
+      //   // checkType(data, dataType[0], logic, match, strict) but take
+      //   // one step plus
+
+      //   // 2 steps (one to one)
+
+      //   if (checkType(data, dataType[0], logic, match, strict)) {
+      //     return true;
+      //   }
+
+      //   // 1 step directly using (one to one)
+
+      //   // for (let dt of data) {
+      //   //   if (checkType(dt, dataType[0], logic, match, strict)) {
+      //   //     return true;
+      //   //   }
+
+      //   //   // the same as this
+
+      //   //   if (typeof dt === dataType[0]) {
+      //   //     return true;
+      //   //   }
+      //   // }
+
+      //   // shared return
+
+      //   return false;
+      // }
+
+      // checking relationship type in this case (many to many)
+
+      // we can embeds this in recursive (one to many) with the condition
+      // if (data.length < 2 || (data.length > 1 && dataType.length > 1)){
+      // with adding a for loop for any number of data at least one
+      // and replacing data[0] with dt from the loop and remove the next
+      // condition if (dataType.length < 2) {} because it's the last one no
+      // more conditions after it run the nested condition directly
+      // and set just one global true in the last of the two logics
+
+      // for (let dt of data) {
+      //   // [w, x], [y, z] => w, [y, z]
+      //   // [w, x], [y, z] => x, [y, z]
+      //   // (one to many) 1 step directly & 2 steps if (one to one)
+
+      //   // we can call isType(dt, dataType, logic) in place of
+      //   // checkType(dt, dataType, logic, match, strict) but take
+      //   // one step plus
+
+      //   if (checkType(dt, dataType, logic, match, strict)) {
+      //     return true;
+      //   }
+      // }
+
+      // return false;
+
+      // checking relationship type in this case (many to many)
+
+      // for (let dtype of dataType) {
+      //   // [w, x], [y, z] => [w, x], y
+      //   // [w, x], [y, z] => [w, x], z
+      //   // (many to one) 1 step directly & 2 steps (one to one)
+
+      //   // we can call isType(data, dtype, logic) in place of
+      //   // checkType(data, dtype, logic, match, strict) but take
+      //   // one step plus
+
+      //   if (checkType(data, dtype, logic, match, strict)) {
+      //     return true;
+      //   }
+      // }
+
+      // return false;
+
+      // checking relationship type in this case (many to many)
+
+      // for (let dt of data) {
+      //   // [w, x], [y, z] => [w], [y, z]
+      //   // [w, x], [y, z] => [x], [y, z]
+      //   //  (one to many) 2 steps & 3 steps (one to one)
+
+      //   // we can call isType([dt], dataType, logic, match) in place of
+      //   // checkType([dt], dataType, logic, match, strict) but take
+      //   // one step plus
+
+      //   if (checkType([dt], dataType, logic, match, strict)) {
+      //     return true;
+      //   }
+      // }
+
+      // return false;
+
+      // checking relationship type in this case (many to many)
+
+      // for (let dtype of dataType) {
+      //   // [w, x], [y, z] => [w, x], [y]
+      //   // [w, x], [y, z] => [w, x], [z]
+      //   //  (many to one) 2 steps & 3 steps (one to one)
+
+      //   // we can call isType(data, [dtype], logic, match) in place of
+      //   // checkType(data, [dtype], logic, match, strict) but take
+      //   // one step plus
+
+      //   if (checkType(data, [dtype], logic, match, strict)) {
+      //     return true;
+      //   }
+      // }
+
+      // return false;
+    }
+
+    throw new TypeError("logic type undefined !");
+  }
+
+  if (data.length !== dataType.length) {
+    if (strict) {
+      throw new TypeError(
+        "length of array of dataTypes must match number of data"
+      );
+    }
+
+    /** @type {number} */
+
+    let min;
+
+    if (data.length < dataType.length) {
+      min = data.length;
+    } else {
+      min = dataType.length;
+    }
+
+    if (logic === and) {
+      for (let i = 0; i < min; ++i) {
+        // 1 step directly in all cases
+
+        if (!(typeof data[i] === dataType[i])) {
+          return false;
+        }
+
+        // or using recursion (one to one)
+        // 2 steps
+
+        // if (!checkType(data[i], dataType[i], logic, match, strict)) {
+        //   return false;
+        // }
+      }
+
+      // shared return
+
+      return true;
+    }
+
+    if (logic === or) {
+      for (let i = 0; i < min; ++i) {
+        // 1 step directly in all cases
+
+        if (typeof data[i] === dataType[i]) {
+          return true;
+        }
+
+        // or using recursion (one to one)
+        // 2 steps
+
+        // if (checkType(data[i], dataType[i], logic, match, strict)) {
+        //   return true;
+        // }
+      }
+
+      // shared return
+
+      return false;
+    }
+
+    throw new TypeError("logic type undefined !");
+  }
+
+  if (logic === and) {
+    for (let i = 0; i < data.length; ++i) {
+      // 1 step directly in all cases
+
+      if (!(typeof data[i] === dataType[i])) {
+        return false;
+      }
+
+      // or using recursion (one to one)
+      // 2 steps
+
+      // if (!checkType(data[i], dataType[i], logic, match, strict)) {
+      //   return false;
+      // }
+    }
+
+    // shared return
+
+    return true;
+  }
+
+  if (logic === or) {
+    for (let i = 0; i < data.length; ++i) {
+      // 1 step directly in all cases
+
+      if (typeof data[i] === dataType[i]) {
+        return true;
+      }
+
+      // or using recursion (one to one)
+      // 2 steps
+
+      // if (checkType(data[i], dataType[i], logic, match, strict)) {
+      //   return true;
+      // }
+    }
+
+    // shared return
+
+    return false;
+  }
+
+  throw new TypeError("logic type undefined !");
+}
+
+/**
+ * Checks whether one or more objects are instances of a given class (or classes),
+ * similar to using the `instanceof` operator — but extended to handle arrays
+ * and multiple constructors with logical control.
+ *
+ * Works like a plural form of `instanceof`, allowing you to check several objects
+ * against one or more classes, using `"and"` or `"or"` logic.
+ *
+ * @template T - The instance type returned by the constructor(s).
+ * @param {* | Array<*>} objs - The object or array of objects to test.
+ * @param {(new (...args: any[]) => T) | Array<new (...args: any[]) => T>} type - The constructor or list of constructors to test against.
+ * @param {"and" | "or"} logic - Logic mode: `"and"` requires all matches, `"or"` allows any match.
+ * @param {boolean} match - Whether to compare classes names strictly or loosely.
+ * @param {boolean} strict - If `true`, enables strict comparison behavior.
+ * @returns {boolean} `true` if the provided object(s) match the given type(s) according to the chosen logic, otherwise `false`.
+ */
+
+function isinstances(objs, type, logic, match, strict) {
+  if (!(type instanceof Array)) {
+    // uncomment (return objs instanceof type)
+    // to enable the 1/4 of (one to one)
+
+    if (!(objs instanceof Array)) {
+      // return objs instanceof type;
+
+      throw new TypeError(
+        `instancesof expected at least : 2 objects as first argument 'objs' or 2 types as second argument 'type', got 1`
+      );
+    }
+
+    // remove this (if) condition to enable the 1/4 of (one to one)
+
+    if (objs.length < 2) {
+      throw new TypeError(
+        `instancesof expected at least 2 objects as first argument 'objs', got 1`
+      );
+    }
+
+    if (logic === and) {
+      for (let obj of objs) {
+        // 1 step directly in all cases
+
+        try {
+          if (!(obj instanceof type)) {
+            return false;
+          }
+        } catch (error) {
+          throw new TypeError(
+            "second argument of 'instancesof' is not a type/class or array of types/classes"
+          );
+        }
+
+        // or using recursion if (one to one) enabled
+        // 2 steps
+
+        // if (!isinstances(obj, type, logic, match, strict)) {
+        //   return false;
+        // }
+      }
+
+      return true;
+    }
+
+    if (logic === or) {
+      for (let obj of objs) {
+        // 1 step directly in all cases
+
+        try {
+          if (obj instanceof type) {
+            return true;
+          }
+        } catch (error) {
+          throw new TypeError(
+            "second argument of 'instancesof' is not a type/class or array of types/classes"
+          );
+        }
+
+        // or using recursion if (one to one) enabled
+        // 2 steps
+
+        // if (isinstances(obj, type, logic, match, strict)) {
+        //   return true;
+        // }
+      }
+
+      return false;
+    }
+
+    throw new TypeError("logic type undefined !");
+  }
+
+  if (!(objs instanceof Array)) {
+    // remove this (if) condition to enable the 1/4 of (one to one)
+
+    if (type.length < 2) {
+      throw new TypeError(
+        `instancesof expected at least 2 types as second argument 'type', got 1`
+      );
+    }
+
+    for (let dt of type) {
+      // 1 step directly in all cases
+
+      try {
+        if (objs instanceof dt) {
+          return true;
+        }
+      } catch (error) {
+        throw new TypeError(
+          "second argument of 'instancesof' is not a type/class or array of types/classes"
+        );
+      }
+
+      // or using recursion if (one to one) enabled
+      // 2 steps
+
+      // if (isinstances(objs, dt, logic, match, strict)) {
+      //   return true;
+      // }
+    }
+
+    return false;
+  }
+
+  // remove this (if) to enable 1/4 of (one to one)
+
+  if (objs.length < 2 && type.length < 2) {
+    throw new TypeError(
+      `instancesof expected at least : 2 objects as first argument 'objs' or 2 types as second argument 'type', got 1`
+    );
+  }
+
+  if (!match) {
+    if (logic === and) {
+      outerLoop: for (let obj of objs) {
+        for (let dt of type) {
+          try {
+            if (obj instanceof dt) {
+              continue outerLoop;
+            }
+          } catch (error) {
+            throw new TypeError(
+              "second argument of 'instancesof' is not a type/class or array of types/classes"
+            );
+          }
+        }
+
+        return false;
+      }
+
+      return true;
+
+      // or like this handling each case individually using recursion
+
+      // checking relationship type in this case (one to many)
+
+      // if (objs.length < 2) {
+      //   // [x], [y, z] => x, [y, z] (one to many)
+
+      //   // we can call instancesof(objs[0], type) in place of
+      //   // isinstances(objs[0], type, logic, match, strict) but take
+      //   // one step plus
+
+      //   // 2 steps if (one to one) enabled
+      //   if (!isinstances(objs[0], type, logic, match, strict)) {
+      //     return false;
+      //   }
+
+      //   return true;
+
+      //   // 1 step directly using (one to one) if enabled
+
+      //   // for (let dt of type) {
+      //   //   if (isinstances(objs[0], dt, logic, match, strict)) {
+      //   //     return true;
+      //   //   }
+
+      //   //   // the same as this
+
+      //   //   // if (objs[0] instanceof dt) {
+      //   //   //   return true;
+      //   //   // }
+      //   // }
+
+      //   // return false;
+      // }
+
+      // checking relationship type in this case (many to one)
+
+      // if (type.length < 2) {
+      //   // [x, y], [z] => [x, y], z (many to one)
+
+      //   // we can call instancesof(objs, type[0]) in place of
+      //   // isinstances(objs, type[0], logic, match, strict) but take
+      //   // one step plus
+
+      //   // 2 steps if (one to one) enabled
+
+      //   if (!isinstances(objs, type[0], logic, match, strict)) {
+      //     return false;
+      //   }
+
+      //   // 1 step directly using (one to one) if enabled
+
+      //   // for (let obj of objs) {
+      //   //   if (!isinstances(obj, type[0], logic, match, strict)) {
+      //   //     return false;
+      //   //   }
+
+      //   //   // the same as this
+
+      //   //   // if (!(obj instanceof type[0])) {
+      //   //   //   return false;
+      //   //   // }
+      //   // }
+
+      //   // shared return
+
+      //   return true;
+      // }
+
+      // checking relationship type in this case (many to many)
+
+      // we can embeds this in recursive (one to many) with the condition
+      // if (objs.length < 2 || (objs.length > 1 && type.length > 1)){
+      // with adding a for loop for any number of objs at least one
+      // and replacing objs[0] with obj from the loop and remove the next
+      // condition if (type.length < 2) {} because it's the last one no
+      // more conditions after it run the nested condition directly
+      // and set just one global true in the last of the two logics
+
+      // for (let obj of objs) {
+      //   // [w, x], [y, z] => w, [y, z]
+      //   // [w, x], [y, z] => x, [y, z]
+      //   // (one to many) (1 step directly)
+
+      //   // we can call instancesof(obj, type) in place of
+      //   // isinstances(obj, type, logic, match, strict) but take
+      //   // one step plus
+
+      //   if (!isinstances(obj, type, logic, match, strict)) {
+      //     return false;
+      //   }
+      // }
+
+      // return true;
+
+      // checking relationship type in this case (many to many)
+
+      // for (let obj of objs) {
+      //   // [w, x], [y, z] => [w], [y, z]
+      //   // [w, x], [y, z] => [x], [y, z]
+      //   //  (one to many) (2 steps)
+
+      //   // we can call instancesof([obj], type, match) in place of
+      //   // isinstances([obj], type, logic, match, strict) but take
+      //   // one step plus
+
+      //   if (!isinstances([obj], type, logic, match, strict)) {
+      //     return false;
+      //   }
+      // }
+
+      // return true;
+    }
+
+    if (logic === or) {
+      for (let obj of objs) {
+        for (let dt of type) {
+          try {
+            if (obj instanceof dt) {
+              return true;
+            }
+          } catch (error) {
+            throw new TypeError(
+              "second argument of 'instancesof' is not a type/class or array of types/classes"
+            );
+          }
+        }
+      }
+      return false;
+
+      // or like this handling each case individually using recursion
+
+      // checking relationship type in this case (one to many)
+
+      // if (objs.length < 2) {
+      //   // [x], [y, z] => x, [y, z] (one to many)
+
+      //   // we can call instancesof(objs[0], type, logic) in place of
+      //   // isinstances(objs[0], type, logic, match, strict) but take
+      //   // one step plus
+
+      //   // 2 steps if (one to one) enabled
+
+      //   if (isinstances(objs[0], type, logic, match, strict)) {
+      //     return true;
+      //   }
+
+      //   // // 1 step directly using (one to one) if enabled
+
+      //   // for (let dt of type) {
+      //   //   if (isinstances(objs[0], dt, logic, match, strict)) {
+      //   //     return true;
+      //   //   }
+
+      //   //   // the same as this
+
+      //   //   // if (objs[0] instanceof dt) {
+      //   //   //   return true;
+      //   //   // }
+      //   // }
+
+      //   // shared return
+
+      //   return false;
+      // }
+
+      // checking relationship type in this case (many to one)
+
+      // if (type.length < 2) {
+      //   // [x, y], [z] => [x, y], z (many to one)
+
+      //   // we can call instancesof(objs, type[0], logic) in place of
+      //   // isinstances(objs, type[0], logic, match, strict) but take
+      //   // one step plus
+
+      //   // 2 steps if (one to one) enabled
+
+      //   if (isinstances(objs, type[0], logic, match, strict)) {
+      //     return true;
+      //   }
+
+      //   // // 1 step directly using (one to one) if enabled
+
+      //   // for (let obj of objs) {
+      //   //   if (isinstances(obj, type[0], logic, match, strict)) {
+      //   //     return true;
+      //   //   }
+
+      //   //   // the same as this
+
+      //   //   // if (obj instanceof type[0]) {
+      //   //   //   return true;
+      //   //   // }
+      //   // }
+
+      //   // shared return
+
+      //   return false;
+      // }
+
+      // checking relationship type in this case (many to many)
+
+      // we can embeds this in recursive (one to many) with the condition
+      // if (objs.length < 2 || (objs.length > 1 && type.length > 1)){
+      // with adding a for loop for any number of objs at least one
+      // and replacing objs[0] with obj from the loop and remove the next
+      // condition if (type.length < 2) {} because it's the last one no
+      // more conditions after it run the nested condition directly
+      // and set just one global true in the last of the two logics
+
+      // for (let obj of objs) {
+      //   // [w, x], [y, z] => w, [y, z]
+      //   // [w, x], [y, z] => x, [y, z]
+      //   // (one to many) (1 step directly) & (2 steps if (one to one) enabled)
+
+      //   // we can call instancesof(obj, type, logic) in place of
+      //   // isinstances(obj, type, logic, match, strict) but take
+      //   // one step plus
+
+      //   if (isinstances(obj, type, logic, match, strict)) {
+      //     return true;
+      //   }
+      // }
+
+      // return false;
+
+      // checking relationship type in this case (many to many)
+
+      // for (let dt of type) {
+      //   // [w, x], [y, z] => [w, x], y
+      //   // [w, x], [y, z] => [w, x], z
+      //   // (many to one) (1 step directly) & (2 steps if (one to one) enabled)
+
+      //   // we can call instancesof(objs, dt, logic) in place of
+      //   // isinstances(objs, dt, logic, match, strict) but take
+      //   // one step plus
+
+      //   if (isinstances(objs, dt, logic, match, strict)) {
+      //     return true;
+      //   }
+      // }
+
+      // return false;
+
+      // checking relationship type in this case (many to many)
+
+      // for (let obj of objs) {
+      //   // [w, x], [y, z] => [w], [y, z]
+      //   // [w, x], [y, z] => [x], [y, z]
+      //   //  (one to many) (2 steps) & (3 steps if (one to one) enabled)
+
+      //   // we can call instancesof([obj], type, logic, match) in place of
+      //   // isinstances([obj], type, logic, match, strict) but take
+      //   // one step plus
+
+      //   if (isinstances([obj], type, logic, match, strict)) {
+      //     return true;
+      //   }
+      // }
+
+      // return false;
+
+      // checking relationship type in this case (many to many)
+
+      // for (let dt of type) {
+      //   // [w, x], [y, z] => [w, x], [y]
+      //   // [w, x], [y, z] => [w, x], [z]
+      //   //  (many to one) (2 steps) & (3 steps if (one to one) enabled)
+
+      //   // we can call instancesof(objs, [dt], logic, match) in place of
+      //   // isinstances(objs, [dt], logic, match, strict) but take
+      //   // one step plus
+
+      //   if (isinstances(objs, [dt], logic, match, strict)) {
+      //     return true;
+      //   }
+      // }
+
+      // return false;
+    }
+
+    throw new TypeError("logic type undefined !");
+  }
+
+  if (objs.length !== type.length) {
+    if (strict) {
+      throw new TypeError(
+        "length of array of types must match number of objects"
+      );
+    }
+
+    /** @type {number} */
+
+    let min;
+
+    if (objs.length < type.length) {
+      min = objs.length;
+    } else {
+      min = type.length;
+    }
+
+    if (logic === and) {
+      for (let i = 0; i < min; ++i) {
+        // 1 step directly in all cases
+
+        try {
+          if (!(objs[i] instanceof type[i])) {
+            return false;
+          }
+        } catch (error) {
+          throw new TypeError(
+            "second argument of 'instancesof' is not a type/class or array of types/classes"
+          );
+        }
+
+        // or using recursion if (one to one) enabled
+        // 2 steps
+
+        // if (!isinstances(objs[i], type[i], logic, match, strict)) {
+        //   return false;
+        // }
+      }
+
+      // shared return
+
+      return true;
+    }
+
+    if (logic === or) {
+      for (let i = 0; i < min; ++i) {
+        // 1 step directly in all cases
+
+        try {
+          if (objs[i] instanceof type[i]) {
+            return true;
+          }
+        } catch (error) {
+          throw new TypeError(
+            "second argument of 'instancesof' is not a type/class or array of types/classes"
+          );
+        }
+
+        // or using recursion if (one to one) enabled
+        // 2 steps
+
+        // if (isinstances(objs[i], type[i], logic, match, strict)) {
+        //   return true;
+        // }
+      }
+
+      // shared return
+
+      return false;
+    }
+
+    throw new TypeError("logic type undefined !");
+  }
+
+  if (logic === and) {
+    for (let i = 0; i < objs.length; ++i) {
+      // 1 step directly in all cases
+
+      try {
+        if (!(objs[i] instanceof type[i])) {
+          return false;
+        }
+      } catch (error) {
+        throw new TypeError(
+          "second argument of 'instancesof' is not a type/class or array of types/classes"
+        );
+      }
+
+      // or using recursion if (one to one) enabled
+      // 2 steps
+
+      // if (!isinstances(objs[i], type[i], logic, match, strict)) {
+      //   return false;
+      // }
+    }
+
+    // shared return
+
+    return true;
+  }
+
+  if (logic === or) {
+    for (let i = 0; i < objs.length; ++i) {
+      // 1 step directly in all cases
+
+      try {
+        if (objs[i] instanceof type[i]) {
+          return true;
+        }
+      } catch (error) {
+        throw new TypeError(
+          "second argument of 'instancesof' is not a type/class or array of types/classes"
+        );
+      }
+
+      // or using recursion if (one to one) enabled
+      // 2 steps
+
+      // if (isinstances(objs[i], type[i], logic, match, strict)) {
+      //   return true;
+      // }
+    }
+
+    // shared return
+
+    return false;
+  }
+
+  throw new TypeError("logic type undefined !");
+}
+
+/**
+ * Checks whether one or more objects are instances of a given class (or classes),
+ * similar to using the `instanceof` operator — but extended to handle arrays
+ * and multiple constructors with logical control.
+ *
+ * Works like a plural form of `instanceof`, allowing you to check several objects
+ * against one or more classes, using `"and"` or `"or"` logic.
+ *
+ * @template T - The instance type returned by the constructor(s).
+ * @param {*|Array<*>} objs - The object or array of objects to test.
+ * @param {(new (...args: any[]) => T) | Array<new (...args: any[]) => T>} type - The constructor or list of constructors to test against.
+ * @param {"and" | "or" | boolean} logic_or_match - Logic mode: `"and"` requires all matches, `"or"` allows any match.
+ * @param {boolean} match_or_strict - Whether to compare classes names strictly or loosely.
+ * @param {boolean} strict - If `true`, enables strict comparison behavior.
+ * @returns {boolean} `true` if the provided object(s) match the given type(s) according to the chosen logic, otherwise `false`.
+ */
+
+export function instancesof(
+  objs,
+  type,
+  logic_or_match = and,
+  match_or_strict = true,
+  strict = true
+) {
+  /** @type {number} */
+
+  let len = arguments.length;
+
+  if (len < 2) {
+    throw new TypeError(
+      len == 1
+        ? "instancesof() missing 1 required arguments: 'type'"
+        : "instancesof() missing 2 required arguments: 'objs' and 'type'"
+    );
+  }
+
+  if (len > 5) {
+    throw new TypeError(
+      `instancesof() takes 5 positional arguments but ${len} were given`
+    );
+  }
+
+  if (len === 3) {
+    switch (arguments[2]) {
+      case true:
+      case false:
+        return isinstances(objs, type, and, logic_or_match, strict);
+    }
+  }
+
+  if (len === 4) {
+    switch (arguments[3]) {
+      case true:
+      case false:
+        break;
+      default:
+        throw new TypeError("forth argument must be true or false");
+    }
+
+    switch (arguments[2]) {
+      case true:
+      case false:
+        return isinstances(objs, type, and, logic_or_match, match_or_strict);
+    }
+  }
+
+  return isinstances(objs, type, logic_or_match, match_or_strict, strict);
+}
+
+/**
+ * Compares a value or a list of values against a given type (or list of types),
+ * similar to using `typeof x === y`, but in a more flexible and readable way.
+ *
+ * Supports single values or arrays, and can combine results using logical
+ * operators like `"and"` or `"or"`.
+ *
+ * @param {* | Array<*>} data - The value or array of values to check.
+ * @param {* | Array<*>} dataType - The expected type or array of expected types.
+ * @param {"and" | "or" | boolean} logic_or_match - Logic mode: `"and"` requires all matches, `"or"` allows any match.
+ * @param {boolean} match_or_strict - Whether to compare type names strictly or loosely.
+ * @param {boolean} strict - If `true`, enforces strict comparison rules.
+ * @returns {boolean} `true` if the data matches the expected type(s) according to the given logic, otherwise `false`.
+ */
+
+export function isType(
+  data,
+  dataType,
+  logic_or_match = and,
+  match_or_strict = true,
+  strict = true
+) {
+  /** @type {number} */
+
+  let len = arguments.length;
+
+  if (len < 2) {
+    throw new TypeError(
+      len == 1
+        ? "isType() missing 1 required arguments: 'dataType'"
+        : "isType() missing 2 required arguments: 'data' and 'dataType'"
+    );
+  }
+
+  if (len > 5) {
+    throw new TypeError(
+      `isType() takes 5 positional arguments but ${len} were given`
+    );
+  }
+
+  if (len === 3) {
+    switch (arguments[2]) {
+      case true:
+      case false:
+        return checkType(data, dataType, and, logic_or_match, strict);
+    }
+  }
+
+  if (len === 4) {
+    switch (arguments[3]) {
+      case true:
+      case false:
+        break;
+      default:
+        throw new TypeError("forth argument must be true or false");
+    }
+
+    switch (arguments[2]) {
+      case true:
+      case false:
+        return checkType(data, dataType, and, logic_or_match, match_or_strict);
+    }
+  }
+
+  return checkType(data, dataType, logic_or_match, match_or_strict, strict);
+}
+
+/**
+ * Checks whether all provided values have the same length.
+ * Each value must have a numeric `length` property (e.g., arrays, strings, typed arrays, etc.).
+ *
+ * If all lengths are equal, returns a tuple containing that length and `true`.
+ * Otherwise, returns a tuple containing an array of all detected lengths and `false`.
+ *
+ * @param {...{length: number}} objs - The values to compare by their length property.
+ * @returns {[number | number[], boolean]} A tuple:
+ *   - `[length, true]` if all values have the same length.
+ *   - `[lengths, false]` if the lengths differ.
+ */
+
+export function lengths(...objs) {
+  // use not(objs) to enable all cases including one argument only
+
+  if (objs.length < 2) {
+    throw new TypeError(
+      `lengths() takes at least two arguments (${objs.length} given)`
+    );
+  }
+
+  /** @type {Array<number>} */
+
+  let lens = [objs[0].length];
+
+  /** @type {boolean} */
+
+  let equal = true;
+
+  /** @type {number} */
+
+  let len;
+
+  for (let i = 1; i < objs.length; ++i) {
+    len = objs[i].length;
+
+    lens.push(len);
+
+    if (!equal) {
+      continue;
+    }
+
+    if (len !== lens[i - 1]) {
+      equal = false;
+    }
+  }
+
+  if (equal) {
+    return [lens[0], equal];
+  }
+
+  return [lens, equal];
+}
+
+/**
+ * Evaluates the truthiness of a given value.
+ * Works like the logical NOT operator (`!`), returning `true` if the value is falsy and `false` if it is truthy.
+ *
+ * @param {*} obj - The value to evaluate.
+ * @returns {boolean} `true` if the value is falsy, otherwise `false`.
+ */
+
+export function not(obj) {
+  if (arguments.length === 0) {
+    throw new TypeError("not() takes exactly one argument (0 given)");
+  }
+
+  if (obj instanceof Boolean) {
+    return obj == false;
+  }
+
+  return obj?.length === 0 || !obj; // handling the object case
+}
+
+/**
+ * Checks whether all provided values are of the same type.
+ * Similar to the `typeof` operator but supports multiple inputs.
+ *
+ * If all values share the same type, returns a tuple containing that type as a string and `true`.
+ * Otherwise, returns a tuple containing an array of the detected types and `false`.
+ *
+ * @param {...*} objs - The values to check.
+ * @returns {[string | string[], boolean]} A tuple:
+ *   - `[type, true]` if all values are of the same type.
+ *   - `[types, false]` if values have mixed types.
+ */
+
+export function typesof(...objs) {
+  // use not(objs) to enable all cases including one argument only
+
+  if (objs.length < 2) {
+    throw new TypeError(
+      `typesof() takes at least two arguments (${objs.length} given)`
+    );
+  }
+
+  /** @type {Array<string>} */
+
+  let types = [typeof objs[0]];
+
+  /** @type {boolean} */
+
+  let equal = true;
+
+  /** @type {string} */
+
+  let type;
+
+  for (let i = 1; i < objs.length; ++i) {
+    type = typeof objs[i];
+
+    types.push(type);
+
+    if (!equal) {
+      continue;
+    }
+
+    if (type !== types[i - 1]) {
+      equal = false;
+    }
+  }
+
+  if (equal) {
+    return [types[0], equal];
+  }
+
+  return [types, equal];
+}
+
+/**
+ * Evaluates the truthiness of a given value.
+ * Works like the logical NOT operator (`!`), returning `true` if the value is falsy and `false` if it is truthy.
+ *
+ * @param {*} obj - The value to evaluate.
+ * @returns {boolean} `true` if the value is falsy, otherwise `false`.
+ */
+
+export function $(obj) {
+  return not(obj);
+}
+
+function main() {
+  console.log("----------instancesof----------");
+
+  /** @type {Number} */
+
+  let a = new Number(3);
+
+  /** @type {Number} */
+
+  let b = new Number(7);
+
+  /** @type {String} */
+
+  let c = new String("test");
+
+  // one to one (disabled)
+
+  // console.log(instancesof(a, Number)); // true
+  // console.log(instancesof(a, [Number])); // true
+  // console.log(instancesof([a], Number)); // true
+
+  // match=true and strict=true (default)
+  // console.log(instancesof([a], [Number])); // true
+
+  // match=false and strict=true
+  // but when match=false strict don't matter True or False
+  // console.log(instancesof([a], [Number], false)); // true
+
+  // one to many
+
+  console.log(instancesof(a, [Number, String], false)); // true
+  console.log(instancesof([a], [Number, String], false)); // true
+
+  // match=true and strict=false
+  // in this case take just Number with x the second type ignored
+  console.log(instancesof(a, [Number, String], true, false)); // true
+
+  console.log(instancesof([a], [Number, String], true, false)); // true
+
+  // many to one
+
+  // AND
+
+  console.log(instancesof([a, b], Number)); // true
+  console.log(instancesof([a, b], [Number], false)); // true
+
+  // OR
+
+  console.log(instancesof([b, c], Number, or)); // true
+  console.log(instancesof([b, c], [Number], or, false)); // true
+
+  // many to many
+
+  // AND
+
+  console.log(instancesof([a, b], [Number, String], false)); // true
+
+  // OR
+
+  console.log(instancesof([b, c], [Number, Boolean], or, false)); // true
+
+  // pattern matching
+
+  // AND
+
+  console.log(instancesof([a, b], [Number, Number])); // true
+
+  console.log(instancesof([a, b], [Number, Number, String], true, false)); // true
+
+  // OR
+
+  console.log(instancesof([b, c], [Number, Boolean], or)); // true
+
+  console.log(instancesof([b, c], [Number, Boolean, String], or, true, false)); // true
+
+  console.log("------------isType------------");
+
+  /** @type {number} */
+
+  let x = 3; // or Number(3)
+
+  /** @type {number} */
+
+  let y = 7; // or Number(7)
+
+  /** @type {number} */
+
+  let z = "test"; // or String("test")
+
+  // one to one
+
+  console.log(isType(x, number)); // true
+  console.log(isType(x, [number])); // true
+  console.log(isType([x], number)); // true
+
+  // match=true and strict=true (default)
+  console.log(isType([x], [number])); // true
+
+  // match=false and strict=true
+  // but when match=false strict don't matter True or False
+  console.log(isType([x], [number], false)); // true
+
+  // one to many
+
+  console.log(isType(x, [number, string], false)); // true
+  console.log(isType([x], [number, string], false)); // true
+
+  // match=true and strict=false
+  // in this case take just Number with x the second type ignored
+  console.log(isType(x, [number, string], true, false)); // true
+
+  console.log(isType([x], [number, string], true, false)); // true
+
+  // many to one
+
+  // AND
+
+  console.log(isType([x, y], number)); // true
+  console.log(isType([x, y], [number], false)); // true
+
+  // OR
+
+  console.log(isType([y, z], number, or)); // true
+  console.log(isType([y, z], [number], or, false)); // true
+
+  // many to many
+
+  // AND
+
+  console.log(isType([x, y], [number, string], false)); // true
+
+  // OR
+
+  console.log(isType([y, z], [number, boolean], or, false)); // true
+
+  // pattern matching
+
+  // AND
+
+  console.log(isType([x, y], [number, number])); // true
+
+  console.log(isType([x, y], [number, number, string], true, false)); // true
+
+  // OR
+
+  console.log(isType([y, z], [number, boolean], or)); // true
+
+  console.log(isType([y, z], [number, boolean, string], or, true, false)); // true
+
+  console.log("-----------lengths-----------");
+
+  // // use .length directly in this case is the best practice
+  // // one arg (disabled)
+
+  // console.log(lengths([1, 2, 3])); // [ 3, true ]
+
+  // two args +
+
+  console.log(lengths([1, 2, 3], [1, 2, 3])); // [ 3, true ]
+  console.log(lengths([1, 2, 3], "hello")); // [ [3, 5], false ]
+
+  console.log("--------------!--------------");
+
+  console.log(!"test"); // false
+  console.log(!1); // false
+  console.log(!true); // false
+  console.log(!""); // true
+  console.log(!0); // true
+  console.log(!false); // true
+  console.log(!null); // true
+  console.log(!undefined); // true
+
+  // using (!) these is false because objects in JS always true
+  console.log(![]); // new Array()
+  console.log(!new Boolean(""));
+  console.log(!new Boolean(0));
+  console.log(!new Boolean(false));
+  console.log(!new Boolean(null));
+  console.log(!new Boolean(undefined));
+
+  console.log("-------------not-------------");
+
+  console.log(not("test")); // false
+  console.log(not(1)); // false
+  console.log(not(true)); // false
+  console.log(not("")); // true
+  console.log(not(0)); // true
+  console.log(not(false)); // true
+  console.log(not(null)); // true
+  console.log(not(undefined)); // true
+
+  // using (not) these is true because is empty/falsy values
+  console.log(not([])); // new Array()
+  console.log(not(new Boolean("")));
+  console.log(not(new Boolean(0)));
+  console.log(not(new Boolean(false)));
+  console.log(not(new Boolean(null)));
+  console.log(not(new Boolean(undefined)));
+
+  // you can use $() in place of not() (syntactic sugar)
+
+  console.log("-----------typesof-----------");
+
+  // // use typeof directly in this case is the best practice
+  // // one arg (disabled)
+
+  // console.log(typesof(1)); // [ number, true ]
+
+  // two args +
+
+  console.log(typesof(1, 2)); // [ number, true ]
+  console.log(typesof(1, "hi")); // [ [number, string], false ]
+
+  console.log("------------------------------");
+
+  console.log("51 tests passed");
+
+  console.log("7 tests are commented");
+
+  console.log("total tests : 58");
+
+  console.log("============ jsfunx ============");
+}
+
+/**
+ * The name of the main script file that was executed.
+ * Derived from the second CLI argument (`process.argv[1]`).
+ *
+ * @type {string}
+ */
+
+const mainFile = basename(argv[1]);
+
+/**
+ * The name of the currently running module file.
+ * Computed from the current module URL using `fileURLToPath(import.meta.url)`.
+ *
+ * @type {string}
+ */
+
+const currentFile = basename(fileURLToPath(import.meta.url));
+
+if (currentFile === mainFile) {
+  main(); // testing
+}