@nasriya/atomix
Version:
Composable helper functions for building reliable systems
330 lines (329 loc) • 12.2 kB
TypeScript
declare class ValueIs {
/**
* Checks if the provided value is defined, i.e. not null and not undefined.
*
* @param value - The value to check.
* @returns True if the value is defined, otherwise false.
* @example
* valueIs.defined(null); // ❌ false
* valueIs.defined(undefined); // ❌ false
* valueIs.defined(0); // ✅ true
* @since v1.0.0
*/
defined(value: unknown): value is NonNullable<unknown>;
/**
* Checks if the provided value is an instance of the specified class.
*
* @template T - The type of the instance.
* @param value - The value to check.
* @param constructor - The constructor function to check against.
* @returns True if the value is an instance of the constructor, otherwise false.
* @example
* const date = new Date();
* valueIs.instanceOf(date, Date); // ✅ true
* @example
* const number = 42;
* valueIs.instanceOf(number, Date); // ❌ false
* @since v1.0.0
*/
instanceOf<T>(value: unknown, constructor: abstract new (...args: any[]) => T): value is T;
/**
* Checks if the provided value is an instance of the specified class, or if its
* type matches the constructor in a loose sense.
*
* For example, if the value is a number, it will return true for the Number
* constructor, even if the value is not an instance of Number (i.e. it is a
* primitive number, not a boxed Number object).
*
* @template T - The type of the instance.
* @param value - The value to check.
* @param constructor - The constructor function to check against.
* @returns True if the value is an instance of the constructor, or if its type
* matches the constructor in a loose sense, otherwise false.
* @example
* const number = 42;
* valueIs.instanceOfLoose(number, Number); // ✅ true
* @example
* const string = 'hello';
* valueIs.instanceOfLoose(string, String); // ✅ true
* @example
* const boolean = true;
* valueIs.instanceOfLoose(boolean, Boolean); // ✅ true
* @example
* const date = new Date();
* valueIs.instanceOfLoose(date, Date); // ✅ true
* @example
* const invalid = null;
* valueIs.instanceOfLoose(invalid, Date); // ❌ false
* @since v1.0.0
*/
instanceOfLoose<T>(value: unknown, constructor: abstract new (...args: any[]) => T): value is T;
/**
* Checks if the provided value is a number.
*
* @param value - The value to check.
* @returns True if the value is a number, otherwise false.
* @since v1.0.0
*/
readonly number: (value: unknown) => value is number;
/**
* Checks if the provided value is a negative number.
*
* @param value - The value to check.
* @returns True if the value is a negative number, otherwise false.
* @since v1.0.0
*/
readonly negativeNumber: (value: unknown) => boolean;
/**
* Checks if the provided value is a positive number.
*
* @param value - The value to check.
* @returns True if the value is a positive number, otherwise false.
* @since v1.0.0
*/
readonly positiveNumber: (value: unknown) => boolean;
/**
* Checks if the provided value is an integer.
*
* @param value - The value to check.
* @returns True if the value is an integer, otherwise false.
* @since v1.0.0
*/
readonly integer: (value: unknown) => boolean;
/**
* Checks if the provided value is a floating point number.
*
* @param value - The value to check.
* @returns True if the value is a floating point number, otherwise false.
* @since v1.0.0
*/
readonly float: (value: unknown) => boolean;
/**
* Checks if the provided value is a finite number.
*
* @param value - The value to check.
* @returns True if the value is a finite number, otherwise false.
* @since v1.0.0
*/
readonly finite: (value: unknown) => boolean;
/**
* Checks if the provided value is `NaN` (Not-a-Number).
*
* @param value - The value to check.
* @returns True if the value is NaN, otherwise false.
* @since v1.0.0
*/
readonly NaN: (value: unknown) => value is typeof NaN;
/**
* Checks if the provided value is a string.
*
* @param value - The value to check.
* @returns True if the value is a string, otherwise false.
* @since v1.0.0
*/
readonly string: (value: unknown) => value is string;
/**
* Checks if the provided string value is blank (contains only whitespace).
*
* @param value - The value to check.
* @returns True if the value is a string containing only whitespace, otherwise false.
* @since v1.0.0
*/
readonly blankString: (value: unknown) => boolean;
/**
* Checks if the provided string value is empty.
*
* @param value - The value to check.
* @returns True if the value is an empty string, otherwise false.
* @since v1.0.0
*/
readonly emptyString: (value: unknown) => boolean;
/**
* Checks if the provided string value is not empty.
*
* @param value - The value to check.
* @returns True if the value is a non-empty string, otherwise false.
* @since v1.0.0
*/
readonly notEmptyString: (value: unknown) => boolean;
/**
* Checks if the provided value is a valid string.
*
* @param value - The value to check.
* @returns True if the value is a valid string, otherwise false.
* @since v1.0.0
* @description
* A valid string is a string that is not empty and has some content.
* The string is trimmed before its length is checked.
*/
readonly validString: (value: unknown) => boolean;
/**
* Checks if the provided value is an alphabetic string.
*
* @param value - The value to check.
* @returns True if the value is a string containing only alphabetic characters, otherwise false.
* @since v1.0.0
*/
readonly alphaString: (value: unknown) => boolean;
/**
* Checks if the provided value is an alphanumeric string.
*
* @param value - The value to check.
* @returns True if the value is a string containing only alphabetic and numeric characters, otherwise false.
* @since v1.0.0
*/
readonly alphaNumericString: (value: unknown) => boolean;
/**
* Checks if the provided value is a valid UUID string.
*
* @param value - The value to check.
* @param version - The UUID version to check against, defaults to v4.
* @returns True if the value is a valid UUID, otherwise false.
* @since v1.0.0
* @description
* A valid UUID is a string of the following format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
* The format is different for each version.
*/
readonly uuid: (value: unknown, version?: "v1" | "v4" | "v5") => boolean;
/**
* Checks if the given pattern is a glob-like pattern, meaning it contains at least one of the
* characters `*` or `?`.
* @param pattern The pattern to check.
* @returns true if the given pattern is a glob-like pattern, false otherwise.
* @since v1.0.0
*/
readonly globLike: (pattern: string) => boolean;
/**
* Checks if the provided value is an object.
*
* @param value - The value to check.
* @returns True if the value is an object, otherwise false.
* @since v1.0.0
* @description
* An object is a value that is not null and is of type object.
* This includes objects created with the Object constructor, objects
* created with object literals, and objects created with the new keyword.
*
* @example
* const object = { };
* objectsUtils.guard.isObject(object); // true
* @example
* const invalid = null;
* objectsUtils.guard.isObject(invalid); // false
* @example
* class MyClass { }
* const invalid = new MyClass();
* objectsUtils.guard.isObject(invalid); // false
*/
readonly object: (value: unknown) => value is object;
/**
* Checks if the provided value is freezable.
*
* @param value - The value to check.
* @returns True if the value is freezable, otherwise false.
* @since v1.0.0
* @description
* A freezable is a value that is an object or an array.
* This means that the value can be frozen using the Object.freeze method.
*
* @example
* const object = { };
* objectsUtils.guard.isFreezable(object); // true
* @example
* const array = [1, 2, 3];
* objectsUtils.guard.isFreezable(array); // true
* @example
* const invalid = null;
* objectsUtils.guard.isFreezable(invalid); // false
* @example
* class MyClass { }
* const invalid = new MyClass();
* objectsUtils.guard.isFreezable(invalid); // false
*/
readonly freezable: (value: unknown) => value is object;
/**
* Checks if the provided value is a Record.
*
* @param value - The value to check.
* @returns True if the value is a Record, otherwise false.
* @since v1.0.0
* @description
* A Record is an object that is not null, is not an array, and contains
* at least one key-value pair.
*
* @example
* const record = { foo: 'bar' };
* recordsUtils.guard.isRecord(record); // ✅ true
* @example
* const invalid = null;
* recordsUtils.guard.isRecord(invalid); // ❌ false
* @example
* const invalid = [1, 2, 3];
* recordsUtils.guard.isRecord(invalid); // ❌ false
*/
readonly record: (value: unknown) => value is Record<string, any>;
/**
* Checks if the provided value is an empty Record.
*
* @param value - The value to check.
* @returns True if the value is an empty Record, otherwise false.
* @since v1.0.0
* @description
* An empty Record is a Record that contains no key-value pairs.
*
* @example
* const record = { };
* recordsUtils.guard.isEmpty(record); // ✅ true
* @example
* const invalid = null;
* recordsUtils.guard.isEmpty(invalid); // ❌ false
* @example
* const invalid = [1, 2, 3];
* recordsUtils.guard.isEmpty(invalid); // ❌ false
*/
readonly emptyRecord: (value: unknown) => boolean;
/**
* Checks if the provided value is an array.
*
* @param value - The value to check.
* @returns True if the value is an array, otherwise false.
* @since v1.0.0
*/
readonly array: (value: unknown) => value is Array<any>;
/**
* Checks if the provided value is a non-empty array.
*
* @param value - The value to check.
* @returns True if the value is a non-empty array, otherwise false.
* @since v1.0.0
*/
readonly notEmptyArray: <T extends Array<T>>(value: unknown) => value is import(".").NonEmptyArray<T>;
/**
* Checks if the provided value is an array of the given type.
*
* @param itemGuard - A function that takes an item and returns true if the
* item is of the given type, otherwise false.
* @returns A function that takes a value and returns true if the value is an
* array and every item in the array is of the given type, otherwise false.
* @since v1.0.0
*/
readonly arrayOf: <T>(itemGuard: (item: unknown) => item is T) => (value: unknown) => value is T[];
/**
* Checks if the provided value is an array of numbers.
*
* @param value - The value to check.
* @returns True if the value is an array of numbers, otherwise false.
* @since v1.0.0
*/
readonly arrayOfNumbers: (value: unknown) => value is number[];
/**
* Checks if the provided value is an array of strings.
*
* @param value - The value to check.
* @returns True if the value is an array of strings, otherwise false.
* @since v1.0.0
*/
readonly arrayOfStrings: (value: unknown) => value is string[];
}
declare const valueIs: ValueIs;
export default valueIs;