docs: JSDoc

behaviors/common/alpha.ts

@@ -1,3 +1,39 @@
+/**
+ * A collection of regular expressions for validating alphabetic characters
+ * in various languages and locales.
+ *
+ * The keys represent the locale codes, and the values are the corresponding
+ * regular expressions that match alphabetic characters for that locale.
+ *
+ * Supported locales include:
+ * - Arabic (`ar`)
+ * - Bulgarian (`bg-BG`)
+ * - Czech (`cs-CZ`)
+ * - Danish (`da-DK`)
+ * - German (`de-DE`)
+ * - Greek (`el-GR`)
+ * - English (`en-US`)
+ * - Spanish (`es-ES`)
+ * - Persian (`fa-IR`)
+ * - French (`fr-FR`)
+ * - Hebrew (`he`)
+ * - Hungarian (`hu-HU`)
+ * - Italian (`it-IT`)
+ * - Kurdish (`ku-IQ`)
+ * - Norwegian Bokmål (`nb-NO`)
+ * - Dutch (`nl-NL`)
+ * - Norwegian Nynorsk (`nn-NO`)
+ * - Polish (`pl-PL`)
+ * - Portuguese (`pt-PT`)
+ * - Russian (`ru-RU`)
+ * - Slovak (`sk-SK`)
+ * - Slovenian (`sl-SI`)
+ * - Serbian Cyrillic (`sr-RS`)
+ * - Serbian Latin (`sr-RS@latin`)
+ * - Swedish (`sv-SE`)
+ * - Turkish (`tr-TR`)
+ * - Ukrainian (`uk-UA`)
+ */
 export const alpha: { [key: string]: RegExp } = {
 	ar: /^[ءآأؤإئابةتثجحخدذرزسشصضطظعغفقكلمنهوىيًٌٍَُِّْٰ]+$/,
 	'bg-BG': /^[А-Я]+$/i,
@@ -28,6 +64,41 @@ export const alpha: { [key: string]: RegExp } = {
 	'uk-UA': /^[А-ЩЬЮЯЄIЇҐі]+$/i,
 };
 
+/**
+ * A collection of regular expressions for validating alphanumeric characters
+ * across various locales. Each key represents a locale identifier, and the
+ * corresponding value is a regular expression that matches alphanumeric
+ * characters specific to that locale.
+ *
+ * Supported locales include:
+ * - 'en-US': English (United States)
+ * - 'bg-BG': Bulgarian
+ * - 'cs-CZ': Czech
+ * - 'da-DK': Danish
+ * - 'de-DE': German
+ * - 'el-GR': Greek
+ * - 'es-ES': Spanish
+ * - 'fr-FR': French
+ * - 'it-IT': Italian
+ * - 'hu-HU': Hungarian
+ * - 'nb-NO': Norwegian Bokmål
+ * - 'nl-NL': Dutch
+ * - 'nn-NO': Norwegian Nynorsk
+ * - 'pl-PL': Polish
+ * - 'pt-PT': Portuguese
+ * - 'ru-RU': Russian
+ * - 'sl-SI': Slovenian
+ * - 'sk-SK': Slovak
+ * - 'sr-RS@latin': Serbian (Latin script)
+ * - 'sr-RS': Serbian (Cyrillic script)
+ * - 'sv-SE': Swedish
+ * - 'tr-TR': Turkish
+ * - 'uk-UA': Ukrainian
+ * - 'ku-IQ': Kurdish (Iraq)
+ * - 'ar': Arabic
+ * - 'he': Hebrew
+ * - 'fa-IR': Persian (Iran)
+ */
 export const alphanumeric: { [key: string]: RegExp } = {
 	'en-US': /^[0-9A-Z]+$/i,
 	'bg-BG': /^[0-9А-Я]+$/i,
@@ -58,11 +129,34 @@ export const alphanumeric: { [key: string]: RegExp } = {
 	'fa-IR': /^['0-9آابپتثجچهخدذرزژسشصضطظعغفقکگلمنوهی۱۲۳۴۵۶۷۸۹۰']+$/i,
 };
 
+/**
+ * An object that maps locale identifiers to their corresponding decimal separator symbols.
+ *
+ * @example
+ * ```typescript
+ * import { decimal } from './alpha';
+ *
+ * console.log(decimal['en-US']); // Output: '.'
+ * console.log(decimal['ar']);    // Output: '٫'
+ * ```
+ */
 export const decimal: { [key: string]: string } = {
 	'en-US': '.',
 	ar: '٫',
 };
 
+/**
+ * An array of strings representing English-speaking locales.
+ *
+ * The locales included are:
+ * - 'AU' (Australia)
+ * - 'GB' (United Kingdom)
+ * - 'HK' (Hong Kong)
+ * - 'IN' (India)
+ * - 'NZ' (New Zealand)
+ * - 'ZA' (South Africa)
+ * - 'ZM' (Zambia)
+ */
 export const englishLocales: Array<string> = [
 	'AU',
 	'GB',
@@ -81,6 +175,28 @@ for (let locale: string, i = 0; i < englishLocales.length; i++) {
 }
 
 // Source: http://www.localeplanet.com/java/
+/**
+ * An array of strings representing the locales for Arabic-speaking countries.
+ * http://www.localeplanet.com/java/
+ * The locales included are:
+ * - AE: United Arab Emirates
+ * - BH: Bahrain
+ * - DZ: Algeria
+ * - EG: Egypt
+ * - IQ: Iraq
+ * - JO: Jordan
+ * - KW: Kuwait
+ * - LB: Lebanon
+ * - LY: Libya
+ * - MA: Morocco
+ * - QM: Qatar
+ * - QA: Qatar
+ * - SA: Saudi Arabia
+ * - SD: Sudan
+ * - SY: Syria
+ * - TN: Tunisia
+ * - YE: Yemen
+ */
 export const arabicLocales: Array<string> = [
 	'AE',
 	'BH',
@@ -108,8 +224,28 @@ for (let locale: string, i = 0; i < arabicLocales.length; i++) {
 	decimal[locale] = decimal.ar;
 }
 
-// Source: https://en.wikipedia.org/wiki/Decimal_mark
+/**
+ * An array of locale strings that use dot as the decimal separator.
+ * Source: https://en.wikipedia.org/wiki/Decimal_mark
+ * This array includes the following locales:
+ * - ar-EG: Arabic (Egypt)
+ * - ar-LB: Arabic (Lebanon)
+ * - ar-LY: Arabic (Libya)
+ */
 export const dotDecimal: Array<string> = ['ar-EG', 'ar-LB', 'ar-LY'];
+/**
+ * An array of locale strings that use a comma as the decimal separator.
+ *
+ * This array includes locales from various regions and languages where
+ * the comma is used instead of a period for decimal separation.
+ *
+ * Example locales:
+ * - 'de-DE' for German (Germany)
+ * - 'fr-FR' for French (France)
+ * - 'es-ES' for Spanish (Spain)
+ *
+ * @constant {Array<string>} commaDecimal
+ */
 export const commaDecimal: Array<string> = [
 	'bg-BG',
 	'cs-CZ',

behaviors/common/contains.ts

@@ -8,6 +8,14 @@ export const defaultContainsOptions: ContainsOptions = {
 	ignoreCase: false,
 };
 
+/**
+ * Checks if a string contains a specified substring, with optional case insensitivity.
+ *
+ * @param str - The string to search within.
+ * @param elem - The substring to search for.
+ * @param options - Optional settings to modify the behavior of the search.
+ * @returns `true` if the substring is found within the string, otherwise `false`.
+ */
 export function contains(
 	str: string,
 	elem: string,

behaviors/common/equals.ts

@@ -10,6 +10,14 @@ const defaultEqualsOptions: EqualsOptions = {
 	ignoreCase: false,
 };
 
+/**
+ * Compares two strings for equality with optional configurations.
+ *
+ * @param str1 - The first string to compare.
+ * @param str2 - The second string to compare.
+ * @param options - Optional configuration for comparison.
+ * @returns `true` if the strings are considered equal based on the options, otherwise `false`.
+ */
 export function equals(
 	str1: string,
 	str2: string,

behaviors/common/isAfter.ts

@@ -1,5 +1,12 @@
 import { toDate } from './toDate.ts';
 
+/**
+ * Checks if the given date string is after the comparison date string.
+ *
+ * @param str - The date string to be checked.
+ * @param date - The comparison date string. Defaults to the current date and time.
+ * @returns `true` if the date represented by `str` is after the date represented by `date`, otherwise `false`.
+ */
 export function isAfter(
 	str: string,
 	date: string = `${new Date()}`,

behaviors/common/isAlpha.ts

@@ -1,5 +1,13 @@
 import { alpha } from './alpha.ts';
 
+/**
+ * Checks if the given string contains only alphabetic characters based on the specified locale.
+ *
+ * @param str - The string to be checked.
+ * @param locale - The locale to be used for the alphabetic check. Defaults to 'en-US'.
+ * @returns `true` if the string contains only alphabetic characters for the specified locale, otherwise `false`.
+ * @throws Will throw an error if the specified locale is not supported.
+ */
 export function isAlpha(
 	str: string,
 	locale = 'en-US',

behaviors/common/isAlphanumeric.ts

@@ -1,5 +1,13 @@
 import { alphanumeric } from './alpha.ts';
 
+/**
+ * Checks if a given string is alphanumeric according to the specified locale.
+ *
+ * @param str - The string to be checked.
+ * @param locale - The locale to be used for the alphanumeric check. Defaults to 'en-US'.
+ * @returns A boolean indicating whether the string is alphanumeric.
+ * @throws Will throw an error if the specified locale is not supported.
+ */
 export function isAlphanumeric(
 	str: string,
 	locale = 'en-US',

behaviors/common/isAscii.ts

@@ -1,5 +1,11 @@
 const ascii = /^[\x00-\x7F]+$/;
 
+/**
+ * Checks if the given string consists only of ASCII characters.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string contains only ASCII characters, otherwise `false`.
+ */
 export function isAscii(str: string): boolean {
 	return ascii.test(str);
 }

behaviors/common/isBIC.ts

@@ -1,5 +1,11 @@
 const isBICReg = /^[A-z]{4}[A-z]{2}\w{2}(\w{3})?$/;
 
+/**
+ * Checks if the given string is a valid BIC (Bank Identifier Code).
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid BIC, otherwise `false`.
+ */
 export function isBIC(str: string): boolean {
 	return isBICReg.test(str);
 }

behaviors/common/isBase32.ts

@@ -1,5 +1,16 @@
 const base32 = /^[A-Z2-7]+=*$/;
 
+/**
+ * Checks if a given string is a valid Base32 encoded string.
+ *
+ * A valid Base32 string must:
+ * - Have a length greater than 0.
+ * - Have a length that is a multiple of 8.
+ * - Match the Base32 regular expression pattern.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid Base32 encoded string, otherwise `false`.
+ */
 export function isBase32(str: string): boolean {
 	return str.length > 0 && str.length % 8 === 0 && base32.test(str);
 }

behaviors/common/isBase64.ts

@@ -11,6 +11,13 @@ const defaultIsBase64Options: IsBase64Options = {
 	urlSafe: false,
 };
 
+/**
+ * Checks if a given string is a valid Base64 encoded string.
+ *
+ * @param str - The string to be checked.
+ * @param options - Optional settings to customize the validation.
+ * @returns `true` if the string is a valid Base64 encoded string, `false` otherwise.
+ */
 export function isBase64(
 	str: string,
 	options: IsBase64Options = defaultIsBase64Options,

behaviors/common/isBefore.ts

@@ -1,5 +1,12 @@
 import { toDate } from './toDate.ts';
 
+/**
+ * Checks if the given date string is before the comparison date string.
+ *
+ * @param str - The date string to compare.
+ * @param date - The date string to compare against. Defaults to the current date and time.
+ * @returns `true` if `str` is before `date`, otherwise `false`.
+ */
 export function isBefore(
 	str: string,
 	date: string = `${new Date()}`,

behaviors/common/isBoolean.ts

@@ -1,3 +1,15 @@
+/**
+ * Checks if the given string represents a boolean value.
+ *
+ * This function returns `true` if the input string is one of the following:
+ * - "true"
+ * - "false"
+ * - "1"
+ * - "0"
+ *
+ * @param str - The string to check.
+ * @returns `true` if the string is a boolean representation, otherwise `false`.
+ */
 export function isBoolean(str: string): boolean {
 	return (['true', 'false', '1', '0'].indexOf(str) >= 0);
 }

behaviors/common/isBtcAddress.ts

@@ -1,6 +1,12 @@
 // supports Bech32 addresses
 const btc = /^(bc1|[13])[a-zA-HJ-NP-Z0-9]{25,39}$/;
 
+/**
+ * Checks if the given string is a valid Bitcoin address.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid Bitcoin address, otherwise `false`.
+ */
 export function isBtcAddress(str: string): boolean {
 	return btc.test(str);
 }

behaviors/common/isByteLength.ts

@@ -10,6 +10,13 @@ export const defaultIsByteLengthOptions: IsByteLengthOptions = {
 	max: undefined,
 };
 
+/**
+ * Checks if the length of the given string, in bytes, falls within the specified range.
+ *
+ * @param str - The string to be checked.
+ * @param options - An optional object specifying the minimum and maximum byte length.
+ * @returns `true` if the byte length of the string is within the specified range, otherwise `false`.
+ */
 export function isByteLength(
 	str: string,
 	options: IsByteLengthOptions = defaultIsByteLengthOptions,

behaviors/common/isCreditCard.ts

@@ -1,6 +1,15 @@
 const creditCard =
 	/^(?:4[0-9]{12}(?:[0-9]{3,6})?|5[1-5][0-9]{14}|(222[1-9]|22[3-9][0-9]|2[3-6][0-9]{2}|27[01][0-9]|2720)[0-9]{12}|6(?:011|5[0-9][0-9])[0-9]{12,15}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|(?:2131|1800|35\d{3})\d{11}|6[27][0-9]{14})$/;
 
+/**
+ * Checks if the provided string is a valid credit card number.
+ *
+ * This function sanitizes the input by removing any dashes or spaces,
+ * then uses the Luhn algorithm to validate the credit card number.
+ *
+ * @param str - The string to be checked as a credit card number.
+ * @returns `true` if the string is a valid credit card number, `false` otherwise.
+ */
 export function isCreditCard(str: string): boolean {
 	const sanitized = str.replace(/[- ]+/g, '');
 	if (!creditCard.test(sanitized)) {

behaviors/common/isCurrency.ts

@@ -96,6 +96,13 @@ export const defaultCurrencyOptions: CurrencyOptions = {
 	allow_space_after_digits: false,
 };
 
+/**
+ * Checks if a given string is a valid currency format based on the provided options.
+ *
+ * @param str - The string to be validated as currency.
+ * @param options - Optional. The configuration options for currency validation. Defaults to `defaultCurrencyOptions`.
+ * @returns `true` if the string is a valid currency format, otherwise `false`.
+ */
 export function isCurrency(
 	str: string,
 	options: CurrencyOptions = defaultCurrencyOptions,