@ix-xs/node-comfort 1.2.0 → 2.1.0

package/types/src/Checker.d.ts

@@ -1,407 +1,826 @@
 /**
- * Checks if a value is a real Array.
+ * Any built-in typed array.
+ */
+export type AnyTypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+/**
+ * Any primitive value.
+ */
+export type Primitive = string | number | boolean | symbol | bigint | null | undefined;
+/**
+ * Options for `isURL()`.
+ */
+export type IsURLOptions = {
+    /**
+     * Accepted protocols, colon included. Defaults to `["http:", "https:"]`.
+     */
+    protocols?: string[] | undefined;
+    /**
+     * Require a domain like `example.com`, rejecting `localhost` and bare IPs.
+     */
+    requireTld?: boolean | undefined;
+};
+/**
+ * Options for `isUUID()`.
+ */
+export type IsUUIDOptions = {
+    /**
+     * Only accept this version. Otherwise versions 1 to 8 pass, plus the nil and max UUIDs.
+     */
+    version?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | undefined;
+};
+/**
+ * Options for `isHostname()`.
+ */
+export type IsHostnameOptions = {
+    /**
+     * Require a domain like `example.com`, rejecting `localhost`.
+     */
+    requireTld?: boolean | undefined;
+};
+/**
+ * Options for `isBase64()`.
+ */
+export type IsBase64Options = {
+    /**
+     * Expect the URL-safe alphabet (`-` and `_`), padding optional.
+     */
+    urlSafe?: boolean | undefined;
+};
+/**
+ * Any built-in typed array.
+ * @typedef {Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array} AnyTypedArray
+ */
+/**
+ * Any primitive value.
+ * @typedef {string | number | boolean | symbol | bigint | null | undefined} Primitive
+ */
+/**
+ * Options for `isURL()`.
+ * @typedef {object} IsURLOptions
+ * @property {string[]} [protocols] Accepted protocols, colon included. Defaults to `["http:", "https:"]`.
+ * @property {boolean} [requireTld] Require a domain like `example.com`, rejecting `localhost` and bare IPs.
+ */
+/**
+ * Options for `isUUID()`.
+ * @typedef {object} IsUUIDOptions
+ * @property {1|2|3|4|5|6|7|8} [version] Only accept this version. Otherwise versions 1 to 8 pass, plus the nil and max UUIDs.
+ */
+/**
+ * Options for `isHostname()`.
+ * @typedef {object} IsHostnameOptions
+ * @property {boolean} [requireTld] Require a domain like `example.com`, rejecting `localhost`.
+ */
+/**
+ * Options for `isBase64()`.
+ * @typedef {object} IsBase64Options
+ * @property {boolean} [urlSafe] Expect the URL-safe alphabet (`-` and `_`), padding optional.
+ */
+/**
+ * Is it an array?
+ *
+ * @example
+ * nc.isArray([1, 2]);        // true
+ * nc.isArray({ length: 0 }); // false
+ *
+ * @param {unknown} value
+ * @returns {value is any[]}
+ */
+export function isArray(value: unknown): value is any[];
+/**
+ * Is it a number? `NaN` is rejected, `Infinity` passes (see `isFinite`).
+ *
+ * @example
+ * nc.isNumber(42);   // true
+ * nc.isNumber(NaN);  // false
+ * nc.isNumber("42"); // false, use isNumeric for strings
+ *
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+export function isNumber(value: unknown): value is number;
+/**
+ * Is it a finite number? Unlike the global `isFinite`, strings are rejected.
+ *
+ * @example
+ * nc.isFinite(42);       // true
+ * nc.isFinite(Infinity); // false
+ * nc.isFinite("42");     // false
+ *
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+export function isFinite(value: unknown): value is number;
+/**
+ * Is it an integer?
+ *
+ * @example
+ * nc.isInteger(4);   // true
+ * nc.isInteger(4.5); // false
+ *
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+export function isInteger(value: unknown): value is number;
+/**
+ * Is it an integer JavaScript can represent exactly (up to 2^53 - 1)?
+ *
+ * @example
+ * nc.isSafeInteger(2 ** 53 - 1); // true
+ * nc.isSafeInteger(2 ** 53);     // false
+ *
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+export function isSafeInteger(value: unknown): value is number;
+/**
+ * Is it a finite number with a decimal part?
+ *
+ * @example
+ * nc.isFloat(4.2); // true
+ * nc.isFloat(4);   // false
+ *
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+export function isFloat(value: unknown): value is number;
+/**
+ * Is it a number greater than zero?
+ *
+ * @example
+ * nc.isPositive(3); // true
+ * nc.isPositive(0); // false
+ *
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+export function isPositive(value: unknown): value is number;
+/**
+ * Is it a number lower than zero?
+ *
+ * @example
+ * nc.isNegative(-3); // true
+ * nc.isNegative(0);  // false
+ *
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+export function isNegative(value: unknown): value is number;
+/**
+ * Is it `true` or `false`? Truthy and falsy values don't count.
  *
  * @example
- * nodeComfort.isArray([1, 2, 3]);    // true
- * nodeComfort.isArray("not array");  // false
+ * nc.isBoolean(false); // true
+ * nc.isBoolean(0);     // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is an Array.
+ * @param {unknown} value
+ * @returns {value is boolean}
  */
-export function isArray(value: any): boolean;
+export function isBoolean(value: unknown): value is boolean;
 /**
- * Checks if a value is a number (excluding NaN).
+ * Is it a string?
  *
  * @example
- * nodeComfort.isNumber(42);          // true
- * nodeComfort.isNumber(NaN);         // false
- * nodeComfort.isNumber("42");        // false
+ * nc.isString("hello");             // true
+ * nc.isString(new String("hello")); // false
+ *
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isString(value: unknown): value is string;
+/**
+ * Is it a symbol?
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a finite number or Infinity/-Infinity.
+ * @param {unknown} value
+ * @returns {value is symbol}
  */
-export function isNumber(value: any): boolean;
+export function isSymbol(value: unknown): value is symbol;
 /**
- * Checks if a value is a finite number (excludes NaN, Infinity and -Infinity).
+ * Is it a bigint?
  *
  * @example
- * nodeComfort.isFinite(42);        // true
- * nodeComfort.isFinite(Infinity);  // false
+ * nc.isBigInt(10n); // true
+ * nc.isBigInt(10);  // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a finite number.
+ * @param {unknown} value
+ * @returns {value is bigint}
  */
-export function isFinite(value: any): boolean;
+export function isBigInt(value: unknown): value is bigint;
 /**
- * Checks if a value is a safe integer.
+ * Is it `undefined`?
+ *
+ * @param {unknown} value
+ * @returns {value is undefined}
+ */
+export function isUndefined(value: unknown): value is undefined;
+/**
+ * Is it `null`?
+ *
+ * @param {unknown} value
+ * @returns {value is null}
+ */
+export function isNull(value: unknown): value is null;
+/**
+ * Is it `null` or `undefined`?
  *
  * @example
- * nodeComfort.isInteger(42);    // true
- * nodeComfort.isInteger(4.2);   // false
+ * nc.isNil(undefined); // true
+ * nc.isNil(0);         // false
+ *
+ * @param {unknown} value
+ * @returns {value is null | undefined}
+ */
+export function isNil(value: unknown): value is null | undefined;
+/**
+ * Is it anything but `null` or `undefined`? Pass it to `filter()` to drop
+ * missing values and keep the right type.
+ *
+ * @example
+ * const ids = [1, null, 2, undefined].filter(nc.isDefined); // number[]
+ *
+ * @template T
+ * @param {T} value
+ * @returns {value is NonNullable<T>}
+ */
+export function isDefined<T>(value: T): value is NonNullable<T>;
+/**
+ * Is it a primitive (string, number, boolean, symbol, bigint, `null` or `undefined`)?
+ *
+ * @param {unknown} value
+ * @returns {value is Primitive}
+ */
+export function isPrimitive(value: unknown): value is Primitive;
+/**
+ * Is it callable? Classes, async and generator functions count.
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is an integer.
+ * @param {unknown} value
+ * @returns {value is (...args: any[]) => any}
  */
-export function isInteger(value: any): boolean;
+export function isFunction(value: unknown): value is (...args: any[]) => any;
 /**
- * Checks if a value is a floating-point number (a finite non-integer number).
+ * Was it declared with `async`? A function that merely returns a promise
+ * doesn't count.
  *
  * @example
- * nodeComfort.isFloat(4.2);   // true
- * nodeComfort.isFloat(4);     // false
+ * nc.isAsyncFunction(async () => {});         // true
+ * nc.isAsyncFunction(() => Promise.resolve()); // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a non-integer finite number.
+ * @param {unknown} value
+ * @returns {value is (...args: any[]) => Promise<any>}
  */
-export function isFloat(value: any): boolean;
+export function isAsyncFunction(value: unknown): value is (...args: any[]) => Promise<any>;
 /**
- * Checks if a value is a function.
+ * Is it a generator function (`function*`)?
+ *
+ * @param {unknown} value
+ * @returns {value is (...args: any[]) => Generator}
+ */
+export function isGeneratorFunction(value: unknown): value is (...args: any[]) => Generator;
+/**
+ * Is it a generator object, the result of calling a `function*`?
+ *
+ * @param {unknown} value
+ * @returns {value is Generator}
+ */
+export function isGenerator(value: unknown): value is Generator;
+/**
+ * Is it a `class` rather than a plain function?
  *
  * @example
- * nodeComfort.isFunction(() => {});  // true
- * nodeComfort.isFunction(class {});  // true
- * nodeComfort.isFunction("fn");      // false
+ * nc.isClass(class User {});  // true
+ * nc.isClass(function () {}); // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a function.
+ * @param {unknown} value
+ * @returns {value is new (...args: any[]) => any}
  */
-export function isFunction(value: any): boolean;
+export function isClass(value: unknown): value is new (...args: any[]) => any;
 /**
- * Checks if a value is an async function (declared with `async`).
+ * Is it an object, and not `null`? Arrays, dates and class instances count;
+ * use `isPlainObject` for `{}` literals only.
+ *
+ * @param {unknown} value
+ * @returns {value is object}
+ */
+export function isObject(value: unknown): value is object;
+/**
+ * Is it a plain object, made with `{}`, `new Object()` or
+ * `Object.create(null)`? Arrays, dates, maps and class instances are rejected.
  *
  * @example
- * nodeComfort.isAsyncFunction(async () => {});  // true
- * nodeComfort.isAsyncFunction(() => {});        // false
+ * nc.isPlainObject({ a: 1 });   // true
+ * nc.isPlainObject(new Date()); // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is an async function.
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
  */
-export function isAsyncFunction(value: any): boolean;
+export function isPlainObject(value: unknown): value is Record<string, unknown>;
 /**
- * Checks if a value is a non-null object.
+ * Can it be awaited like a promise (anything with a `then` method)?
  *
- * Note: Arrays, Maps, Sets, Dates, etc. are also considered objects here.
+ * @param {unknown} value
+ * @returns {value is PromiseLike<any>}
+ */
+export function isPromise(value: unknown): value is PromiseLike<any>;
+/**
+ * Is it a regular expression?
+ *
+ * @param {unknown} value
+ * @returns {value is RegExp}
+ */
+export function isRegExp(value: unknown): value is RegExp;
+/**
+ * Is it a `Date`, valid or not? Use `isValidDate` to reject `Invalid Date`.
+ *
+ * @param {unknown} value
+ * @returns {value is Date}
+ */
+export function isDate(value: unknown): value is Date;
+/**
+ * Is it a `Date` holding a real point in time?
  *
  * @example
- * nodeComfort.isObject({});          // true
- * nodeComfort.isObject([]);          // true
- * nodeComfort.isObject(null);        // false
- * nodeComfort.isObject("str");       // false
+ * nc.isValidDate(new Date());       // true
+ * nc.isValidDate(new Date("nope")); // false
+ *
+ * @param {unknown} value
+ * @returns {value is Date}
+ */
+export function isValidDate(value: unknown): value is Date;
+/**
+ * Is it a `Map`?
+ *
+ * @param {unknown} value
+ * @returns {value is Map<unknown, unknown>}
+ */
+export function isMap(value: unknown): value is Map<unknown, unknown>;
+/**
+ * Is it a `Set`?
+ *
+ * @param {unknown} value
+ * @returns {value is Set<unknown>}
+ */
+export function isSet(value: unknown): value is Set<unknown>;
+/**
+ * Is it a `WeakMap`?
+ *
+ * @param {unknown} value
+ * @returns {value is WeakMap<object, unknown>}
+ */
+export function isWeakMap(value: unknown): value is WeakMap<object, unknown>;
+/**
+ * Is it a `WeakSet`?
+ *
+ * @param {unknown} value
+ * @returns {value is WeakSet<object>}
+ */
+export function isWeakSet(value: unknown): value is WeakSet<object>;
+/**
+ * Does it work with `for...of`? Strings, arrays, maps, sets and generators do.
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a non-null object.
+ * @param {unknown} value
+ * @returns {value is Iterable<unknown>}
  */
-export function isObject(value: any): boolean;
+export function isIterable(value: unknown): value is Iterable<unknown>;
 /**
- * Checks if a value is a plain object (created via `{}` or `new Object()`).
+ * Does it work with `for await...of`, like streams and async generators?
  *
- * Unlike {@link isObject}, this excludes arrays, Maps, Dates, class instances, etc.
+ * @param {unknown} value
+ * @returns {value is AsyncIterable<unknown>}
+ */
+export function isAsyncIterable(value: unknown): value is AsyncIterable<unknown>;
+/**
+ * Is it a Node.js `Buffer`?
+ *
+ * @param {unknown} value
+ * @returns {value is Buffer}
+ */
+export function isBuffer(value: unknown): value is Buffer;
+/**
+ * Is it a typed array (`Uint8Array`, `Float64Array`...)? Buffers count.
+ *
+ * @param {unknown} value
+ * @returns {value is AnyTypedArray}
+ */
+export function isTypedArray(value: unknown): value is AnyTypedArray;
+/**
+ * Is it an `Error`, including subclasses and errors from other realms?
+ *
+ * @param {unknown} value
+ * @returns {value is Error}
+ */
+export function isError(value: unknown): value is Error;
+/**
+ * Is it empty? `null`, `undefined`, `""`, `[]`, `{}` and empty maps and sets
+ * are. Numbers, booleans, functions, dates, regular expressions and errors
+ * never are.
  *
  * @example
- * nodeComfort.isPlainObject({ a: 1 });    // true
- * nodeComfort.isPlainObject([]);          // false
- * nodeComfort.isPlainObject(new Date());  // false
+ * nc.isEmpty({});  // true
+ * nc.isEmpty(0);   // false
+ * nc.isEmpty(" "); // false, see isBlank
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a plain object.
+ * @param {unknown} value
+ * @returns {boolean}
  */
-export function isPlainObject(value: any): boolean;
+export function isEmpty(value: unknown): boolean;
 /**
- * Checks if a value is a boolean.
+ * Is it `null`, `undefined`, or a string with nothing but whitespace?
  *
  * @example
- * nodeComfort.isBoolean(true);       // true
- * nodeComfort.isBoolean(false);      // true
- * nodeComfort.isBoolean(0);          // false
+ * nc.isBlank("  \n"); // true
+ * nc.isBlank(" a ");  // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a boolean.
+ * @param {unknown} value
+ * @returns {boolean}
  */
-export function isBoolean(value: any): boolean;
+export function isBlank(value: unknown): boolean;
 /**
- * Checks if a value is a string.
+ * Is it an array where every item passes `guard`?
  *
  * @example
- * nodeComfort.isString("hello");     // true
- * nodeComfort.isString(123);         // false
+ * if (nc.isArrayOf(input, nc.isString)) input.join(", "); // input: string[]
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a string.
+ * @template T
+ * @param {unknown} value
+ * @param {(item: unknown) => item is T} guard Checked against every item, like `nc.isString`.
+ * @returns {value is T[]}
  */
-export function isString(value: any): boolean;
+export function isArrayOf<T>(value: unknown, guard: (item: unknown) => item is T): value is T[];
 /**
- * Checks if a value is a symbol.
+ * Is it one of the allowed values? With a constant list, the value gets the
+ * matching literal type.
  *
  * @example
- * nodeComfort.isSymbol(Symbol("x"));  // true
+ * const ROLES = ["admin", "user"] as const;
+ * if (nc.isOneOf(input, ROLES)) input; // "admin" | "user"
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a symbol.
+ * @template {readonly unknown[]} L
+ * @param {unknown} value
+ * @param {L} allowed
+ * @returns {value is L[number]}
  */
-export function isSymbol(value: any): boolean;
+export function isOneOf<L extends readonly unknown[]>(value: unknown, allowed: L): value is L[number];
 /**
- * Checks if a value is a BigInt.
+ * 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.
  *
  * @example
- * nodeComfort.isBigInt(10n);  // true
- * nodeComfort.isBigInt(10);   // false
+ * nc.isEmail("jose@exemple.fr");     // true
+ * nc.isEmail("john..doe@example.com"); // false
+ * nc.isEmail("john@localhost");       // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a BigInt.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isBigInt(value: any): boolean;
+export function isEmail(value: unknown): value is string;
 /**
- * Checks if a value is exactly undefined.
+ * Is it an absolute URL with an allowed protocol (http and https by default)?
  *
  * @example
- * nodeComfort.isUndefined(undefined);  // true
- * nodeComfort.isUndefined(null);       // false
+ * 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
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is undefined.
+ * @param {unknown} value
+ * @param {IsURLOptions} [options]
+ * @returns {value is string}
  */
-export function isUndefined(value: any): boolean;
+export function isURL(value: unknown, options?: IsURLOptions): value is string;
 /**
- * Checks if a value is exactly null.
+ * Is it a UUID?
  *
  * @example
- * nodeComfort.isNull(null);          // true
- * nodeComfort.isNull(undefined);     // false
+ * nc.isUUID(nc.id.uuid());           // true
+ * nc.isUUID(id, { version: 7 });     // only v7
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is null.
+ * @param {unknown} value
+ * @param {IsUUIDOptions} [options]
+ * @returns {value is string}
  */
-export function isNull(value: any): boolean;
+export function isUUID(value: unknown, options?: IsUUIDOptions): value is string;
 /**
- * Checks if a value is `null` or `undefined`.
+ * Is it a string of valid JSON?
  *
  * @example
- * nodeComfort.isNil(null);       // true
- * nodeComfort.isNil(undefined);  // true
- * nodeComfort.isNil(0);          // false
+ * nc.isJSON('{"a":1}'); // true
+ * nc.isJSON("{a:1}");   // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is null or undefined.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isNil(value: any): boolean;
+export function isJSON(value: unknown): value is string;
 /**
- * Checks if a value is a primitive (string, number, boolean, symbol, bigint, null or undefined).
+ * Is it a finite number, or a string that is exactly one (spaces around are fine)?
  *
  * @example
- * nodeComfort.isPrimitive(42);    // true
- * nodeComfort.isPrimitive({});    // false
+ * nc.isNumeric("4.2e3"); // true
+ * nc.isNumeric(" 12 ");  // true
+ * nc.isNumeric("12px");  // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a primitive.
+ * @param {unknown} value
+ * @returns {value is number | string}
  */
-export function isPrimitive(value: any): boolean;
+export function isNumeric(value: unknown): value is number | string;
 /**
- * Checks if a value is a Promise (or a thenable object).
+ * Is it an IP address?
  *
  * @example
- * nodeComfort.isPromise(Promise.resolve());       // true
- * nodeComfort.isPromise({ then() {} });            // true
- * nodeComfort.isPromise(42);                       // false
+ * nc.isIP("192.168.0.1"); // true
+ * nc.isIP("::1");         // true
+ * nc.isIP("::1", 4);      // false
+ *
+ * @param {unknown} value
+ * @param {4|6} [version] Only accept IPv4 or IPv6.
+ * @returns {value is string}
+ */
+export function isIP(value: unknown, version?: 4 | 6): value is string;
+/**
+ * Is it an IPv4 address, like `192.168.0.1`?
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a Promise or thenable.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isPromise(value: any): boolean;
+export function isIPv4(value: unknown): value is string;
 /**
- * Checks if a value is a RegExp instance.
+ * Is it an IPv6 address, like `::1`?
+ *
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isIPv6(value: unknown): value is string;
+/**
+ * Is it a valid port (0 to 65535), as a number or a numeric string?
  *
  * @example
- * nodeComfort.isRegExp(/a/);   // true
- * nodeComfort.isRegExp("a");   // false
+ * nc.isPort("8080"); // true
+ * nc.isPort(70000);  // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a RegExp.
+ * @param {unknown} value
+ * @returns {boolean}
  */
-export function isRegExp(value: any): boolean;
+export function isPort(value: unknown): boolean;
 /**
- * Checks if a value is a built-in Date instance.
+ * Is it a hexadecimal string? A `0x` prefix is allowed.
  *
- * Uses `util.types.isDate` under the hood to handle cross-realm Dates.
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isHex(value: unknown): value is string;
+/**
+ * Is it a CSS hex color (`#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`)?
  *
  * @example
- * nodeComfort.isDate(new Date());    // true
- * nodeComfort.isDate("2024-01-01");  // false
+ * nc.isHexColor("#f80"); // true
+ * nc.isHexColor("f80");  // false, the # is required
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a Date instance.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isDate(value: any): boolean;
+export function isHexColor(value: unknown): value is string;
 /**
- * Checks if a value is a **valid** Date (a Date instance that is not `Invalid Date`).
+ * Is it valid Base64?
  *
  * @example
- * nodeComfort.isValidDate(new Date());            // true
- * nodeComfort.isValidDate(new Date("nope"));      // false
+ * nc.isBase64("aGVsbG8=");                   // true
+ * nc.isBase64("aGVsbG8", { urlSafe: true }); // true
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a valid Date.
+ * @param {unknown} value
+ * @param {IsBase64Options} [options]
+ * @returns {value is string}
  */
-export function isValidDate(value: any): boolean;
+export function isBase64(value: unknown, options?: IsBase64Options): value is string;
 /**
- * Checks if a value is a built-in Map instance.
+ * Is it a semantic version? A leading `v` is fine.
  *
  * @example
- * nodeComfort.isMap(new Map());      // true
- * nodeComfort.isMap({});             // false
+ * nc.isSemver("v2.0.0-rc.1"); // true
+ * nc.isSemver("1.2");         // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a Map.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isMap(value: any): boolean;
+export function isSemver(value: unknown): value is string;
 /**
- * Checks if a value is a built-in Set instance.
+ * Is it an ISO 8601 date or date-time, and a real calendar date?
  *
  * @example
- * nodeComfort.isSet(new Set());      // true
- * nodeComfort.isSet([]);             // false
+ * nc.isISODate("2024-02-29T10:00:00Z"); // true
+ * nc.isISODate("2023-02-29");           // false, not a leap year
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a Set.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isSet(value: any): boolean;
+export function isISODate(value: unknown): value is string;
 /**
- * Checks if a value is a WeakMap instance.
+ * Is it a URL slug like `my-first-post`? See `nc.str.slugify()` to make one.
+ *
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isSlug(value: unknown): value is string;
+/**
+ * Is it made only of letters, in any alphabet?
+ *
+ * @example
+ * nc.isAlpha("Élodie"); // true
+ * nc.isAlpha("abc1");   // false
+ *
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isAlpha(value: unknown): value is string;
+/**
+ * Is it made only of letters and digits, in any alphabet?
+ *
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isAlphanumeric(value: unknown): value is string;
+/**
+ * Could it be a card number? Checks the length and the Luhn checksum;
+ * spaces and dashes are ignored.
+ *
+ * @example
+ * nc.isCreditCard("4242 4242 4242 4242"); // true
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a WeakMap.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isWeakMap(value: any): boolean;
+export function isCreditCard(value: unknown): value is string;
 /**
- * Checks if a value is a WeakSet instance.
+ * Does it look like a JSON Web Token? The signature is not verified; use
+ * `nc.crypto.verifyJWT()` for that.
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a WeakSet.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isWeakSet(value: any): boolean;
+export function isJWT(value: unknown): value is string;
 /**
- * Checks if a value is an iterable (has a `Symbol.iterator`).
+ * Is it a host name, like `example.com`, `api.internal` or `localhost`?
+ * International names are accepted. IP addresses aren't: see `isIP`.
+ *
+ * @example
+ * nc.isHostname("api.example.com");                    // true
+ * nc.isHostname("localhost");                          // true
+ * nc.isHostname("localhost", { requireTld: true });    // false
+ * nc.isHostname("-bad-.com");                          // false
  *
- * Strings, arrays, Maps, Sets and generators are iterable.
+ * @param {unknown} value
+ * @param {IsHostnameOptions} [options]
+ * @returns {value is string}
+ */
+export function isHostname(value: unknown, options?: IsHostnameOptions): value is string;
+/**
+ * Is it a MAC address? Accepts `aa:bb:cc:dd:ee:ff`, `aa-bb-cc-dd-ee-ff` and
+ * `aabb.ccdd.eeff`.
  *
  * @example
- * nodeComfort.isIterable([1, 2]);   // true
- * nodeComfort.isIterable("hi");     // true
- * nodeComfort.isIterable({});       // false
+ * nc.isMACAddress("00:1B:44:11:3A:B7"); // true
+ * nc.isMACAddress("00:1B:44:11:3A");    // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is iterable.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isIterable(value: any): boolean;
+export function isMACAddress(value: unknown): value is string;
 /**
- * Checks if a value is a Node.js Buffer.
+ * Is it a valid IBAN? Checks the format and the checksum, spaces allowed.
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a Buffer.
+ * @example
+ * nc.isIBAN("FR76 3000 6000 0112 3456 7890 189"); // true
+ * nc.isIBAN("FR76 3000 6000 0112 3456 7890 180"); // false, wrong checksum
+ *
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isBuffer(value: any): boolean;
+export function isIBAN(value: unknown): value is string;
 /**
- * Checks if a value is any TypedArray (Uint8Array, Float64Array, etc.).
+ * Is it a phone number in the international E.164 format: a `+`, then 7 to
+ * 15 digits, no spaces? That's what SMS and telephony APIs expect.
+ *
+ * @example
+ * nc.isE164("+33612345678"); // true
+ * nc.isE164("06 12 34 56 78"); // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a TypedArray.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isTypedArray(value: any): boolean;
+export function isE164(value: unknown): value is string;
 /**
- * Checks if a value is a native Error instance.
+ * Is it a MongoDB ObjectId, 24 hexadecimal characters?
  *
- * Uses `util.types.isNativeError` to correctly handle errors from other realms.
+ * @example
+ * nc.isObjectId("507f1f77bcf86cd799439011"); // true
+ *
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isObjectId(value: unknown): value is string;
+/**
+ * Is it a ULID, like the ones `nc.id.ulid()` makes?
  *
  * @example
- * nodeComfort.isError(new Error("x"));      // true
- * nodeComfort.isError(new TypeError("x"));  // true
- * nodeComfort.isError({ message: "x" });    // false
+ * nc.isULID(nc.id.ulid()); // true
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a native Error.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isError(value: any): boolean;
+export function isULID(value: unknown): value is string;
 /**
- * Checks if a value is "empty".
+ * Is it a `data:` URL, like an inline image?
  *
- * Emptiness rules:
- * - `null` / `undefined` -> empty
- * - string / array -> empty when `length === 0`
- * - Map / Set -> empty when `size === 0`
- * - plain object -> empty when it has no own enumerable keys
- * - anything else (numbers, booleans, functions, ...) -> never empty
+ * @example
+ * nc.isDataURL("data:image/png;base64,iVBORw0KGgo="); // true
+ * nc.isDataURL("data:,Hello");                         // true
+ *
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isDataURL(value: unknown): value is string;
+/**
+ * Is it a media type, like `application/json` or
+ * `text/html; charset=utf-8`?
  *
  * @example
- * nodeComfort.isEmpty("");        // true
- * nodeComfort.isEmpty([]);        // true
- * nodeComfort.isEmpty({});        // true
- * nodeComfort.isEmpty(new Map()); // true
- * nodeComfort.isEmpty("x");       // false
- * nodeComfort.isEmpty(0);         // false
+ * nc.isMimeType("image/svg+xml"); // true
+ * nc.isMimeType("json");          // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is considered empty.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isEmpty(value: any): boolean;
+export function isMimeType(value: unknown): value is string;
 /**
- * Checks if a string is a valid, well-formed email address.
+ * Is it a time zone Node.js knows, like `"Europe/Paris"` or `"UTC"`?
+ *
+ * @example
+ * nc.isTimeZone("America/New_York"); // true
+ * nc.isTimeZone("Mars/Olympus");     // false
  *
- * This is a pragmatic check (not a full RFC 5322 parser) that covers the
- * vast majority of real-world addresses.
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+export function isTimeZone(value: unknown): value is string;
+/**
+ * Is it a well-formed locale, like `"fr"`, `"en-GB"` or `"zh-Hant-TW"`?
  *
  * @example
- * nodeComfort.isEmail("john@example.com");  // true
- * nodeComfort.isEmail("nope");              // false
+ * nc.isLocale("pt-BR"); // true
+ * nc.isLocale("en_US"); // false, use a dash
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value looks like an email address.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isEmail(value: any): boolean;
+export function isLocale(value: unknown): value is string;
 /**
- * Checks if a string is a valid HTTP(S) URL.
+ * Is it a cron expression `nc.time.cron()` understands?
  *
  * @example
- * nodeComfort.isURL("https://example.com");  // true
- * nodeComfort.isURL("ftp://example.com");    // false (not http/https)
+ * nc.isCron("0 9 * * 1-5"); // true
+ * nc.isCron("@daily");      // true
+ * nc.isCron("61 * * * *");  // false
  *
- * @param {*} value - Value to check.
- * @param {{ protocols?: string[] }} [options] - Allowed protocols (default: http, https).
- * @returns {boolean} True if the value is a valid URL with an allowed protocol.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isURL(value: any, options?: {
-    protocols?: string[];
-}): boolean;
+export function isCron(value: unknown): value is string;
 /**
- * Checks if a string is a valid UUID (versions 1-5, any variant).
+ * Is it made only of ASCII characters?
  *
  * @example
- * nodeComfort.isUUID("123e4567-e89b-12d3-a456-426614174000");  // true
+ * nc.isASCII("hello"); // true
+ * nc.isASCII("héllo"); // false
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a UUID.
+ * @param {unknown} value
+ * @returns {value is string}
  */
-export function isUUID(value: any): boolean;
+export function isASCII(value: unknown): value is string;
 /**
- * Checks if a string is valid, parseable JSON.
+ * Throws an `AssertionError` if `condition` is falsy. Afterwards, TypeScript
+ * knows the condition holds.
  *
  * @example
- * nodeComfort.isJSON('{"a":1}');  // true
- * nodeComfort.isJSON("{a:1}");    // false
+ * const user = users.find((u) => u.id === id);
+ * nc.assert(user, `User ${id} not found`);
+ * user.name; // no "possibly undefined" here
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is a JSON-parseable string.
+ * @param {unknown} condition
+ * @param {string | (() => string)} [message="Assertion failed"] A message, or a function that builds it.
+ * @returns {asserts condition}
+ * @throws {AssertionError}
  */
-export function isJSON(value: any): boolean;
+export function assert(condition: unknown, message?: string | (() => string)): asserts condition;
 /**
- * Checks if a value is numeric • a number, or a string that fully represents one.
+ * Throws an `AssertionError` unless `value` passes `guard`. Afterwards,
+ * `value` has the guarded type.
  *
  * @example
- * nodeComfort.isNumeric(42);      // true
- * nodeComfort.isNumeric("42");    // true
- * nodeComfort.isNumeric("4.2e3"); // true
- * nodeComfort.isNumeric("4px");   // false
+ * nc.assertType(config.port, nc.isInteger, "port must be an integer");
  *
- * @param {*} value - Value to check.
- * @returns {boolean} True if the value is numeric.
+ * @template T
+ * @param {unknown} value
+ * @param {(value: unknown) => value is T} guard A check like `nc.isString`.
+ * @param {string | (() => string)} [message]
+ * @returns {asserts value is T}
+ * @throws {AssertionError}
  */
-export function isNumeric(value: any): boolean;
+export function assertType<T>(value: unknown, guard: (value: unknown) => value is T, message?: string | (() => string)): asserts value is T;
 //# sourceMappingURL=Checker.d.ts.map