jsfunx 1.0.0 → 1.0.2

package/jsfunx.mjs

@@ -38,7 +38,11 @@ export const and = "and";
 
 /** @type {string} */
 
-export const or = "or";
+export const bi = "bigint";
+
+/** @type {BigIntConstructor} */
+
+export const BI = BigInt;
 
 /** @type {string} */
 
@@ -46,27 +50,95 @@ export const bigint = "bigint";
 
 /** @type {string} */
 
+export const bool = "boolean";
+
+/** @type {BooleanConstructor} */
+
+export const Bool = Boolean;
+
+/** @type {string} */
+
+export const boolean = "boolean";
+
+/** @type {string} */
+
+export const fn = "function";
+
+/** @type {FunctionConstructor} */
+
+export const Fn = Function;
+
+/** @type {string} */
+
+export const fun = "function";
+
+/** @type {FunctionConstructor} */
+
+export const Fun = Function;
+
+/** @type {string} */
+
 export const func = "function";
 
+/** @type {FunctionConstructor} */
+
+export const Func = Function;
+
+/** @type {null} */
+
+export const nil = null;
+
+/** @type {string} */
+
+export const num = "number";
+
+/** @type {NumberConstructor} */
+
+export const Num = Number;
+
 /** @type {string} */
 
 export const number = "number";
 
 /** @type {string} */
 
+export const obj = "object";
+
+/** @type {ObjectConstructor} */
+
+export const Obj = Object;
+
+/** @type {string} */
+
 export const object = "object";
 
 /** @type {string} */
 
+export const or = "or";
+
+/** @type {string} */
+
+export const str = "string";
+
+/** @type {StringConstructor} */
+
+export const Str = String;
+
+/** @type {string} */
+
 export const string = "string";
 
 /** @type {string} */
 
-export const symbol = "symbol";
+export const sym = "symbol";
+
+/** @type {SymbolConstructor} */
+
+export const Sym = Symbol;
 
 /** @type {string} */
 
-export const boolean = "boolean";
+export const symbol = "symbol";
 
 /** @type {string} */
 
@@ -88,17 +160,62 @@ export const undef = "undefined";
  */
 
 function checkType(data, dataType, logic, match, strict) {
-  // if data or dataType is Array must be nested Array
+  /** @type {Set<string | null | undefined>} */
+
+  let setOfTypes = new Set([
+    and,
+    bi,
+    bool,
+    fn,
+    null,
+    num,
+    obj,
+    or,
+    str,
+    sym,
+    undef,
+    undefined,
+  ]);
 
   if (!(dataType instanceof Array)) {
+    if (!setOfTypes.has(dataType)) {
+      throw new TypeError("type undefined !");
+    }
+
     if (!(data instanceof Array)) {
+      if (data === null) {
+        return dataType === null;
+      }
+
+      if (dataType === undefined) {
+        return data === undefined;
+      }
+
       return typeof data === dataType;
     }
 
-    if (logic === and) {
+    if (data.length === 0) {
+      data[0] = [];
+    }
+
+    if (logic === and || (logic instanceof String && logic.valueOf() === and)) {
       for (let dt of data) {
         // 1 step directly in all cases
 
+        if (dt === null) {
+          if (dataType !== null) {
+            return false;
+          }
+          continue;
+        }
+
+        if (dataType === undefined) {
+          if (dt !== undefined) {
+            return false;
+          }
+          continue;
+        }
+
         if (!(typeof dt === dataType)) {
           return false;
         }
@@ -114,10 +231,24 @@ function checkType(data, dataType, logic, match, strict) {
       return true;
     }
 
-    if (logic === or) {
+    if (logic === or || (logic instanceof String && logic.valueOf() === or)) {
       for (let dt of data) {
         // 1 step directly in all cases
 
+        if (dt === null) {
+          if (dataType === null) {
+            return true;
+          }
+          continue;
+        }
+
+        if (dataType === undefined) {
+          if (dt === undefined) {
+            return true;
+          }
+          continue;
+        }
+
         if (typeof dt === dataType) {
           return true;
         }
@@ -140,6 +271,24 @@ function checkType(data, dataType, logic, match, strict) {
     for (let dtype of dataType) {
       // 1 step directly in all cases
 
+      if (!setOfTypes.has(dtype)) {
+        throw new TypeError(`type ${dtype} undefined !`);
+      }
+
+      if (data === null) {
+        if (dtype === null) {
+          return true;
+        }
+        continue;
+      }
+
+      if (dtype === undefined) {
+        if (data === undefined) {
+          return true;
+        }
+        continue;
+      }
+
       if (typeof data === dtype) {
         return true;
       }
@@ -155,10 +304,32 @@ function checkType(data, dataType, logic, match, strict) {
     return false;
   }
 
-  if (!match) {
-    if (logic === and) {
+  if (data.length === 0) {
+    data[0] = [];
+  }
+
+  if (not(match)) {
+    if (logic === and || (logic instanceof String && logic.valueOf() === and)) {
       outerLoop: for (let dt of data) {
         for (let dtype of dataType) {
+          if (!setOfTypes.has(dtype)) {
+            throw new TypeError(`type ${dtype} undefined !`);
+          }
+
+          if (dt === null) {
+            if (dtype === null) {
+              continue outerLoop;
+            }
+            continue;
+          }
+
+          if (dtype === undefined) {
+            if (dt === undefined) {
+              continue outerLoop;
+            }
+            continue;
+          }
+
           if (typeof dt === dtype) {
             continue outerLoop;
           }
@@ -196,6 +367,24 @@ function checkType(data, dataType, logic, match, strict) {
 
       //   //   // the same as this
 
+      //   //   // if (!setOfTypes.has(dtype)) {
+      //   //   //   throw new TypeError(`type ${dtype} undefined !`);
+      //   //   // }
+
+      //   //   // if (data[0] === null) {
+      //   //   //   if (dtype === null) {
+      //   //   //     return true;
+      //   //   //   }
+      //   //   //   continue;
+      //   //   // }
+
+      //   //   // if (dtype === undefined) {
+      //   //   //   if (data[0] === undefined) {
+      //   //   //     return true;
+      //   //   //   }
+      //   //   //   continue;
+      //   //   // }
+
       //   //   // if (typeof data[0] === dtype) {
       //   //   //   return true;
       //   //   // }
@@ -228,6 +417,24 @@ function checkType(data, dataType, logic, match, strict) {
 
       //   //   // the same as this
 
+      //   //   // if (!setOfTypes.has(dataType[0])) {
+      //   //   //   throw new TypeError("type undefined !");
+      //   //   // }
+
+      //   //   // if (dt === null) {
+      //   //   //   if (dataType[0] !== null) {
+      //   //   //     return false;
+      //   //   //   }
+      //   //   //   continue;
+      //   //   // }
+
+      //   //   // if (dataType[0] === undefined) {
+      //   //   //   if (dt !== undefined) {
+      //   //   //     return false;
+      //   //   //   }
+      //   //   //   continue;
+      //   //   // }
+
       //   //   // if (!(typeof dt === dataType[0])) {
       //   //   //   return false;
       //   //   // }
@@ -283,9 +490,27 @@ function checkType(data, dataType, logic, match, strict) {
       // return true;
     }
 
-    if (logic === or) {
+    if (logic === or || (logic instanceof String && logic.valueOf() === or)) {
       for (let dt of data) {
         for (let dtype of dataType) {
+          if (!setOfTypes.has(dtype)) {
+            throw new TypeError(`type ${dtype} undefined !`);
+          }
+
+          if (dt === null) {
+            if (dtype === null) {
+              return true;
+            }
+            continue;
+          }
+
+          if (dtype === undefined) {
+            if (dt === undefined) {
+              return true;
+            }
+            continue;
+          }
+
           if (typeof dt === dtype) {
             return true;
           }
@@ -319,6 +544,24 @@ function checkType(data, dataType, logic, match, strict) {
 
       //   //   // the same as this
 
+      //   //   // if (!setOfTypes.has(dtype)) {
+      //   //   //   throw new TypeError(`type ${dtype} undefined !`);
+      //   //   // }
+
+      //   //   // if (data[0] === null) {
+      //   //   //   if (dtype === null) {
+      //   //   //     return true;
+      //   //   //   }
+      //   //   //   continue;
+      //   //   // }
+
+      //   //   // if (dtype === undefined) {
+      //   //   //   if (data[0] === undefined) {
+      //   //   //     return true;
+      //   //   //   }
+      //   //   //   continue;
+      //   //   // }
+
       //   //   // if (typeof data[0] === dtype) {
       //   //   //   return true;
       //   //   // }
@@ -353,9 +596,27 @@ function checkType(data, dataType, logic, match, strict) {
 
       //   //   // the same as this
 
-      //   //   if (typeof dt === dataType[0]) {
-      //   //     return true;
-      //   //   }
+      //   //   // if (!setOfTypes.has(dataType[0])) {
+      //   //   //   throw new TypeError("type undefined !");
+      //   //   // }
+
+      //   //   // if (dt === null) {
+      //   //   //   if (dataType[0] === null) {
+      //   //   //     return true;
+      //   //   //   }
+      //   //   //   continue;
+      //   //   // }
+
+      //   //   // if (dataType[0] === undefined) {
+      //   //   //   if (dt === undefined) {
+      //   //   //     return true;
+      //   //   //   }
+      //   //   //   continue;
+      //   //   // }
+
+      //   //   // if (typeof dt === dataType[0]) {
+      //   //   //   return true;
+      //   //   // }
       //   // }
 
       //   // shared return
@@ -464,10 +725,28 @@ function checkType(data, dataType, logic, match, strict) {
       min = dataType.length;
     }
 
-    if (logic === and) {
+    if (logic === and || (logic instanceof String && logic.valueOf() === and)) {
       for (let i = 0; i < min; ++i) {
         // 1 step directly in all cases
 
+        if (!setOfTypes.has(dataType[i])) {
+          throw new TypeError(`type ${dataType[i]} undefined !`);
+        }
+
+        if (data[i] === null) {
+          if (dataType[i] !== null) {
+            return false;
+          }
+          continue;
+        }
+
+        if (dataType[i] === undefined) {
+          if (data[i] !== undefined) {
+            return false;
+          }
+          continue;
+        }
+
         if (!(typeof data[i] === dataType[i])) {
           return false;
         }
@@ -485,10 +764,28 @@ function checkType(data, dataType, logic, match, strict) {
       return true;
     }
 
-    if (logic === or) {
+    if (logic === or || (logic instanceof String && logic.valueOf() === or)) {
       for (let i = 0; i < min; ++i) {
         // 1 step directly in all cases
 
+        if (!setOfTypes.has(dataType[i])) {
+          throw new TypeError(`type ${dataType[i]} undefined !`);
+        }
+
+        if (data[i] === null) {
+          if (dataType[i] === null) {
+            return true;
+          }
+          continue;
+        }
+
+        if (dataType[i] === undefined) {
+          if (data[i] === undefined) {
+            return true;
+          }
+          continue;
+        }
+
         if (typeof data[i] === dataType[i]) {
           return true;
         }
@@ -509,10 +806,28 @@ function checkType(data, dataType, logic, match, strict) {
     throw new TypeError("logic type undefined !");
   }
 
-  if (logic === and) {
+  if (logic === and || (logic instanceof String && logic.valueOf() === and)) {
     for (let i = 0; i < data.length; ++i) {
       // 1 step directly in all cases
 
+      if (!setOfTypes.has(dataType[i])) {
+        throw new TypeError(`type ${dataType[i]} undefined !`);
+      }
+
+      if (data[i] === null) {
+        if (dataType[i] !== null) {
+          return false;
+        }
+        continue;
+      }
+
+      if (dataType[i] === undefined) {
+        if (data[i] !== undefined) {
+          return false;
+        }
+        continue;
+      }
+
       if (!(typeof data[i] === dataType[i])) {
         return false;
       }
@@ -530,10 +845,28 @@ function checkType(data, dataType, logic, match, strict) {
     return true;
   }
 
-  if (logic === or) {
+  if (logic === or || (logic instanceof String && logic.valueOf() === or)) {
     for (let i = 0; i < data.length; ++i) {
       // 1 step directly in all cases
 
+      if (!setOfTypes.has(dataType[i])) {
+        throw new TypeError(`type ${dataType[i]} undefined !`);
+      }
+
+      if (data[i] === null) {
+        if (dataType[i] === null) {
+          return true;
+        }
+        continue;
+      }
+
+      if (dataType[i] === undefined) {
+        if (data[i] === undefined) {
+          return true;
+        }
+        continue;
+      }
+
       if (typeof data[i] === dataType[i]) {
         return true;
       }
@@ -571,7 +904,7 @@ function checkType(data, dataType, logic, match, strict) {
  * @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) {
+function isinstancesof(objs, type, logic, match, strict) {
   if (!(type instanceof Array)) {
     // uncomment (return objs instanceof type)
     // to enable the 1/4 of (one to one)
@@ -592,7 +925,7 @@ function isinstances(objs, type, logic, match, strict) {
       );
     }
 
-    if (logic === and) {
+    if (logic === and || (logic instanceof String && logic.valueOf() === and)) {
       for (let obj of objs) {
         // 1 step directly in all cases
 
@@ -617,7 +950,7 @@ function isinstances(objs, type, logic, match, strict) {
       return true;
     }
 
-    if (logic === or) {
+    if (logic === or || (logic instanceof String && logic.valueOf() === or)) {
       for (let obj of objs) {
         // 1 step directly in all cases
 
@@ -686,8 +1019,12 @@ function isinstances(objs, type, logic, match, strict) {
     );
   }
 
-  if (!match) {
-    if (logic === and) {
+  if (not(match)) {
+    if (objs.length === 0) {
+      objs[0] = [];
+    }
+
+    if (logic === and || (logic instanceof String && logic.valueOf() === and)) {
       outerLoop: for (let obj of objs) {
         for (let dt of type) {
           try {
@@ -820,7 +1157,7 @@ function isinstances(objs, type, logic, match, strict) {
       // return true;
     }
 
-    if (logic === or) {
+    if (logic === or || (logic instanceof String && logic.valueOf() === or)) {
       for (let obj of objs) {
         for (let dt of type) {
           try {
@@ -1007,7 +1344,7 @@ function isinstances(objs, type, logic, match, strict) {
       min = type.length;
     }
 
-    if (logic === and) {
+    if (logic === and || (logic instanceof String && logic.valueOf() === and)) {
       for (let i = 0; i < min; ++i) {
         // 1 step directly in all cases
 
@@ -1034,7 +1371,7 @@ function isinstances(objs, type, logic, match, strict) {
       return true;
     }
 
-    if (logic === or) {
+    if (logic === or || (logic instanceof String && logic.valueOf() === or)) {
       for (let i = 0; i < min; ++i) {
         // 1 step directly in all cases
 
@@ -1064,7 +1401,7 @@ function isinstances(objs, type, logic, match, strict) {
     throw new TypeError("logic type undefined !");
   }
 
-  if (logic === and) {
+  if (logic === and || (logic instanceof String && logic.valueOf() === and)) {
     for (let i = 0; i < objs.length; ++i) {
       // 1 step directly in all cases
 
@@ -1091,7 +1428,7 @@ function isinstances(objs, type, logic, match, strict) {
     return true;
   }
 
-  if (logic === or) {
+  if (logic === or || (logic instanceof String && logic.valueOf() === or)) {
     for (let i = 0; i < objs.length; ++i) {
       // 1 step directly in all cases
 
@@ -1121,6 +1458,21 @@ function isinstances(objs, type, logic, match, strict) {
   throw new TypeError("logic type undefined !");
 }
 
+/**
+ * Logs any number of values to the console.
+ *
+ * @function
+ * @param {...any} data - The values to be logged.
+ * @returns {void}
+ */
+
+export function echo(data) {
+  if (arguments.length > 1) {
+    throw new TypeError('unexpected token ","');
+  }
+  process.stdout.write(data);
+}
+
 /**
  * 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
@@ -1151,7 +1503,7 @@ export function instancesof(
 
   if (len < 2) {
     throw new TypeError(
-      len == 1
+      len === 1
         ? "instancesof() missing 1 required arguments: 'type'"
         : "instancesof() missing 2 required arguments: 'objs' and 'type'"
     );
@@ -1164,30 +1516,70 @@ export function instancesof(
   }
 
   if (len === 3) {
-    switch (arguments[2]) {
-      case true:
-      case false:
-        return isinstances(objs, type, and, logic_or_match, strict);
+    if (checkType(arguments[2], boolean) || arguments[2] instanceof Boolean) {
+      return isinstancesof(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");
+    if (
+      not(checkType(arguments[3], boolean)) &&
+      not(arguments[3] instanceof Boolean)
+    ) {
+      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);
+    if (checkType(arguments[2], boolean) || arguments[2] instanceof Boolean) {
+      return isinstancesof(objs, type, and, logic_or_match, match_or_strict);
     }
   }
 
-  return isinstances(objs, type, logic_or_match, match_or_strict, strict);
+  return isinstancesof(objs, type, logic_or_match, match_or_strict, strict);
+}
+
+/**
+ * Checks whether an object is an instance of a given class or constructor.
+ *
+ * @function
+ * @param {any} obj - The object to check.
+ * @param {Function} cls - The class or constructor to check against.
+ * @returns {boolean} True if `obj` is an instance of `cls`, otherwise false.
+ * @throws {TypeError} If `cls` is not a valid constructor.
+ */
+
+export function isinstance(obj, cls) {
+  try {
+    return obj instanceof cls;
+  } catch (error) {
+    throw new TypeError("Right-hand side of 'isinstance' is not callable");
+  }
+}
+
+/**
+ * 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 isinstances(
+  objs,
+  type,
+  logic_or_match = and,
+  match_or_strict = true,
+  strict = true
+) {
+  return instancesof(objs, type, logic_or_match, match_or_strict, strict);
 }
 
 /**
@@ -1218,7 +1610,7 @@ export function isType(
 
   if (len < 2) {
     throw new TypeError(
-      len == 1
+      len === 1
         ? "isType() missing 1 required arguments: 'dataType'"
         : "isType() missing 2 required arguments: 'data' and 'dataType'"
     );
@@ -1231,32 +1623,43 @@ export function isType(
   }
 
   if (len === 3) {
-    switch (arguments[2]) {
-      case true:
-      case false:
-        return checkType(data, dataType, and, logic_or_match, strict);
+    if (checkType(arguments[2], boolean) || arguments[2] instanceof Boolean) {
+      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");
+    if (
+      not(checkType(arguments[3], boolean)) &&
+      not(arguments[3] instanceof Boolean)
+    ) {
+      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);
+    if (checkType(arguments[2], boolean) || arguments[2] instanceof Boolean) {
+      return checkType(data, dataType, and, logic_or_match, match_or_strict);
     }
   }
 
   return checkType(data, dataType, logic_or_match, match_or_strict, strict);
 }
 
+/**
+ * Returns the length of an iterable or object that has a `length` property.
+ *
+ * @function
+ * @param {any} iter - The value to measure. Must have a `length` property.
+ * @returns {number} The length of the given value.
+ * @throws {TypeError} If the value does not have a `length` property.
+ */
+
+export function len(iter) {
+  if (iter.length === undefined) {
+    throw new TypeError(`type '${typeof iter}' has no len()`);
+  }
+  return iter.length;
+}
+
 /**
  * Checks whether all provided values have the same length.
  * Each value must have a numeric `length` property (e.g., arrays, strings, typed arrays, etc.).
@@ -1312,6 +1715,35 @@ export function lengths(...objs) {
   return [lens, equal];
 }
 
+/**
+ * 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 lens(...objs) {
+  return lengths(...objs);
+}
+
+/**
+ * Logs any number of values to the console.
+ *
+ * @function
+ * @param {...any} data - The values to be logged.
+ * @returns {void}
+ */
+
+export function log(...data) {
+  console.log(...data);
+}
+
 /**
  * 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.
@@ -1332,6 +1764,86 @@ export function not(obj) {
   return obj?.length === 0 || !obj; // handling the object case
 }
 
+/**
+ * Logs any number of values to the console.
+ *
+ * @function
+ * @param {...any} data - The values to be logged.
+ * @returns {void}
+ */
+
+export function print(...data) {
+  console.log(...data);
+}
+
+/**
+ * Logs any number of values to the console.
+ *
+ * @function
+ * @param {...any} data - The values to be logged.
+ * @returns {void}
+ */
+
+export function printf(data) {
+  if (arguments.length > 1) {
+    throw new TypeError('unexpected token ","');
+  }
+  process.stdout.write(...data);
+}
+
+/**
+ * Logs any number of values to the console.
+ *
+ * @function
+ * @param {...any} data - The values to be logged.
+ * @returns {void}
+ */
+
+export function println(...data) {
+  console.log(...data);
+}
+
+/**
+ * Logs any number of values to the console.
+ *
+ * @function
+ * @param {...any} data - The values to be logged.
+ * @returns {void}
+ */
+
+export function puts(...data) {
+  console.log(...data);
+}
+
+/**
+ * Returns the JavaScript type of a value using the `typeof` operator.
+ *
+ * @function
+ * @param {any} data - The value whose type will be determined.
+ * @returns {string} The type of the value (e.g., "string", "number", "object", "undefined").
+ */
+
+export function type(data) {
+  return typeof data;
+}
+
+/**
+ * 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 types(...objs) {
+  return typesof(...objs);
+}
+
 /**
  * Checks whether all provided values are of the same type.
  * Similar to the `typeof` operator but supports multiple inputs.