@jeniex/utils 1.2.0 → 1.4.0

package/browser/index.cjs

@@ -48,16 +48,130 @@ function remove(array, object) {
     array.splice(index, 1);
 }
 
+/**
+ * Asserts that an object is neither `null` nor `undefined`.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * assert(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.length);
+ */
+function assert(object) {
+    if (object === null || object === undefined) {
+        throw new TypeError('object is either null or undefined');
+    }
+}
+/**
+ * Asserts that an object satisfies the given type guard.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to the type accepted by
+ * the type guard.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * assertType(object, isNumber);
+ *
+ * // `object` is now typed as `number`.
+ * console.log(object.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * assertType(object, isString);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.toUpperCase());
+ */
+function assertType(object, guard) {
+    if (!guard(object)) {
+        throw new TypeError('object has an invalid type');
+    }
+}
+/**
+ * Asserts that an object is neither `null` nor `undefined` and returns it.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, the object is returned with its type narrowed to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * const string = asserted(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(string.length);
+ */
 function asserted(object) {
     if (object === null || object === undefined) {
-        throw new Error('Value is either null or undefined.');
+        throw new TypeError('object is either null or undefined');
     }
     return object;
 }
-function stringOrThrow(value) {
-    if (!isString(value)) {
-        throw new Error('Expected a string.');
+/**
+ * Asserts that an object satisfies the given type guard and returns it
+ * with the narrowed type.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * const number = assertedType(object, isNumber);
+ *
+ * // `number` is typed as `number`.
+ * console.log(number.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * const text = assertedType(object, isString);
+ *
+ * // `text` is typed as `string`.
+ * console.log(text.toUpperCase());
+ */
+function assertedType(object, guard) {
+    if (!guard(object)) {
+        throw new TypeError('object has an invalid type');
     }
+    return object;
 }
 function isTruthy(object) {
     return Boolean(object) === true;
@@ -585,7 +699,10 @@ exports.$ = $;
 exports.$$ = $$;
 exports.addStyle = addStyle;
 exports.alert = alert;
+exports.assert = assert;
+exports.assertType = assertType;
 exports.asserted = asserted;
+exports.assertedType = assertedType;
 exports.capitalize = capitalize;
 exports.checkVPN = checkVPN;
 exports.checkVPNRandomly = checkVPNRandomly;
@@ -621,6 +738,5 @@ exports.saveFile = saveFile;
 exports.scriptName = scriptName;
 exports.setSearchParam = setSearchParam;
 exports.sleep = sleep;
-exports.stringOrThrow = stringOrThrow;
 exports.tabURL = tabURL;
 exports.toString = toString;

package/browser/index.d.ts

@@ -16,8 +16,113 @@ declare function remove<T>(array: T[], object: T): void;
 declare function noop(): void;
 declare function toString(object: unknown): string;
 
+/**
+ * Asserts that an object is neither `null` nor `undefined`.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * assert(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.length);
+ */
+declare function assert<T>(object: T | null | undefined): asserts object is T;
+/**
+ * Asserts that an object satisfies the given type guard.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to the type accepted by
+ * the type guard.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * assertType(object, isNumber);
+ *
+ * // `object` is now typed as `number`.
+ * console.log(object.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * assertType(object, isString);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.toUpperCase());
+ */
+declare function assertType<T>(object: unknown, guard: (object: unknown) => object is T): asserts object is T;
+/**
+ * Asserts that an object is neither `null` nor `undefined` and returns it.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, the object is returned with its type narrowed to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * const string = asserted(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(string.length);
+ */
 declare function asserted<T>(object: T | null | undefined): T;
-declare function stringOrThrow(value: unknown): asserts value is string;
+/**
+ * Asserts that an object satisfies the given type guard and returns it
+ * with the narrowed type.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * const number = assertedType(object, isNumber);
+ *
+ * // `number` is typed as `number`.
+ * console.log(number.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * const text = assertedType(object, isString);
+ *
+ * // `text` is typed as `string`.
+ * console.log(text.toUpperCase());
+ */
+declare function assertedType<T>(object: unknown, guard: (object: unknown) => object is T): T;
 declare function isTruthy<T>(object: T): object is Exclude<T, '' | 0 | false | null | undefined>;
 declare function isFalsy(object: unknown): object is '' | 0 | false | null | undefined;
 declare function isNullish(object: unknown): object is null | undefined;
@@ -203,4 +308,4 @@ declare function rx(url: string, options?: RxOptions): RqRequest;
 
 declare function createRequest<TOptions>(transport: Transport<TOptions>, url: string, options?: TOptions): RqRequest;
 
-export { $, $$, Flag, Fn, Nullable, Prettify, addStyle, alert, asserted, capitalize, checkVPN, checkVPNRandomly, confirm, customizeConsole, fish, fishResponse, fishX, fishXResponse, getOptions, getSearchParam, imageLoad, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, noop, padZeros, pageLoad, prompt, remove, removeSearchParams, rq, createRequest as rqc, rx, saveFile, scriptName, setSearchParam, sleep, stringOrThrow, tabURL, toString };
+export { $, $$, Flag, Fn, Nullable, Prettify, addStyle, alert, assert, assertType, asserted, assertedType, capitalize, checkVPN, checkVPNRandomly, confirm, customizeConsole, fish, fishResponse, fishX, fishXResponse, getOptions, getSearchParam, imageLoad, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, noop, padZeros, pageLoad, prompt, remove, removeSearchParams, rq, createRequest as rqc, rx, saveFile, scriptName, setSearchParam, sleep, tabURL, toString };

package/browser/index.js

@@ -46,16 +46,130 @@ function remove(array, object) {
     array.splice(index, 1);
 }
 
+/**
+ * Asserts that an object is neither `null` nor `undefined`.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * assert(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.length);
+ */
+function assert(object) {
+    if (object === null || object === undefined) {
+        throw new TypeError('object is either null or undefined');
+    }
+}
+/**
+ * Asserts that an object satisfies the given type guard.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to the type accepted by
+ * the type guard.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * assertType(object, isNumber);
+ *
+ * // `object` is now typed as `number`.
+ * console.log(object.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * assertType(object, isString);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.toUpperCase());
+ */
+function assertType(object, guard) {
+    if (!guard(object)) {
+        throw new TypeError('object has an invalid type');
+    }
+}
+/**
+ * Asserts that an object is neither `null` nor `undefined` and returns it.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, the object is returned with its type narrowed to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * const string = asserted(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(string.length);
+ */
 function asserted(object) {
     if (object === null || object === undefined) {
-        throw new Error('Value is either null or undefined.');
+        throw new TypeError('object is either null or undefined');
     }
     return object;
 }
-function stringOrThrow(value) {
-    if (!isString(value)) {
-        throw new Error('Expected a string.');
+/**
+ * Asserts that an object satisfies the given type guard and returns it
+ * with the narrowed type.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * const number = assertedType(object, isNumber);
+ *
+ * // `number` is typed as `number`.
+ * console.log(number.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * const text = assertedType(object, isString);
+ *
+ * // `text` is typed as `string`.
+ * console.log(text.toUpperCase());
+ */
+function assertedType(object, guard) {
+    if (!guard(object)) {
+        throw new TypeError('object has an invalid type');
     }
+    return object;
 }
 function isTruthy(object) {
     return Boolean(object) === true;
@@ -579,4 +693,4 @@ function rx(url, options) {
     return createRequest(gmTransport, url, options);
 }
 
-export { $, $$, addStyle, alert, asserted, capitalize, checkVPN, checkVPNRandomly, confirm, customizeConsole, fish, fishResponse, fishX, fishXResponse, getOptions, getSearchParam, imageLoad, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, noop, padZeros, pageLoad, prompt, remove, removeSearchParams, rq, createRequest as rqc, rx, saveFile, scriptName, setSearchParam, sleep, stringOrThrow, tabURL, toString };
+export { $, $$, addStyle, alert, assert, assertType, asserted, assertedType, capitalize, checkVPN, checkVPNRandomly, confirm, customizeConsole, fish, fishResponse, fishX, fishXResponse, getOptions, getSearchParam, imageLoad, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, noop, padZeros, pageLoad, prompt, remove, removeSearchParams, rq, createRequest as rqc, rx, saveFile, scriptName, setSearchParam, sleep, tabURL, toString };

package/node/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var fs = require('node:fs');
 var fsp = require('node:fs/promises');
+var fs = require('node:fs');
 var path = require('node:path');
 
 function noop() { }
@@ -52,16 +52,130 @@ function remove(array, object) {
     array.splice(index, 1);
 }
 
+/**
+ * Asserts that an object is neither `null` nor `undefined`.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * assert(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.length);
+ */
+function assert(object) {
+    if (object === null || object === undefined) {
+        throw new TypeError('object is either null or undefined');
+    }
+}
+/**
+ * Asserts that an object satisfies the given type guard.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to the type accepted by
+ * the type guard.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * assertType(object, isNumber);
+ *
+ * // `object` is now typed as `number`.
+ * console.log(object.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * assertType(object, isString);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.toUpperCase());
+ */
+function assertType(object, guard) {
+    if (!guard(object)) {
+        throw new TypeError('object has an invalid type');
+    }
+}
+/**
+ * Asserts that an object is neither `null` nor `undefined` and returns it.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, the object is returned with its type narrowed to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * const string = asserted(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(string.length);
+ */
 function asserted(object) {
     if (object === null || object === undefined) {
-        throw new Error('Value is either null or undefined.');
+        throw new TypeError('object is either null or undefined');
     }
     return object;
 }
-function stringOrThrow(value) {
-    if (!isString(value)) {
-        throw new Error('Expected a string.');
+/**
+ * Asserts that an object satisfies the given type guard and returns it
+ * with the narrowed type.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * const number = assertedType(object, isNumber);
+ *
+ * // `number` is typed as `number`.
+ * console.log(number.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * const text = assertedType(object, isString);
+ *
+ * // `text` is typed as `string`.
+ * console.log(text.toUpperCase());
+ */
+function assertedType(object, guard) {
+    if (!guard(object)) {
+        throw new TypeError('object has an invalid type');
     }
+    return object;
 }
 function isTruthy(object) {
     return Boolean(object) === true;
@@ -134,6 +248,64 @@ function capitalize(sentence) {
     return capitalizeWord(sentence);
 }
 
+async function exists(path) {
+    try {
+        await fsp.access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+async function existsFile(path) {
+    try {
+        const stats = await fsp.stat(path);
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+
+function existsFileSync(path) {
+    try {
+        return fs.statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+
+async function existsFolder(path) {
+    try {
+        const stats = await fsp.stat(path);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+
+function existsFolderSync(path) {
+    try {
+        return fs.statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+
+function existsSync(path) {
+    try {
+        fs.accessSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
 /**
  * Lists the files that are present in the provided folder path.
  * @throws an error if the provided folder path does not exist.
@@ -315,8 +487,17 @@ function rq(url, options) {
     return createRequest(fetchTransport, url, options);
 }
 
+exports.assert = assert;
+exports.assertType = assertType;
 exports.asserted = asserted;
+exports.assertedType = assertedType;
 exports.capitalize = capitalize;
+exports.exists = exists;
+exports.existsFile = existsFile;
+exports.existsFileSync = existsFileSync;
+exports.existsFolder = existsFolder;
+exports.existsFolderSync = existsFolderSync;
+exports.existsSync = existsSync;
 exports.isBoolean = isBoolean;
 exports.isFalsy = isFalsy;
 exports.isFunction = isFunction;
@@ -338,5 +519,4 @@ exports.removeFiles = removeFiles;
 exports.rq = rq;
 exports.rqc = createRequest;
 exports.sleep = sleep;
-exports.stringOrThrow = stringOrThrow;
 exports.toString = toString;

package/node/index.d.ts

@@ -16,8 +16,113 @@ declare function remove<T>(array: T[], object: T): void;
 declare function noop(): void;
 declare function toString(object: unknown): string;
 
+/**
+ * Asserts that an object is neither `null` nor `undefined`.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * assert(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.length);
+ */
+declare function assert<T>(object: T | null | undefined): asserts object is T;
+/**
+ * Asserts that an object satisfies the given type guard.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to the type accepted by
+ * the type guard.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * assertType(object, isNumber);
+ *
+ * // `object` is now typed as `number`.
+ * console.log(object.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * assertType(object, isString);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.toUpperCase());
+ */
+declare function assertType<T>(object: unknown, guard: (object: unknown) => object is T): asserts object is T;
+/**
+ * Asserts that an object is neither `null` nor `undefined` and returns it.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, the object is returned with its type narrowed to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * const string = asserted(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(string.length);
+ */
 declare function asserted<T>(object: T | null | undefined): T;
-declare function stringOrThrow(value: unknown): asserts value is string;
+/**
+ * Asserts that an object satisfies the given type guard and returns it
+ * with the narrowed type.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * const number = assertedType(object, isNumber);
+ *
+ * // `number` is typed as `number`.
+ * console.log(number.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * const text = assertedType(object, isString);
+ *
+ * // `text` is typed as `string`.
+ * console.log(text.toUpperCase());
+ */
+declare function assertedType<T>(object: unknown, guard: (object: unknown) => object is T): T;
 declare function isTruthy<T>(object: T): object is Exclude<T, '' | 0 | false | null | undefined>;
 declare function isFalsy(object: unknown): object is '' | 0 | false | null | undefined;
 declare function isNullish(object: unknown): object is null | undefined;
@@ -56,6 +161,18 @@ type Prettify<T> = {
     [KeyType in keyof T]: T[KeyType];
 } & {};
 
+declare function exists(path: string): Promise<boolean>;
+
+declare function existsFile(path: string): Promise<boolean>;
+
+declare function existsFileSync(path: string): boolean;
+
+declare function existsFolder(path: string): Promise<boolean>;
+
+declare function existsFolderSync(path: string): boolean;
+
+declare function existsSync(path: string): boolean;
+
 interface ListBaseOpt {
     /** The absolute path of the target folder. */
     folderPath: string;
@@ -134,4 +251,4 @@ declare function rq(url: string, options?: RequestInit): RqRequest;
 
 declare function createRequest<TOptions>(transport: Transport<TOptions>, url: string, options?: TOptions): RqRequest;
 
-export { Fn, Nullable, Prettify, asserted, capitalize, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, listFiles, listFolders, listFoldersSync, noop, padZeros, readJSON, remove, removeFiles, rq, createRequest as rqc, sleep, stringOrThrow, toString };
+export { Fn, Nullable, Prettify, assert, assertType, asserted, assertedType, capitalize, exists, existsFile, existsFileSync, existsFolder, existsFolderSync, existsSync, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, listFiles, listFolders, listFoldersSync, noop, padZeros, readJSON, remove, removeFiles, rq, createRequest as rqc, sleep, toString };

package/node/index.js

@@ -1,5 +1,5 @@
-import fs from 'node:fs';
-import fsp from 'node:fs/promises';
+import fsp, { access, stat } from 'node:fs/promises';
+import fs, { statSync, accessSync } from 'node:fs';
 import path from 'node:path';
 
 function noop() { }
@@ -50,16 +50,130 @@ function remove(array, object) {
     array.splice(index, 1);
 }
 
+/**
+ * Asserts that an object is neither `null` nor `undefined`.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * assert(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.length);
+ */
+function assert(object) {
+    if (object === null || object === undefined) {
+        throw new TypeError('object is either null or undefined');
+    }
+}
+/**
+ * Asserts that an object satisfies the given type guard.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to the type accepted by
+ * the type guard.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * assertType(object, isNumber);
+ *
+ * // `object` is now typed as `number`.
+ * console.log(object.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * assertType(object, isString);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.toUpperCase());
+ */
+function assertType(object, guard) {
+    if (!guard(object)) {
+        throw new TypeError('object has an invalid type');
+    }
+}
+/**
+ * Asserts that an object is neither `null` nor `undefined` and returns it.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, the object is returned with its type narrowed to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * const string = asserted(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(string.length);
+ */
 function asserted(object) {
     if (object === null || object === undefined) {
-        throw new Error('Value is either null or undefined.');
+        throw new TypeError('object is either null or undefined');
     }
     return object;
 }
-function stringOrThrow(value) {
-    if (!isString(value)) {
-        throw new Error('Expected a string.');
+/**
+ * Asserts that an object satisfies the given type guard and returns it
+ * with the narrowed type.
+ *
+ * If the type guard returns `false`, a `TypeError` is thrown.
+ *
+ * @template T The type checked by the type guard.
+ *
+ * @param object The object to validate.
+ * @param guard A type guard used to validate the object.
+ *
+ * @returns The validated object, narrowed to `T`.
+ *
+ * @throws {TypeError} If the object does not satisfy the type guard.
+ *
+ * @example
+ * const object: number | string = Math.random() < 0.5 ? 1 : 'Hello';
+ *
+ * const number = assertedType(object, isNumber);
+ *
+ * // `number` is typed as `number`.
+ * console.log(number.toFixed(2));
+ *
+ * @example
+ * const object: unknown = 'hello';
+ *
+ * const text = assertedType(object, isString);
+ *
+ * // `text` is typed as `string`.
+ * console.log(text.toUpperCase());
+ */
+function assertedType(object, guard) {
+    if (!guard(object)) {
+        throw new TypeError('object has an invalid type');
     }
+    return object;
 }
 function isTruthy(object) {
     return Boolean(object) === true;
@@ -132,6 +246,64 @@ function capitalize(sentence) {
     return capitalizeWord(sentence);
 }
 
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
+async function existsFile(path) {
+    try {
+        const stats = await stat(path);
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+
+function existsFileSync(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+
+async function existsFolder(path) {
+    try {
+        const stats = await stat(path);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+
+function existsFolderSync(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+
+function existsSync(path) {
+    try {
+        accessSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+
 /**
  * Lists the files that are present in the provided folder path.
  * @throws an error if the provided folder path does not exist.
@@ -313,4 +485,4 @@ function rq(url, options) {
     return createRequest(fetchTransport, url, options);
 }
 
-export { asserted, capitalize, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, listFiles, listFolders, listFoldersSync, noop, padZeros, readJSON, remove, removeFiles, rq, createRequest as rqc, sleep, stringOrThrow, toString };
+export { assert, assertType, asserted, assertedType, capitalize, exists, existsFile, existsFileSync, existsFolder, existsFolderSync, existsSync, isBoolean, isFalsy, isFunction, isNotNullish, isNullish, isNumber, isObject, isString, isTruthy, join, listFiles, listFolders, listFoldersSync, noop, padZeros, readJSON, remove, removeFiles, rq, createRequest as rqc, sleep, toString };

package/node/inquirer/index.js

@@ -42,6 +42,26 @@ async function confirm(message, defaultAnswer = false) {
     return confirmValue;
 }
 
+/**
+ * Asserts that an object is neither `null` nor `undefined`.
+ *
+ * If the object is `null` or `undefined`, a `TypeError` is thrown.
+ * Otherwise, TypeScript narrows the object to `T`.
+ *
+ * @template T The type of the object.
+ *
+ * @param object The object to validate.
+ *
+ * @throws {TypeError} If the object is `null` or `undefined`.
+ *
+ * @example
+ * const object: string | undefined = Math.random() < 0.5 ? undefined : 'Hello';
+ *
+ * assert(object);
+ *
+ * // `object` is now typed as `string`.
+ * console.log(object.length);
+ */
 function isFalsy(object) {
     return Boolean(object) === false;
 }

package/package.json

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