@jeniex/utils 1.0.14 → 1.0.16

package/browser/index.cjs

@@ -1,17 +1,52 @@
 'use strict';
 
+function noop() { }
+function toString(object) {
+    return Object.prototype.toString.call(object);
+}
+
 function isString(object) {
     return typeof object === 'string';
 }
+function isNumber(object) {
+    return typeof object === 'number';
+}
+function isBoolean(object) {
+    return typeof object === 'boolean';
+}
+function isObject(object) {
+    return toString(object) === '[object Object]';
+}
+// eslint-disable-next-line @typescript-eslint/ban-types
+function isFunction(object) {
+    return typeof object === 'function';
+}
 
-function ensureJoin(object, separator = ',') {
+/**
+ * Joins an array's items or do nothing if it is joined already.
+ *
+ * @category Array
+ */
+function join(object, separator = ',') {
     if (isString(object)) {
         return object;
     }
     return object.join(separator);
 }
 
-function noop() { }
+/**
+ * Removes an item from an array by mutating it.
+ * @throws An error if the object to be removed does not exist inside the array.
+ *
+ * @category Array
+ */
+function remove(array, object) {
+    const index = array.indexOf(object);
+    if (index === -1) {
+        throw new Error('Provided value does not exist inside the array.');
+    }
+    array.splice(index, 1);
+}
 
 function asserted(object) {
     if (object === null || object === undefined) {
@@ -32,6 +67,11 @@ function isNotNullish(object) {
     return object !== null && object !== undefined;
 }
 
+/**
+ * A wrapper around `setTimeout`.
+ *
+ * @category Promise
+ */
 async function sleep(milliSeconds) {
     return new Promise((resolve) => {
         setTimeout(resolve, milliSeconds);
@@ -154,14 +194,14 @@ const fishX = {
 };
 
 function $(selectors, parent) {
-    const element = (parent ?? document).querySelector(ensureJoin(selectors));
+    const element = (parent ?? document).querySelector(join(selectors));
     if (element === null) {
         throw new Error(`Couldn't find the element with the selector ${selectors}`);
     }
     return element;
 }
 function $$(selectors, parent) {
-    const elements = (parent ?? document).querySelectorAll(ensureJoin(selectors));
+    const elements = (parent ?? document).querySelectorAll(join(selectors));
     if (elements.length === 0) {
         throw new Error(`Couldn't find any element with the selector ${selectors}`);
     }
@@ -334,7 +374,6 @@ exports.addStyle = addStyle;
 exports.alert = alert;
 exports.asserted = asserted;
 exports.confirm = confirm;
-exports.ensureJoin = ensureJoin;
 exports.fish = fish;
 exports.fishResponse = fishResponse;
 exports.fishX = fishX;
@@ -342,16 +381,23 @@ exports.fishXResponse = fishXResponse;
 exports.getOptions = getOptions;
 exports.getSearchParam = getSearchParam;
 exports.imageLoad = imageLoad;
+exports.isBoolean = isBoolean;
 exports.isFalsy = isFalsy;
+exports.isFunction = isFunction;
 exports.isNotNullish = isNotNullish;
 exports.isNullish = isNullish;
+exports.isNumber = isNumber;
+exports.isObject = isObject;
 exports.isString = isString;
 exports.isTruthy = isTruthy;
+exports.join = join;
 exports.logId = logId;
 exports.noop = noop;
 exports.pageLoad = pageLoad;
 exports.prompt = prompt;
+exports.remove = remove;
 exports.scriptName = scriptName;
 exports.setSearchParam = setSearchParam;
 exports.sleep = sleep;
 exports.tabURL = tabURL;
+exports.toString = toString;

package/browser/index.d.ts

@@ -1,6 +1,20 @@
-declare function ensureJoin(object: string[] | string, separator?: string): string;
+/**
+ * Joins an array's items or do nothing if it is joined already.
+ *
+ * @category Array
+ */
+declare function join(object: string[] | string, separator?: string): string;
+
+/**
+ * Removes an item from an array by mutating it.
+ * @throws An error if the object to be removed does not exist inside the array.
+ *
+ * @category Array
+ */
+declare function remove<T>(array: T[], object: T): void;
 
 declare function noop(): void;
+declare function toString(object: unknown): string;
 
 declare function asserted<T>(object: T | null | undefined): T;
 declare function isTruthy<T>(object: T): object is Exclude<T, '' | 0 | false | null | undefined>;
@@ -9,7 +23,16 @@ declare function isNullish(object: unknown): object is null | undefined;
 declare function isNotNullish<T>(object: T): object is Exclude<T, null | undefined>;
 
 declare function isString(object: unknown): object is string;
+declare function isNumber(object: unknown): object is number;
+declare function isBoolean(object: unknown): object is boolean;
+declare function isObject(object: unknown): object is object;
+declare function isFunction<T extends Function>(object: unknown): object is T;
 
+/**
+ * A wrapper around `setTimeout`.
+ *
+ * @category Promise
+ */
 declare function sleep(milliSeconds: number): Promise<void>;
 
 type Nullable<T> = T | null | undefined;
@@ -106,4 +129,4 @@ type Options = Record<string, FlagValue>;
 
 declare function getOptions(flags: Flag[]): Promise<Options>;
 
-export { $, $$, Flag, Fn, Nullable, addStyle, alert, asserted, confirm, ensureJoin, fish, fishResponse, fishX, fishXResponse, getOptions, getSearchParam, imageLoad, isFalsy, isNotNullish, isNullish, isString, isTruthy, logId, noop, pageLoad, prompt, scriptName, setSearchParam, sleep, tabURL };
+export { $, $$, Flag, Fn, Nullable, addStyle, alert, asserted, confirm, fish, fishResponse, fishX, fishXResponse, getOptions, getSearchParam, imageLoad, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, logId, noop, pageLoad, prompt, remove, scriptName, setSearchParam, sleep, tabURL, toString };

package/browser/index.js

@@ -1,15 +1,50 @@
+function noop() { }
+function toString(object) {
+    return Object.prototype.toString.call(object);
+}
+
 function isString(object) {
     return typeof object === 'string';
 }
+function isNumber(object) {
+    return typeof object === 'number';
+}
+function isBoolean(object) {
+    return typeof object === 'boolean';
+}
+function isObject(object) {
+    return toString(object) === '[object Object]';
+}
+// eslint-disable-next-line @typescript-eslint/ban-types
+function isFunction(object) {
+    return typeof object === 'function';
+}
 
-function ensureJoin(object, separator = ',') {
+/**
+ * Joins an array's items or do nothing if it is joined already.
+ *
+ * @category Array
+ */
+function join(object, separator = ',') {
     if (isString(object)) {
         return object;
     }
     return object.join(separator);
 }
 
-function noop() { }
+/**
+ * Removes an item from an array by mutating it.
+ * @throws An error if the object to be removed does not exist inside the array.
+ *
+ * @category Array
+ */
+function remove(array, object) {
+    const index = array.indexOf(object);
+    if (index === -1) {
+        throw new Error('Provided value does not exist inside the array.');
+    }
+    array.splice(index, 1);
+}
 
 function asserted(object) {
     if (object === null || object === undefined) {
@@ -30,6 +65,11 @@ function isNotNullish(object) {
     return object !== null && object !== undefined;
 }
 
+/**
+ * A wrapper around `setTimeout`.
+ *
+ * @category Promise
+ */
 async function sleep(milliSeconds) {
     return new Promise((resolve) => {
         setTimeout(resolve, milliSeconds);
@@ -152,14 +192,14 @@ const fishX = {
 };
 
 function $(selectors, parent) {
-    const element = (parent ?? document).querySelector(ensureJoin(selectors));
+    const element = (parent ?? document).querySelector(join(selectors));
     if (element === null) {
         throw new Error(`Couldn't find the element with the selector ${selectors}`);
     }
     return element;
 }
 function $$(selectors, parent) {
-    const elements = (parent ?? document).querySelectorAll(ensureJoin(selectors));
+    const elements = (parent ?? document).querySelectorAll(join(selectors));
     if (elements.length === 0) {
         throw new Error(`Couldn't find any element with the selector ${selectors}`);
     }
@@ -326,4 +366,4 @@ async function getOptions(flags) {
     return options;
 }
 
-export { $, $$, addStyle, alert, asserted, confirm, ensureJoin, fish, fishResponse, fishX, fishXResponse, getOptions, getSearchParam, imageLoad, isFalsy, isNotNullish, isNullish, isString, isTruthy, logId, noop, pageLoad, prompt, scriptName, setSearchParam, sleep, tabURL };
+export { $, $$, addStyle, alert, asserted, confirm, fish, fishResponse, fishX, fishXResponse, getOptions, getSearchParam, imageLoad, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, logId, noop, pageLoad, prompt, remove, scriptName, setSearchParam, sleep, tabURL, toString };

package/node/index.cjs

@@ -4,18 +4,53 @@ var fs = require('node:fs');
 var fsp = require('node:fs/promises');
 var path = require('node:path');
 
+function noop() { }
+function toString(object) {
+    return Object.prototype.toString.call(object);
+}
+
 function isString(object) {
     return typeof object === 'string';
 }
+function isNumber(object) {
+    return typeof object === 'number';
+}
+function isBoolean(object) {
+    return typeof object === 'boolean';
+}
+function isObject(object) {
+    return toString(object) === '[object Object]';
+}
+// eslint-disable-next-line @typescript-eslint/ban-types
+function isFunction(object) {
+    return typeof object === 'function';
+}
 
-function ensureJoin(object, separator = ',') {
+/**
+ * Joins an array's items or do nothing if it is joined already.
+ *
+ * @category Array
+ */
+function join(object, separator = ',') {
     if (isString(object)) {
         return object;
     }
     return object.join(separator);
 }
 
-function noop() { }
+/**
+ * Removes an item from an array by mutating it.
+ * @throws An error if the object to be removed does not exist inside the array.
+ *
+ * @category Array
+ */
+function remove(array, object) {
+    const index = array.indexOf(object);
+    if (index === -1) {
+        throw new Error('Provided value does not exist inside the array.');
+    }
+    array.splice(index, 1);
+}
 
 function asserted(object) {
     if (object === null || object === undefined) {
@@ -36,6 +71,11 @@ function isNotNullish(object) {
     return object !== null && object !== undefined;
 }
 
+/**
+ * A wrapper around `setTimeout`.
+ *
+ * @category Promise
+ */
 async function sleep(milliSeconds) {
     return new Promise((resolve) => {
         setTimeout(resolve, milliSeconds);
@@ -92,6 +132,28 @@ async function listFolders({ folderPath, getFullPath }) {
     return folders;
 }
 
+/**
+ * Get a list of folders that are present in the provided folder path.
+ * If the provided folder path does not exists, an error will be thrown.
+ */
+function listFoldersSync({ folderPath, getFullPath }) {
+    if (fs.existsSync(folderPath) === false) {
+        throw new Error('The provided folder path does not exist!');
+    }
+    const entries = fs.readdirSync(folderPath, {
+        withFileTypes: true,
+    });
+    const folders = entries
+        .filter((entry) => entry.isDirectory() === true)
+        .map((folderEntry) => {
+        if (getFullPath === true) {
+            return path.join(folderPath, folderEntry.name);
+        }
+        return folderEntry.name;
+    });
+    return folders;
+}
+
 async function removeFiles({ folderPath, filter }) {
     const nestedFilePathPattern = `${path.resolve('./')}\\`;
     if (!folderPath.startsWith(nestedFilePathPattern)) {
@@ -103,15 +165,37 @@ async function removeFiles({ folderPath, filter }) {
     }
 }
 
+async function readJSON(filePath, withComments = false) {
+    const stringJSON = await fsp.readFile(filePath, 'utf-8');
+    if (withComments === true) {
+        try {
+            const { default: JSON5 } = await import('json5');
+            return JSON5.parse(stringJSON);
+        }
+        catch (exception) {
+            throw new Error(exception.message);
+        }
+    }
+    return JSON.parse(stringJSON);
+}
+
 exports.asserted = asserted;
-exports.ensureJoin = ensureJoin;
+exports.isBoolean = isBoolean;
 exports.isFalsy = isFalsy;
+exports.isFunction = isFunction;
 exports.isNotNullish = isNotNullish;
 exports.isNullish = isNullish;
+exports.isNumber = isNumber;
+exports.isObject = isObject;
 exports.isString = isString;
 exports.isTruthy = isTruthy;
+exports.join = join;
 exports.listFiles = listFiles;
 exports.listFolders = listFolders;
+exports.listFoldersSync = listFoldersSync;
 exports.noop = noop;
+exports.readJSON = readJSON;
+exports.remove = remove;
 exports.removeFiles = removeFiles;
 exports.sleep = sleep;
+exports.toString = toString;

package/node/index.d.ts

@@ -1,6 +1,20 @@
-declare function ensureJoin(object: string[] | string, separator?: string): string;
+/**
+ * Joins an array's items or do nothing if it is joined already.
+ *
+ * @category Array
+ */
+declare function join(object: string[] | string, separator?: string): string;
+
+/**
+ * Removes an item from an array by mutating it.
+ * @throws An error if the object to be removed does not exist inside the array.
+ *
+ * @category Array
+ */
+declare function remove<T>(array: T[], object: T): void;
 
 declare function noop(): void;
+declare function toString(object: unknown): string;
 
 declare function asserted<T>(object: T | null | undefined): T;
 declare function isTruthy<T>(object: T): object is Exclude<T, '' | 0 | false | null | undefined>;
@@ -9,7 +23,16 @@ declare function isNullish(object: unknown): object is null | undefined;
 declare function isNotNullish<T>(object: T): object is Exclude<T, null | undefined>;
 
 declare function isString(object: unknown): object is string;
+declare function isNumber(object: unknown): object is number;
+declare function isBoolean(object: unknown): object is boolean;
+declare function isObject(object: unknown): object is object;
+declare function isFunction<T extends Function>(object: unknown): object is T;
 
+/**
+ * A wrapper around `setTimeout`.
+ *
+ * @category Promise
+ */
 declare function sleep(milliSeconds: number): Promise<void>;
 
 type Nullable<T> = T | null | undefined;
@@ -46,6 +69,14 @@ declare function listFiles({ folderPath, getFullPath, filter }: ListFilesOpt): P
  */
 declare function listFolders({ folderPath, getFullPath }: ListFoldersOpt): Promise<string[]>;
 
+/**
+ * Get a list of folders that are present in the provided folder path.
+ * If the provided folder path does not exists, an error will be thrown.
+ */
+declare function listFoldersSync({ folderPath, getFullPath }: ListFoldersOpt): string[];
+
 declare function removeFiles({ folderPath, filter }: RemoveFilesOpt): Promise<void>;
 
-export { Fn, Nullable, asserted, ensureJoin, isFalsy, isNotNullish, isNullish, isString, isTruthy, listFiles, listFolders, noop, removeFiles, sleep };
+declare function readJSON<T = object>(filePath: string, withComments?: boolean): Promise<T>;
+
+export { Fn, Nullable, asserted, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, listFiles, listFolders, listFoldersSync, noop, readJSON, remove, removeFiles, sleep, toString };

package/node/index.js

@@ -2,18 +2,53 @@ import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 import path from 'node:path';
 
+function noop() { }
+function toString(object) {
+    return Object.prototype.toString.call(object);
+}
+
 function isString(object) {
     return typeof object === 'string';
 }
+function isNumber(object) {
+    return typeof object === 'number';
+}
+function isBoolean(object) {
+    return typeof object === 'boolean';
+}
+function isObject(object) {
+    return toString(object) === '[object Object]';
+}
+// eslint-disable-next-line @typescript-eslint/ban-types
+function isFunction(object) {
+    return typeof object === 'function';
+}
 
-function ensureJoin(object, separator = ',') {
+/**
+ * Joins an array's items or do nothing if it is joined already.
+ *
+ * @category Array
+ */
+function join(object, separator = ',') {
     if (isString(object)) {
         return object;
     }
     return object.join(separator);
 }
 
-function noop() { }
+/**
+ * Removes an item from an array by mutating it.
+ * @throws An error if the object to be removed does not exist inside the array.
+ *
+ * @category Array
+ */
+function remove(array, object) {
+    const index = array.indexOf(object);
+    if (index === -1) {
+        throw new Error('Provided value does not exist inside the array.');
+    }
+    array.splice(index, 1);
+}
 
 function asserted(object) {
     if (object === null || object === undefined) {
@@ -34,6 +69,11 @@ function isNotNullish(object) {
     return object !== null && object !== undefined;
 }
 
+/**
+ * A wrapper around `setTimeout`.
+ *
+ * @category Promise
+ */
 async function sleep(milliSeconds) {
     return new Promise((resolve) => {
         setTimeout(resolve, milliSeconds);
@@ -90,6 +130,28 @@ async function listFolders({ folderPath, getFullPath }) {
     return folders;
 }
 
+/**
+ * Get a list of folders that are present in the provided folder path.
+ * If the provided folder path does not exists, an error will be thrown.
+ */
+function listFoldersSync({ folderPath, getFullPath }) {
+    if (fs.existsSync(folderPath) === false) {
+        throw new Error('The provided folder path does not exist!');
+    }
+    const entries = fs.readdirSync(folderPath, {
+        withFileTypes: true,
+    });
+    const folders = entries
+        .filter((entry) => entry.isDirectory() === true)
+        .map((folderEntry) => {
+        if (getFullPath === true) {
+            return path.join(folderPath, folderEntry.name);
+        }
+        return folderEntry.name;
+    });
+    return folders;
+}
+
 async function removeFiles({ folderPath, filter }) {
     const nestedFilePathPattern = `${path.resolve('./')}\\`;
     if (!folderPath.startsWith(nestedFilePathPattern)) {
@@ -101,4 +163,18 @@ async function removeFiles({ folderPath, filter }) {
     }
 }
 
-export { asserted, ensureJoin, isFalsy, isNotNullish, isNullish, isString, isTruthy, listFiles, listFolders, noop, removeFiles, sleep };
+async function readJSON(filePath, withComments = false) {
+    const stringJSON = await fsp.readFile(filePath, 'utf-8');
+    if (withComments === true) {
+        try {
+            const { default: JSON5 } = await import('json5');
+            return JSON5.parse(stringJSON);
+        }
+        catch (exception) {
+            throw new Error(exception.message);
+        }
+    }
+    return JSON.parse(stringJSON);
+}
+
+export { asserted, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, listFiles, listFolders, listFoldersSync, noop, readJSON, remove, removeFiles, sleep, toString };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeniex/utils",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "author": "JenieX",
   "homepage": "https://github.com/JenieX/utils",
   "type": "module",