tiny-essentials 1.8.1 → 1.8.3

package/dist/TinyBasicsEs.js

@@ -2203,8 +2203,8 @@ async function asyncReplace(str, regex, asyncFn) {
  * This implementation ensures a uniform distribution of permutations.
  * Original algorithm source: StackOverflow (link above).
  *
- * @param {string[]} items - The array to shuffle.
- * @returns {string[]} The same array instance, now shuffled in place.
+ * @param {any[]} items - The array to shuffle.
+ * @returns {any[]} The same array instance, now shuffled in place.
  */
 function shuffleArray(items) {
   let currentIndex = items.length,
@@ -2805,6 +2805,49 @@ function getAge(timeData = 0, now = null) {
   return null;
 }
 
+/**
+ * @typedef {Object} FormattedByteResult
+ * @property {string|null} unit - The resulting unit (e.g., 'MB', 'GB') or null if input is invalid.
+ * @property {number|null} value - The numerical value in the chosen unit, or null if input is invalid.
+ */
+
+/**
+ * Converts a byte value into a human-readable format with unit and value separated.
+ *
+ * @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'.
+ * @returns {FormattedByteResult} An object with the converted value and its corresponding unit. Returns nulls if input is invalid.
+ *
+ * @example
+ * formatBytes(123456789);
+ * // → { unit: 'MB', value: 117.74 }
+ *
+ * @example
+ * formatBytes(1073741824, 2, 'MB');
+ * // → { unit: 'MB', value: 1024 }
+ */
+function formatBytes(bytes, decimals = null, maxUnit = null) {
+  if (typeof bytes !== 'number' || bytes < 0) return { unit: null, value: null };
+  if (bytes === 0) return { unit: 'Bytes', value: 0 };
+
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
+
+  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);
+
+  let value = bytes / Math.pow(k, i);
+
+  if (decimals !== null) {
+    const dm = decimals < 0 ? 0 : decimals;
+    value = parseFloat(value.toFixed(dm));
+  }
+
+  const unit = sizes[i];
+  return { unit, value };
+}
+
 ;// ./src/v1/basics/text.mjs
 /**
  * Converts a string to title case where the first letter of each word is capitalized.

package/dist/TinyEssentials.js

@@ -2349,8 +2349,8 @@ class TinyLevelUp {
  * This implementation ensures a uniform distribution of permutations.
  * Original algorithm source: StackOverflow (link above).
  *
- * @param {string[]} items - The array to shuffle.
- * @returns {string[]} The same array instance, now shuffled in place.
+ * @param {any[]} items - The array to shuffle.
+ * @returns {any[]} The same array instance, now shuffled in place.
  */
 function shuffleArray(items) {
   let currentIndex = items.length,
@@ -2951,6 +2951,49 @@ function getAge(timeData = 0, now = null) {
   return null;
 }
 
+/**
+ * @typedef {Object} FormattedByteResult
+ * @property {string|null} unit - The resulting unit (e.g., 'MB', 'GB') or null if input is invalid.
+ * @property {number|null} value - The numerical value in the chosen unit, or null if input is invalid.
+ */
+
+/**
+ * Converts a byte value into a human-readable format with unit and value separated.
+ *
+ * @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'.
+ * @returns {FormattedByteResult} An object with the converted value and its corresponding unit. Returns nulls if input is invalid.
+ *
+ * @example
+ * formatBytes(123456789);
+ * // → { unit: 'MB', value: 117.74 }
+ *
+ * @example
+ * formatBytes(1073741824, 2, 'MB');
+ * // → { unit: 'MB', value: 1024 }
+ */
+function formatBytes(bytes, decimals = null, maxUnit = null) {
+  if (typeof bytes !== 'number' || bytes < 0) return { unit: null, value: null };
+  if (bytes === 0) return { unit: 'Bytes', value: 0 };
+
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
+
+  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);
+
+  let value = bytes / Math.pow(k, i);
+
+  if (decimals !== null) {
+    const dm = decimals < 0 ? 0 : decimals;
+    value = parseFloat(value.toFixed(dm));
+  }
+
+  const unit = sizes[i];
+  return { unit, value };
+}
+
 ;// ./src/v1/basics/text.mjs
 /**
  * Converts a string to title case where the first letter of each word is capitalized.

package/dist/v1/basics/array.cjs

@@ -8,8 +8,8 @@
  * This implementation ensures a uniform distribution of permutations.
  * Original algorithm source: StackOverflow (link above).
  *
- * @param {string[]} items - The array to shuffle.
- * @returns {string[]} The same array instance, now shuffled in place.
+ * @param {any[]} items - The array to shuffle.
+ * @returns {any[]} The same array instance, now shuffled in place.
  */
 function shuffleArray(items) {
   let currentIndex = items.length,

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

@@ -4,8 +4,8 @@
  * This implementation ensures a uniform distribution of permutations.
  * Original algorithm source: StackOverflow (link above).
  *
- * @param {string[]} items - The array to shuffle.
- * @returns {string[]} The same array instance, now shuffled in place.
+ * @param {any[]} items - The array to shuffle.
+ * @returns {any[]} The same array instance, now shuffled in place.
  */
-export function shuffleArray(items: string[]): string[];
+export function shuffleArray(items: any[]): any[];
 //# sourceMappingURL=array.d.mts.map

package/dist/v1/basics/array.mjs

@@ -5,8 +5,8 @@
  * This implementation ensures a uniform distribution of permutations.
  * Original algorithm source: StackOverflow (link above).
  *
- * @param {string[]} items - The array to shuffle.
- * @returns {string[]} The same array instance, now shuffled in place.
+ * @param {any[]} items - The array to shuffle.
+ * @returns {any[]} The same array instance, now shuffled in place.
  */
 export function shuffleArray(items) {
     let currentIndex = items.length, randomIndex;

package/dist/v1/basics/simpleMath.cjs

@@ -83,6 +83,50 @@ function getAge(timeData = 0, now = null) {
   return null;
 }
 
+/**
+ * @typedef {Object} FormattedByteResult
+ * @property {string|null} unit - The resulting unit (e.g., 'MB', 'GB') or null if input is invalid.
+ * @property {number|null} value - The numerical value in the chosen unit, or null if input is invalid.
+ */
+
+/**
+ * Converts a byte value into a human-readable format with unit and value separated.
+ *
+ * @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'.
+ * @returns {FormattedByteResult} An object with the converted value and its corresponding unit. Returns nulls if input is invalid.
+ *
+ * @example
+ * formatBytes(123456789);
+ * // → { unit: 'MB', value: 117.74 }
+ *
+ * @example
+ * formatBytes(1073741824, 2, 'MB');
+ * // → { unit: 'MB', value: 1024 }
+ */
+function formatBytes(bytes, decimals = null, maxUnit = null) {
+  if (typeof bytes !== 'number' || bytes < 0) return { unit: null, value: null };
+  if (bytes === 0) return { unit: 'Bytes', value: 0 };
+
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
+
+  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);
+
+  let value = bytes / Math.pow(k, i);
+
+  if (decimals !== null) {
+    const dm = decimals < 0 ? 0 : decimals;
+    value = parseFloat(value.toFixed(dm));
+  }
+
+  const unit = sizes[i];
+  return { unit, value };
+}
+
+exports.formatBytes = formatBytes;
 exports.getAge = getAge;
 exports.getSimplePerc = getSimplePerc;
 exports.ruleOfThree = ruleOfThree;

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

@@ -52,4 +52,36 @@ export function getSimplePerc(price: number, percentage: number): number;
  * @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;
+/**
+ * @typedef {Object} FormattedByteResult
+ * @property {string|null} unit - The resulting unit (e.g., 'MB', 'GB') or null if input is invalid.
+ * @property {number|null} value - The numerical value in the chosen unit, or null if input is invalid.
+ */
+/**
+ * Converts a byte value into a human-readable format with unit and value separated.
+ *
+ * @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'.
+ * @returns {FormattedByteResult} An object with the converted value and its corresponding unit. Returns nulls if input is invalid.
+ *
+ * @example
+ * formatBytes(123456789);
+ * // → { unit: 'MB', value: 117.74 }
+ *
+ * @example
+ * formatBytes(1073741824, 2, 'MB');
+ * // → { unit: 'MB', value: 1024 }
+ */
+export function formatBytes(bytes: number, decimals?: number | null, maxUnit?: string | null): FormattedByteResult;
+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

package/dist/v1/basics/simpleMath.mjs

@@ -73,3 +73,41 @@ export function getAge(timeData = 0, now = null) {
     }
     return null;
 }
+/**
+ * @typedef {Object} FormattedByteResult
+ * @property {string|null} unit - The resulting unit (e.g., 'MB', 'GB') or null if input is invalid.
+ * @property {number|null} value - The numerical value in the chosen unit, or null if input is invalid.
+ */
+/**
+ * Converts a byte value into a human-readable format with unit and value separated.
+ *
+ * @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'.
+ * @returns {FormattedByteResult} An object with the converted value and its corresponding unit. Returns nulls if input is invalid.
+ *
+ * @example
+ * formatBytes(123456789);
+ * // → { unit: 'MB', value: 117.74 }
+ *
+ * @example
+ * formatBytes(1073741824, 2, 'MB');
+ * // → { unit: 'MB', value: 1024 }
+ */
+export function formatBytes(bytes, decimals = null, maxUnit = null) {
+    if (typeof bytes !== 'number' || bytes < 0)
+        return { unit: null, value: null };
+    if (bytes === 0)
+        return { unit: 'Bytes', value: 0 };
+    const k = 1024;
+    const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
+    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);
+    let value = bytes / Math.pow(k, i);
+    if (decimals !== null) {
+        const dm = decimals < 0 ? 0 : decimals;
+        value = parseFloat(value.toFixed(dm));
+    }
+    const unit = sizes[i];
+    return { unit, value };
+}

package/docs/basics/simpleMath.md

@@ -63,3 +63,59 @@ If the `timeData` is not provided or is invalid, the function returns `null`.
 ```js
 getAge('1990-01-01'); // → 35 (assuming the current year is 2025)
 ```
+
+---
+
+### 📦 `formatBytes(bytes, decimals, maxUnit)`
+
+Converts a byte value into a human-readable format with the unit and value separated. It allows you to set the number of decimal places and restricts the conversion to a specified maximum unit (optional). 🌐
+
+### Parameters:
+
+- `bytes` (number) ➡️ **The number of bytes to format.**  
+  Must be a non-negative number.  
+- `decimals` (number|null) ➡️ **The number of decimal places to include in the result.**  
+  Defaults to `2`. If negative, it will be treated as `0`. If `null`, no rounding is applied and the full precision is used.  
+- `maxUnit` (string|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'`.  
+  Defaults to `null`, meaning no restriction.
+
+### Returns:
+
+- **Object** with two properties:
+  - `unit`: (string|null) ➡️ **The unit of the value** (e.g., 'MB', 'GB', etc.).
+  - `value`: (number|null) ➡️ **The formatted byte value.**  
+    If the input is invalid, returns `null` for both.
+
+### Example Usage:
+
+```js
+formatBytes(123456789);
+// Returns: { unit: 'MB', value: 117.74 }
+```
+
+```js
+formatBytes(1073741824, 2, 'MB');
+// Returns: { unit: 'MB', value: 1024 }
+```
+
+```js
+formatBytes(10485760); 
+// Returns: { unit: 'MB', value: 10 }
+
+formatBytes(1073741824); 
+// Returns: { unit: 'GB', value: 1 }
+
+formatBytes(1073741824, 2, 'MB'); 
+// Returns: { unit: 'MB', value: 1024 }
+```
+
+---
+
+### Notes:
+
+* **Formatting:** Converts bytes to the most appropriate unit (from 'Bytes' to 'YB') based on the byte value.
+* **Max Unit:** The `maxUnit` parameter allows you to limit the highest unit for conversion. If not provided, it will convert all the way up to 'YB'.
+* **Decimals:** The result can be customized with a specified number of decimal places for precision. If `decimals` is `null`, no rounding is applied, and the full precision value is returned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",