@rzl-zone/utils-js 3.5.7 → 3.6.0

package/dist/predicates/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.5.7.
+ * Version: 3.6.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
@@ -2131,6 +2131,146 @@ declare const isURL:(value:unknown)=>value is URL;
  * isUndefined("abc");     // ➔ false
  */
 declare const isUndefined:(value:unknown)=>value is undefined;
+/** ---------------------------------------------------------
+ * * ***Options for `isValidDomain` predicate.***
+ * ---------------------------------------------------------
+ * **Customize the behavior of domain validation.**
+ */
+type IsValidDomainOptions={
+/** * ***Enable conversion of Unicode domains (IDN) to ASCII (punycode).***
+ *
+ * - Example: `"пример.рф"` ➔ `"xn--e1afmkfd.xn--p1ai"`
+ * - Allows validating Unicode domains correctly.
+ * - Default: `false`
+ *
+ * @defaultValue `false`.
+ */
+allowUnicode?:boolean;
+/** * ***If `true`, validates **only top-level domains (TLDs)** that are not part of any SLD/second-level domain.***
+ *
+ * - Accepts country-code TLDs like `"ai"` or `"ai."` ✅
+ * - Rejects common TLDs that are part of SLDs like `"com"` ❌
+ * - Only the final label is checked; subdomains are ignored.
+ * - Default: `false`
+ *
+ * @defaultValue `false`.
+ */
+topLevel?:boolean;
+/** * ***Allow or disallow subdomains.***
+ *
+ * - Example: `"sub.example.com"` ✅ if `subdomain` is `true`, ❌ if `false`
+ * - Wildcards and SLDs are considered when evaluating subdomains.
+ * - Default: `true`
+ *
+ * @defaultValue `true`.
+ */
+subdomain?:boolean;
+/** * ***Allow a wildcard `*` in the left-most label.***
+ *
+ * - Example: `"*.example.com"` ✅ if `wildcard` is `true`, ❌ if `false`
+ * - Wildcards are only valid in the first label and require at least one additional label.
+ * - Default: `false`
+ *
+ * @defaultValue `false`.
+ */
+wildcard?:boolean;
+/** * ***Allow a port after the domain.***
+ *
+ * - Example: `"localhost:3000"` or `"example.com:8080"` ✅ if `allowPort` is `true`
+ * - Validates that the port is a number between `1` and `65535`.
+ * - Does not affect domain validation rules otherwise.
+ * - Default: `false`
+ *
+ * @defaultValue `false`.
+ */
+allowPort?:boolean;
+/** * ***Allow special domains like `localhost`.***
+ *
+ * - Example: `"localhost"` ✅ if `allowLocalhost` is `true`
+ * - Works with or without a port if `allowPort` is enabled.
+ * - Default: `false`
+ *
+ * @defaultValue `false`.
+ */
+allowLocalhost?:boolean;
+/** * ***Allow URLs with protocol (`http`/`https`) and automatically extract the hostname.***
+ *
+ * - Example: `"https://example.com/foo/bar"` ➔ `"example.com"`
+ * - The function will validate only the hostname part and ignore the path, query, and fragment.
+ * - Default: `false`
+ *
+ * @defaultValue `false`.
+ */
+allowProtocol?:boolean;};
+/** ---------------------------------------------------------
+ * * ***Predicate: `isValidDomain`.***
+ * ---------------------------------------------------------
+ * **Validates whether a given string is a properly formatted domain name.**
+ *
+ * - **Supports options for:**
+ *    - `allowUnicode` ➔ allows internationalized domain names (IDN) with Unicode characters.
+ *    - `topLevel` ➔ validates **only top-level domains (TLDs)**; ignores subdomains and SLDs.
+ *    - `subdomain` ➔ allows or disallows subdomains.
+ *    - `wildcard` ➔ allows wildcard (`*`) in the left-most label.
+ *    - `allowPort` ➔ allows a port number after the domain (e.g., `example.com:8080`).
+ *    - `allowLocalhost` ➔ allows the special domain `"localhost"`.
+ *    - `allowProtocol` ➔ allows a URL with protocol (`http`/`https`) and extracts the hostname.
+ *
+ * - **Behavior:**
+ *    - ✅ Converts Unicode to ASCII (punycode) if `allowUnicode` is `true`.
+ *    - ✅ Checks label lengths (≤63 chars), valid characters, and punycode consistency.
+ *    - ✅ Validates port if `allowPort` is `true` (must be 1–65535).
+ *    - ✅ Accepts `"localhost"` if `allowLocalhost` is `true`.
+ *    - ✅ Extracts hostname from URLs if `allowProtocol` is `true`.
+ *    - ❌ Rejects invalid domains, labels starting/ending with `-`, double dots, malformed TLDs, or invalid port numbers.
+ *    - ✅ Handles both standard domains (example.com), URLs with protocols (https://example.com/foo), and IDNs (пример.рф).
+ *
+ * @param {*} value - The value to validate; only strings are valid domains.
+ * @param {IsValidDomainOptions} [options] - Optional configuration for domain validation.
+ * @param {boolean} [options.allowUnicode=false] - Enable punycode conversion for Unicode domains.
+ * @param {boolean} [options.topLevel=false] - Validate only TLDs (e.g., `ai`, `uk.`); ignores SLDs like `com`.
+ * @param {boolean} [options.subdomain=true] - Allow subdomains; set `false` to reject any subdomain.
+ * @param {boolean} [options.wildcard=false] - Allow wildcard `*` in the left-most label (e.g., `*.example.com`).
+ * @param {boolean} [options.allowPort=false] - Allow port number after domain (e.g., `:3000`); must be 1–65535.
+ * @param {boolean} [options.allowLocalhost=false] - Allow special domain `"localhost"`.
+ * @param {boolean} [options.allowProtocol=false] - Allow URLs with protocol (`http`/`https`) and extract hostname only.
+ * @returns {boolean} Returns `true` if the value is a valid domain according to the rules and options; otherwise `false`.
+ *
+ * @example
+ * isValidDomain("google.com");
+ * // ➔ true
+ *
+ * isValidDomain("пример.рф", { allowUnicode: true });
+ * // ➔ true
+ *
+ * isValidDomain("sub.example.com", { subdomain: false });
+ * // ➔ false
+ *
+ * isValidDomain("*.example.com", { wildcard: true });
+ * // ➔ true
+ *
+ * isValidDomain("com", { topLevel: true });
+ * // ➔ false (common TLD rejected because it's part of SLD)
+ *
+ * isValidDomain("ai.", { topLevel: true });
+ * // ➔ true (country-code TLD accepted)
+ *
+ * isValidDomain("localhost", { allowLocalhost: true });
+ * // ➔ true
+ *
+ * isValidDomain("localhost:3000", { allowLocalhost: true, allowPort: true });
+ * // ➔ true
+ *
+ * isValidDomain("example.com:8080", { allowPort: true });
+ * // ➔ true
+ *
+ * isValidDomain("https://example.com/foo/bar", { allowProtocol: true });
+ * // ➔ true (protocol stripped and hostname validated)
+ *
+ * isValidDomain("invalid_domain.com");
+ * // ➔ false
+ */
+declare function isValidDomain(value:unknown,options?:IsValidDomainOptions):boolean;
 /** ---------------------------------------------------------
  * * ***Predicate: `isValidURL`.***
  * ---------------------------------------------------------
@@ -2169,4 +2309,4 @@ declare const isValidURL:(url:unknown)=>boolean;
  * isWeakMap(new Map);
  * // ➔ false
  */
-declare function isWeakMap<K extends object=object,V=unknown>(value:unknown):value is WeakMap<K,V>;export{type IsArrayResult,IsPlainObjectResult,areArraysEqual,areObjectsEqual,areURLsEqualPath,areURLsIdentical,arrayHasAnyMatch,doesKeyExist,hasOwnProp,isArguments,isArray,isArrayBuffer,isArrayLike,isArrayLikeObject,isBigInt,isBoolean,isBooleanObject,isBuffer,isCurrencyLike,isDate,isDeepEqual,isElement,isEmpty,isEmptyArray,isEmptyDeep,isEmptyObject,isEmptyString,isEmptyValue,isEqual,isEqualWith,isError,isFinite,isFunction,isInfinityNumber,isInteger,isLength,isMap,isMatch,isMatchWith,isNaN,isNative,isNil,isNonEmptyArray,isNonEmptyString,isNonEmptyValue,isNull,isNumberObject,isObject,isObjectLoose,isObjectOrArray,isPropertyKey,isRegExp,isSafeInteger,isServer,isSet,isString,isStringObject,isSymbol,isTypedArray,isURL,isUndefined,isValidURL,isWeakMap,textContainsAll,textContainsAny};
+declare function isWeakMap<K extends object=object,V=unknown>(value:unknown):value is WeakMap<K,V>;export{type IsArrayResult,IsPlainObjectResult,areArraysEqual,areObjectsEqual,areURLsEqualPath,areURLsIdentical,arrayHasAnyMatch,doesKeyExist,hasOwnProp,isArguments,isArray,isArrayBuffer,isArrayLike,isArrayLikeObject,isBigInt,isBoolean,isBooleanObject,isBuffer,isCurrencyLike,isDate,isDeepEqual,isElement,isEmpty,isEmptyArray,isEmptyDeep,isEmptyObject,isEmptyString,isEmptyValue,isEqual,isEqualWith,isError,isFinite,isFunction,isInfinityNumber,isInteger,isLength,isMap,isMatch,isMatchWith,isNaN,isNative,isNil,isNonEmptyArray,isNonEmptyString,isNonEmptyValue,isNull,isNumberObject,isObject,isObjectLoose,isObjectOrArray,isPropertyKey,isRegExp,isSafeInteger,isServer,isSet,isString,isStringObject,isSymbol,isTypedArray,isURL,isUndefined,isValidDomain,isValidURL,isWeakMap,textContainsAll,textContainsAny};

package/dist/predicates/index.js

@@ -2,12 +2,12 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.5.7.
+ * Version: 3.6.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
-export { areArraysEqual, areObjectsEqual, areURLsEqualPath, areURLsIdentical, arrayHasAnyMatch, doesKeyExist, isArguments, isArrayLike, isArrayLikeObject, isCurrencyLike, isDeepEqual, isElement, isEmpty, isEmptyDeep, isEqualWith, isLength, isMatch, isMatchWith, isNative, isObjectLoose, isPropertyKey, isSafeInteger, isValidURL, isWeakMap, textContainsAll, textContainsAny } from '../chunk-SN6YRDLG.js';
+export { areArraysEqual, areObjectsEqual, areURLsEqualPath, areURLsIdentical, arrayHasAnyMatch, doesKeyExist, isArguments, isArrayLike, isArrayLikeObject, isCurrencyLike, isDeepEqual, isElement, isEmpty, isEmptyDeep, isEqualWith, isLength, isMatch, isMatchWith, isNative, isObjectLoose, isPropertyKey, isSafeInteger, isValidURL, isWeakMap, textContainsAll, textContainsAny } from '../chunk-U5VR4TJN.js';
 export { isURL } from '../chunk-ONZFBJVW.js';
 export { isNonEmptyValue, isTypedArray } from '../chunk-ZN53RM3R.js';
 export { isEmptyValue } from '../chunk-PZQC3FZY.js';
@@ -15,6 +15,7 @@ export { isServer } from '../chunk-L5RDAVVH.js';
 import '../chunk-DPLL67OT.js';
 export { isFinite } from '../chunk-7ZNEUWYP.js';
 export { isInteger } from '../chunk-WVSPXFTY.js';
+export { isValidDomain } from '../chunk-YS27V6LS.js';
 export { isEmptyString } from '../chunk-JY4HLZ4W.js';
 import '../chunk-FI76UZRF.js';
 export { isArrayBuffer, isEqual, isRegExp } from '../chunk-SZJ7OI4S.js';

package/dist/promises/index.cjs

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.5.7.
+ * Version: 3.6.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================

package/dist/promises/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.5.7.
+ * Version: 3.6.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================

package/dist/promises/index.js

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.5.7.
+ * Version: 3.6.0.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================