@jeniex/utils 1.3.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

@@ -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;
@@ -373,7 +487,10 @@ 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;
@@ -402,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;
@@ -146,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, 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, 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

@@ -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;
@@ -371,4 +485,4 @@ function rq(url, options) {
     return createRequest(fetchTransport, url, options);
 }
 
-export { asserted, 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, 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.3.0",
+  "version": "1.4.0",
   "author": "JenieX",
   "homepage": "https://github.com/JenieX/utils",
   "type": "module",