docs: JSDoc everywhere

behaviors/common/isFQDN.ts

@@ -10,6 +10,16 @@ const default_fqdn_options: { [key: string]: boolean } = {
 	allow_trailing_dot: false,
 };
 
+/**
+ * Checks if the given string is a fully qualified domain name (FQDN).
+ *
+ * @param str - The string to be checked.
+ * @param options - Configuration options for FQDN validation.
+ * @param options.allow_trailing_dot - If true, allows the FQDN to have a trailing dot.
+ * @param options.require_tld - If true, requires the FQDN to have a top-level domain (TLD).
+ * @param options.allow_underscores - If true, allows underscores in the FQDN.
+ * @returns `true` if the string is a valid FQDN, `false` otherwise.
+ */
 export function isFQDN(
 	str: string,
 	options: isFQDN = default_fqdn_options,

behaviors/common/isFullWidth.ts

@@ -1,5 +1,11 @@
 export const fullWidth = /[^\u0020-\u007E\uFF61-\uFF9F\uFFA0-\uFFDC\uFFE8-\uFFEE0-9a-zA-Z]/;
 
+/**
+ * Checks if the given string contains any full-width characters.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string contains full-width characters, otherwise `false`.
+ */
 export function isFullWidth(str: string): boolean {
 	return fullWidth.test(str);
 }

behaviors/common/isHSL.ts

@@ -3,6 +3,16 @@ const hslcomma =
 const hslspace =
 	/^(hsl)a?\(\s*((\+|\-)?([0-9]+(\.[0-9]+)?(e(\+|\-)?[0-9]+)?|\.[0-9]+(e(\+|\-)?[0-9]+)?))(deg|grad|rad|turn|\s)(\s*(\+|\-)?([0-9]+(\.[0-9]+)?(e(\+|\-)?[0-9]+)?|\.[0-9]+(e(\+|\-)?[0-9]+)?)%){2}\s*(\/\s*((\+|\-)?([0-9]+(\.[0-9]+)?(e(\+|\-)?[0-9]+)?|\.[0-9]+(e(\+|\-)?[0-9]+)?)%?)\s*)?\)$/i;
 
+/**
+ * Checks if a given string is a valid HSL (Hue, Saturation, Lightness) color format.
+ *
+ * The function tests the input string against two regular expressions:
+ * - One for HSL values separated by commas.
+ * - One for HSL values separated by spaces.
+ *
+ * @param str - The string to be tested.
+ * @returns `true` if the string is a valid HSL color format, otherwise `false`.
+ */
 export function isHSL(str: string): boolean {
 	return hslcomma.test(str) || hslspace.test(str);
 }

behaviors/common/isHalfWidth.ts

@@ -1,5 +1,14 @@
 export const halfWidth = /[\u0020-\u007E\uFF61-\uFF9F\uFFA0-\uFFDC\uFFE8-\uFFEE0-9a-zA-Z]/;
 
+/**
+ * Checks if the given string contains any half-width characters.
+ *
+ * Half-width characters are characters that occupy half the width of a full-width character.
+ * This is common in East Asian typography, where characters can be either full-width or half-width.
+ *
+ * @param str - The string to be checked for half-width characters.
+ * @returns `true` if the string contains any half-width characters, otherwise `false`.
+ */
 export function isHalfWidth(str: string): boolean {
 	return halfWidth.test(str);
 }

behaviors/common/isHash.ts

@@ -14,6 +14,13 @@ const lengths: { [key: string]: number } = {
 	crc32b: 8,
 };
 
+/**
+ * Checks if a given string is a valid hash for the specified algorithm.
+ *
+ * @param str - The string to be checked.
+ * @param algorithm - The algorithm to be used for validation. This should correspond to an index in the `lengths` array.
+ * @returns `true` if the string is a valid hash for the specified algorithm, `false` otherwise.
+ */
 export function isHash(str: string, algorithm: number): boolean {
 	const hash = new RegExp(`^[a-fA-F0-9]{${lengths[algorithm]}}$`);
 	return hash.test(str);

behaviors/common/isHexColor.ts

@@ -1,5 +1,14 @@
 const hexcolor = /^#?([0-9A-F]{3}|[0-9A-F]{4}|[0-9A-F]{6}|[0-9A-F]{8})$/i;
 
+/**
+ * Checks if the given string is a valid hexadecimal color code.
+ *
+ * A valid hexadecimal color code starts with a '#' followed by either
+ * 3 or 6 hexadecimal digits (0-9, a-f, A-F).
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid hexadecimal color code, otherwise `false`.
+ */
 export function isHexColor(str: string): boolean {
 	return hexcolor.test(str);
 }

behaviors/common/isHexadecimal.ts

@@ -1,5 +1,11 @@
 const hexadecimal = /^(0x|0h)?[0-9A-F]+$/i;
 
+/**
+ * Checks if the given string is a valid hexadecimal number.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid hexadecimal number, otherwise `false`.
+ */
 export function isHexadecimal(str: string): boolean {
 	return hexadecimal.test(str);
 }

behaviors/common/isIBAN.ts

@@ -131,6 +131,14 @@ function hasValidIbanChecksum(str: string): boolean {
 	return remainder === 1;
 }
 
+/**
+ * Checks if the provided string is a valid IBAN (International Bank Account Number).
+ *
+ * This function verifies both the format and the checksum of the IBAN.
+ *
+ * @param str - The string to be checked as an IBAN.
+ * @returns `true` if the string is a valid IBAN, `false` otherwise.
+ */
 export function isIBAN(str: string): boolean {
 	return hasValidIbanFormat(str) && hasValidIbanChecksum(str);
 }

behaviors/common/isIP.ts

@@ -30,6 +30,14 @@
 const ipv4Maybe = /^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$/;
 const ipv6Block = /^[0-9A-F]{1,4}$/i;
 
+/**
+ * Checks if a given string is a valid IP address (either IPv4 or IPv6).
+ *
+ * @param str - The string to be checked as an IP address.
+ * @param version - The IP version to check against. Can be '4', '6', or an empty string.
+ *                   If an empty string is provided, the function will check for both IPv4 and IPv6.
+ * @returns `true` if the string is a valid IP address of the specified version, `false` otherwise.
+ */
 export function isIP(
 	str: string,
 	version: string | number = '',

behaviors/common/isIPRange.ts

@@ -2,6 +2,16 @@ import { isIP } from './isIP.ts';
 
 const subnetMaybe = /^\d{1,2}$/;
 
+/**
+ * Checks if the given string is a valid IPv4 range in CIDR notation.
+ *
+ * The function splits the input string into two parts: the IP address and the subnet mask.
+ * It validates the subnet mask to ensure it is a number between 0 and 32, inclusive, and
+ * does not have leading zeros. It also checks if the IP address is a valid IPv4 address.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid IPv4 range in CIDR notation, otherwise `false`.
+ */
 export function isIPRange(str: string): boolean {
 	const parts: string[] = str.split('/');
 

behaviors/common/isISBN.ts

@@ -2,6 +2,13 @@ const isbn10Maybe = /^(?:[0-9]{9}X|[0-9]{10})$/;
 const isbn13Maybe = /^(?:[0-9]{13})$/;
 const factor = [1, 3];
 
+/**
+ * Checks if a given string is a valid ISBN (International Standard Book Number).
+ *
+ * @param str - The string to be checked.
+ * @param version - The ISBN version to validate against (either '10' or '13'). If not provided, the function will check against both versions.
+ * @returns `true` if the string is a valid ISBN, `false` otherwise.
+ */
 export function isISBN(
 	str: string,
 	version: string | number = '',

behaviors/common/isISIN.ts

@@ -1,5 +1,14 @@
 const isin = /^[A-Z]{2}[0-9A-Z]{9}[0-9]$/;
 
+/**
+ * Checks if the given string is a valid ISIN (International Securities Identification Number).
+ *
+ * The function first verifies the format of the ISIN using a regular expression.
+ * Then, it calculates the checksum using the Luhn algorithm to ensure the ISIN is valid.
+ *
+ * @param str - The string to be checked as an ISIN.
+ * @returns `true` if the string is a valid ISIN, `false` otherwise.
+ */
 export function isISIN(str: string): boolean {
 	if (!isin.test(str)) {
 		return false;

behaviors/common/isISO31661Alpha2.ts

@@ -253,6 +253,16 @@ const validISO31661Alpha2CountriesCodes: Array<string> = [
 	'ZW',
 ];
 
+/**
+ * Checks if the given string is a valid ISO 3166-1 alpha-2 country code.
+ *
+ * ISO 3166-1 alpha-2 codes are two-letter country codes defined in ISO 3166-1, part of the ISO 3166 standard
+ * published by the International Organization for Standardization (ISO), to represent countries, dependent territories,
+ * and special areas of geographical interest.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid ISO 3166-1 alpha-2 country code, otherwise `false`.
+ */
 export function isISO31661Alpha2(str: string): boolean {
 	return includes(validISO31661Alpha2CountriesCodes, str.toUpperCase());
 }

behaviors/common/isISO31661Alpha3.ts

@@ -253,6 +253,12 @@ const validISO31661Alpha3CountriesCodes: Array<string> = [
 	'ZWE',
 ];
 
+/**
+ * Checks if the given string is a valid ISO 3166-1 alpha-3 country code.
+ *
+ * @param str - The string to validate as an ISO 3166-1 alpha-3 country code.
+ * @returns `true` if the string is a valid ISO 3166-1 alpha-3 country code, otherwise `false`.
+ */
 export function isISO31661Alpha3(str: string): boolean {
 	return includes(validISO31661Alpha3CountriesCodes, str.toUpperCase());
 }

behaviors/common/isISO8601.ts

@@ -44,6 +44,13 @@ const defaultISO8601Options: ISO8601Options = {
 	strict: false,
 };
 
+/**
+ * Checks if a given string is a valid ISO 8601 date.
+ *
+ * @param str - The string to be checked.
+ * @param options - Optional settings to customize the validation.
+ * @returns `true` if the string is a valid ISO 8601 date, otherwise `false`.
+ */
 export function isISO8601(
 	str: string,
 	options: ISO8601Options = defaultISO8601Options,

behaviors/common/isISRC.ts

@@ -1,6 +1,12 @@
 // see http://isrc.ifpi.org/en/isrc-standard/code-syntax
 const isrc = /^[A-Z]{2}[0-9A-Z]{3}\d{2}\d{5}$/;
 
+/**
+ * Checks if the given string is a valid International Standard Recording Code (ISRC).
+ *
+ * @param str - The string to be checked.
+ * @returns True if the string is a valid ISRC, false otherwise.
+ */
 export function isISRC(str: string): boolean {
 	return isrc.test(str);
 }

behaviors/common/isISSN.ts

@@ -1,5 +1,14 @@
 const issn = '^\\d{4}-?\\d{3}[\\dX]$';
 
+/**
+ * Validates whether a given string is a valid ISSN (International Standard Serial Number).
+ *
+ * @param str - The string to be validated as an ISSN.
+ * @param options - Optional configuration object.
+ * @param options.require_hyphen - If true, the ISSN must include a hyphen.
+ * @param options.case_sensitive - If true, the validation will be case-sensitive.
+ * @returns A boolean indicating whether the string is a valid ISSN.
+ */
 export function isISSN(
 	str: string,
 	options: { require_hyphen?: boolean; case_sensitive?: boolean } = {},

behaviors/common/isIdentityCard.ts

@@ -345,6 +345,14 @@ const validators: { [key: string]: (str: string) => boolean } = {
 	},
 };
 
+/**
+ * Validates if a given string is an identity card number for a specified locale.
+ *
+ * @param str - The string to be validated as an identity card number.
+ * @param locale - The locale to validate against. If 'any', it will check against all available locales.
+ * @returns `true` if the string is a valid identity card number for the specified locale, otherwise `false`.
+ * @throws Will throw an error if the provided locale is not supported.
+ */
 export function isIdentityCard(str: string, locale: string): boolean {
 	if (locale in validators) {
 		return validators[locale](str);

behaviors/common/isIn.ts

@@ -1,4 +1,11 @@
 import { toString } from './util/toString.ts';
+/**
+ * Checks if a given string is present in the provided options.
+ *
+ * @param str - The string to check for presence.
+ * @param options - The options to check against. Can be an array, an object, or any type with an `indexOf` method.
+ * @returns `true` if the string is found in the options, `false` otherwise.
+ */
 // deno-lint-ignore no-explicit-any
 export function isIn(str: string, options: any): boolean {
 	// deno-lint-ignore no-explicit-any

behaviors/common/isInt.ts

@@ -13,6 +13,18 @@ const defaultOptions: Options = {
 const int = /^[-+]?(0|[1-9][0-9]*)$/;
 const intLeadingZeros = /^[-+]?[0-9]+$/;
 
+/**
+ * Checks if the given string is a valid integer based on the provided options.
+ *
+ * @param str - The string to be checked.
+ * @param options - An optional object to specify validation criteria.
+ * @param options.allow_leading_zeroes - If true, allows integers with leading zeroes.
+ * @param options.min - The minimum value the integer can be.
+ * @param options.max - The maximum value the integer can be.
+ * @param options.lt - The integer must be less than this value.
+ * @param options.gt - The integer must be greater than this value.
+ * @returns A boolean indicating whether the string is a valid integer.
+ */
 export function isInt(
 	str: string,
 	options: Options = defaultOptions,

behaviors/common/isJSON.ts

@@ -1,3 +1,9 @@
+/**
+ * Checks if a given string is a valid JSON.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid JSON object, otherwise `false`.
+ */
 export function isJSON(str: string): boolean {
 	try {
 		const obj = JSON.parse(str);

behaviors/common/isJWT.ts

@@ -1,5 +1,13 @@
 import { isBase64 } from './isBase64.ts';
 
+/**
+ * Checks if the given string is a valid JWT (JSON Web Token).
+ *
+ * A valid JWT consists of either two or three base64url encoded segments separated by dots.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid JWT, `false` otherwise.
+ */
 export function isJWT(str: string): boolean {
 	const dotSplit: Array<string> = str.split('.');
 	const len = dotSplit.length;

behaviors/common/isLatLong.ts

@@ -1,6 +1,15 @@
 const lat = /^\(?[+-]?(90(\.0+)?|[1-8]?\d(\.\d+)?)$/;
 const long = /^\s?[+-]?(180(\.0+)?|1[0-7]\d(\.\d+)?|\d{1,2}(\.\d+)?)\)?$/;
 
+/**
+ * Checks if a given string is a valid latitude and longitude pair.
+ *
+ * The string should be in the format "latitude,longitude". Optionally, the latitude and longitude
+ * can be enclosed in parentheses.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid latitude and longitude pair, `false` otherwise.
+ */
 export function isLatLong(str: string): boolean {
 	if (!str.includes(',')) return false;
 	const pair = str.split(',');

behaviors/common/isLocale.ts

@@ -1,5 +1,14 @@
 const localeReg = /^[A-z]{2,4}([_-]([A-z]{4}|[\d]{3}))?([_-]([A-z]{2}|[\d]{3}))?$/;
 
+/**
+ * Checks if the given string is a valid locale.
+ *
+ * This function returns `true` if the string matches either 'en_US_POSIX' or 'ca_ES_VALENCIA',
+ * or if it matches the regular expression defined by `localeReg`.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid locale, otherwise `false`.
+ */
 export function isLocale(str: string): boolean {
 	if (str === 'en_US_POSIX' || str === 'ca_ES_VALENCIA') {
 		return true;

behaviors/common/isLowerCase.ts

@@ -1,3 +1,9 @@
+/**
+ * Checks if the given string is in lower case.
+ *
+ * @param str - The string to check.
+ * @returns `true` if the string is in lower case, otherwise `false`.
+ */
 export function isLowerCase(str: string): boolean {
 	return str === str.toLowerCase();
 }

behaviors/common/isMACAddress.ts

@@ -8,6 +8,14 @@ interface isMACAddressOptions {
 	no_colons: boolean;
 }
 
+/**
+ * Checks if the given string is a valid MAC address.
+ *
+ * @param str - The string to be checked.
+ * @param options - An object containing options for validation.
+ * @param options.no_colons - If true, the function will validate MAC addresses without colons.
+ * @returns `true` if the string is a valid MAC address, `false` otherwise.
+ */
 export function isMACAddress(
 	str: string,
 	options: isMACAddressOptions,

behaviors/common/isMagnetURI.ts

@@ -1,5 +1,11 @@
 const magnetURI = /^magnet:\?xt=urn:[a-z0-9]+:[a-z0-9]{32,40}&dn=.+&tr=.+$/i;
 
+/**
+ * Checks if the given URL is a valid Magnet URI.
+ *
+ * @param url - The URL string to be validated.
+ * @returns `true` if the URL is a valid Magnet URI, otherwise `false`.
+ */
 export function isMagnetURI(url: string): boolean {
 	return magnetURI.test(url.trim());
 }