tiny-essentials 1.28.0 → 1.28.2

package/dist/v1/basics/objFilter.d.mts

@@ -1,3 +1,7 @@
+import { countObj, isJsonObject } from './objChecker.mjs';
+export { countObj, isJsonObject };
+export type ExtendObjType = Object<string, (val: any) => any>;
+export type ExtendObjTypeArray = Array<[string, (val: any) => any]>;
 /** @typedef {Object.<string, (val: any) => *>} ExtendObjType */
 /** @typedef {Array<[string, (val: any) => *]>} ExtendObjTypeArray */
 /**
@@ -7,22 +11,22 @@
  * If no index is provided, the type is inserted just before 'object' (if it exists), or at the end.
  *
  * @param {ExtendObjType|ExtendObjTypeArray} newItems
- *        - New type validators to be added.
+ * - New type validators to be added.
  * @param {number} [index] - Optional. Position at which to insert each new type. Ignored if the type already exists.
  * @returns {string[]} - A list of successfully added type names.
  *
  * @example
  * extendObjType({
- *   htmlElement2: val => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement
+ * htmlElement2: val => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement
  * });
  *
  * @example
  * extendObjType([
- *   ['alpha', val => typeof val === 'string'],
- *   ['beta', val => Array.isArray(val)]
+ * ['alpha', val => typeof val === 'string'],
+ * ['beta', val => Array.isArray(val)]
  * ]);
  */
-export function extendObjType(newItems: ExtendObjType | ExtendObjTypeArray, index?: number): string[];
+export declare function extendObjType(newItems: ExtendObjType | ExtendObjTypeArray, index?: number): string[];
 /**
  * Reorders the typeValidator.order array according to a custom new order.
  * All values in the new order must already exist in the current order.
@@ -33,24 +37,24 @@ export function extendObjType(newItems: ExtendObjType | ExtendObjTypeArray, inde
  *
  * @example
  * reorderObjTypeOrder([
- *   'string', 'number', 'array', 'object'
+ * 'string', 'number', 'array', 'object'
  * ]);
  */
-export function reorderObjTypeOrder(newOrder: string[]): boolean;
+export declare function reorderObjTypeOrder(newOrder: string[]): boolean;
 /**
  * Returns a cloned version of the `typeValidator.order` array.
  * The cloned array will not be affected by future changes to the original `order`.
  *
  * @returns {string[]} - A new array with the same values as `typeValidator.order`.
  */
-export function cloneObjTypeOrder(): string[];
+export declare function cloneObjTypeOrder(): string[];
 /**
  * Checks the type of a given object or returns its type as a string.
  *
  * @param {*} obj - The object to check or identify.
  * @param {string} [type] - Optional. If provided, checks whether the object matches this type (e.g., "object", "array", "string").
  * @returns {boolean|string|null} - Returns `true` if the type matches, `false` if not,
- *                                   the type string if no type is provided, or `null` if the object is `undefined`.
+ * the type string if no type is provided, or `null` if the object is `undefined`.
  *
  * @example
  * objType([], 'array'); // true
@@ -58,14 +62,14 @@ export function cloneObjTypeOrder(): string[];
  * objType('hello'); // "string"
  * objType(undefined); // null
  */
-export function objType(obj: any, type?: string): boolean | string | null;
+export declare function objType(obj: any, type?: string): boolean | string | null;
 /**
  * Checks the type of a given object and returns the validation value if a known type is detected.
  *
  * @param {*} obj - The object to check or identify.
  * @returns {{ valid:*; type: string | null }} - Returns the type result.
  */
-export function checkObj(obj: any): {
+export declare function checkObj(obj: any): {
     valid: any;
     type: string | null;
 };
@@ -73,14 +77,7 @@ export function checkObj(obj: any): {
  * Creates a clone of the functions from the `typeValidator` object.
  * It returns a new object where the keys are the same and the values are the cloned functions.
  */
-export function getCheckObj(): {
+export declare function getCheckObj(): {
     [k: string]: any;
 };
-export type ExtendObjType = {
-    [x: string]: (val: any) => any;
-};
-export type ExtendObjTypeArray = Array<[string, (val: any) => any]>;
-import { countObj } from './objChecker.mjs';
-import { isJsonObject } from './objChecker.mjs';
-export { countObj, isJsonObject };
 //# sourceMappingURL=objFilter.d.mts.map

package/dist/v1/basics/objFilter.mjs

@@ -28,25 +28,41 @@ const typeValidator = {
  * If no index is provided, the type is inserted just before 'object' (if it exists), or at the end.
  *
  * @param {ExtendObjType|ExtendObjTypeArray} newItems
- *        - New type validators to be added.
+ * - New type validators to be added.
  * @param {number} [index] - Optional. Position at which to insert each new type. Ignored if the type already exists.
  * @returns {string[]} - A list of successfully added type names.
  *
  * @example
  * extendObjType({
- *   htmlElement2: val => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement
+ * htmlElement2: val => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement
  * });
  *
  * @example
  * extendObjType([
- *   ['alpha', val => typeof val === 'string'],
- *   ['beta', val => Array.isArray(val)]
+ * ['alpha', val => typeof val === 'string'],
+ * ['beta', val => Array.isArray(val)]
  * ]);
  */
 export function extendObjType(newItems, index) {
+    if (typeof newItems !== 'object' || newItems === null) {
+        throw new TypeError("Argument 'newItems' must be an object or an array.");
+    }
+    if (typeof index !== 'undefined' && typeof index !== 'number') {
+        throw new TypeError("Argument 'index' must be a number.");
+    }
     const added = [];
     const entries = Array.isArray(newItems) ? newItems : Object.entries(newItems);
-    for (const [key, fn] of entries) {
+    for (const entry of entries) {
+        if (!Array.isArray(entry) || entry.length < 2) {
+            throw new TypeError("Each item in 'newItems' array must be a [key, function] pair.");
+        }
+        const [key, fn] = entry;
+        if (typeof key !== 'string') {
+            throw new TypeError('Validator key must be a string.');
+        }
+        if (typeof fn !== 'function') {
+            throw new TypeError(`Validator for key '${key}' must be a function.`);
+        }
         if (!typeValidator.items.hasOwnProperty(key)) {
             // @ts-ignore
             typeValidator.items[key] = fn;
@@ -74,10 +90,16 @@ export function extendObjType(newItems, index) {
  *
  * @example
  * reorderObjTypeOrder([
- *   'string', 'number', 'array', 'object'
+ * 'string', 'number', 'array', 'object'
  * ]);
  */
 export function reorderObjTypeOrder(newOrder) {
+    if (!Array.isArray(newOrder)) {
+        throw new TypeError("Argument 'newOrder' must be an array of strings.");
+    }
+    if (!newOrder.every((item) => typeof item === 'string')) {
+        throw new TypeError("All elements in 'newOrder' must be strings.");
+    }
     const currentOrder = [...typeValidator.order]; // shallow clone
     // All keys in newOrder must exist in currentOrder
     const isValid = newOrder.every((type) => currentOrder.includes(type));
@@ -131,7 +153,7 @@ const getType = (val) => {
  * @param {*} obj - The object to check or identify.
  * @param {string} [type] - Optional. If provided, checks whether the object matches this type (e.g., "object", "array", "string").
  * @returns {boolean|string|null} - Returns `true` if the type matches, `false` if not,
- *                                   the type string if no type is provided, or `null` if the object is `undefined`.
+ * the type string if no type is provided, or `null` if the object is `undefined`.
  *
  * @example
  * objType([], 'array'); // true
@@ -142,6 +164,9 @@ const getType = (val) => {
 export function objType(obj, type) {
     if (typeof obj === 'undefined')
         return null;
+    if (typeof type !== 'undefined' && typeof type !== 'string') {
+        throw new TypeError("Argument 'type' must be a string.");
+    }
     const result = getType(obj);
     if (typeof type === 'string')
         return result === type.toLowerCase();
@@ -221,7 +246,10 @@ extendObjType([
     ],
     [
         'array',
-        /** @param {*} val @returns {val is any[]} */
+        /**
+         * @template {any} Value
+         * @param {*} val @returns {val is Value[]}
+         */
         (val) => Array.isArray(val),
     ],
 ]);
@@ -247,27 +275,44 @@ extendObjType([
     ],
     [
         'map',
-        /** @param {*} val @returns {val is Map<unknown, unknown>} */
+        /**
+         * @template {any} Key
+         * @template {any} Value
+         * @param {*} val @returns {val is Map<Key, Value>}
+         */
         (val) => val instanceof Map,
     ],
     [
         'set',
-        /** @param {*} val @returns {val is Set<unknown>} */
+        /**
+         * @template {any} Value
+         * @param {*} val @returns {val is Set<Value>}
+         */
         (val) => val instanceof Set,
     ],
     [
         'weakmap',
-        /** @param {*} val @returns {val is WeakMap<unknown, unknown>} */
+        /**
+         * @template {WeakKey} Key
+         * @template {any} Value
+         * @param {*} val @returns {val is WeakMap<Key, Value>}
+         */
         (val) => val instanceof WeakMap,
     ],
     [
         'weakset',
-        /** @param {*} val @returns {val is WeakSet<unknown>} */
+        /**
+         * @template {WeakKey} Value
+         * @param {*} val @returns {val is WeakSet<Value>}
+         */
         (val) => val instanceof WeakSet,
     ],
     [
         'promise',
-        /** @param {*} val @returns {val is Promise<unknown>} */
+        /**
+         * @template {any} Value
+         * @param {*} val @returns {val is Promise<Value>}
+         */
         (val) => val instanceof Promise,
     ],
 ]);
@@ -283,7 +328,11 @@ if (isBrowser) {
 extendObjType([
     [
         'object',
-        /** @param {*} val @returns {val is Record<string | number | symbol, unknown>} */
+        /**
+         * @template {string | number | symbol} Key
+         * @template {any} Value
+         * @param {*} val @returns {val is Record<Key, Value>}
+         */
         (val) => isJsonObject(val),
     ],
 ]);

package/dist/v1/basics/simpleMath.cjs

@@ -36,6 +36,14 @@
  * ruleOfThree.execute(2, 6, 3, true); // → 4
  */
 function ruleOfThree(val1, val2, val3, inverse = false) {
+  if (typeof val1 !== 'number' || !Number.isFinite(val1))
+    throw new TypeError('val1 must be a finite number.');
+  if (typeof val2 !== 'number' || !Number.isFinite(val2))
+    throw new TypeError('val2 must be a finite number.');
+  if (typeof val3 !== 'number' || !Number.isFinite(val3))
+    throw new TypeError('val3 must be a finite number.');
+  if (typeof inverse !== 'boolean') throw new TypeError('inverse must be a boolean.');
+
   return inverse ? Number(val1 * val2) / val3 : Number(val3 * val2) / val1;
 }
 
@@ -52,6 +60,11 @@ function ruleOfThree(val1, val2, val3, inverse = false) {
  * getSimplePerc(200, 15); // 30
  */
 function getSimplePerc(price, percentage) {
+  if (typeof price !== 'number' || !Number.isFinite(price))
+    throw new TypeError('price must be a finite number.');
+  if (typeof percentage !== 'number' || !Number.isFinite(percentage))
+    throw new TypeError('percentage must be a finite number.');
+
   return price * (percentage / 100);
 }
 
@@ -66,6 +79,11 @@ function getSimplePerc(price, percentage) {
  * getPercentage(5, 100); // 5
  */
 function getPercentage(part, total) {
+  if (typeof part !== 'number' || !Number.isFinite(part))
+    throw new TypeError('part must be a finite number.');
+  if (typeof total !== 'number' || !Number.isFinite(total))
+    throw new TypeError('total must be a finite number.');
+
   if (total === 0) return 0;
   return (part / total) * 100;
 }
@@ -78,27 +96,31 @@ function getPercentage(part, total) {
  * @returns {number|null} The age in years, or null if `timeData` is not provided or invalid.
  */
 function getAge(timeData = 0, now = null) {
-  if (typeof timeData !== 'undefined' && timeData !== null && timeData !== 0) {
-    const birthDate = new Date(timeData);
-    if (Number.isNaN(birthDate.getTime())) return null;
+  if (typeof timeData !== 'number' && typeof timeData !== 'string' && !(timeData instanceof Date)) {
+    throw new TypeError('timeData must be a number, string, or Date object.');
+  }
 
-    const currentDate = now instanceof Date ? now : new Date();
+  if (now !== null && !(now instanceof Date)) {
+    throw new TypeError('now must be a Date object or null.');
+  }
 
-    let age = currentDate.getFullYear() - birthDate.getFullYear();
+  const birthDate = new Date(timeData);
+  if (Number.isNaN(birthDate.getTime())) return null;
 
-    const currentMonth = currentDate.getMonth();
-    const birthMonth = birthDate.getMonth();
+  const currentDate = now instanceof Date ? now : new Date();
 
-    const currentDay = currentDate.getDate();
-    const birthDay = birthDate.getDate();
+  let age = currentDate.getFullYear() - birthDate.getFullYear();
 
-    // Adjust if birthday hasn't occurred yet this year
-    if (currentMonth < birthMonth || (currentMonth === birthMonth && currentDay < birthDay)) age--;
+  const currentMonth = currentDate.getMonth();
+  const birthMonth = birthDate.getMonth();
 
-    return Math.abs(age);
-  }
+  const currentDay = currentDate.getDate();
+  const birthDay = birthDate.getDate();
+
+  // Adjust if birthday hasn't occurred yet this year
+  if (currentMonth < birthMonth || (currentMonth === birthMonth && currentDay < birthDay)) age--;
 
-  return null;
+  return Math.abs(age);
 }
 
 /**
@@ -112,7 +134,7 @@ function getAge(timeData = 0, now = null) {
  *
  * @param {number} bytes - The number of bytes to format. Must be a non-negative number.
  * @param {number|null} [decimals=null] - The number of decimal places to include in the result. Defaults to null. If negative, it will be treated as 0. If null, no rounding is applied.
- * @param {string|null} [maxUnit=null] - Optional unit limit. If provided, restricts conversion to this unit at most (e.g., 'MB' prevents conversion to 'GB' or higher). Must be one of: 'Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'.
+ * @param {'Bytes'|'KB'|'MB'|'GB'|'TB'|'PB'|'EB'|'ZB'|'YB'|null} [maxUnit=null] - Optional unit limit. If provided, restricts conversion to this unit at most (e.g., 'MB' prevents conversion to 'GB' or higher).
  * @returns {FormattedByteResult} An object with the converted value and its corresponding unit. Returns nulls if input is invalid.
  *
  * @example
@@ -124,12 +146,23 @@ function getAge(timeData = 0, now = null) {
  * // → { unit: 'MB', value: 1024 }
  */
 function formatBytes(bytes, decimals = null, maxUnit = null) {
-  if (typeof bytes !== 'number' || bytes < 0) return { unit: null, value: null };
+  if (typeof bytes !== 'number' || !Number.isFinite(bytes) || bytes < 0)
+    throw new TypeError('bytes must be a positive number.');
   if (bytes === 0) return { unit: 'Bytes', value: 0 };
 
+  if (decimals !== null && (typeof decimals !== 'number' || !Number.isFinite(decimals))) {
+    throw new TypeError('decimals must be a number or null.');
+  }
+
   const k = 1024;
   const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
 
+  if (maxUnit !== null) {
+    if (typeof maxUnit !== 'string') throw new TypeError('maxUnit must be a string or null.');
+    if (!sizes.includes(maxUnit))
+      throw new RangeError(`maxUnit must be one of: ${sizes.join(', ')}`);
+  }
+
   const maxIndex = maxUnit && sizes.includes(maxUnit) ? sizes.indexOf(maxUnit) : sizes.length - 1;
   const i = Math.min(Math.floor(Math.log(bytes) / Math.log(k)), maxIndex);
 
@@ -168,8 +201,19 @@ function genFibonacciSeq({
   length = 10,
   combiner = (a, b) => a + b,
 } = {}) {
-  if (!Array.isArray(baseValues) || baseValues.length !== 2)
-    throw new Error('baseValues must be an array of exactly two numbers');
+  if (
+    !Array.isArray(baseValues) ||
+    baseValues.length !== 2 ||
+    !baseValues.every((value) => typeof value === 'number')
+  ) {
+    throw new Error('baseValues must be an array of exactly two numbers.');
+  }
+  if (typeof length !== 'number' || !Number.isInteger(length)) {
+    throw new RangeError('length must be an integer.');
+  }
+  if (typeof combiner !== 'function') {
+    throw new TypeError('combiner must be a function.');
+  }
 
   const sequence = [...baseValues.slice(0, 2)];
 
@@ -192,11 +236,19 @@ function genFibonacciSeq({
  * @returns {number} The calculated price per unit of the asset.
  */
 function calculateMarketcap(originalMarketCap, circulatingSupply) {
-  if (Number.isNaN(originalMarketCap) || !Number.isFinite(originalMarketCap))
-    throw new TypeError('Original market cap must be a number.');
-  if (Number.isNaN(circulatingSupply) || !Number.isFinite(circulatingSupply))
-    throw new TypeError('Circulating supply must be a number.');
-  if (circulatingSupply <= 0) throw new Error('Circulating supply must be greater than zero.');
+  if (
+    typeof originalMarketCap !== 'number' ||
+    Number.isNaN(originalMarketCap) ||
+    !Number.isFinite(originalMarketCap)
+  )
+    throw new TypeError('Original market cap must be a finite number.');
+  if (
+    typeof circulatingSupply !== 'number' ||
+    Number.isNaN(circulatingSupply) ||
+    !Number.isFinite(circulatingSupply)
+  )
+    throw new TypeError('Circulating supply must be a finite number.');
+  if (circulatingSupply <= 0) throw new RangeError('Circulating supply must be greater than zero.');
   return originalMarketCap / circulatingSupply;
 }
 
@@ -212,8 +264,12 @@ function calculateMarketcap(originalMarketCap, circulatingSupply) {
  * }}
  */
 function compareMarketcap(originalMarketCap, circulatingSupply, newMarketCap) {
-  if (Number.isNaN(newMarketCap) || !Number.isFinite(newMarketCap))
-    throw new TypeError('New market cap must be a number.');
+  if (
+    typeof newMarketCap !== 'number' ||
+    Number.isNaN(newMarketCap) ||
+    !Number.isFinite(newMarketCap)
+  )
+    throw new TypeError('New market cap must be a finite number.');
   const originalPrice = calculateMarketcap(originalMarketCap, circulatingSupply);
   const newPrice = typeof newMarketCap === 'number' ? newMarketCap / circulatingSupply : NaN;
   const priceChangePercent =

package/dist/v1/basics/simpleMath.d.mts

@@ -33,7 +33,7 @@
  * // Inverse proportion:
  * ruleOfThree.execute(2, 6, 3, true); // → 4
  */
-export function ruleOfThree(val1: number, val2: number, val3: number, inverse?: boolean): number;
+export declare function ruleOfThree(val1: number, val2: number, val3: number, inverse?: boolean): number;
 /**
  * Calculates the actual value that corresponds to a percentage of a base number.
  * Unlike `getPercentage`, which tells how much something represents in percent,
@@ -46,7 +46,7 @@ export function ruleOfThree(val1: number, val2: number, val3: number, inverse?:
  * @example
  * getSimplePerc(200, 15); // 30
  */
-export function getSimplePerc(price: number, percentage: number): number;
+export declare function getSimplePerc(price: number, percentage: number): number;
 /**
  * Calculates how much percent a partial value represents of the total value.
  *
@@ -57,7 +57,7 @@ export function getSimplePerc(price: number, percentage: number): number;
  * @example
  * getPercentage(5, 100); // 5
  */
-export function getPercentage(part: number, total: number): number;
+export declare function getPercentage(part: number, total: number): number;
 /**
  * Calculates the age based on the given date.
  *
@@ -65,7 +65,17 @@ export function getPercentage(part: number, total: number): number;
  * @param {Date|null} [now=null] - The Date object representing the current date. Defaults to the current date and time if not provided.
  * @returns {number|null} The age in years, or null if `timeData` is not provided or invalid.
  */
-export function getAge(timeData?: number | string | Date, now?: Date | null): number | null;
+export declare function getAge(timeData?: number | string | Date, now?: Date | null): number | null;
+export type FormattedByteResult = {
+    /**
+     * - The resulting unit (e.g., 'MB', 'GB') or null if input is invalid.
+     */
+    unit: string | null;
+    /**
+     * - The numerical value in the chosen unit, or null if input is invalid.
+     */
+    value: number | null;
+};
 /**
  * @typedef {Object} FormattedByteResult
  * @property {string|null} unit - The resulting unit (e.g., 'MB', 'GB') or null if input is invalid.
@@ -76,7 +86,7 @@ export function getAge(timeData?: number | string | Date, now?: Date | null): nu
  *
  * @param {number} bytes - The number of bytes to format. Must be a non-negative number.
  * @param {number|null} [decimals=null] - The number of decimal places to include in the result. Defaults to null. If negative, it will be treated as 0. If null, no rounding is applied.
- * @param {string|null} [maxUnit=null] - Optional unit limit. If provided, restricts conversion to this unit at most (e.g., 'MB' prevents conversion to 'GB' or higher). Must be one of: 'Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'.
+ * @param {'Bytes'|'KB'|'MB'|'GB'|'TB'|'PB'|'EB'|'ZB'|'YB'|null} [maxUnit=null] - Optional unit limit. If provided, restricts conversion to this unit at most (e.g., 'MB' prevents conversion to 'GB' or higher).
  * @returns {FormattedByteResult} An object with the converted value and its corresponding unit. Returns nulls if input is invalid.
  *
  * @example
@@ -87,7 +97,7 @@ export function getAge(timeData?: number | string | Date, now?: Date | null): nu
  * formatBytes(1073741824, 2, 'MB');
  * // → { unit: 'MB', value: 1024 }
  */
-export function formatBytes(bytes: number, decimals?: number | null, maxUnit?: string | null): FormattedByteResult;
+export declare function formatBytes(bytes: number, decimals?: number | null, maxUnit?: 'Bytes' | 'KB' | 'MB' | 'GB' | 'TB' | 'PB' | 'EB' | 'ZB' | 'YB' | null): FormattedByteResult;
 /**
  * Generates a Fibonacci-like sequence as an array of vectors.
  *
@@ -107,10 +117,10 @@ export function formatBytes(bytes: number, decimals?: number | null, maxUnit?: s
  *
  * @beta
  */
-export function genFibonacciSeq({ baseValues, length, combiner, }?: {
-    baseValues?: number[] | undefined;
-    length?: number | undefined;
-    combiner?: ((a: number, b: number, index: number) => number) | undefined;
+export declare function genFibonacciSeq({ baseValues, length, combiner, }?: {
+    baseValues?: number[];
+    length?: number;
+    combiner?: (a: number, b: number, index: number) => number;
 }): number[];
 /**
  * Calculates the unit price of a coin or token based on the market capitalization and circulating supply.
@@ -122,7 +132,7 @@ export function genFibonacciSeq({ baseValues, length, combiner, }?: {
  * @param {number} circulatingSupply - The number of coins/tokens currently in circulation.
  * @returns {number} The calculated price per unit of the asset.
  */
-export function calculateMarketcap(originalMarketCap: number, circulatingSupply: number): number;
+export declare function calculateMarketcap(originalMarketCap: number, circulatingSupply: number): number;
 /**
  * Calculates the new price of a coin when the market cap changes.
  * @param {number} originalMarketCap - The original market cap.
@@ -134,19 +144,9 @@ export function calculateMarketcap(originalMarketCap: number, circulatingSupply:
  *   priceChangePercent: number
  * }}
  */
-export function compareMarketcap(originalMarketCap: number, circulatingSupply: number, newMarketCap: number): {
+export declare function compareMarketcap(originalMarketCap: number, circulatingSupply: number, newMarketCap: number): {
     originalPrice: number;
     newPrice: number;
     priceChangePercent: number;
 };
-export type FormattedByteResult = {
-    /**
-     * - The resulting unit (e.g., 'MB', 'GB') or null if input is invalid.
-     */
-    unit: string | null;
-    /**
-     * - The numerical value in the chosen unit, or null if input is invalid.
-     */
-    value: number | null;
-};
 //# sourceMappingURL=simpleMath.d.mts.map