nc.checker

nc.checker.isArray()

isArray(value: unknown): value is any[]

Is it an array?

Returns value is any[]

Example

nc.isArray([1, 2]);        // true
nc.isArray({ length: 0 }); // false

nc.checker.isNumber()

isNumber(value: unknown): value is number

Is it a number? NaN is rejected, Infinity passes (see isFinite).

Returns value is number

Example

nc.isNumber(42);   // true
nc.isNumber(NaN);  // false
nc.isNumber("42"); // false, use isNumeric for strings

nc.checker.isFinite()

isFinite(value: unknown): value is number

Is it a finite number? Unlike the global isFinite, strings are rejected.

Returns value is number

Example

nc.isFinite(42);       // true
nc.isFinite(Infinity); // false
nc.isFinite("42");     // false

nc.checker.isInteger()

isInteger(value: unknown): value is number

Is it an integer?

Returns value is number

Example

nc.isInteger(4);   // true
nc.isInteger(4.5); // false

nc.checker.isSafeInteger()

isSafeInteger(value: unknown): value is number

Is it an integer JavaScript can represent exactly (up to 2^53 - 1)?

Returns value is number

Example

nc.isSafeInteger(2 ** 53 - 1); // true
nc.isSafeInteger(2 ** 53);     // false

nc.checker.isFloat()

isFloat(value: unknown): value is number

Is it a finite number with a decimal part?

Returns value is number

Example

nc.isFloat(4.2); // true
nc.isFloat(4);   // false

nc.checker.isPositive()

isPositive(value: unknown): value is number

Is it a number greater than zero?

Returns value is number

Example

nc.isPositive(3); // true
nc.isPositive(0); // false

nc.checker.isNegative()

isNegative(value: unknown): value is number

Is it a number lower than zero?

Returns value is number

Example

nc.isNegative(-3); // true
nc.isNegative(0);  // false

nc.checker.isBoolean()

isBoolean(value: unknown): value is boolean

Is it true or false? Truthy and falsy values don't count.

Returns value is boolean

Example

nc.isBoolean(false); // true
nc.isBoolean(0);     // false

nc.checker.isString()

isString(value: unknown): value is string

Is it a string?

Returns value is string

Example

nc.isString("hello");             // true
nc.isString(new String("hello")); // false

nc.checker.isSymbol()

isSymbol(value: unknown): value is symbol

Is it a symbol?

Returns value is symbol

nc.checker.isBigInt()

isBigInt(value: unknown): value is bigint

Is it a bigint?

Returns value is bigint

Example

nc.isBigInt(10n); // true
nc.isBigInt(10);  // false

nc.checker.isUndefined()

isUndefined(value: unknown): value is undefined

Is it undefined?

Returns value is undefined

nc.checker.isNull()

isNull(value: unknown): value is null

Is it null?

Returns value is null

nc.checker.isNil()

isNil(value: unknown): value is null | undefined

Is it null or undefined?

Returns value is null | undefined

Example

nc.isNil(undefined); // true
nc.isNil(0);         // false

nc.checker.isDefined()

isDefined<T>(value: T): value is NonNullable<T>

Is it anything but null or undefined? Pass it to filter() to drop missing values and keep the right type.

Returns value is NonNullable<T>

Example

const ids = [1, null, 2, undefined].filter(nc.isDefined); // number[]

nc.checker.isPrimitive()

isPrimitive(value: unknown): value is Primitive

Is it a primitive (string, number, boolean, symbol, bigint, null or undefined)?

Returns value is Primitive

nc.checker.isFunction()

isFunction(value: unknown): value is (...args: any[]) => any

Is it callable? Classes, async and generator functions count.

Returns value is (...args: any[]) => any

nc.checker.isAsyncFunction()

isAsyncFunction(value: unknown): value is (...args: any[]) => Promise<any>

Was it declared with async? A function that merely returns a promise doesn't count.

Returns value is (...args: any[]) => Promise<any>

Example

nc.isAsyncFunction(async () => {});         // true
nc.isAsyncFunction(() => Promise.resolve()); // false

nc.checker.isGeneratorFunction()

isGeneratorFunction(value: unknown): value is (...args: any[]) => Generator<unknown, any, any>

Is it a generator function (function*)?

Returns value is (...args: any[]) => Generator

nc.checker.isGenerator()

isGenerator(value: unknown): value is Generator<unknown, any, any>

Is it a generator object, the result of calling a function*?

Returns value is Generator

nc.checker.isClass()

isClass(value: unknown): value is new (...args: any[]) => any

Is it a class rather than a plain function?

Returns value is new (...args: any[]) => any

Example

nc.isClass(class User {});  // true
nc.isClass(function () {}); // false

nc.checker.isObject()

isObject(value: unknown): value is object

Is it an object, and not null? Arrays, dates and class instances count; use isPlainObject for {} literals only.

Returns value is object

nc.checker.isPlainObject()

isPlainObject(value: unknown): value is Record<string, unknown>

Is it a plain object, made with {}, new Object() or Object.create(null)? Arrays, dates, maps and class instances are rejected.

Returns value is Record<string, unknown>

Example

nc.isPlainObject({ a: 1 });   // true
nc.isPlainObject(new Date()); // false

nc.checker.isPromise()

isPromise(value: unknown): value is PromiseLike<any>

Can it be awaited like a promise (anything with a then method)?

Returns value is PromiseLike<any>

nc.checker.isRegExp()

isRegExp(value: unknown): value is RegExp

Is it a regular expression?

Returns value is RegExp

nc.checker.isDate()

isDate(value: unknown): value is Date

Is it a Date, valid or not? Use isValidDate to reject Invalid Date.

Returns value is Date

nc.checker.isValidDate()

isValidDate(value: unknown): value is Date

Is it a Date holding a real point in time?

Returns value is Date

Example

nc.isValidDate(new Date());       // true
nc.isValidDate(new Date("nope")); // false

nc.checker.isMap()

isMap(value: unknown): value is Map<unknown, unknown>

Is it a Map?

Returns value is Map<unknown, unknown>

nc.checker.isSet()

isSet(value: unknown): value is Set<unknown>

Is it a Set?

Returns value is Set<unknown>

nc.checker.isWeakMap()

isWeakMap(value: unknown): value is WeakMap<object, unknown>

Is it a WeakMap?

Returns value is WeakMap<object, unknown>

nc.checker.isWeakSet()

isWeakSet(value: unknown): value is WeakSet<object>

Is it a WeakSet?

Returns value is WeakSet<object>

nc.checker.isIterable()

isIterable(value: unknown): value is Iterable<unknown>

Does it work with for...of? Strings, arrays, maps, sets and generators do.

Returns value is Iterable<unknown>

nc.checker.isAsyncIterable()

isAsyncIterable(value: unknown): value is AsyncIterable<unknown>

Does it work with for await...of, like streams and async generators?

Returns value is AsyncIterable<unknown>

nc.checker.isBuffer()

isBuffer(value: unknown): value is Buffer<ArrayBufferLike>

Is it a Node.js Buffer?

Returns value is Buffer

nc.checker.isTypedArray()

isTypedArray(value: unknown): value is AnyTypedArray

Is it a typed array (Uint8Array, Float64Array...)? Buffers count.

Returns value is AnyTypedArray

nc.checker.isError()

isError(value: unknown): value is Error

Is it an Error, including subclasses and errors from other realms?

Returns value is Error

nc.checker.isEmpty()

isEmpty(value: unknown): boolean

Is it empty? null, undefined, "", [], {} and empty maps and sets are. Numbers, booleans and functions never are.

Returns boolean

Example

nc.isEmpty({});  // true
nc.isEmpty(0);   // false
nc.isEmpty(" "); // false, see isBlank

nc.checker.isBlank()

isBlank(value: unknown): boolean

Is it null, undefined, or a string with nothing but whitespace?

Returns boolean

Example

nc.isBlank("  \n"); // true
nc.isBlank(" a ");  // false

nc.checker.isArrayOf()

isArrayOf<T>(value: unknown, guard: (item: unknown) => item is T): value is T[]

Is it an array where every item passes guard?

Returns value is T[]

Example

if (nc.isArrayOf(input, nc.isString)) input.join(", "); // input: string[]

nc.checker.isOneOf()

isOneOf<L extends readonly unknown[]>(value: unknown, allowed: L): value is L[number]

Is it one of the allowed values? With a constant list, the value gets the matching literal type.

Returns value is L[number]

Example

const ROLES = ["admin", "user"] as const;
if (nc.isOneOf(input, ROLES)) input; // "admin" | "user"

nc.checker.isEmail()

isEmail(value: unknown): value is string

Does it look like an email address? The rules are practical rather than the full RFC: one @, no stray dots, a real top-level domain. International addresses are accepted.

Returns value is string

Example

nc.isEmail("jose@exemple.fr");     // true
nc.isEmail("john..doe@example.com"); // false
nc.isEmail("john@localhost");       // false

nc.checker.isURL()

isURL(value: unknown, options?: IsURLOptions): value is string

Is it an absolute URL with an allowed protocol (http and https by default)?

Returns value is string

Example

nc.isURL("https://example.com/a?b=1");                 // true
nc.isURL("ftp://example.com", { protocols: ["ftp:"] }); // true
nc.isURL("http://localhost:3000", { requireTld: true }); // false

nc.checker.isUUID()

isUUID(value: unknown, options?: IsUUIDOptions): value is string

Is it a UUID?

Returns value is string

Example

nc.isUUID(nc.id.uuid());           // true
nc.isUUID(id, { version: 7 });     // only v7

nc.checker.isJSON()

isJSON(value: unknown): value is string

Is it a string of valid JSON?

Returns value is string

Example

nc.isJSON('{"a":1}'); // true
nc.isJSON("{a:1}");   // false

nc.checker.isNumeric()

isNumeric(value: unknown): value is string | number

Is it a finite number, or a string that is exactly one (spaces around are fine)?

Returns value is number | string

Example

nc.isNumeric("4.2e3"); // true
nc.isNumeric(" 12 ");  // true
nc.isNumeric("12px");  // false

nc.checker.isIP()

isIP(value: unknown, version?: 4 | 6): value is string

Is it an IP address?

Returns value is string

Example

nc.isIP("192.168.0.1"); // true
nc.isIP("::1");         // true
nc.isIP("::1", 4);      // false

nc.checker.isIPv4()

isIPv4(value: unknown): value is string

Is it an IPv4 address, like 192.168.0.1?

Returns value is string

nc.checker.isIPv6()

isIPv6(value: unknown): value is string

Is it an IPv6 address, like ::1?

Returns value is string

nc.checker.isPort()

isPort(value: unknown): boolean

Is it a valid port (0 to 65535), as a number or a numeric string?

Returns boolean

Example

nc.isPort("8080"); // true
nc.isPort(70000);  // false

nc.checker.isHex()

isHex(value: unknown): value is string

Is it a hexadecimal string? A 0x prefix is allowed.

Returns value is string

nc.checker.isHexColor()

isHexColor(value: unknown): value is string

Is it a CSS hex color (#rgb, #rgba, #rrggbb or #rrggbbaa)?

Returns value is string

Example

nc.isHexColor("#f80"); // true
nc.isHexColor("f80");  // false, the # is required

nc.checker.isBase64()

isBase64(value: unknown, options?: IsBase64Options): value is string

Is it valid Base64?

Returns value is string

Example

nc.isBase64("aGVsbG8=");                   // true
nc.isBase64("aGVsbG8", { urlSafe: true }); // true

nc.checker.isSemver()

isSemver(value: unknown): value is string

Is it a semantic version? A leading v is fine.

Returns value is string

Example

nc.isSemver("v2.0.0-rc.1"); // true
nc.isSemver("1.2");         // false

nc.checker.isISODate()

isISODate(value: unknown): value is string

Is it an ISO 8601 date or date-time, and a real calendar date?

Returns value is string

Example

nc.isISODate("2024-02-29T10:00:00Z"); // true
nc.isISODate("2023-02-29");           // false, not a leap year

nc.checker.isSlug()

isSlug(value: unknown): value is string

Is it a URL slug like my-first-post? See nc.str.slugify() to make one.

Returns value is string

nc.checker.isAlpha()

isAlpha(value: unknown): value is string

Is it made only of letters, in any alphabet?

Returns value is string

Example

nc.isAlpha("Élodie"); // true
nc.isAlpha("abc1");   // false

nc.checker.isAlphanumeric()

isAlphanumeric(value: unknown): value is string

Is it made only of letters and digits, in any alphabet?

Returns value is string

nc.checker.isCreditCard()

isCreditCard(value: unknown): value is string

Could it be a card number? Checks the length and the Luhn checksum; spaces and dashes are ignored.

Returns value is string

Example

nc.isCreditCard("4242 4242 4242 4242"); // true

nc.checker.isJWT()

isJWT(value: unknown): value is string

Does it look like a JSON Web Token? The signature is not verified; use nc.crypto.verifyJWT() for that.

Returns value is string

nc.checker.assert()

assert(condition: unknown, message?: string | (() => string) | undefined): asserts condition

Throws an AssertionError if condition is falsy. Afterwards, TypeScript knows the condition holds.

Returns asserts condition

Throws AssertionError

Example

const user = users.find((u) => u.id === id);
nc.assert(user, `User ${id} not found`);
user.name; // no "possibly undefined" here

nc.checker.assertType()

assertType<T>(value: unknown, guard: (value: unknown) => value is T, message?: string | (() => string) | undefined): asserts value is T

Throws an AssertionError unless value passes guard. Afterwards, value has the guarded type.

Returns asserts value is T

Throws AssertionError

Example

nc.assertType(config.port, nc.isInteger, "port must be an integer");