@rzl-zone/utils-js 3.13.1 → 3.14.0-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -6
- package/dist/.references/index.d.cts +2 -1
- package/dist/.references/index.d.ts +2 -1
- package/dist/AbortError-DK6kpzbu.cjs +26 -0
- package/dist/AbortError-DK6kpzbu.cjs.map +1 -0
- package/dist/AbortError-DVT8lAKn.js +20 -0
- package/dist/AbortError-DVT8lAKn.js.map +1 -0
- package/dist/{assertIsArray-HgzPQIAM.js → assertIsArray-CG7L7vlt.js} +3 -3
- package/dist/assertIsArray-CG7L7vlt.js.map +1 -0
- package/dist/{assertIsArray-CeXL4xv5.cjs → assertIsArray-CtCRD-_G.cjs} +5 -5
- package/dist/assertIsArray-CtCRD-_G.cjs.map +1 -0
- package/dist/assertIsPlainObject-DPZLj-Ho.cjs +26 -0
- package/dist/assertIsPlainObject-DPZLj-Ho.cjs.map +1 -0
- package/dist/assertIsPlainObject-j9bDqNLo.js +20 -0
- package/dist/assertIsPlainObject-j9bDqNLo.js.map +1 -0
- package/dist/{assertIsString-CY_WkCLr.js → assertIsString-CHIwE12y.js} +4 -4
- package/dist/assertIsString-CHIwE12y.js.map +1 -0
- package/dist/{assertIsString-DUrVt82d.cjs → assertIsString-CjE9kbQ_.cjs} +6 -6
- package/dist/assertIsString-CjE9kbQ_.cjs.map +1 -0
- package/dist/assertions/index.cjs +14 -12
- package/dist/assertions/index.cjs.map +1 -1
- package/dist/assertions/index.d.cts +2 -2
- package/dist/assertions/index.d.ts +2 -2
- package/dist/assertions/index.js +10 -8
- package/dist/assertions/index.js.map +1 -1
- package/dist/conversions/index.cjs +6 -6
- package/dist/conversions/index.d.cts +2 -2
- package/dist/conversions/index.d.ts +2 -2
- package/dist/conversions/index.js +6 -6
- package/dist/conversions-BFz6MKaV.cjs +449 -0
- package/dist/conversions-BFz6MKaV.cjs.map +1 -0
- package/dist/{conversions-1s7xMBe_.js → conversions-Ben5p5Ts.js} +43 -40
- package/dist/conversions-Ben5p5Ts.js.map +1 -0
- package/dist/errors/index.cjs +13 -0
- package/dist/errors/index.d.cts +180 -0
- package/dist/errors/index.d.ts +180 -0
- package/dist/errors/index.js +11 -0
- package/dist/events/index.cjs +10 -9
- package/dist/events/index.cjs.map +1 -1
- package/dist/events/index.d.cts +185 -100
- package/dist/events/index.d.ts +185 -100
- package/dist/events/index.js +9 -8
- package/dist/events/index.js.map +1 -1
- package/dist/formatter-ekJQF_bA-BepnCBkQ.cjs +67 -0
- package/dist/formatter-ekJQF_bA-BepnCBkQ.cjs.map +1 -0
- package/dist/formatter-ekJQF_bA-xLD9mGk4.js +55 -0
- package/dist/formatter-ekJQF_bA-xLD9mGk4.js.map +1 -0
- package/dist/formatters/index.cjs +2 -2
- package/dist/formatters/index.d.cts +2 -2
- package/dist/formatters/index.d.ts +2 -2
- package/dist/formatters/index.js +2 -2
- package/dist/{formatters-C6cVZBbG.js → formatters-BAbGsnYA.js} +78 -71
- package/dist/formatters-BAbGsnYA.js.map +1 -0
- package/dist/formatters-zd0Gs4Cs.cjs +436 -0
- package/dist/formatters-zd0Gs4Cs.cjs.map +1 -0
- package/dist/generators/index.cjs +37 -31
- package/dist/generators/index.cjs.map +1 -1
- package/dist/generators/index.d.cts +2 -2
- package/dist/generators/index.d.ts +2 -2
- package/dist/generators/index.js +29 -23
- package/dist/generators/index.js.map +1 -1
- package/dist/hasOwnProp-CVIhlD1i.js +47 -0
- package/dist/hasOwnProp-CVIhlD1i.js.map +1 -0
- package/dist/hasOwnProp-D9Tpgokd.cjs +53 -0
- package/dist/hasOwnProp-D9Tpgokd.cjs.map +1 -0
- package/dist/{index-RNQBTK8A.d.cts → index-9JsU_wMu.d.ts} +1375 -937
- package/dist/{index-ORbo-7zA.d.cts → index-BP3sUrAx.d.ts} +242 -133
- package/dist/{index-BG8wdusZ.d.cts → index-BVovC-yK.d.cts} +229 -200
- package/dist/index-C1X6ha9s.d.cts +1041 -0
- package/dist/index-CcPQZ41G.d.cts +1103 -0
- package/dist/index-CjpbuJF4.d.ts +2424 -0
- package/dist/index-CssrQyHh.d.cts +2424 -0
- package/dist/index-DZHiYYR7.d.cts +2179 -0
- package/dist/index-DZHiYYR7.d.ts +2179 -0
- package/dist/index-DlyDmXUo.d.ts +1103 -0
- package/dist/index-Dm4a___O.d.ts +1041 -0
- package/dist/{index-CRz9rSZL.d.ts → index-Dwduk7ez.d.cts} +1375 -937
- package/dist/{index-DPJ-e2JZ.d.ts → index-I5V6RbZM.d.cts} +1592 -790
- package/dist/{index-B5EBAgmC.d.cts → index-hOqBIL7F.d.ts} +1592 -790
- package/dist/{index-B1VQ6USF.d.ts → index-jyuOZMX7.d.ts} +229 -200
- package/dist/{index-ORbo-7zA.d.ts → index-lI0b7iUz.d.cts} +242 -133
- package/dist/{isBigInt-y7s3rsKc.js → isBigInt-Cez32M69.js} +2 -2
- package/dist/isBigInt-Cez32M69.js.map +1 -0
- package/dist/{isBigInt-BVj0M5pq.cjs → isBigInt-YgpNKTbA.cjs} +2 -2
- package/dist/isBigInt-YgpNKTbA.cjs.map +1 -0
- package/dist/{isEmptyString-BYMz_wt9.js → isEmptyString-C9QLWjx2.js} +4 -4
- package/dist/isEmptyString-C9QLWjx2.js.map +1 -0
- package/dist/{isEmptyString-C8PYNPgw.cjs → isEmptyString-O4TFe1Ao.cjs} +5 -5
- package/dist/isEmptyString-O4TFe1Ao.cjs.map +1 -0
- package/dist/isEmptyValue-CFExALXZ.cjs +54 -0
- package/dist/isEmptyValue-CFExALXZ.cjs.map +1 -0
- package/dist/isEmptyValue-kCjnLjbN.js +36 -0
- package/dist/isEmptyValue-kCjnLjbN.js.map +1 -0
- package/dist/{isFinite-DeDaBDr2.cjs → isFinite-B_hHbDpa.cjs} +6 -6
- package/dist/isFinite-B_hHbDpa.cjs.map +1 -0
- package/dist/{isFinite-BEJFOv6B.js → isFinite-ZvNhyHlF.js} +5 -5
- package/dist/isFinite-ZvNhyHlF.js.map +1 -0
- package/dist/{isInteger-DEDbBGez.js → isInteger-aZgzTTZG.js} +4 -4
- package/dist/isInteger-aZgzTTZG.js.map +1 -0
- package/dist/{isInteger-CQLThJOR.cjs → isInteger-dnc6W63Z.cjs} +4 -4
- package/dist/isInteger-dnc6W63Z.cjs.map +1 -0
- package/dist/isNumber-BCWD4dW0.js +20 -0
- package/dist/isNumber-BCWD4dW0.js.map +1 -0
- package/dist/isNumber-BkzwAe50.cjs +26 -0
- package/dist/isNumber-BkzwAe50.cjs.map +1 -0
- package/dist/isPlainObject-CAe_ElKO.d.cts +331 -0
- package/dist/isPlainObject-CJvRG4Je.d.ts +331 -0
- package/dist/{isServer-q3o6cSwD.js → isServer-CQzrX5e0.js} +2 -2
- package/dist/isServer-CQzrX5e0.js.map +1 -0
- package/dist/{isServer-DmycqWsF.cjs → isServer-DhFaedeT.cjs} +2 -2
- package/dist/isServer-DhFaedeT.cjs.map +1 -0
- package/dist/{isEqual-DaPDxMyw.cjs → isTypedArray-DjADSu8q.cjs} +45 -13
- package/dist/isTypedArray-DjADSu8q.cjs.map +1 -0
- package/dist/{isEqual-DM4S_kWh.js → isTypedArray-DxsPKrLh.js} +29 -9
- package/dist/isTypedArray-DxsPKrLh.js.map +1 -0
- package/dist/{isValidDomain-B8Nukgw0.js → isValidDomain-CDtNOhMc.js} +13 -54
- package/dist/isValidDomain-CDtNOhMc.js.map +1 -0
- package/dist/{isValidDomain-ZbyeGOO9.cjs → isValidDomain-D_x7uNIu.cjs} +16 -69
- package/dist/isValidDomain-D_x7uNIu.cjs.map +1 -0
- package/dist/{assertIsBoolean-CWUs-I5l.js → logger-CLWnKRKE.js} +657 -587
- package/dist/logger-CLWnKRKE.js.map +1 -0
- package/dist/{assertIsBoolean-D41HrTB_.cjs → logger-CUacYy3D.cjs} +658 -612
- package/dist/logger-CUacYy3D.cjs.map +1 -0
- package/dist/{noop-BY43WaoU.cjs → noop-CjEbNsJL.cjs} +2 -2
- package/dist/noop-CjEbNsJL.cjs.map +1 -0
- package/dist/{noop-CjY8xVHv.js → noop-qxrcogt5.js} +2 -2
- package/dist/noop-qxrcogt5.js.map +1 -0
- package/dist/{normalizeSpaces-BhZp0U_6.cjs → normalizeSpaces-D0_Z4qnO.cjs} +6 -9
- package/dist/normalizeSpaces-D0_Z4qnO.cjs.map +1 -0
- package/dist/{normalizeSpaces-BoUDtq5P.js → normalizeSpaces-DAsxzBEQ.js} +4 -7
- package/dist/normalizeSpaces-DAsxzBEQ.js.map +1 -0
- package/dist/operations/index.cjs +152 -22
- package/dist/operations/index.cjs.map +1 -1
- package/dist/operations/index.d.cts +257 -35
- package/dist/operations/index.d.ts +257 -35
- package/dist/operations/index.js +142 -13
- package/dist/operations/index.js.map +1 -1
- package/dist/parsers/index.cjs +2 -2
- package/dist/parsers/index.d.cts +238 -180
- package/dist/parsers/index.d.ts +238 -180
- package/dist/parsers/index.js +2 -2
- package/dist/{parsers-B8KYXIjE.js → parsers-BBAE_xVM.js} +9 -8
- package/dist/parsers-BBAE_xVM.js.map +1 -0
- package/dist/{parsers-B_FPX35n.cjs → parsers-i8WEeMJl.cjs} +10 -9
- package/dist/parsers-i8WEeMJl.cjs.map +1 -0
- package/dist/{parsing-Bfaw85Hd.js → parsing-D9tbKQ0v.js} +3 -3
- package/dist/parsing-D9tbKQ0v.js.map +1 -0
- package/dist/{parsing-BCZGco7n.cjs → parsing-DGjB8cwr.cjs} +4 -4
- package/dist/parsing-DGjB8cwr.cjs.map +1 -0
- package/dist/predicates/index.cjs +43 -43
- package/dist/predicates/index.d.cts +3 -3
- package/dist/predicates/index.d.ts +3 -3
- package/dist/predicates/index.js +14 -14
- package/dist/{predicates-KlyOvBSC.js → predicates-C0dova7l.js} +45 -40
- package/dist/predicates-C0dova7l.js.map +1 -0
- package/dist/{predicates-8y28VrbT.cjs → predicates-Dd7To7B4.cjs} +89 -84
- package/dist/predicates-Dd7To7B4.cjs.map +1 -0
- package/dist/promises/index.cjs +27 -26
- package/dist/promises/index.cjs.map +1 -1
- package/dist/promises/index.d.cts +227 -75
- package/dist/promises/index.d.ts +227 -75
- package/dist/promises/index.js +27 -26
- package/dist/promises/index.js.map +1 -1
- package/dist/{punyCode-DnKi0qjS.cjs → punyCode-DHTLhGdD.cjs} +12 -12
- package/dist/punyCode-DHTLhGdD.cjs.map +1 -0
- package/dist/{punyCode-Dwto1RpA.js → punyCode-Deb1Mrkc.js} +12 -12
- package/dist/punyCode-Deb1Mrkc.js.map +1 -0
- package/dist/{removeSpaces--8NW-HSx.js → removeSpaces-BPnsdRN0.js} +4 -4
- package/dist/removeSpaces-BPnsdRN0.js.map +1 -0
- package/dist/{removeSpaces-CmrrkeXz.cjs → removeSpaces-CN3pxBz_.cjs} +7 -7
- package/dist/removeSpaces-CN3pxBz_.cjs.map +1 -0
- package/dist/rzl-utils.global.js +13 -13
- package/dist/safeJsonParse-D1FLVTEM.cjs +209 -0
- package/dist/safeJsonParse-D1FLVTEM.cjs.map +1 -0
- package/dist/{safeJsonParse-OnUwG2El.js → safeJsonParse-DEVKNDSn.js} +29 -28
- package/dist/safeJsonParse-DEVKNDSn.js.map +1 -0
- package/dist/safeStableStringify-C5HHKUdn.cjs +125 -0
- package/dist/safeStableStringify-C5HHKUdn.cjs.map +1 -0
- package/dist/{safeStableStringify-B2KTTS3r.js → safeStableStringify-DfwxmiWn.js} +20 -13
- package/dist/safeStableStringify-DfwxmiWn.js.map +1 -0
- package/dist/strings/index.cjs +26 -30
- package/dist/strings/index.cjs.map +1 -1
- package/dist/strings/index.d.cts +2 -2
- package/dist/strings/index.d.ts +2 -2
- package/dist/strings/index.js +13 -17
- package/dist/strings/index.js.map +1 -1
- package/dist/tailwind/index.cjs +3 -3
- package/dist/tailwind/index.d.cts +3 -3
- package/dist/tailwind/index.d.ts +3 -3
- package/dist/tailwind/index.js +3 -3
- package/dist/{tailwind-DUuboq52.cjs → tailwind-BG7B0cDs.cjs} +59 -53
- package/dist/tailwind-BG7B0cDs.cjs.map +1 -0
- package/dist/{tailwind-CUdmv-oO.js → tailwind-tJNnFPsF.js} +38 -32
- package/dist/tailwind-tJNnFPsF.js.map +1 -0
- package/dist/{toStringArrayUnRecursive-OOHGazks.js → toStringArrayUnRecursive-D0WbLIRz.js} +9 -9
- package/dist/toStringArrayUnRecursive-D0WbLIRz.js.map +1 -0
- package/dist/toStringArrayUnRecursive-QLoaNX_-.cjs +51 -0
- package/dist/toStringArrayUnRecursive-QLoaNX_-.cjs.map +1 -0
- package/dist/urls/index.cjs +3 -3
- package/dist/urls/index.d.cts +635 -443
- package/dist/urls/index.d.ts +635 -443
- package/dist/urls/index.js +3 -3
- package/dist/{urls-BXT4Krsq.js → urls-EoWslGgg.js} +50 -41
- package/dist/urls-EoWslGgg.js.map +1 -0
- package/dist/urls-NCzPepe2.cjs +308 -0
- package/dist/urls-NCzPepe2.cjs.map +1 -0
- package/package.json +6 -6
- package/dist/assertIsArray-CeXL4xv5.cjs.map +0 -1
- package/dist/assertIsArray-HgzPQIAM.js.map +0 -1
- package/dist/assertIsBoolean-CWUs-I5l.js.map +0 -1
- package/dist/assertIsBoolean-D41HrTB_.cjs.map +0 -1
- package/dist/assertIsString-CY_WkCLr.js.map +0 -1
- package/dist/assertIsString-DUrVt82d.cjs.map +0 -1
- package/dist/conversions-1s7xMBe_.js.map +0 -1
- package/dist/conversions-B3Rf8uId.cjs +0 -446
- package/dist/conversions-B3Rf8uId.cjs.map +0 -1
- package/dist/formatters-C6cVZBbG.js.map +0 -1
- package/dist/formatters-aEAAuzjx.cjs +0 -429
- package/dist/formatters-aEAAuzjx.cjs.map +0 -1
- package/dist/index-CPCt6_Wq.d.cts +0 -765
- package/dist/index-CPCt6_Wq.d.ts +0 -765
- package/dist/index-DBwNa1iO.d.ts +0 -947
- package/dist/index-DPTYOQkn.d.cts +0 -947
- package/dist/index-Dig1fIhZ.d.cts +0 -1716
- package/dist/index-Dig1fIhZ.d.ts +0 -1716
- package/dist/isBigInt-BVj0M5pq.cjs.map +0 -1
- package/dist/isBigInt-y7s3rsKc.js.map +0 -1
- package/dist/isEmptyObject-BsHngDz4.cjs +0 -37
- package/dist/isEmptyObject-BsHngDz4.cjs.map +0 -1
- package/dist/isEmptyObject-DPGR9iPj.js +0 -25
- package/dist/isEmptyObject-DPGR9iPj.js.map +0 -1
- package/dist/isEmptyString-BYMz_wt9.js.map +0 -1
- package/dist/isEmptyString-C8PYNPgw.cjs.map +0 -1
- package/dist/isEmptyValue-BXf7f1jz.cjs +0 -30
- package/dist/isEmptyValue-BXf7f1jz.cjs.map +0 -1
- package/dist/isEmptyValue-D4OHTB3u.js +0 -24
- package/dist/isEmptyValue-D4OHTB3u.js.map +0 -1
- package/dist/isEqual-DM4S_kWh.js.map +0 -1
- package/dist/isEqual-DaPDxMyw.cjs.map +0 -1
- package/dist/isFinite-BEJFOv6B.js.map +0 -1
- package/dist/isFinite-DeDaBDr2.cjs.map +0 -1
- package/dist/isInteger-CQLThJOR.cjs.map +0 -1
- package/dist/isInteger-DEDbBGez.js.map +0 -1
- package/dist/isPlainObject-BwTkj3G0.d.cts +0 -339
- package/dist/isPlainObject-BwTkj3G0.d.ts +0 -339
- package/dist/isServer-DmycqWsF.cjs.map +0 -1
- package/dist/isServer-q3o6cSwD.js.map +0 -1
- package/dist/isTypedArray-BQLbLXsU.cjs +0 -43
- package/dist/isTypedArray-BQLbLXsU.cjs.map +0 -1
- package/dist/isTypedArray-XiBnifLN.js +0 -31
- package/dist/isTypedArray-XiBnifLN.js.map +0 -1
- package/dist/isValidDomain-B8Nukgw0.js.map +0 -1
- package/dist/isValidDomain-ZbyeGOO9.cjs.map +0 -1
- package/dist/noop-BY43WaoU.cjs.map +0 -1
- package/dist/noop-CjY8xVHv.js.map +0 -1
- package/dist/normalizeSpaces-BhZp0U_6.cjs.map +0 -1
- package/dist/normalizeSpaces-BoUDtq5P.js.map +0 -1
- package/dist/parsers-B8KYXIjE.js.map +0 -1
- package/dist/parsers-B_FPX35n.cjs.map +0 -1
- package/dist/parsing-BCZGco7n.cjs.map +0 -1
- package/dist/parsing-Bfaw85Hd.js.map +0 -1
- package/dist/predicates-8y28VrbT.cjs.map +0 -1
- package/dist/predicates-KlyOvBSC.js.map +0 -1
- package/dist/punyCode-DnKi0qjS.cjs.map +0 -1
- package/dist/punyCode-Dwto1RpA.js.map +0 -1
- package/dist/removeSpaces--8NW-HSx.js.map +0 -1
- package/dist/removeSpaces-CmrrkeXz.cjs.map +0 -1
- package/dist/safeJsonParse-OnUwG2El.js.map +0 -1
- package/dist/safeJsonParse-sFqVXf-e.cjs +0 -208
- package/dist/safeJsonParse-sFqVXf-e.cjs.map +0 -1
- package/dist/safeStableStringify-B2KTTS3r.js.map +0 -1
- package/dist/safeStableStringify-Cmi6GyWj.cjs +0 -106
- package/dist/safeStableStringify-Cmi6GyWj.cjs.map +0 -1
- package/dist/tailwind-CUdmv-oO.js.map +0 -1
- package/dist/tailwind-DUuboq52.cjs.map +0 -1
- package/dist/toStringArrayUnRecursive-OOHGazks.js.map +0 -1
- package/dist/toStringArrayUnRecursive-pfk2oP8C.cjs +0 -51
- package/dist/toStringArrayUnRecursive-pfk2oP8C.cjs.map +0 -1
- package/dist/urls-BL9C_yU3.cjs +0 -299
- package/dist/urls-BL9C_yU3.cjs.map +0 -1
- package/dist/urls-BXT4Krsq.js.map +0 -1
|
@@ -2,20 +2,24 @@
|
|
|
2
2
|
* ========================================================================
|
|
3
3
|
* @rzl-zone/utils-js
|
|
4
4
|
* ------------------------------------------------------------------------
|
|
5
|
-
* Version: `3.
|
|
5
|
+
* Version: `3.14.0-beta.0`
|
|
6
6
|
* Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
|
|
7
7
|
* Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
|
|
8
8
|
* ========================================================================
|
|
9
9
|
*/
|
|
10
10
|
|
|
11
|
-
import { i as
|
|
12
|
-
import {
|
|
11
|
+
import { D as NumberRangeUnion, I as Trim, L as TypedArray, N as Prettify, _ as IsNever, a as CharAt, g as IsEmptyString, h as IsArray, i as AnyString, j as ParseNumber, k as OrArr, m as IsAny, r as AnyFunction, s as Extends, t as AnObjectNonArray, v as IsPositive, y as IsStringLiteral } from "./index-DZHiYYR7.cjs";
|
|
12
|
+
import { i as ArrayFallback, r as IsHasKeysObject, t as IsPlainObjectResult } from "./isPlainObject-CAe_ElKO.cjs";
|
|
13
13
|
/** ----------------------------------------------------------
|
|
14
14
|
* * ***Predicate: `areArraysEqual`.***
|
|
15
|
-
*
|
|
15
|
+
* -----------------------------------------------------------
|
|
16
16
|
* **Compares two arrays deeply to check if they are equal.**
|
|
17
|
+
*
|
|
18
|
+
* ---
|
|
17
19
|
* @description Supports deep comparison of arrays containing nested arrays or objects,
|
|
18
20
|
* can also ignore the order of elements at all levels by recursively sorting.
|
|
21
|
+
*
|
|
22
|
+
* ---
|
|
19
23
|
* @param {unknown[]} array1
|
|
20
24
|
* ***The first array to compare, can contain nested arrays or objects.***
|
|
21
25
|
* @param {unknown[]} array2
|
|
@@ -23,9 +27,15 @@ import { AnObjectNonArray, AnyFunction, AnyString, CharAt, Extends, IsAny, IsArr
|
|
|
23
27
|
* @param {boolean|undefined} [ignoreOrder=false]
|
|
24
28
|
* ***Whether to ignore the order of elements when comparing.***
|
|
25
29
|
* - If `true`, will sort both arrays recursively before comparing, default is `false`.
|
|
30
|
+
*
|
|
31
|
+
* ---
|
|
32
|
+
* @throws **{@link TypeError | `TypeError`}** if `array1` or `array2` are not arrays, or if `ignoreOrder` is not a boolean.
|
|
33
|
+
*
|
|
34
|
+
* ---
|
|
26
35
|
* @returns {boolean}
|
|
27
36
|
* Returns `true` if both arrays are deeply equal, otherwise `false`.
|
|
28
|
-
*
|
|
37
|
+
*
|
|
38
|
+
* ---
|
|
29
39
|
* @example
|
|
30
40
|
* ```ts
|
|
31
41
|
* areArraysEqual([1, 2, 3], [1, 2, 3]);
|
|
@@ -39,15 +49,23 @@ import { AnObjectNonArray, AnyFunction, AnyString, CharAt, Extends, IsAny, IsArr
|
|
|
39
49
|
* ```
|
|
40
50
|
*/
|
|
41
51
|
declare const areArraysEqual: (array1: unknown[], array2: unknown[], ignoreOrder?: boolean) => boolean;
|
|
42
|
-
/**
|
|
52
|
+
/** ------------------------------------------------------------------
|
|
43
53
|
* * ***Predicate: `areObjectsEqual`.***
|
|
44
|
-
*
|
|
54
|
+
* -------------------------------------------------------------------
|
|
45
55
|
* **Compares two objects for deep equality.**
|
|
56
|
+
*
|
|
57
|
+
* ---
|
|
46
58
|
* @template T1 The type of the first object.
|
|
47
59
|
* @template T2 The type of the second object.
|
|
60
|
+
*
|
|
61
|
+
* ---
|
|
48
62
|
* @param {*} object1 - The first object to compare.
|
|
49
63
|
* @param {*} object2 - The second object to compare.
|
|
64
|
+
*
|
|
65
|
+
* ---
|
|
50
66
|
* @returns {boolean} Return `true` if both objects are deeply equal, otherwise `false`.
|
|
67
|
+
*
|
|
68
|
+
* ---
|
|
51
69
|
* @example
|
|
52
70
|
* areObjectsEqual({ a: 1, b: 2 }, { a: 1, b: 2 });
|
|
53
71
|
* // ➔ true
|
|
@@ -57,87 +75,119 @@ declare const areArraysEqual: (array1: unknown[], array2: unknown[], ignoreOrder
|
|
|
57
75
|
* // ➔ true
|
|
58
76
|
*/
|
|
59
77
|
declare const areObjectsEqual: (object1: unknown, object2: unknown) => boolean;
|
|
60
|
-
/**
|
|
78
|
+
/** ------------------------------------------------------------------
|
|
61
79
|
* * ***Predicate: `areURLsEqualPath`.***
|
|
62
|
-
*
|
|
80
|
+
* -------------------------------------------------------------------
|
|
63
81
|
* **Checks if two URLs are the same, ignoring query parameters, this function compares only the protocol, host, and pathname.**
|
|
82
|
+
*
|
|
83
|
+
* ---
|
|
64
84
|
* @param {URL} urlA - The first URL to compare.
|
|
65
85
|
* @param {URL} urlB - The second URL to compare.
|
|
66
|
-
* @returns {boolean} Returns `true` if both URLs are the same (ignoring search parameters), otherwise `false`.
|
|
67
|
-
* @example
|
|
68
|
-
* // Same domain, same path, different query -> true
|
|
69
|
-
* areURLsEqualPath(
|
|
70
|
-
* new URL("https://example.com/page?a=1"),
|
|
71
|
-
* new URL("https://example.com/page?b=2")
|
|
72
|
-
* );
|
|
73
|
-
* // ➔ true
|
|
74
|
-
*
|
|
75
|
-
* // Same domain, different path -> false
|
|
76
|
-
* areURLsEqualPath(
|
|
77
|
-
* new URL("https://example.com/page1"),
|
|
78
|
-
* new URL("https://example.com/page2")
|
|
79
|
-
* );
|
|
80
|
-
* // ➔ false
|
|
81
86
|
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
* new URL("http://example.com/page"),
|
|
85
|
-
* new URL("https://example.com/page")
|
|
86
|
-
* );
|
|
87
|
-
* // ➔ false
|
|
87
|
+
* ---
|
|
88
|
+
* @returns {boolean} Returns `true` if both URLs are the same (ignoring search parameters), otherwise `false`.
|
|
88
89
|
*
|
|
89
|
-
*
|
|
90
|
-
*
|
|
91
|
-
*
|
|
92
|
-
*
|
|
93
|
-
*
|
|
94
|
-
*
|
|
90
|
+
* ---
|
|
91
|
+
* @example
|
|
92
|
+
* 1. #### Same domain, same path, different query:
|
|
93
|
+
* ```ts
|
|
94
|
+
* areURLsEqualPath(
|
|
95
|
+
* new URL("https://example.com/page?a=1"),
|
|
96
|
+
* new URL("https://example.com/page?b=2")
|
|
97
|
+
* );
|
|
98
|
+
* // ➔ true
|
|
99
|
+
* ```
|
|
100
|
+
* ---
|
|
101
|
+
* 2. #### Same domain, different path:
|
|
102
|
+
* ```ts
|
|
103
|
+
* areURLsEqualPath(
|
|
104
|
+
* new URL("https://example.com/page1"),
|
|
105
|
+
* new URL("https://example.com/page2")
|
|
106
|
+
* );
|
|
107
|
+
* // ➔ false
|
|
108
|
+
* ```
|
|
109
|
+
* ---
|
|
110
|
+
* 3. #### Different protocol:
|
|
111
|
+
* ```ts
|
|
112
|
+
* areURLsEqualPath(
|
|
113
|
+
* new URL("http://example.com/page"),
|
|
114
|
+
* new URL("https://example.com/page")
|
|
115
|
+
* );
|
|
116
|
+
* // ➔ false
|
|
117
|
+
* ```
|
|
118
|
+
* ---
|
|
119
|
+
* 4. #### Same protocol, same host, same path (ignores query & hash):
|
|
120
|
+
* ```ts
|
|
121
|
+
* areURLsEqualPath(
|
|
122
|
+
* new URL("https://example.com/page#section"),
|
|
123
|
+
* new URL("https://example.com/page")
|
|
124
|
+
* );
|
|
125
|
+
* // ➔ true
|
|
126
|
+
* ```
|
|
95
127
|
*/
|
|
96
128
|
declare const areURLsEqualPath: (urlA: URL, urlB: URL) => boolean;
|
|
97
|
-
/**
|
|
129
|
+
/** ------------------------------------------------------------------
|
|
98
130
|
* * ***Predicate: `areURLsIdentical`.***
|
|
99
|
-
*
|
|
131
|
+
* -------------------------------------------------------------------
|
|
100
132
|
* **Checks if two URLs are exactly the same, including protocol, host, pathname, and query parameters.**
|
|
133
|
+
*
|
|
134
|
+
* ---
|
|
101
135
|
* @param {URL} urlA - The first URL to compare.
|
|
102
136
|
* @param {URL} urlB - The second URL to compare.
|
|
103
|
-
* @returns {boolean} Returns `true` if both URLs are identical, otherwise `false`.
|
|
104
|
-
* @example
|
|
105
|
-
* // Identical URLs -> true
|
|
106
|
-
* areURLsIdentical(
|
|
107
|
-
* new URL("https://example.com/page?a=1"),
|
|
108
|
-
* new URL("https://example.com/page?a=1")
|
|
109
|
-
* );
|
|
110
|
-
* // ➔ true
|
|
111
|
-
*
|
|
112
|
-
* // Same path, different query parameter -> false
|
|
113
|
-
* areURLsIdentical(
|
|
114
|
-
* new URL("https://example.com/page?a=1"),
|
|
115
|
-
* new URL("https://example.com/page?b=2")
|
|
116
|
-
* );
|
|
117
|
-
* // ➔ false
|
|
118
137
|
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
121
|
-
* new URL("http://example.com/page?a=1"),
|
|
122
|
-
* new URL("https://example.com/page?a=1")
|
|
123
|
-
* );
|
|
124
|
-
* // ➔ false
|
|
138
|
+
* ---
|
|
139
|
+
* @returns {boolean} Returns `true` if both URLs are identical, otherwise `false`.
|
|
125
140
|
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
129
|
-
*
|
|
130
|
-
*
|
|
131
|
-
*
|
|
141
|
+
* ---
|
|
142
|
+
* @example
|
|
143
|
+
* 1. #### Identical URLs:
|
|
144
|
+
* ```ts
|
|
145
|
+
* areURLsIdentical(
|
|
146
|
+
* new URL("https://example.com/page?a=1"),
|
|
147
|
+
* new URL("https://example.com/page?a=1")
|
|
148
|
+
* );
|
|
149
|
+
* // ➔ true
|
|
150
|
+
* ```
|
|
151
|
+
* ---
|
|
152
|
+
* 2. #### Same path, different query parameter:
|
|
153
|
+
* ```ts
|
|
154
|
+
* areURLsIdentical(
|
|
155
|
+
* new URL("https://example.com/page?a=1"),
|
|
156
|
+
* new URL("https://example.com/page?b=2")
|
|
157
|
+
* );
|
|
158
|
+
* // ➔ false
|
|
159
|
+
* ```
|
|
160
|
+
* ---
|
|
161
|
+
* 3. #### Same host & query, but different protocol:
|
|
162
|
+
* ```ts
|
|
163
|
+
* areURLsIdentical(
|
|
164
|
+
* new URL("http://example.com/page?a=1"),
|
|
165
|
+
* new URL("https://example.com/page?a=1")
|
|
166
|
+
* );
|
|
167
|
+
* // ➔ false
|
|
168
|
+
* ```
|
|
169
|
+
* ---
|
|
170
|
+
* 4. #### Same everything except trailing slash:
|
|
171
|
+
* ```ts
|
|
172
|
+
* areURLsIdentical(
|
|
173
|
+
* new URL("https://example.com/page"),
|
|
174
|
+
* new URL("https://example.com/page/")
|
|
175
|
+
* );
|
|
176
|
+
* // ➔ false
|
|
177
|
+
* ```
|
|
132
178
|
*/
|
|
133
179
|
declare const areURLsIdentical: (urlA: URL, urlB: URL) => boolean;
|
|
134
180
|
type OptionsTextContainsAll = {
|
|
135
|
-
/**
|
|
181
|
+
/** ----------------------------------------------------------
|
|
182
|
+
* * ***If `true`, matches whole words only, defaultValue is `false`.***
|
|
183
|
+
* -----------------------------------------------------------
|
|
136
184
|
*
|
|
137
185
|
* @default false
|
|
138
186
|
*/
|
|
139
187
|
exactMatch?: boolean;
|
|
140
|
-
/**
|
|
188
|
+
/** ----------------------------------------------------------
|
|
189
|
+
* * ***Optional regex flags (default: `"i"` for case-insensitive).***
|
|
190
|
+
* -----------------------------------------------------------
|
|
141
191
|
*
|
|
142
192
|
* @default "i"
|
|
143
193
|
*/
|
|
@@ -145,20 +195,28 @@ type OptionsTextContainsAll = {
|
|
|
145
195
|
};
|
|
146
196
|
/** ----------------------------------------------------------
|
|
147
197
|
* * ***Predicate: `textContainsAll`.***
|
|
148
|
-
*
|
|
198
|
+
* -----------------------------------------------------------
|
|
149
199
|
* **Checks if the given `text` contains all of the specified `searchWords`.**
|
|
200
|
+
*
|
|
201
|
+
* ---
|
|
150
202
|
* - **Behavior:**
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
*
|
|
154
|
-
*
|
|
155
|
-
*
|
|
203
|
+
* - Returns `false` if `text` or `searchWords` is `null`/`undefined`/invalid.
|
|
204
|
+
* - Uses **regular expressions** for flexible pattern matching.
|
|
205
|
+
* - **Escapes special characters** to prevent regex injection attacks.
|
|
206
|
+
* - **Trims input** to avoid false positives with empty spaces.
|
|
207
|
+
* - **Supports exact word matching** (optional).
|
|
208
|
+
*
|
|
209
|
+
* ---
|
|
156
210
|
* @param {string|null|undefined} text - The string text to search within.
|
|
157
211
|
* @param {string[]|null} [searchWords] - An array of words/phrases to match against the text.
|
|
158
212
|
* @param {OptionsTextContainsAll} [options] - Optional configuration object.
|
|
159
213
|
* @param {OptionsTextContainsAll["exactMatch"]} [options.exactMatch=false] - If `true`, matches whole words only, defaultValue is `false`.
|
|
160
214
|
* @param {OptionsTextContainsAll["flags"]} [options.flags="i"] - Optional regex flags (default: `"i"` for case-insensitive).
|
|
215
|
+
*
|
|
216
|
+
* ---
|
|
161
217
|
* @returns {boolean} Return `true` if all `searchWords` are found in `text`, otherwise `false`.
|
|
218
|
+
*
|
|
219
|
+
* ---
|
|
162
220
|
* @example
|
|
163
221
|
* textContainsAll("Hello world, WithAI APP", ["Hello", "world"]);
|
|
164
222
|
* // ➔ true
|
|
@@ -175,33 +233,44 @@ type OptionsTextContainsAll = {
|
|
|
175
233
|
*/
|
|
176
234
|
declare const textContainsAll: <T extends string>(text?: T | null, searchWords?: T[] | string[] | null, options?: OptionsTextContainsAll) => boolean;
|
|
177
235
|
type OptionsTextContainsAny = {
|
|
178
|
-
/**
|
|
236
|
+
/** ----------------------------------------------------------
|
|
237
|
+
* * ***If `true`, matches whole words only, defaultValue is `false`.***
|
|
238
|
+
* -----------------------------------------------------------
|
|
179
239
|
*
|
|
180
240
|
* @default false
|
|
181
241
|
*/
|
|
182
242
|
exactMatch?: boolean;
|
|
183
|
-
/**
|
|
184
|
-
*
|
|
243
|
+
/** ----------------------------------------------------------
|
|
244
|
+
* * ***Optional regex flags (default: `"i"` for case-insensitive).***
|
|
245
|
+
* -----------------------------------------------------------
|
|
185
246
|
* @default "i"
|
|
186
247
|
*/
|
|
187
248
|
flags?: string;
|
|
188
249
|
};
|
|
189
250
|
/** ----------------------------------------------------------
|
|
190
251
|
* * ***Predicate: `textContainsAny`.***
|
|
191
|
-
*
|
|
252
|
+
* -----------------------------------------------------------
|
|
192
253
|
* **Checks if the given `text` contains at least one of the specified `searchWords`.**
|
|
254
|
+
*
|
|
255
|
+
* ---
|
|
193
256
|
* - **Behavior:**
|
|
194
|
-
*
|
|
195
|
-
*
|
|
196
|
-
*
|
|
197
|
-
*
|
|
198
|
-
*
|
|
257
|
+
* - Returns `false` if `text` or `searchWords` is `null`/`undefined`/invalid.
|
|
258
|
+
* - Uses **regular expressions** for flexible pattern matching.
|
|
259
|
+
* - **Escapes special characters** to prevent regex injection attacks.
|
|
260
|
+
* - **Trims input** to avoid false positives with empty spaces.
|
|
261
|
+
* - **Supports exact word matching** (optional).
|
|
262
|
+
*
|
|
263
|
+
* ---
|
|
199
264
|
* @param {string|null|undefined} text - The string text to search within.
|
|
200
265
|
* @param {string[]|null} [searchWords] - An array of words/phrases to match against the text.
|
|
201
266
|
* @param {OptionsTextContainsAny} [options] - Optional configuration object.
|
|
202
267
|
* @param {OptionsTextContainsAny["exactMatch"]} [options.exactMatch=false] - If `true`, matches whole words only, defaultValue is `false`.
|
|
203
268
|
* @param {OptionsTextContainsAny["flags"]} [options.flags="i"] - Optional regex flags (default: `"i"` for case-insensitive).
|
|
269
|
+
*
|
|
270
|
+
* ---
|
|
204
271
|
* @returns {boolean} Return `true` if at least one `searchWord` is found in `text`, otherwise `false`.
|
|
272
|
+
*
|
|
273
|
+
* ---
|
|
205
274
|
* @example
|
|
206
275
|
* textContainsAny("Hello world", ["hello", "test"]);
|
|
207
276
|
* // ➔ true
|
|
@@ -219,62 +288,88 @@ type OptionsTextContainsAny = {
|
|
|
219
288
|
declare const textContainsAny: <T extends string>(text?: T | null, searchWords?: T[] | string[] | null, options?: OptionsTextContainsAny) => boolean;
|
|
220
289
|
/** ----------------------------------------------------------
|
|
221
290
|
* * ***Predicate: `doesKeyExist`.***
|
|
222
|
-
*
|
|
291
|
+
* -----------------------------------------------------------
|
|
223
292
|
* **Recursively checks if a given key exists in an object or array.**
|
|
293
|
+
*
|
|
294
|
+
* ---
|
|
224
295
|
* - **Behavior:**
|
|
225
|
-
*
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
*
|
|
230
|
-
*
|
|
231
|
-
*
|
|
232
|
-
*
|
|
233
|
-
*
|
|
234
|
-
*
|
|
235
|
-
*
|
|
236
|
-
*
|
|
296
|
+
* - **Supports deeply nested objects and arrays**, searching recursively.
|
|
297
|
+
* - Uses `Object.prototype.hasOwnProperty.call()` to safely check if the
|
|
298
|
+
* key exists at each level, even if its value is `null` or `undefined`.
|
|
299
|
+
* - Optimized to return `true` immediately when the key is found (short-circuits).
|
|
300
|
+
* - Handles edge cases gracefully:
|
|
301
|
+
* - Returns `false` for `null`, `undefined`, or non-object inputs.
|
|
302
|
+
* - Returns `false` if key is not found anywhere, even in deeply nested
|
|
303
|
+
* structures.
|
|
304
|
+
*
|
|
305
|
+
* ---
|
|
306
|
+
* - **Note:**
|
|
307
|
+
* - This function only checks for **the existence of the key itself**,
|
|
308
|
+
* not whether its value is non-null or non-undefined.
|
|
309
|
+
* - If you need to check for both existence and meaningful value, write a stricter function.
|
|
310
|
+
*
|
|
311
|
+
* ---
|
|
237
312
|
* @template T - The type of the input object or array.
|
|
313
|
+
*
|
|
314
|
+
* ---
|
|
238
315
|
* @param {T | Record<string, unknown> | unknown[]} object - The object or array to search.
|
|
239
316
|
* @param {PropertyKey} key - The key to look for (string, number, or symbol).
|
|
240
|
-
* @returns {boolean} Returns `true` if the key exists anywhere in the object or array (even with `null` / `undefined` value), otherwise `false`.
|
|
241
|
-
* @example
|
|
242
|
-
* doesKeyExist({ name: "John", age: 30 }, "age");
|
|
243
|
-
* // ➔ true
|
|
244
|
-
* doesKeyExist({ user: { profile: { email: "test@example.com" } } }, "email");
|
|
245
|
-
* // ➔ true
|
|
246
|
-
* doesKeyExist([{ id: 1 }, { id: 2 }], "id");
|
|
247
|
-
* // ➔ true
|
|
248
|
-
* doesKeyExist({ a: { b: { c: 10 } } }, "d");
|
|
249
|
-
* // ➔ false
|
|
250
|
-
* doesKeyExist(null, "name");
|
|
251
|
-
* // ➔ false
|
|
252
|
-
* doesKeyExist(undefined, "test");
|
|
253
|
-
* // ➔ false
|
|
254
317
|
*
|
|
255
|
-
*
|
|
256
|
-
*
|
|
257
|
-
* doesKeyExist({ a: null, b: undefined, c: { d: null } }, "b"); // ➔ true
|
|
258
|
-
* doesKeyExist({ a: null, b: undefined, c: { d: null } }, "d"); // ➔ true
|
|
318
|
+
* ---
|
|
319
|
+
* @returns {boolean} Returns `true` if the key exists anywhere in the object or array (even with `null` / `undefined` value), otherwise `false`.
|
|
259
320
|
*
|
|
260
|
-
*
|
|
261
|
-
*
|
|
262
|
-
*
|
|
263
|
-
*
|
|
321
|
+
* ---
|
|
322
|
+
* @example
|
|
323
|
+
* 1. #### Basic usage:
|
|
324
|
+
* ```ts
|
|
325
|
+
* doesKeyExist({ name: "John", age: 30 }, "age");
|
|
326
|
+
* // ➔ true
|
|
327
|
+
* doesKeyExist({ user: { profile: { email: "test@example.com" } } }, "email");
|
|
328
|
+
* // ➔ true
|
|
329
|
+
* doesKeyExist([{ id: 1 }, { id: 2 }], "id");
|
|
330
|
+
* // ➔ true
|
|
331
|
+
* doesKeyExist({ a: { b: { c: 10 } } }, "d");
|
|
332
|
+
* // ➔ false
|
|
333
|
+
* doesKeyExist(null, "name");
|
|
334
|
+
* // ➔ false
|
|
335
|
+
* doesKeyExist(undefined, "test");
|
|
336
|
+
* // ➔ false
|
|
337
|
+
* ```
|
|
338
|
+
* ---
|
|
339
|
+
* 2. #### Key exists even if value is null or undefined:
|
|
340
|
+
* ```ts
|
|
341
|
+
* doesKeyExist({ a: null, b: undefined, c: { d: null } }, "a");
|
|
342
|
+
* // ➔ true
|
|
343
|
+
* doesKeyExist({ a: null, b: undefined, c: { d: null } }, "b");
|
|
344
|
+
* // ➔ true
|
|
345
|
+
* doesKeyExist({ a: null, b: undefined, c: { d: null } }, "d");
|
|
346
|
+
* // ➔ true
|
|
347
|
+
* ```
|
|
348
|
+
* ---
|
|
349
|
+
* 3. #### Invalid usage:
|
|
350
|
+
* ```ts
|
|
351
|
+
* doesKeyExist({ a: 1 }, true);
|
|
352
|
+
* // ➔ Throws TypeError
|
|
353
|
+
* doesKeyExist({ a: 1 }, ["not", "valid"]);
|
|
354
|
+
* // ➔ Throws TypeError
|
|
355
|
+
* ```
|
|
264
356
|
*/
|
|
265
357
|
declare const doesKeyExist: (object: Record<string, unknown> | unknown[], key: PropertyKey) => boolean;
|
|
266
358
|
/** ----------------------------------------------------------
|
|
267
359
|
* * ***Predicate: `arrayHasAnyMatch`.***
|
|
268
|
-
*
|
|
360
|
+
* -----------------------------------------------------------
|
|
269
361
|
* **Checks if at least one element from `targetArray` exists in `sourceArray`.**
|
|
362
|
+
*
|
|
270
363
|
* - **Behavior:**
|
|
271
|
-
*
|
|
272
|
-
*
|
|
273
|
-
*
|
|
274
|
-
*
|
|
364
|
+
* - Uses `Set` for **faster lookup** compared to `Array.prototype.includes()`.
|
|
365
|
+
* - Supports **any data type** (`number`, `string`, `boolean`, `object`, `array`, `function`, etc.).
|
|
366
|
+
* - Uses **reference equality** for non-primitive values (object, array, function).
|
|
367
|
+
* - Returns `false` if either array is missing, empty, or not an array.
|
|
368
|
+
*
|
|
275
369
|
* @template T - The expected type of array elements.
|
|
276
370
|
* @param {T[] | null | undefined} sourceArray - The array to search within.
|
|
277
371
|
* @param {T[] | null | undefined} targetArray - The array containing elements to match.
|
|
372
|
+
*
|
|
278
373
|
* @returns {boolean}
|
|
279
374
|
* ***Return:***
|
|
280
375
|
* - `true` if **at least one element from `targetArray` is strictly found
|
|
@@ -317,63 +412,73 @@ declare const doesKeyExist: (object: Record<string, unknown> | unknown[], key: P
|
|
|
317
412
|
*/
|
|
318
413
|
declare const arrayHasAnyMatch: <T>(sourceArray: T[] | null | undefined, targetArray: T[] | null | undefined) => boolean;
|
|
319
414
|
/**
|
|
320
|
-
* Restrict array indices to a fixed numeric range (1–
|
|
415
|
+
* * ***Restrict array indices to a fixed numeric range (1–5).***
|
|
321
416
|
*/
|
|
322
|
-
type ArrayIndex = NumberRangeUnion<1,
|
|
417
|
+
type ArrayIndex = NumberRangeUnion<1, 5>;
|
|
323
418
|
/**
|
|
324
|
-
* Remove `undefined` from a type
|
|
419
|
+
* * ***Remove `undefined` from a type.***
|
|
325
420
|
*/
|
|
326
421
|
type NonUndef<T> = T extends undefined ? never : T;
|
|
327
422
|
/**
|
|
328
|
-
* Remove `null` from a type
|
|
423
|
+
* * ***Remove `null` from a type.***
|
|
329
424
|
*/
|
|
330
425
|
type NonNull<T> = T extends null ? never : T;
|
|
331
426
|
/**
|
|
332
|
-
* Convert optional boolean for "discard undefined" to actual boolean
|
|
427
|
+
* * ***Convert optional boolean for "discard undefined" to actual boolean.***
|
|
333
428
|
*/
|
|
334
429
|
type EffectiveDiscardUndefined<O extends boolean | undefined> = O extends boolean ? O : true;
|
|
335
430
|
/**
|
|
336
|
-
* Convert optional boolean for "discard null" to actual boolean
|
|
431
|
+
* * ***Convert optional boolean for "discard null" to actual boolean.***
|
|
337
432
|
*/
|
|
338
433
|
type EffectiveDiscardNull<O extends boolean | undefined> = O extends boolean ? O : false;
|
|
339
434
|
/**
|
|
340
|
-
* Unwrap array type
|
|
435
|
+
* * ***Unwrap array type.***
|
|
341
436
|
*/
|
|
342
437
|
type UnwrapArray<T> = T extends (infer U)[] ? U : T extends readonly (infer U)[] ? U : T;
|
|
343
438
|
/**
|
|
344
|
-
* Force symbol key to be deep required
|
|
439
|
+
* * ***Force symbol key to be deep required.***
|
|
345
440
|
*/
|
|
346
441
|
type IsOptionalKey<T, K extends keyof T> = Record<never, never> extends Pick<T, K> ? true : false;
|
|
347
|
-
/**
|
|
442
|
+
/** ---------------------------------------------------------
|
|
443
|
+
* * ***Returns numeric keys of an object.***
|
|
444
|
+
* ----------------------------------------------------------
|
|
348
445
|
*
|
|
349
|
-
* @private ***
|
|
446
|
+
* @private ***Types for {@link hasOwnProp}.***
|
|
350
447
|
*/
|
|
351
448
|
type NumericKeyOfHasOwnProp<Obj> = Extract<keyof Obj, number>;
|
|
352
|
-
/**
|
|
449
|
+
/** ---------------------------------------------------------
|
|
450
|
+
* * ***Generate all nested keys of an object or array in dot/bracket notation.***
|
|
451
|
+
* ---------------------------------------------------------
|
|
353
452
|
*
|
|
354
|
-
* @private ***
|
|
453
|
+
* @private ***Types for {@link hasOwnProp}.***
|
|
355
454
|
*
|
|
356
|
-
*
|
|
357
|
-
*
|
|
358
|
-
*
|
|
359
|
-
*
|
|
360
|
-
*
|
|
455
|
+
* ---
|
|
456
|
+
* - #### Example:
|
|
457
|
+
* ```ts
|
|
458
|
+
* type Keys = NestedKeyOfHasOwnProp<{ users: { name: string }[] }>
|
|
459
|
+
* // Keys = "users" | "users.[number]" | "users.[number].name"
|
|
460
|
+
* ```
|
|
361
461
|
*/
|
|
362
462
|
type NestedKeyOfHasOwnProp<T> = T extends readonly (infer U)[] ? `[${number}]` | `[${number}].${NestedKeyOfHasOwnProp<U>}` : T extends object ? { [K in keyof T & (string | number)]: K extends string | number ? NonNullable<T[K]> extends readonly unknown[] ? `${K}` | `${K}.[${ArrayIndex}]` | `${K}.[${ArrayIndex}].${NestedKeyOfHasOwnProp<UnwrapArray<T[K]>>}` : NonNullable<T[K]> extends object ? `${K}` | `${K}.${NestedKeyOfHasOwnProp<NonNullable<T[K]>>}` : `${K}` : never }[keyof T & (string | number)] : never;
|
|
363
|
-
/**
|
|
463
|
+
/** ---------------------------------------------------------
|
|
464
|
+
* * ***Apply discard rules to the last key of a path.***
|
|
465
|
+
* ----------------------------------------------------------
|
|
364
466
|
*
|
|
365
|
-
* Rules:
|
|
366
|
-
*
|
|
367
|
-
*
|
|
467
|
+
* - #### Rules:
|
|
468
|
+
* - If `discardUndefined` is `true` ➔ remove `undefined` from value.
|
|
469
|
+
* - If `discardNull` is `true` ➔ remove `null` from value.
|
|
368
470
|
*
|
|
369
|
-
*
|
|
471
|
+
* ---
|
|
472
|
+
* **Order:** First strip undefined (if requested), then strip null (if requested).
|
|
370
473
|
*/
|
|
371
474
|
type ApplyLastRulesHasOwnProp<V, DiscardU extends boolean, DiscardN extends boolean> = DiscardU extends true ? DiscardN extends true ? NonNull<NonUndef<V>> : NonUndef<V> : DiscardN extends true ? NonNull<V> : V | Extract<V, undefined>;
|
|
372
475
|
/**
|
|
373
|
-
* Force an array index N to type U
|
|
476
|
+
* * ***Force an array index N to type U.***
|
|
374
477
|
*/
|
|
375
478
|
type RefineArrayAtIndex<T extends readonly unknown[], N extends number, U> = T & { [K in N]: U };
|
|
376
|
-
/**
|
|
479
|
+
/** ---------------------------------------------------------
|
|
480
|
+
* * ***Narrow object/array type based on a path string.***
|
|
481
|
+
* ----------------------------------------------------------
|
|
377
482
|
*
|
|
378
483
|
* @template T - object type to narrow
|
|
379
484
|
* @template P - path string like "user.addresses.[2].zip"
|
|
@@ -381,135 +486,176 @@ type RefineArrayAtIndex<T extends readonly unknown[], N extends number, U> = T &
|
|
|
381
486
|
* @template DN - discard null
|
|
382
487
|
*/
|
|
383
488
|
type NarrowByPathHasOwnProp<T, P extends string, DU extends boolean = true, DN extends boolean = false> = P extends `${infer Head}.${infer Rest}` ? Head extends `[${infer N extends number}]` ? T extends readonly (infer U)[] ? RefineArrayAtIndex<T, N, NarrowByPathHasOwnProp<U, Rest, DU, DN>> : T : Head extends keyof T ? Rest extends `[${infer M extends number}]${infer R}` ? M extends R ? { [K in keyof T]-?: NarrowByPathHasOwnProp<EffectiveDiscardUndefined<DU> extends true ? NonUndef<T[K]> : EffectiveDiscardNull<DN> extends true ? NonNull<T[K]> : T[K], Rest, DU, DN> } : EffectiveDiscardUndefined<DU> extends true ? { [K in keyof T]-?: K extends Head ? Exclude<NarrowByPathHasOwnProp<EffectiveDiscardNull<DN> extends true ? Exclude<T[K], null> : EffectiveDiscardUndefined<DU> extends true ? Exclude<T[K], undefined> : T[K], Rest, DU, DN>, undefined> : EffectiveDiscardNull<DN> extends true ? Exclude<T[K], null> : EffectiveDiscardUndefined<DU> extends true ? Exclude<T[K], undefined> : T[K] } : { [K in keyof T]: K extends Head ? NarrowByPathHasOwnProp<EffectiveDiscardNull<DN> extends true ? Exclude<T[K], null> : EffectiveDiscardUndefined<DU> extends true ? Exclude<T[K], undefined> : T[K], Rest, DU, DN> : EffectiveDiscardNull<DN> extends true ? Exclude<T[K], null> : EffectiveDiscardUndefined<DU> extends true ? Exclude<T[K], undefined> : T[K] } : { [K in keyof T]: K extends Head ? NarrowByPathHasOwnProp<NonNullable<T[K]>, Rest, DU, DN> : T[K] } & { [K in Head]-?: NarrowByPathHasOwnProp<NonNullable<T[K]>, Rest, DU, DN> } : T : P extends `[${infer N extends number}]` ? T extends readonly (infer U)[] ? RefineArrayAtIndex<T, N, ApplyLastRulesHasOwnProp<NonNullable<U>, DU, DN>> : T : P extends keyof T ? DU extends true ? { [K in keyof T]: K extends P ? ApplyLastRulesHasOwnProp<T[K], DU, DN> : T[K] } & { [K in P]-?: ApplyLastRulesHasOwnProp<T[P], DU, DN> } : { [K in keyof T]: K extends P ? ApplyLastRulesHasOwnProp<T[K], DU, DN> : T[K] } : T;
|
|
384
|
-
/**
|
|
489
|
+
/** ---------------------------------------------------------
|
|
490
|
+
* * ***Expand an array/string/function into a nested type according
|
|
385
491
|
* to a dot/bracket path.***
|
|
492
|
+
* ----------------------------------------------------------
|
|
386
493
|
*
|
|
387
|
-
* @private ***
|
|
494
|
+
* @private ***Types for {@link hasOwnProp}.***
|
|
388
495
|
*/
|
|
389
496
|
type SmartDetectStringHasOwnProp<Obj extends string | undefined | null, Key extends string | number> = Obj extends undefined ? undefined : Obj extends null ? null : IsPositive<ParseNumber<Key>> extends true ? Extends<IsStringLiteral<Obj>, true> extends true ? CharAt<Exclude<Obj, null | undefined>, ParseNumber<Key>> : string | undefined | null : IsPositive<ParseNumber<Key>> extends true ? string | undefined | null : AnyString | undefined | null;
|
|
390
497
|
/**
|
|
391
|
-
* ***
|
|
498
|
+
* * ***Types for {@link hasOwnProp}.***
|
|
392
499
|
*/
|
|
393
500
|
type SmartDetectArrayFuncHasOwnProp<Obj extends unknown[] | AnyFunction, Key extends PropertyKey> = Prettify<Obj & DotToNestedSpecialSmartDetect<Key> & {
|
|
394
501
|
length: number;
|
|
395
502
|
}, {
|
|
396
503
|
recursive: false;
|
|
397
504
|
}>;
|
|
398
|
-
/**
|
|
505
|
+
/** ---------------------------------------------------------
|
|
506
|
+
* * ***Smartly detect nested path keys of an unknown object or function,
|
|
399
507
|
* falls-back to inferred nested structure when path is not valid.***
|
|
508
|
+
* ----------------------------------------------------------
|
|
400
509
|
*
|
|
401
|
-
* @private ***
|
|
510
|
+
* @private ***Types for {@link hasOwnProp}.***
|
|
402
511
|
*/
|
|
403
512
|
type SmartDetectUnknownKeyHasOwnProp<Obj extends unknown | AnyFunction, Key extends PropertyKey, DiscardUndefined extends boolean = true, DiscardNull extends boolean = false> = Trim<Key> extends "" ? Obj : Prettify<Obj & (Key extends NestedKeyOfHasOwnProp<Obj> ? GuardedHasOwnProp<Obj, Key, DiscardUndefined, DiscardNull> : DotToNestedSpecialSmartDetect<Key>), {
|
|
404
513
|
recursive: true;
|
|
405
514
|
}>;
|
|
406
|
-
/**
|
|
407
|
-
* Convert dot/bracket path string to nested object type with leaf value.
|
|
408
|
-
* Path not found in object key ➔ return unknown
|
|
515
|
+
/** ---------------------------------------------------------
|
|
516
|
+
* * ***Convert dot/bracket path string to nested object type with leaf value.
|
|
517
|
+
* Path not found in object key ➔ return `unknown`.***
|
|
518
|
+
* ----------------------------------------------------------
|
|
409
519
|
*/
|
|
410
520
|
type DotToNestedSpecialSmartDetect<Path extends PropertyKey, Value = unknown> = IsEmptyString<Extract<Path, string>> extends true ? undefined : Path extends `${infer Head}.${infer Rest}` ? Head extends `[${number}]` ? DotToNestedSpecialSmartDetect<Rest, Value>[] : { [Key in Head]: DotToNestedSpecialSmartDetect<Rest, Value> } : Path extends `[${number}]` ? Value[] : { [Key in Path]: Value };
|
|
411
|
-
/**
|
|
521
|
+
/** ---------------------------------------------------------
|
|
522
|
+
* * ***Guarded wrapper for `NarrowByPathHasOwnProp` with `Prettify`.***
|
|
523
|
+
* ----------------------------------------------------------
|
|
412
524
|
*
|
|
413
|
-
* @private ***
|
|
525
|
+
* @private ***Types for {@link hasOwnProp}.***
|
|
414
526
|
*/
|
|
415
527
|
type GuardedHasOwnProp<Obj, Key extends NestedKeyOfHasOwnProp<Obj>, DiscardUndefined extends boolean | undefined, DiscardNull extends boolean | undefined> = Prettify<Obj & NarrowByPathHasOwnProp<Obj, Key & string, EffectiveDiscardUndefined<DiscardUndefined>, EffectiveDiscardNull<DiscardNull>>, {
|
|
416
528
|
recursive: true;
|
|
417
529
|
}>;
|
|
418
|
-
/**
|
|
530
|
+
/** ---------------------------------------------------------
|
|
531
|
+
* * ***Make a specific symbol key deeply required in an object symbols.***
|
|
532
|
+
* ----------------------------------------------------------
|
|
533
|
+
*
|
|
419
534
|
* **Used internally to enforce stronger type narrowing.**
|
|
420
535
|
*
|
|
421
|
-
*
|
|
536
|
+
* ---
|
|
537
|
+
* @private ***Types for {@link hasOwnProp}.***
|
|
422
538
|
*/
|
|
423
539
|
type DeepRequiredSymbolHasOwnProp<Obj, Sym extends symbol, DU extends boolean = true, DN extends boolean = false> = Prettify<Obj & ({ [K in keyof Obj & Sym as DU extends true ? K : never]-?: DN extends true ? NonNull<NonUndef<Obj[K]>> : NonUndef<Obj[K]> } & { [K in keyof Obj & Sym as DU extends true ? never : K]?: DN extends true ? NonNull<Obj[K]> : Obj[K] }), {
|
|
424
540
|
recursive: true;
|
|
425
541
|
}>;
|
|
426
|
-
/**
|
|
542
|
+
/** ---------------------------------------------------------
|
|
543
|
+
* * ***Apply discard rules to numeric keys in an object type.***
|
|
544
|
+
* ----------------------------------------------------------
|
|
427
545
|
*
|
|
546
|
+
* ---
|
|
428
547
|
* - If `discardUndefined = true` ➔ undefined removed, key required
|
|
429
548
|
* - If `discardNull = true` ➔ null removed
|
|
430
549
|
*
|
|
431
|
-
*
|
|
550
|
+
* ---
|
|
551
|
+
* @private ***Types for {@link hasOwnProp}.***
|
|
432
552
|
*/
|
|
433
553
|
type NumericKeyHasOwnPropMapped<Obj extends object, K extends NumericKeyOfHasOwnProp<Obj>, DU extends boolean, DN extends boolean> = Prettify<Obj & (IsOptionalKey<Obj, K> extends true ? { [P in K]?: DN extends true ? NonNull<Obj[K]> : Obj[K] } & (DU extends true ? { [P in K]-?: NonUndef<Obj[K]> } : Record<never, never>) : { [P in K]-?: DN extends true ? NonNull<Obj[K]> : Obj[K] } & (DU extends true ? { [P in K]-?: NonUndef<Obj[K]> } : Record<never, never>)), {
|
|
434
554
|
recursive: true;
|
|
435
555
|
}>;
|
|
436
|
-
/**
|
|
556
|
+
/** ---------------------------------------------------------
|
|
557
|
+
* * ***Options to control `hasOwnProp` behavior.***
|
|
558
|
+
* ----------------------------------------------------------
|
|
437
559
|
*
|
|
438
560
|
* @private ***types options for {@link hasOwnProp}.***
|
|
439
561
|
*/
|
|
440
562
|
type HasOwnPropOptions<DiscardUndefined extends boolean = true, DiscardNull extends boolean = false> = {
|
|
441
|
-
/**
|
|
563
|
+
/** ---------------------------------------------------------
|
|
564
|
+
* * ***If `true` ***(default)***, properties with `undefined` values are treated as non-existent.***
|
|
565
|
+
* ----------------------------------------------------------
|
|
442
566
|
*
|
|
567
|
+
* ---
|
|
443
568
|
* - **Effects:**
|
|
444
|
-
*
|
|
445
|
-
*
|
|
569
|
+
* - **Runtime:** `hasOwnProp(obj, key)` returns `false` if the property exists but its value is `undefined`.
|
|
570
|
+
* - **TypeScript narrowing:** The property's type is narrowed to exclude `undefined`.
|
|
571
|
+
* ---
|
|
446
572
|
* - **Example:**
|
|
447
|
-
*
|
|
573
|
+
* ```ts
|
|
448
574
|
* const obj = { a: undefined, b: 123 };
|
|
449
|
-
* hasOwnProp(obj, "a");
|
|
450
|
-
*
|
|
451
|
-
*
|
|
575
|
+
* hasOwnProp(obj, "a");
|
|
576
|
+
* // ➔ false
|
|
577
|
+
* hasOwnProp(obj, "a", { discardUndefined: false });
|
|
578
|
+
* // ➔ true
|
|
579
|
+
* ```
|
|
452
580
|
*/
|
|
453
581
|
discardUndefined?: DiscardUndefined;
|
|
454
|
-
/**
|
|
582
|
+
/** ---------------------------------------------------------
|
|
583
|
+
* * ***If `true` ***(default: `false`)***, properties with `null` values are treated as non-existent.***
|
|
584
|
+
* ----------------------------------------------------------
|
|
455
585
|
*
|
|
586
|
+
* ---
|
|
456
587
|
* - **Effects:**
|
|
457
|
-
*
|
|
458
|
-
*
|
|
588
|
+
* - **Runtime:** `hasOwnProp(obj, key)` returns `false` if the property exists but its value is `null`.
|
|
589
|
+
* - **TypeScript narrowing:** The property's type is narrowed to exclude `null`.
|
|
590
|
+
*
|
|
591
|
+
* ---
|
|
459
592
|
* - **Example:**
|
|
460
|
-
*
|
|
461
|
-
*
|
|
462
|
-
*
|
|
463
|
-
*
|
|
464
|
-
*
|
|
593
|
+
* ```ts
|
|
594
|
+
* const obj = { a: null, b: 123 };
|
|
595
|
+
* hasOwnProp(obj, "a");
|
|
596
|
+
* // ➔ true (default discardNull = false)
|
|
597
|
+
* hasOwnProp(obj, "a", { discardNull: true });
|
|
598
|
+
* // ➔ false
|
|
599
|
+
* ```
|
|
465
600
|
*/
|
|
466
601
|
discardNull?: DiscardNull;
|
|
467
602
|
};
|
|
468
603
|
/** -------------------------------------------------------
|
|
469
|
-
* * ***
|
|
470
|
-
*
|
|
604
|
+
* * ***Type guard: `hasOwnProp`.***
|
|
605
|
+
* --------------------------------------------------------
|
|
471
606
|
* **A **type-safe** replacement for `Object.prototype.hasOwnProperty` with runtime validation and **TypeScript-aware type narrowing**.**
|
|
472
|
-
*
|
|
473
|
-
*
|
|
474
|
-
*
|
|
475
|
-
*
|
|
476
|
-
*
|
|
477
|
-
*
|
|
478
|
-
*
|
|
479
|
-
*
|
|
480
|
-
*
|
|
481
|
-
*
|
|
482
|
-
*
|
|
483
|
-
*
|
|
484
|
-
*
|
|
485
|
-
*
|
|
486
|
-
*
|
|
487
|
-
*
|
|
488
|
-
*
|
|
489
|
-
*
|
|
490
|
-
*
|
|
491
|
-
*
|
|
492
|
-
*
|
|
493
|
-
*
|
|
494
|
-
*
|
|
495
|
-
*
|
|
496
|
-
*
|
|
497
|
-
*
|
|
498
|
-
*
|
|
499
|
-
*
|
|
500
|
-
*
|
|
501
|
-
*
|
|
502
|
-
*
|
|
503
|
-
*
|
|
504
|
-
*
|
|
505
|
-
*
|
|
506
|
-
*
|
|
507
|
-
*
|
|
508
|
-
*
|
|
509
|
-
*
|
|
510
|
-
*
|
|
511
|
-
*
|
|
512
|
-
*
|
|
607
|
+
*
|
|
608
|
+
* ---
|
|
609
|
+
* - #### *Supported Targets:*
|
|
610
|
+
* - **Plain objects** ➔ `{ foo: "bar" }`.
|
|
611
|
+
* - **Arrays** ➔ `[ { id: 1 }, { id: 2 } ]`.
|
|
612
|
+
* - **Strings** ➔ `"hello"` (as array-like objects with `.length`, index, etc.).
|
|
613
|
+
* - **Functions** ➔ callable objects with extra props.
|
|
614
|
+
* - **Symbols** ➔ own property symbols.
|
|
615
|
+
* ---
|
|
616
|
+
* - #### *Key Advantages over `in` or `obj.hasOwnProperty(key)`:*
|
|
617
|
+
* - Supports **dot/bracket path notation** (e.g. `"user.address.city"`, `"addresses[0].zip"`).
|
|
618
|
+
* - Handles **symbol** keys safely.
|
|
619
|
+
* - **Narrows** the type of `obj` in TypeScript (stronger type safety).
|
|
620
|
+
* - Configurable handling of **`undefined`** and **`null`**.
|
|
621
|
+
* ---
|
|
622
|
+
* - #### *Runtime Behavior:*
|
|
623
|
+
* - #### Returns `true` if:
|
|
624
|
+
* - Value `obj` is an object/array/string/function **and** the property
|
|
625
|
+
* exists **and**, it passes the `options` checks.
|
|
626
|
+
* ---
|
|
627
|
+
* - #### Returns `false` if:
|
|
628
|
+
* - Value `obj` is not a valid type.
|
|
629
|
+
* - The property does not exist.
|
|
630
|
+
* - The value is `undefined` and `discardUndefined: true` (**default**).
|
|
631
|
+
* - The value is `null` and `discardNull: true`.
|
|
632
|
+
* - The `key` (after trimming) is an **empty string** ➔ treated as **invalid**.
|
|
633
|
+
* ---
|
|
634
|
+
* - #### *TypeScript Behavior:*
|
|
635
|
+
* - #### Inside an `if (hasOwnProp(...)) {}` block:
|
|
636
|
+
* - The property is **guaranteed to exist**.
|
|
637
|
+
* - Depending on `options`, the property type is narrowed to exclude
|
|
638
|
+
* `undefined` and/or `null`.
|
|
639
|
+
* ---
|
|
640
|
+
* - #### *Caveats:*
|
|
641
|
+
* - #### Empty keys are invalid:
|
|
642
|
+
* - If the `key` string is empty (`""`) after trimming whitespace or other characters,
|
|
643
|
+
* it will **not** be considered a valid property and always returns `false`.
|
|
644
|
+
* ---
|
|
645
|
+
* - #### Arrays are limited by TypeScript inference:
|
|
646
|
+
* - Checking index `[0]` only narrows **that specific index**, not the rest, example:
|
|
647
|
+
* 1. `hasOwnProp(users, "[0].id")` does **not** imply `users[1].id` exists.
|
|
648
|
+
* - For different indices, use **optional chaining** (`users[1]?.id`).
|
|
649
|
+
* ---
|
|
650
|
+
* - #### Autocomplete limitation for array indices:
|
|
651
|
+
* - Autocompletion for `[index]` is only supported up to **5** (`[0]` ➔ `[4]`).
|
|
652
|
+
* - This limit is intentional for **performance and safety:**
|
|
653
|
+
* 1. Generating infinite union types for all possible indices would cause
|
|
654
|
+
* **TypeScript IntelliSense to hang or crash**.
|
|
655
|
+
* - You can still check higher indices manually (e.g. `"[999].id"`),
|
|
656
|
+
* but they will not show up in IntelliSense suggestions.
|
|
657
|
+
*
|
|
658
|
+
* ---
|
|
513
659
|
* @param {HasOwnPropOptions} [options] - ***Optional configuration object.***
|
|
514
660
|
* @param {HasOwnPropOptions["discardUndefined"]} [options.discardUndefined=true]
|
|
515
661
|
* ***If `true`, properties with `undefined` values are treated as **missing**, default: `true`.***
|
|
@@ -521,77 +667,88 @@ type HasOwnPropOptions<DiscardUndefined extends boolean = true, DiscardNull exte
|
|
|
521
667
|
* - `string` (supports dot/bracket paths, e.g. `"user.address.city"`, `"[0].id"`).
|
|
522
668
|
* - `number` (array-like index).
|
|
523
669
|
* - `symbol` (own property symbols).
|
|
524
|
-
* @returns {boolean} Return `true` if the property exists (and passes `options`), otherwise `false`.
|
|
525
|
-
* @example
|
|
526
670
|
*
|
|
527
|
-
*
|
|
528
|
-
*
|
|
529
|
-
* const obj: { name?: string | null } = {};
|
|
671
|
+
* ---
|
|
672
|
+
* @returns {boolean} Return `true` if the property exists (and passes `options`), otherwise `false`.
|
|
530
673
|
*
|
|
531
|
-
*
|
|
532
|
-
*
|
|
533
|
-
* console.log(obj.name); // string | null
|
|
534
|
-
* }
|
|
674
|
+
* ---
|
|
675
|
+
* @example
|
|
535
676
|
*
|
|
536
|
-
*
|
|
537
|
-
*
|
|
538
|
-
*
|
|
539
|
-
* }
|
|
540
|
-
* ```
|
|
541
|
-
* - #### ✅ Arrays:
|
|
542
|
-
* ```ts
|
|
543
|
-
* const users = [{ id: 1 }, { id: 2 }];
|
|
677
|
+
* - #### Objects:
|
|
678
|
+
* ```ts
|
|
679
|
+
* const obj: { name?: string | null } = {};
|
|
544
680
|
*
|
|
545
|
-
*
|
|
546
|
-
*
|
|
547
|
-
*
|
|
548
|
-
*
|
|
681
|
+
* if (hasOwnProp(obj, "name")) {
|
|
682
|
+
* // obj is now ➔ { name: string | null }
|
|
683
|
+
* console.log(obj.name); // string | null
|
|
684
|
+
* }
|
|
549
685
|
*
|
|
550
|
-
*
|
|
551
|
-
*
|
|
552
|
-
*
|
|
553
|
-
*
|
|
554
|
-
*
|
|
686
|
+
* if (hasOwnProp(obj, "name", { discardUndefined: true, discardNull: true })) {
|
|
687
|
+
* // obj is now ➔ { name: string }
|
|
688
|
+
* console.log(obj.name.toUpperCase()); // safe
|
|
689
|
+
* }
|
|
690
|
+
* ```
|
|
691
|
+
* - #### Arrays:
|
|
692
|
+
* ```ts
|
|
693
|
+
* const users = [{ id: 1 }, { id: 2 }];
|
|
694
|
+
*
|
|
695
|
+
* if (hasOwnProp(users, "[1].id")) {
|
|
696
|
+
* // ➔ users[1].id is guaranteed to exist
|
|
697
|
+
* console.log(users[1].id); // number
|
|
698
|
+
* }
|
|
555
699
|
*
|
|
556
|
-
*
|
|
557
|
-
*
|
|
558
|
-
*
|
|
700
|
+
* // Caveat: narrowing only applies to checked index
|
|
701
|
+
* if (hasOwnProp(users, "[0].id")) {
|
|
702
|
+
* console.log(users[0].id); // safe
|
|
703
|
+
* console.log(users[1].id); // not guaranteed!
|
|
704
|
+
* }
|
|
559
705
|
*
|
|
560
|
-
*
|
|
561
|
-
*
|
|
562
|
-
*
|
|
563
|
-
*
|
|
706
|
+
* // Solution: optional chaining
|
|
707
|
+
* console.log(users[1]?.id);
|
|
708
|
+
* // ➔ safe, even without narrowing
|
|
709
|
+
* ```
|
|
564
710
|
*
|
|
565
|
-
*
|
|
566
|
-
*
|
|
567
|
-
*
|
|
568
|
-
*
|
|
569
|
-
* - #### ✅ Strings:
|
|
570
|
-
* ```ts
|
|
571
|
-
* if (hasOwnProp("hello", "length")) {
|
|
572
|
-
* console.log("hello".length); // ➔ 5
|
|
573
|
-
* }
|
|
711
|
+
* - #### Symbols:
|
|
712
|
+
* ```ts
|
|
713
|
+
* const secret = Symbol("secret");
|
|
714
|
+
* const obj2 = { [secret]: 42 };
|
|
574
715
|
*
|
|
575
|
-
*
|
|
576
|
-
*
|
|
577
|
-
*
|
|
578
|
-
*
|
|
579
|
-
*
|
|
580
|
-
*
|
|
581
|
-
*
|
|
582
|
-
*
|
|
716
|
+
* if (hasOwnProp(obj2, secret)) {
|
|
717
|
+
* console.log(obj2[secret] + 1);
|
|
718
|
+
* // ➔ 43
|
|
719
|
+
* }
|
|
720
|
+
* ```
|
|
721
|
+
* - #### Strings:
|
|
722
|
+
* ```ts
|
|
723
|
+
* if (hasOwnProp("hello", "length")) {
|
|
724
|
+
* console.log("hello".length);
|
|
725
|
+
* // ➔ 5
|
|
726
|
+
* }
|
|
583
727
|
*
|
|
584
|
-
*
|
|
585
|
-
*
|
|
586
|
-
*
|
|
587
|
-
*
|
|
588
|
-
*
|
|
589
|
-
*
|
|
590
|
-
*
|
|
728
|
+
* if (hasOwnProp("hello", 1)) {
|
|
729
|
+
* console.log("hello"[1]);
|
|
730
|
+
* // ➔ "e"
|
|
731
|
+
* }
|
|
732
|
+
* ```
|
|
733
|
+
* - #### Functions:
|
|
734
|
+
* ```ts
|
|
735
|
+
* function fn() {}
|
|
736
|
+
* fn.extra = 123;
|
|
737
|
+
*
|
|
738
|
+
* if (hasOwnProp(fn, "extra")) {
|
|
739
|
+
* console.log(fn.extra);
|
|
740
|
+
* // ➔ 123
|
|
741
|
+
* }
|
|
742
|
+
* ```
|
|
743
|
+
* - #### Empty key:
|
|
744
|
+
* ```ts
|
|
745
|
+
* const obj = { a: 1 };
|
|
591
746
|
*
|
|
592
|
-
*
|
|
593
|
-
*
|
|
594
|
-
*
|
|
747
|
+
* hasOwnProp(obj, "");
|
|
748
|
+
* // ➔ false (invalid key)
|
|
749
|
+
* hasOwnProp(obj, " ");
|
|
750
|
+
* // ➔ false (trimmed to empty)
|
|
751
|
+
* ```
|
|
595
752
|
*/
|
|
596
753
|
declare function hasOwnProp<Obj>(obj: IsAny<Obj> extends true ? Obj : never, key: PropertyKey, options?: HasOwnPropOptions<boolean, boolean>): obj is unknown;
|
|
597
754
|
declare function hasOwnProp<Obj extends null | undefined>(obj: Obj, key: PropertyKey, options?: HasOwnPropOptions<boolean, boolean>): false;
|
|
@@ -601,12 +758,14 @@ declare function hasOwnProp<Obj extends object | AnyFunction, Sym extends symbol
|
|
|
601
758
|
declare function hasOwnProp<Obj extends string | null | undefined, Key extends string | number>(obj: Obj | null | undefined, key: Key, options?: HasOwnPropOptions<boolean, boolean>): obj is IsStringLiteral<SmartDetectStringHasOwnProp<Obj, Key>> extends true ? AnyString | SmartDetectStringHasOwnProp<Obj, Key> : SmartDetectStringHasOwnProp<Obj, Key>;
|
|
602
759
|
declare function hasOwnProp<Obj extends unknown[] | AnyFunction, Key extends PropertyKey>(obj: Obj, key: Key, options?: HasOwnPropOptions<boolean, boolean>): obj is SmartDetectArrayFuncHasOwnProp<Obj, Key>;
|
|
603
760
|
declare function hasOwnProp<Obj extends unknown | AnyFunction, Key extends PropertyKey, DiscardUndefined extends boolean = true, DiscardNull extends boolean = false>(obj: Obj, key: Key | "length" | (IsPlainObjectResult<Obj> extends never ? never : keyof Obj), options?: HasOwnPropOptions<DiscardUndefined, DiscardNull>): obj is SmartDetectUnknownKeyHasOwnProp<Obj, Key, DiscardUndefined, DiscardNull>;
|
|
604
|
-
/**
|
|
761
|
+
/** ----------------------------------------------------------
|
|
605
762
|
* * ***Type guard: `isArguments`.***
|
|
606
|
-
*
|
|
763
|
+
* -----------------------------------------------------------
|
|
607
764
|
* **Checks if `value` is likely an `arguments` object.**
|
|
765
|
+
*
|
|
608
766
|
* @param {*} value The value to check.
|
|
609
767
|
* @returns {boolean} Returns `true` if `value` is an ***[`IArguments`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/arguments)*** object, else `false`.
|
|
768
|
+
*
|
|
610
769
|
* @example
|
|
611
770
|
* isArguments(function() { return arguments; }());
|
|
612
771
|
* // ➔ true
|
|
@@ -616,15 +775,18 @@ declare function hasOwnProp<Obj extends unknown | AnyFunction, Key extends Prope
|
|
|
616
775
|
declare const isArguments: (value: unknown) => value is IArguments;
|
|
617
776
|
/** ----------------------------------------------------------
|
|
618
777
|
* * ***Type guard: `isArray`.***
|
|
619
|
-
*
|
|
620
|
-
|
|
778
|
+
* -----------------------------------------------------------
|
|
779
|
+
* **Checks if a value is an ***[`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)***.**
|
|
780
|
+
*
|
|
621
781
|
* - **Behavior:**
|
|
622
|
-
*
|
|
623
|
-
*
|
|
624
|
-
*
|
|
782
|
+
* - Uses ***[`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray)*** for reliable and safe type checking.
|
|
783
|
+
* - Supports TypeScript **type narrowing** using `value is T[]`.
|
|
784
|
+
* - Handles edge cases like `null`, `undefined`, and non-array objects.
|
|
785
|
+
*
|
|
625
786
|
* @template T - The expected type of array elements.
|
|
626
787
|
* @param {*} value - The value to check.
|
|
627
788
|
* @returns {boolean} Returns `true` if the value is an `array`, otherwise `false`.
|
|
789
|
+
*
|
|
628
790
|
* @example
|
|
629
791
|
* isArray([1, 2, 3]);
|
|
630
792
|
* // ➔ true
|
|
@@ -644,26 +806,36 @@ declare function isArray<T>(value: T): value is ArrayFallback<T>;
|
|
|
644
806
|
declare function isArray(value: unknown): value is unknown[];
|
|
645
807
|
/** ----------------------------------------------------
|
|
646
808
|
* * ***Type guard: `isArrayBuffer`.***
|
|
647
|
-
*
|
|
809
|
+
* -----------------------------------------------------
|
|
648
810
|
* **Checks if `value` is classified as an `ArrayBuffer` object.**
|
|
811
|
+
*
|
|
649
812
|
* @param {*} value The value to check.
|
|
650
813
|
* @returns {boolean} Returns `true` if `value` is instance of ***[`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)***, else `false`.
|
|
814
|
+
*
|
|
651
815
|
* @example
|
|
652
816
|
* isArrayBuffer(new ArrayBuffer(2));
|
|
653
817
|
* // ➔ true
|
|
654
818
|
* isArrayBuffer(new Array(2));
|
|
655
819
|
* // ➔ false
|
|
656
820
|
*/
|
|
657
|
-
declare
|
|
821
|
+
declare const isArrayBuffer: (value: unknown) => value is ArrayBuffer;
|
|
658
822
|
/** ----------------------------------------------------
|
|
659
823
|
* * ***Type guard: `isArrayLike`.***
|
|
660
|
-
*
|
|
824
|
+
* -----------------------------------------------------
|
|
661
825
|
* **Checks if `value` is array-like, a value is considered array-like if it's
|
|
662
826
|
* not a function and has a `value.length` that's an integer greater than or
|
|
663
827
|
* equal to `0` and less than or equal to `Number.MAX_SAFE_INTEGER`.**
|
|
828
|
+
*
|
|
829
|
+
* ---
|
|
664
830
|
* @template T - The type of the value being checked.
|
|
831
|
+
*
|
|
832
|
+
* ---
|
|
665
833
|
* @param {*} value The value to check.
|
|
834
|
+
*
|
|
835
|
+
* ---
|
|
666
836
|
* @returns {boolean} Returns `true` if `value` is array-like, else `false`.
|
|
837
|
+
*
|
|
838
|
+
* ---
|
|
667
839
|
* @example
|
|
668
840
|
* isArrayLike([1, 2, 3]);
|
|
669
841
|
* // ➔ true
|
|
@@ -683,12 +855,20 @@ declare function isArrayLike(value: unknown): value is {
|
|
|
683
855
|
};
|
|
684
856
|
/** ----------------------------------------------------
|
|
685
857
|
* * ***Type guard: `isArrayLikeObject`.***
|
|
686
|
-
*
|
|
858
|
+
* -----------------------------------------------------
|
|
687
859
|
* **This method is like ***`isArrayLike` utility function*** except that
|
|
688
860
|
* it also checks if `value` is an object.**
|
|
861
|
+
*
|
|
862
|
+
* ---
|
|
689
863
|
* @template T - The type of the value being checked.
|
|
864
|
+
*
|
|
865
|
+
* ---
|
|
690
866
|
* @param {*} value The value to check.
|
|
867
|
+
*
|
|
868
|
+
* ---
|
|
691
869
|
* @returns {boolean} Returns `true` if `value` is `array-like object`, else `false`.
|
|
870
|
+
*
|
|
871
|
+
* ---
|
|
692
872
|
* @example
|
|
693
873
|
* isArrayLikeObject([1, 2, 3]);
|
|
694
874
|
* // ➔ true
|
|
@@ -708,15 +888,23 @@ declare function isArrayLikeObject(value: unknown): value is object & {
|
|
|
708
888
|
};
|
|
709
889
|
/** ----------------------------------------------------------
|
|
710
890
|
* * ***Type guard: `isBigInt`.***
|
|
711
|
-
*
|
|
891
|
+
* -----------------------------------------------------------
|
|
712
892
|
* **Checks if a value is of type **[`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)**.**
|
|
893
|
+
*
|
|
894
|
+
* ---
|
|
713
895
|
* - **Behavior:**
|
|
714
|
-
*
|
|
715
|
-
*
|
|
716
|
-
*
|
|
717
|
-
*
|
|
896
|
+
* - Uses `typeof value === "bigint"` for strict type checking.
|
|
897
|
+
* - Supports TypeScript type narrowing with `value is bigint`.
|
|
898
|
+
* - Returns `false` for `BigInt` object (object-wrapped), e.g:
|
|
899
|
+
* - `Object(BigInt(123))`.
|
|
900
|
+
*
|
|
901
|
+
* ---
|
|
718
902
|
* @param {*} value - The value to check.
|
|
903
|
+
*
|
|
904
|
+
* ---
|
|
719
905
|
* @returns {boolean} Return `true` if value is a primitive bigint.
|
|
906
|
+
*
|
|
907
|
+
* ---
|
|
720
908
|
* @example
|
|
721
909
|
* isBigInt(123n);
|
|
722
910
|
* // ➔ true
|
|
@@ -730,36 +918,57 @@ declare function isArrayLikeObject(value: unknown): value is object & {
|
|
|
730
918
|
declare const isBigInt: (value: unknown) => value is bigint;
|
|
731
919
|
/** ----------------------------------------------------------
|
|
732
920
|
* * ***Type guard: `isBoolean`.***
|
|
733
|
-
*
|
|
921
|
+
* -----------------------------------------------------------
|
|
734
922
|
* **Checks if a value is of type **[`boolean`](https://developer.mozilla.org/en-US/docs/Glossary/Boolean/JavaScript)**.**
|
|
923
|
+
*
|
|
924
|
+
* ---
|
|
735
925
|
* @param {*} value - The value to check.
|
|
926
|
+
*
|
|
927
|
+
* ---
|
|
736
928
|
* @returns {boolean} Returns `true` if the value is a `boolean`, otherwise `false`.
|
|
929
|
+
*
|
|
930
|
+
* ---
|
|
737
931
|
* @example
|
|
738
|
-
* isBoolean(true);
|
|
739
|
-
*
|
|
740
|
-
* isBoolean(
|
|
932
|
+
* isBoolean(true);
|
|
933
|
+
* // ➔ true
|
|
934
|
+
* isBoolean(false);
|
|
935
|
+
* // ➔ true
|
|
936
|
+
* isBoolean("true");
|
|
937
|
+
* // ➔ false
|
|
741
938
|
*/
|
|
742
939
|
declare const isBoolean: (value: unknown) => value is boolean;
|
|
743
940
|
/** ----------------------------------------------------
|
|
744
941
|
* * ***Type guard: `isBooleanObject`.***
|
|
745
|
-
*
|
|
942
|
+
* -----------------------------------------------------
|
|
746
943
|
* **Checks if a value is a **`Boolean` object wrapper**
|
|
747
944
|
* (`new Boolean(...)`), not a primitive boolean.**
|
|
945
|
+
*
|
|
946
|
+
* ---
|
|
748
947
|
* @param {*} value The value to check.
|
|
948
|
+
*
|
|
949
|
+
* ---
|
|
749
950
|
* @returns {value is Boolean} Returns `true` if `value` is a `Boolean` object.
|
|
951
|
+
*
|
|
952
|
+
* ---
|
|
750
953
|
* @example
|
|
751
954
|
* isBooleanObject(new Boolean(true));
|
|
752
955
|
* // ➔ true
|
|
753
956
|
* isBooleanObject(true);
|
|
754
957
|
* // ➔ false
|
|
755
958
|
*/
|
|
756
|
-
declare
|
|
757
|
-
/**
|
|
959
|
+
declare const isBooleanObject: (value: unknown) => value is Boolean;
|
|
960
|
+
/** ---------------------------------------------------------
|
|
758
961
|
* * ***Type guard: `isBuffer`.***
|
|
759
962
|
* ----------------------------------------------------------
|
|
760
963
|
* **Checks if a value is a *****{@link Buffer | `Node.js - Buffer`}***** instance.**
|
|
964
|
+
*
|
|
965
|
+
* ---
|
|
761
966
|
* @param {*} value The value to check.
|
|
967
|
+
*
|
|
968
|
+
* ---
|
|
762
969
|
* @returns {boolean} Returns `true` if `value` is a `Buffer`, else `false`.
|
|
970
|
+
*
|
|
971
|
+
* ---
|
|
763
972
|
* @example
|
|
764
973
|
* isBuffer(new Buffer(2));
|
|
765
974
|
* // ➔ true
|
|
@@ -777,23 +986,33 @@ declare function isBooleanObject(value: unknown): value is Boolean;
|
|
|
777
986
|
declare const isBuffer: (value: unknown) => value is Buffer;
|
|
778
987
|
/** -----------------------------------------------------------
|
|
779
988
|
* * ***Predicate: `isCurrencyLike`.***
|
|
780
|
-
*
|
|
989
|
+
* ------------------------------------------------------------
|
|
781
990
|
* **Determines if the given `input` can be interpreted as a currency-like number,
|
|
782
991
|
* using the same **multi-locale parsing logic** as ***`parseCurrencyString`***.**
|
|
992
|
+
*
|
|
993
|
+
* ---
|
|
783
994
|
* - **Highlights:**
|
|
784
|
-
*
|
|
785
|
-
*
|
|
786
|
-
*
|
|
787
|
-
*
|
|
788
|
-
*
|
|
789
|
-
*
|
|
790
|
-
*
|
|
791
|
-
*
|
|
792
|
-
*
|
|
793
|
-
*
|
|
794
|
-
*
|
|
995
|
+
* - *Supports strings or numbers like:*
|
|
996
|
+
* - `"15.000,10"` ***(European)***.
|
|
997
|
+
* - `"15,000.10"` ***(US)***.
|
|
998
|
+
* - `"15'000.10"` ***(Swiss)***.
|
|
999
|
+
* - `"15 000,10"` ***(French)***.
|
|
1000
|
+
* - `"Rp 15.000,10"` or `"$15,000.10"`.
|
|
1001
|
+
* - Also accepts simple numbers (`15300.95`).
|
|
1002
|
+
*
|
|
1003
|
+
* ---
|
|
1004
|
+
* - **Note:**
|
|
1005
|
+
* - Uses the same core logic as
|
|
1006
|
+
* ***`parseCurrencyString`*** but
|
|
1007
|
+
* just checks if a final parsed float is sensible.
|
|
1008
|
+
*
|
|
1009
|
+
* ---
|
|
795
1010
|
* @param {*} input - The input value to check.
|
|
1011
|
+
*
|
|
1012
|
+
* ---
|
|
796
1013
|
* @returns {boolean} Return `true` if it can be reasonably parsed into a currency-like number, `false` otherwise.
|
|
1014
|
+
*
|
|
1015
|
+
* ---
|
|
797
1016
|
* @example
|
|
798
1017
|
* isCurrencyLike(15300.95);
|
|
799
1018
|
* // ➔ true
|
|
@@ -810,33 +1029,45 @@ declare const isBuffer: (value: unknown) => value is Buffer;
|
|
|
810
1029
|
*/
|
|
811
1030
|
declare const isCurrencyLike: (input: unknown) => boolean;
|
|
812
1031
|
type isDateOptions = {
|
|
813
|
-
/**
|
|
1032
|
+
/** ----------------------------------------------------------
|
|
1033
|
+
* * ***Skip the validity check (`!isNaN(date.getTime())`).***
|
|
1034
|
+
* -----------------------------------------------------------
|
|
814
1035
|
*
|
|
815
1036
|
* When `true`, the function only checks that the value is an
|
|
816
1037
|
* instance of `Date` without verifying that it represents a valid
|
|
817
1038
|
* date value, default: `false`.
|
|
818
1039
|
*
|
|
1040
|
+
* ---
|
|
819
1041
|
* @default false
|
|
820
1042
|
*/
|
|
821
1043
|
skipInvalidDate?: boolean;
|
|
822
1044
|
};
|
|
823
1045
|
/** ----------------------------------------------------------
|
|
824
1046
|
* * ***Type guard: `isDate`.***
|
|
825
|
-
*
|
|
1047
|
+
* -----------------------------------------------------------
|
|
826
1048
|
* **Determines whether the given `value` is a real, valid JavaScript
|
|
827
1049
|
* **[`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)** object.**
|
|
828
|
-
*
|
|
829
|
-
*
|
|
830
|
-
*
|
|
831
|
-
*
|
|
832
|
-
*
|
|
833
|
-
*
|
|
834
|
-
*
|
|
835
|
-
*
|
|
836
|
-
*
|
|
1050
|
+
*
|
|
1051
|
+
* ---
|
|
1052
|
+
* - #### *Behavior:*
|
|
1053
|
+
* - #### Returns **true** only if:
|
|
1054
|
+
* - `value` is an instance of `Date`.
|
|
1055
|
+
* - and, unless `options.skipInvalidDate` is `true`,
|
|
1056
|
+
* the underlying time value is valid (`!isNaN(value.getTime())`).
|
|
1057
|
+
* ---
|
|
1058
|
+
* - #### Returns **false** for:
|
|
1059
|
+
* - non-Date values (strings, numbers, etc.).
|
|
1060
|
+
* - `Date` instances that represent an invalid time value
|
|
1061
|
+
* (e.g. `new Date("bad")`), unless skipping is enabled.
|
|
1062
|
+
*
|
|
1063
|
+
* ---
|
|
837
1064
|
* @param {*} value - The value to check.
|
|
838
1065
|
* @param {isDateOptions} [options] - Optional settings.
|
|
1066
|
+
*
|
|
1067
|
+
* ---
|
|
839
1068
|
* @returns {boolean} Return `true` if value is a valid Date object.
|
|
1069
|
+
*
|
|
1070
|
+
* ---
|
|
840
1071
|
* @example
|
|
841
1072
|
* isDate(new Date());
|
|
842
1073
|
* // ➜ true
|
|
@@ -852,69 +1083,101 @@ type isDateOptions = {
|
|
|
852
1083
|
declare const isDate: (value: unknown, options?: isDateOptions) => value is Date;
|
|
853
1084
|
/** ----------------------------------------------------------
|
|
854
1085
|
* * ***Predicate: `isDeepEqual`.***
|
|
855
|
-
*
|
|
1086
|
+
* -----------------------------------------------------------
|
|
856
1087
|
* **Performs a deep equality check between two values.**
|
|
1088
|
+
*
|
|
1089
|
+
* ---
|
|
857
1090
|
* - **Behavior:**
|
|
858
|
-
*
|
|
859
|
-
*
|
|
860
|
-
*
|
|
861
|
-
*
|
|
862
|
-
*
|
|
863
|
-
*
|
|
864
|
-
*
|
|
865
|
-
*
|
|
866
|
-
*
|
|
867
|
-
*
|
|
868
|
-
*
|
|
1091
|
+
* - Compares nested `arrays`, `objects`, `Dates`, `RegExp`, `NaN`, `Symbols`,
|
|
1092
|
+
* `Set`, and `Map`.
|
|
1093
|
+
* - Handles special cases:
|
|
1094
|
+
* - `NaN` is considered equal to `NaN`.
|
|
1095
|
+
* - `Date` objects are equal if `.getTime()` is equal.
|
|
1096
|
+
* - `RegExp` objects are equal if `.toString()` is equal.
|
|
1097
|
+
* - `Symbol("x")` and `Symbol("x")` are treated equal if
|
|
1098
|
+
* `.toString()` matches.
|
|
1099
|
+
* - `Set` and `Map` are deeply compared by content (order-insensitive).
|
|
1100
|
+
*
|
|
1101
|
+
* ---
|
|
1102
|
+
* - **Note:**
|
|
1103
|
+
* - Does not support circular references.
|
|
1104
|
+
*
|
|
1105
|
+
* ---
|
|
869
1106
|
* @param {*} a - First value to compare.
|
|
870
1107
|
* @param {*} b - Second value to compare.
|
|
871
|
-
* @returns {boolean} `true` if both values are deeply equal, otherwise `false`.
|
|
872
|
-
* @example
|
|
873
|
-
* // ✅ Primitives
|
|
874
|
-
* isDeepEqual(1, 1);
|
|
875
|
-
* // ➔ true
|
|
876
|
-
* isDeepEqual(NaN, NaN);
|
|
877
|
-
* // ➔ true
|
|
878
|
-
* isDeepEqual("hello", "world");
|
|
879
|
-
* // ➔ false
|
|
880
|
-
*
|
|
881
|
-
* // ✅ Objects
|
|
882
|
-
* isDeepEqual({ x: 1 }, { x: 1 });
|
|
883
|
-
* // ➔ true
|
|
884
|
-
* isDeepEqual({ x: 1 }, { y: 1 });
|
|
885
|
-
* // ➔ false
|
|
886
|
-
*
|
|
887
|
-
* // ✅ Arrays
|
|
888
|
-
* isDeepEqual([1, 2], [1, 2]);
|
|
889
|
-
* // ➔ true
|
|
890
|
-
* isDeepEqual([1, 2], [2, 1]);
|
|
891
|
-
* // ➔ false
|
|
892
1108
|
*
|
|
893
|
-
*
|
|
894
|
-
*
|
|
895
|
-
* // ➔ true
|
|
896
|
-
*
|
|
897
|
-
* // ✅ Sets
|
|
898
|
-
* isDeepEqual(new Set([1, 2]), new Set([2, 1]));
|
|
899
|
-
* // ➔ true
|
|
900
|
-
*
|
|
901
|
-
* // ✅ Maps
|
|
902
|
-
* isDeepEqual(new Map([["a", 1]]), new Map([["a", 1]]));
|
|
903
|
-
* // ➔ true
|
|
1109
|
+
* ---
|
|
1110
|
+
* @returns {boolean} `true` if both values are deeply equal, otherwise `false`.
|
|
904
1111
|
*
|
|
905
|
-
*
|
|
906
|
-
*
|
|
907
|
-
*
|
|
1112
|
+
* ---
|
|
1113
|
+
* @example
|
|
1114
|
+
* 1. #### Primitives:
|
|
1115
|
+
* ```ts
|
|
1116
|
+
* isDeepEqual(1, 1);
|
|
1117
|
+
* // ➔ true
|
|
1118
|
+
* isDeepEqual(NaN, NaN);
|
|
1119
|
+
* // ➔ true
|
|
1120
|
+
* isDeepEqual("hello", "world");
|
|
1121
|
+
* // ➔ false
|
|
1122
|
+
* ```
|
|
1123
|
+
* ---
|
|
1124
|
+
* 2. #### Objects:
|
|
1125
|
+
* ```ts
|
|
1126
|
+
* isDeepEqual({ x: 1 }, { x: 1 });
|
|
1127
|
+
* // ➔ true
|
|
1128
|
+
* isDeepEqual({ x: 1 }, { y: 1 });
|
|
1129
|
+
* // ➔ false
|
|
1130
|
+
* ```
|
|
1131
|
+
* ---
|
|
1132
|
+
* 3. #### Arrays:
|
|
1133
|
+
* ```ts
|
|
1134
|
+
* isDeepEqual([1, 2], [1, 2]);
|
|
1135
|
+
* // ➔ true
|
|
1136
|
+
* isDeepEqual([1, 2], [2, 1]);
|
|
1137
|
+
* // ➔ false
|
|
1138
|
+
* ```
|
|
1139
|
+
* ---
|
|
1140
|
+
* 4. #### Dates:
|
|
1141
|
+
* ```ts
|
|
1142
|
+
* isDeepEqual(new Date(123), new Date(123));
|
|
1143
|
+
* // ➔ true
|
|
1144
|
+
* ```
|
|
1145
|
+
* ---
|
|
1146
|
+
* 5. #### Sets:
|
|
1147
|
+
* ```ts
|
|
1148
|
+
* isDeepEqual(new Set([1, 2]), new Set([2, 1]));
|
|
1149
|
+
* // ➔ true
|
|
1150
|
+
* ```
|
|
1151
|
+
* ---
|
|
1152
|
+
* 6. #### Maps:
|
|
1153
|
+
* ```ts
|
|
1154
|
+
* isDeepEqual(new Map([["a", 1]]), new Map([["a", 1]]));
|
|
1155
|
+
* // ➔ true
|
|
1156
|
+
* ```
|
|
1157
|
+
* ---
|
|
1158
|
+
* 7. #### Different types:
|
|
1159
|
+
* ```ts
|
|
1160
|
+
* isDeepEqual(1, "1");
|
|
1161
|
+
* // ➔ false
|
|
1162
|
+
* ```
|
|
908
1163
|
*/
|
|
909
1164
|
declare const isDeepEqual: (a: unknown, b: unknown) => boolean;
|
|
910
|
-
/**
|
|
1165
|
+
/** ---------------------------------------------------------
|
|
911
1166
|
* * ***Type guard: `isElement`.***
|
|
912
1167
|
* ----------------------------------------------------------
|
|
913
1168
|
* **Checks if `value` is likely a
|
|
914
1169
|
* **[`DOM Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element)**.**
|
|
1170
|
+
*
|
|
1171
|
+
* ---
|
|
915
1172
|
* @template T - The type of the value being checked.
|
|
1173
|
+
*
|
|
1174
|
+
* ---
|
|
916
1175
|
* @param {*} value The value to check.
|
|
1176
|
+
*
|
|
1177
|
+
* ---
|
|
917
1178
|
* @returns {boolean} Returns `true` if `value` is extends instance of **[`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element)**, else `false`.
|
|
1179
|
+
*
|
|
1180
|
+
* ---
|
|
918
1181
|
* @example
|
|
919
1182
|
* isElement(document.body);
|
|
920
1183
|
* // ➔ true
|
|
@@ -936,7 +1199,11 @@ declare function isElement(value: unknown): value is Element;
|
|
|
936
1199
|
* -------------------------------------------------------------------
|
|
937
1200
|
* **Represents objects with indexed elements and a `length` property,
|
|
938
1201
|
* similar to arrays, but not necessarily full Array instances.**
|
|
1202
|
+
*
|
|
1203
|
+
* ---
|
|
939
1204
|
* @template T The type of elements stored in the array-like object.
|
|
1205
|
+
*
|
|
1206
|
+
* ---
|
|
940
1207
|
* @example
|
|
941
1208
|
* ```ts
|
|
942
1209
|
* function logArrayLike<T>(items: ArrayLike<T>) {
|
|
@@ -950,16 +1217,24 @@ declare function isElement(value: unknown): value is Element;
|
|
|
950
1217
|
* ```
|
|
951
1218
|
*/
|
|
952
1219
|
interface ArrayLike<T> {
|
|
953
|
-
/**
|
|
1220
|
+
/**
|
|
1221
|
+
* * ***Number of elements in the array-like object.***
|
|
1222
|
+
*/
|
|
954
1223
|
readonly length: number;
|
|
955
|
-
/**
|
|
1224
|
+
/**
|
|
1225
|
+
* * ***Indexed access to elements.***
|
|
1226
|
+
*/
|
|
956
1227
|
readonly [n: number]: T;
|
|
957
1228
|
}
|
|
958
1229
|
/** -------------------------------------------------------------------
|
|
959
1230
|
* * ***Represents an object with no allowed properties.***
|
|
960
1231
|
* -------------------------------------------------------------------
|
|
961
1232
|
* **Useful for cases where you want to ensure a type has **no keys**.**
|
|
1233
|
+
*
|
|
1234
|
+
* ---
|
|
962
1235
|
* @template T - The base type to convert into an empty object type.
|
|
1236
|
+
*
|
|
1237
|
+
* ---
|
|
963
1238
|
* @example
|
|
964
1239
|
* ```ts
|
|
965
1240
|
* type Test = EmptyObject<{ a: number }>;
|
|
@@ -971,7 +1246,11 @@ type EmptyObject<T> = { [K in keyof T]?: never };
|
|
|
971
1246
|
* * ***Conditional empty object type.***
|
|
972
1247
|
* -------------------------------------------------------------------
|
|
973
1248
|
* **Produces `EmptyObject<T>` only if it is assignable to `T`.**
|
|
1249
|
+
*
|
|
1250
|
+
* ---
|
|
974
1251
|
* @template T - The base type to check.
|
|
1252
|
+
*
|
|
1253
|
+
* ---
|
|
975
1254
|
* @example
|
|
976
1255
|
* ```ts
|
|
977
1256
|
* type Test = EmptyObjectOf<{ a: number }>;
|
|
@@ -983,7 +1262,11 @@ type EmptyObjectOf<T> = EmptyObject<T> extends T ? EmptyObject<T> : never;
|
|
|
983
1262
|
* * ***List type alias.***
|
|
984
1263
|
* -------------------------------------------------------------------
|
|
985
1264
|
* **Represents any array-like structure.**
|
|
1265
|
+
*
|
|
1266
|
+
* ---
|
|
986
1267
|
* @template T - The type of elements in the list.
|
|
1268
|
+
*
|
|
1269
|
+
* ---
|
|
987
1270
|
* @example
|
|
988
1271
|
* ```ts
|
|
989
1272
|
* const arr: List<number> = [1, 2, 3];
|
|
@@ -991,24 +1274,36 @@ type EmptyObjectOf<T> = EmptyObject<T> extends T ? EmptyObject<T> : never;
|
|
|
991
1274
|
* ```
|
|
992
1275
|
*/
|
|
993
1276
|
type List<T> = ArrayLike<T>;
|
|
994
|
-
/**
|
|
1277
|
+
/** ---------------------------------------------------------
|
|
995
1278
|
* * ***Predicate: `isEmpty`.***
|
|
996
1279
|
* ----------------------------------------------------------
|
|
997
1280
|
* **Checks if `value` is an empty object, collection, map, or set.**
|
|
1281
|
+
*
|
|
1282
|
+
* ---
|
|
998
1283
|
* - **Behavior:**
|
|
999
|
-
*
|
|
1000
|
-
*
|
|
1001
|
-
*
|
|
1002
|
-
*
|
|
1003
|
-
*
|
|
1004
|
-
*
|
|
1005
|
-
*
|
|
1006
|
-
*
|
|
1007
|
-
*
|
|
1008
|
-
*
|
|
1284
|
+
* - **Objects** are empty if they have no own enumerable string keyed properties.
|
|
1285
|
+
* - **Array-like values** (arrays, strings, `arguments`, typed arrays, buffers)
|
|
1286
|
+
* are empty if their `length` is `0`.
|
|
1287
|
+
* - **Maps** and **Sets** are empty if their `size` is `0`.
|
|
1288
|
+
* - **Booleans**, **numbers** (including `NaN`), **symbols**, and `null`/
|
|
1289
|
+
* `undefined` are treated as empty.
|
|
1290
|
+
* - **Functions** are considered empty if they have no own enumerable keys.
|
|
1291
|
+
*
|
|
1292
|
+
* ---
|
|
1293
|
+
* - **Note:**
|
|
1294
|
+
* - For more `Strict`, you can use
|
|
1295
|
+
* ***`isEmptyValue` utility function*** instead.
|
|
1296
|
+
*
|
|
1297
|
+
* ---
|
|
1009
1298
|
* @template T - The type of the value being checked.
|
|
1299
|
+
*
|
|
1300
|
+
* ---
|
|
1010
1301
|
* @param {*} value The value to check.
|
|
1302
|
+
*
|
|
1303
|
+
* ---
|
|
1011
1304
|
* @returns {boolean} Returns `true` if `value` is empty, else `false`.
|
|
1305
|
+
*
|
|
1306
|
+
* ----
|
|
1012
1307
|
* @example
|
|
1013
1308
|
* isEmpty(null);
|
|
1014
1309
|
* // ➔ true
|
|
@@ -1043,18 +1338,31 @@ declare function isEmpty<T extends object>(value: T | null | undefined): value i
|
|
|
1043
1338
|
declare function isEmpty(value: any): boolean;
|
|
1044
1339
|
/** ----------------------------------------------------------
|
|
1045
1340
|
* * ***Predicate: `isEmptyArray`.***
|
|
1046
|
-
*
|
|
1341
|
+
* -----------------------------------------------------------
|
|
1047
1342
|
* **Checks whether a given value is an empty array.**
|
|
1343
|
+
*
|
|
1344
|
+
* ---
|
|
1048
1345
|
* - **Behavior:**
|
|
1049
|
-
*
|
|
1346
|
+
* - Non-array inputs are considered ***`empty`*** ***(defensive strategy)***.
|
|
1347
|
+
*
|
|
1348
|
+
* ---
|
|
1050
1349
|
* @param {*} [value] - The value to check.
|
|
1350
|
+
*
|
|
1351
|
+
* ---
|
|
1051
1352
|
* @returns {boolean} Returns `true` if it's ***not an array*** or ***an empty-array***.
|
|
1353
|
+
*
|
|
1354
|
+
* ---
|
|
1052
1355
|
* @example
|
|
1053
|
-
* isEmptyArray([]);
|
|
1054
|
-
*
|
|
1055
|
-
* isEmptyArray(
|
|
1056
|
-
*
|
|
1057
|
-
* isEmptyArray(
|
|
1356
|
+
* isEmptyArray([]);
|
|
1357
|
+
* // ➔ true
|
|
1358
|
+
* isEmptyArray([1, 2, 3]);
|
|
1359
|
+
* // ➔ false
|
|
1360
|
+
* isEmptyArray("not an array");
|
|
1361
|
+
* // ➔ true
|
|
1362
|
+
* isEmptyArray(null);
|
|
1363
|
+
* // ➔ true
|
|
1364
|
+
* isEmptyArray(undefined);
|
|
1365
|
+
* // ➔ true
|
|
1058
1366
|
*
|
|
1059
1367
|
* if (isEmptyArray(data.items)) {
|
|
1060
1368
|
* console.log("No items to display.");
|
|
@@ -1063,19 +1371,29 @@ declare function isEmpty(value: any): boolean;
|
|
|
1063
1371
|
declare const isEmptyArray: (value: unknown) => boolean;
|
|
1064
1372
|
/** ----------------------------------------------------------
|
|
1065
1373
|
* * ***Predicate: `isEmptyDeep`.***
|
|
1066
|
-
*
|
|
1374
|
+
* -----------------------------------------------------------
|
|
1067
1375
|
* **Recursively checks whether a value is **deeply empty**.**
|
|
1068
|
-
*
|
|
1069
|
-
*
|
|
1070
|
-
*
|
|
1071
|
-
*
|
|
1072
|
-
*
|
|
1073
|
-
*
|
|
1074
|
-
*
|
|
1075
|
-
*
|
|
1076
|
-
*
|
|
1376
|
+
*
|
|
1377
|
+
* ---
|
|
1378
|
+
* - #### *Behavior:*
|
|
1379
|
+
* - #### Returns `true` for:
|
|
1380
|
+
* - Empty objects: `{}`.
|
|
1381
|
+
* - Empty arrays: `[]`.
|
|
1382
|
+
* - Nested empty structures: `{ a: [], b: {} }`.
|
|
1383
|
+
* - Falsy values (except numbers): `null`, `undefined`, `false`, `""`, `NaN`.
|
|
1384
|
+
* ---
|
|
1385
|
+
* - #### Returns `false` for:
|
|
1386
|
+
* - Non-zero numbers.
|
|
1387
|
+
* - Objects or arrays containing non-empty values.
|
|
1388
|
+
* - Non-empty strings, `true`, functions, symbols, etc.
|
|
1389
|
+
*
|
|
1390
|
+
* ---
|
|
1077
1391
|
* @param {*} value - The value to deeply check.
|
|
1392
|
+
*
|
|
1393
|
+
* ---
|
|
1078
1394
|
* @returns {boolean} `true` if the value is deeply empty, otherwise `false`.
|
|
1395
|
+
*
|
|
1396
|
+
* ---
|
|
1079
1397
|
* @example
|
|
1080
1398
|
* isEmptyDeep({});
|
|
1081
1399
|
* // ➔ true
|
|
@@ -1100,7 +1418,9 @@ declare const isEmptyArray: (value: unknown) => boolean;
|
|
|
1100
1418
|
*/
|
|
1101
1419
|
declare const isEmptyDeep: (value: unknown) => boolean;
|
|
1102
1420
|
type IsEmptyObjectOptions = {
|
|
1103
|
-
/**
|
|
1421
|
+
/** ----------------------------------------------------------
|
|
1422
|
+
* * ***Whether to check for symbol properties in addition to string keys, defaultValue: `false`.***
|
|
1423
|
+
* -----------------------------------------------------------
|
|
1104
1424
|
*
|
|
1105
1425
|
* @default false
|
|
1106
1426
|
*/
|
|
@@ -1108,16 +1428,24 @@ type IsEmptyObjectOptions = {
|
|
|
1108
1428
|
};
|
|
1109
1429
|
/** ----------------------------------------------------------
|
|
1110
1430
|
* * ***Predicate: `isEmptyObject`.***
|
|
1111
|
-
*
|
|
1431
|
+
* -----------------------------------------------------------
|
|
1112
1432
|
* **Checks if a value is a plain object with **no own enumerable string-key properties**,
|
|
1113
1433
|
* and optionally **no own enumerable symbol-key properties** when `checkSymbols` is `true`.**
|
|
1434
|
+
*
|
|
1435
|
+
* ---
|
|
1114
1436
|
* - **Behavior:**
|
|
1115
|
-
*
|
|
1116
|
-
*
|
|
1437
|
+
* - If the value is **not an object** (e.g. `null`, array, primitive), it is considered empty.
|
|
1438
|
+
* - If `options.checkSymbols` is `true`, **symbol properties** are also checked.
|
|
1439
|
+
*
|
|
1440
|
+
* ---
|
|
1117
1441
|
* @param {*} value - The value to check.
|
|
1118
1442
|
* @param {IsEmptyObjectOptions} [options] - Optional settings.
|
|
1119
1443
|
* @param {IsEmptyObjectOptions["checkSymbols"]} [options.checkSymbols=false] - Whether to also check symbol properties.
|
|
1444
|
+
*
|
|
1445
|
+
* ---
|
|
1120
1446
|
* @returns {boolean} Return `true` if the value is considered empty or not an object, false otherwise.
|
|
1447
|
+
*
|
|
1448
|
+
* ---
|
|
1121
1449
|
* @example
|
|
1122
1450
|
* isEmptyObject({});
|
|
1123
1451
|
* // ➔ true
|
|
@@ -1136,25 +1464,42 @@ type IsEmptyObjectOptions = {
|
|
|
1136
1464
|
* isEmptyObject(123);
|
|
1137
1465
|
* // ➔ true (not object)
|
|
1138
1466
|
*/
|
|
1139
|
-
declare
|
|
1467
|
+
declare const isEmptyObject: (value: unknown, options?: IsEmptyObjectOptions) => boolean;
|
|
1140
1468
|
type IsEmptyStringOptions = {
|
|
1141
|
-
/**
|
|
1469
|
+
/** ----------------------------------------------------------
|
|
1470
|
+
* * ***Whether to trim leading and trailing whitespace before checking.***
|
|
1471
|
+
* -----------------------------------------------------------
|
|
1472
|
+
*
|
|
1473
|
+
* @note
|
|
1474
|
+
* Non-boolean values fall back to the default behavior.
|
|
1142
1475
|
*
|
|
1143
|
-
*
|
|
1476
|
+
* ---
|
|
1477
|
+
* @default true
|
|
1478
|
+
*/
|
|
1144
1479
|
trim?: boolean;
|
|
1145
1480
|
};
|
|
1146
1481
|
/** ----------------------------------------------------------
|
|
1147
1482
|
* * ***Predicate: `isEmptyString`.***
|
|
1148
|
-
*
|
|
1483
|
+
* -----------------------------------------------------------
|
|
1149
1484
|
* **Checks whether a given value is an **empty-string**.**
|
|
1485
|
+
*
|
|
1486
|
+
* ---
|
|
1150
1487
|
* - **Behavior:**
|
|
1151
|
-
*
|
|
1152
|
-
*
|
|
1153
|
-
*
|
|
1488
|
+
* - Considers `""` and whitespace-only strings as
|
|
1489
|
+
* empty (if `trim` is enabled, which is the default).
|
|
1490
|
+
* - Non-string inputs are also considered empty.
|
|
1491
|
+
*
|
|
1492
|
+
* ---
|
|
1154
1493
|
* @param {*} value - The value to check.
|
|
1155
|
-
* @param {IsEmptyStringOptions} [options]
|
|
1156
|
-
*
|
|
1494
|
+
* @param {IsEmptyStringOptions} [options]
|
|
1495
|
+
* Optional settings (non-plain object values are ignored and replaced with default options).
|
|
1496
|
+
* @param {IsEmptyStringOptions["trim"]} [options.trim=true]
|
|
1497
|
+
* If `true`, trims the string before checking (non-boolean values fall back to the default behavior), defaults: `true`.
|
|
1498
|
+
*
|
|
1499
|
+
* ---
|
|
1157
1500
|
* @returns {boolean} Returns `true` if the value is string not a string or value string is considered empty.
|
|
1501
|
+
*
|
|
1502
|
+
* ---
|
|
1158
1503
|
* @example
|
|
1159
1504
|
* isEmptyString("");
|
|
1160
1505
|
* // ➔ true
|
|
@@ -1178,8 +1523,9 @@ type IsEmptyStringOptions = {
|
|
|
1178
1523
|
*/
|
|
1179
1524
|
declare const isEmptyString: (value: unknown, options?: IsEmptyStringOptions) => boolean;
|
|
1180
1525
|
type IsEmptyValueOptions = {
|
|
1181
|
-
/**
|
|
1182
|
-
*
|
|
1526
|
+
/** ----------------------------------------------------------
|
|
1527
|
+
* * ***Whether to check symbol properties when checking empty objects.***
|
|
1528
|
+
* ----------------------------------------------------------
|
|
1183
1529
|
*
|
|
1184
1530
|
* @default false
|
|
1185
1531
|
*/
|
|
@@ -1187,21 +1533,30 @@ type IsEmptyValueOptions = {
|
|
|
1187
1533
|
};
|
|
1188
1534
|
/** ----------------------------------------------------------
|
|
1189
1535
|
* * ***Predicate: `isEmptyValue`.***
|
|
1190
|
-
*
|
|
1536
|
+
* -----------------------------------------------------------
|
|
1191
1537
|
* **Determines if a value is **`empty`**.**
|
|
1192
|
-
*
|
|
1193
|
-
*
|
|
1194
|
-
*
|
|
1195
|
-
*
|
|
1196
|
-
*
|
|
1197
|
-
*
|
|
1198
|
-
*
|
|
1199
|
-
*
|
|
1200
|
-
*
|
|
1201
|
-
*
|
|
1538
|
+
*
|
|
1539
|
+
* ---
|
|
1540
|
+
* - #### *Behavior:*
|
|
1541
|
+
* - #### Covering:
|
|
1542
|
+
* - Empty objects: `{}`.
|
|
1543
|
+
* - Empty arrays: `[]`.
|
|
1544
|
+
* - Empty strings: `""` or whitespace-only (trimmed).
|
|
1545
|
+
* - `null`, `undefined`, `false`, or `NaN`.
|
|
1546
|
+
* ---
|
|
1547
|
+
* - #### Returns **`false`** for:
|
|
1548
|
+
* - Non-empty objects/arrays.
|
|
1549
|
+
* - Non-empty strings.
|
|
1550
|
+
* - Numbers (except `NaN`).
|
|
1551
|
+
* - `Functions`, `true`, `symbols`, `etc`.
|
|
1552
|
+
*
|
|
1553
|
+
* ---
|
|
1202
1554
|
* @param {*} value - The value to evaluate.
|
|
1203
1555
|
* @param {IsEmptyValueOptions} [options] - Optional settings.
|
|
1556
|
+
*
|
|
1557
|
+
* ---
|
|
1204
1558
|
* @returns {boolean} Return `true` if the value is considered empty, otherwise `false`.
|
|
1559
|
+
*
|
|
1205
1560
|
* @example
|
|
1206
1561
|
* isEmptyValue({});
|
|
1207
1562
|
* // ➔ true
|
|
@@ -1241,26 +1596,37 @@ type IsEmptyValueOptions = {
|
|
|
1241
1596
|
* // ➔ false
|
|
1242
1597
|
*/
|
|
1243
1598
|
declare const isEmptyValue: (value: unknown, options?: IsEmptyValueOptions) => boolean;
|
|
1244
|
-
/**
|
|
1599
|
+
/** ---------------------------------------------------------
|
|
1245
1600
|
* * ***Predicate: `isEqual`.***
|
|
1246
1601
|
* ----------------------------------------------------------
|
|
1247
1602
|
* **Performs a deep comparison between two values to determine if they are equivalent.**
|
|
1603
|
+
*
|
|
1604
|
+
* ---
|
|
1248
1605
|
* @description
|
|
1249
1606
|
* Checks whether two values are **deeply equal**, not just reference-equal (`===`).
|
|
1250
|
-
*
|
|
1251
|
-
*
|
|
1252
|
-
*
|
|
1253
|
-
*
|
|
1254
|
-
*
|
|
1255
|
-
*
|
|
1256
|
-
*
|
|
1257
|
-
*
|
|
1258
|
-
*
|
|
1259
|
-
*
|
|
1260
|
-
*
|
|
1607
|
+
*
|
|
1608
|
+
* ---
|
|
1609
|
+
* - #### *Behavior:*
|
|
1610
|
+
* - **This method compares:**
|
|
1611
|
+
* - Arrays and TypedArrays.
|
|
1612
|
+
* - ArrayBuffers.
|
|
1613
|
+
* - Plain objects (`Object`) ➔ own enumerable properties only.
|
|
1614
|
+
* - Booleans, Numbers, Strings, Symbols.
|
|
1615
|
+
* - Dates.
|
|
1616
|
+
* - Errors.
|
|
1617
|
+
* - Maps.
|
|
1618
|
+
* - Sets.
|
|
1619
|
+
* - Regular expressions.
|
|
1620
|
+
* - `Functions` and `DOM nodes` are ***not supported***.
|
|
1621
|
+
*
|
|
1622
|
+
* ---
|
|
1261
1623
|
* @param {*} value The value to compare.
|
|
1262
1624
|
* @param {*} other The other value to compare.
|
|
1625
|
+
*
|
|
1626
|
+
* ---
|
|
1263
1627
|
* @returns {boolean} Returns `true` if the values are equivalent, else `false`.
|
|
1628
|
+
*
|
|
1629
|
+
* ---
|
|
1264
1630
|
* @example
|
|
1265
1631
|
* const obj1 = { user: "fred" };
|
|
1266
1632
|
* const obj2 = { user: "fred" };
|
|
@@ -1280,11 +1646,13 @@ declare const isEmptyValue: (value: unknown, options?: IsEmptyValueOptions) => b
|
|
|
1280
1646
|
* isEqual({ a: 1 }, { a: 1, b: undefined });
|
|
1281
1647
|
* // ➔ false
|
|
1282
1648
|
*/
|
|
1283
|
-
declare
|
|
1649
|
+
declare const isEqual: (value: unknown, other: unknown) => boolean;
|
|
1284
1650
|
/** -------------------------------------------------------------------
|
|
1285
1651
|
* * ***Customizer function for `isEqualWith`.***
|
|
1286
1652
|
* -------------------------------------------------------------------
|
|
1287
1653
|
* **Allows customizing how two values are compared for deep equality.**
|
|
1654
|
+
*
|
|
1655
|
+
* ---
|
|
1288
1656
|
* @param value
|
|
1289
1657
|
* - The current value being compared.
|
|
1290
1658
|
* @param other
|
|
@@ -1297,10 +1665,14 @@ declare function isEqual(value: unknown, other: unknown): boolean;
|
|
|
1297
1665
|
* - The parent object or array containing `other`.
|
|
1298
1666
|
* @param stack
|
|
1299
1667
|
* - WeakMap or tracking structure for already visited objects to handle circular references.
|
|
1668
|
+
*
|
|
1669
|
+
* ---
|
|
1300
1670
|
* @returns
|
|
1301
|
-
* - `true`
|
|
1302
|
-
* - `false`
|
|
1303
|
-
* - `undefined`
|
|
1671
|
+
* - `true` ➔ Treat the values as equal.
|
|
1672
|
+
* - `false` ➔ Treat the values as unequal.
|
|
1673
|
+
* - `undefined` ➔ Fallback to default deep equality comparison.
|
|
1674
|
+
*
|
|
1675
|
+
* ---
|
|
1304
1676
|
* @example
|
|
1305
1677
|
* ```ts
|
|
1306
1678
|
* const customizer: CustomizerIsEqualWith = (value, other, key) => {
|
|
@@ -1311,18 +1683,22 @@ declare function isEqual(value: unknown, other: unknown): boolean;
|
|
|
1311
1683
|
* };
|
|
1312
1684
|
*
|
|
1313
1685
|
* baseDeepEqual({ name: "Alice" }, { name: "alice" }, customizer);
|
|
1314
|
-
* //
|
|
1686
|
+
* // ➔ true
|
|
1315
1687
|
* ```
|
|
1316
1688
|
*/
|
|
1317
1689
|
type CustomizerIsEqualWith = (value: unknown, other: unknown, indexOrKey: PropertyKey, parent: unknown, otherParent: unknown, stack: unknown) => boolean | undefined;
|
|
1318
1690
|
/** ----------------------------------------------------
|
|
1319
1691
|
* * ***Predicate: `isEqualWith`.***
|
|
1320
|
-
*
|
|
1692
|
+
* -----------------------------------------------------
|
|
1321
1693
|
* **Performs a deep comparison between two values with support for a
|
|
1322
1694
|
* customizer function.**
|
|
1695
|
+
*
|
|
1696
|
+
* ---
|
|
1323
1697
|
* @description
|
|
1324
1698
|
* This method is like ***`isEqual` utility function*** except that it
|
|
1325
1699
|
* accepts a `customizer` which is invoked to compare values.
|
|
1700
|
+
*
|
|
1701
|
+
* ---
|
|
1326
1702
|
* - **Behavior:**
|
|
1327
1703
|
* - If `customizer` returns `undefined`, the comparison is handled by
|
|
1328
1704
|
* the default deep equality algorithm.
|
|
@@ -1332,10 +1708,16 @@ type CustomizerIsEqualWith = (value: unknown, other: unknown, indexOrKey: Proper
|
|
|
1332
1708
|
* - Supports comparing `arrays`, `objects`, `maps`, `sets`, `dates`,
|
|
1333
1709
|
* `regexes`, `typed arrays`, `etc`.
|
|
1334
1710
|
* - Functions and DOM nodes are **not** supported.
|
|
1711
|
+
*
|
|
1712
|
+
* ---
|
|
1335
1713
|
* @param {*} value The value to compare.
|
|
1336
1714
|
* @param {*} other The other value to compare.
|
|
1337
1715
|
* @param {CustomizerIsEqualWith} [customizer] The function to customize comparisons.
|
|
1716
|
+
*
|
|
1717
|
+
* ---
|
|
1338
1718
|
* @returns {boolean} Returns `true` if the values are equivalent, else `false`.
|
|
1719
|
+
*
|
|
1720
|
+
* ---
|
|
1339
1721
|
* @example
|
|
1340
1722
|
* function isGreeting(value: unknown) {
|
|
1341
1723
|
* return typeof value === "string" && /^h(?:i|ello)$/.test(value);
|
|
@@ -1353,16 +1735,24 @@ type CustomizerIsEqualWith = (value: unknown, other: unknown, indexOrKey: Proper
|
|
|
1353
1735
|
* isEqualWith(array, other, customizer);
|
|
1354
1736
|
* // ➔ true
|
|
1355
1737
|
*/
|
|
1356
|
-
declare
|
|
1738
|
+
declare const isEqualWith: (value: unknown, other: unknown, customizer?: CustomizerIsEqualWith) => boolean;
|
|
1357
1739
|
/** ----------------------------------------------------------
|
|
1358
1740
|
* * ***Type guard: `isError`.***
|
|
1359
|
-
*
|
|
1741
|
+
* -----------------------------------------------------------
|
|
1360
1742
|
* **Checks whether the given value is an ****[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)** object**.**
|
|
1743
|
+
*
|
|
1744
|
+
* ---
|
|
1361
1745
|
* - **Behavior:**
|
|
1362
|
-
*
|
|
1363
|
-
*
|
|
1746
|
+
* - Ensures that the provided value is a valid JavaScript error instance.
|
|
1747
|
+
* - Useful in TypeScript for narrowing types during error handling.
|
|
1748
|
+
*
|
|
1749
|
+
* ---
|
|
1364
1750
|
* @param {*} error - The value to check.
|
|
1751
|
+
*
|
|
1752
|
+
* ---
|
|
1365
1753
|
* @returns {boolean} Returns `true` if `value` is instance of **[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)**, else `false`.
|
|
1754
|
+
*
|
|
1755
|
+
* ---
|
|
1366
1756
|
* @example
|
|
1367
1757
|
* isError(new Error("Something went wrong"));
|
|
1368
1758
|
* // ➔ true
|
|
@@ -1376,49 +1766,72 @@ declare const isError: (error: unknown) => error is Error;
|
|
|
1376
1766
|
* * ***Type guard: `isFinite`.***
|
|
1377
1767
|
* -----------------------------------------------------------
|
|
1378
1768
|
* **Checks if a value is a finite primitive number.**
|
|
1769
|
+
*
|
|
1770
|
+
* ---
|
|
1379
1771
|
* @description
|
|
1380
1772
|
* This function verifies that `value` is a **primitive number** and is **finite**
|
|
1381
1773
|
* (i.e., not `NaN`, `Infinity`, or `-Infinity`).
|
|
1774
|
+
*
|
|
1775
|
+
* ---
|
|
1382
1776
|
* - **Behavior:**
|
|
1383
|
-
*
|
|
1384
|
-
*
|
|
1385
|
-
*
|
|
1777
|
+
* - Behaves like
|
|
1778
|
+
* [`Number.isFinite()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite).
|
|
1779
|
+
* - But also works as a **TypeScript type guard**.
|
|
1780
|
+
*
|
|
1781
|
+
* ---
|
|
1386
1782
|
* @param {*} value - The value to check.
|
|
1387
|
-
* @returns {boolean} Returns `true` if `value` is a finite primitive number, else `false`.
|
|
1388
|
-
* @example
|
|
1389
|
-
* import * as RzlUtilsJs from "@rzl-zone/utils-js/predicates";
|
|
1390
1783
|
*
|
|
1391
|
-
*
|
|
1392
|
-
*
|
|
1393
|
-
* // ➔ true
|
|
1394
|
-
* RzlUtilsJs.isFinite(Number.MIN_VALUE);
|
|
1395
|
-
* // ➔ true
|
|
1396
|
-
* RzlUtilsJs.isFinite("3");
|
|
1397
|
-
* // ➔ false (string is not a number)
|
|
1398
|
-
* RzlUtilsJs.isFinite(NaN);
|
|
1399
|
-
* // ➔ false
|
|
1400
|
-
* RzlUtilsJs.isFinite(Infinity);
|
|
1401
|
-
* // ➔ false
|
|
1402
|
-
* RzlUtilsJs.isFinite(new Number(3));
|
|
1403
|
-
* // ➔ false (Number object is not primitive)
|
|
1784
|
+
* ---
|
|
1785
|
+
* @returns {boolean} Returns `true` if `value` is a finite primitive number, else `false`.
|
|
1404
1786
|
*
|
|
1405
|
-
*
|
|
1406
|
-
*
|
|
1407
|
-
*
|
|
1408
|
-
*
|
|
1409
|
-
*
|
|
1410
|
-
|
|
1411
|
-
|
|
1787
|
+
* ---
|
|
1788
|
+
* @example
|
|
1789
|
+
* 1. #### Strict finite number check (only primitive numbers):
|
|
1790
|
+
* ```ts
|
|
1791
|
+
* import * as RzlUtilsJs from "@rzl-zone/utils-js/predicates";
|
|
1792
|
+
*
|
|
1793
|
+
* RzlUtilsJs.isFinite(3);
|
|
1794
|
+
* // ➔ true
|
|
1795
|
+
* RzlUtilsJs.isFinite(Number.MIN_VALUE);
|
|
1796
|
+
* // ➔ true
|
|
1797
|
+
* RzlUtilsJs.isFinite("3");
|
|
1798
|
+
* // ➔ false (string is not a number)
|
|
1799
|
+
* RzlUtilsJs.isFinite(NaN);
|
|
1800
|
+
* // ➔ false
|
|
1801
|
+
* RzlUtilsJs.isFinite(Infinity);
|
|
1802
|
+
* // ➔ false
|
|
1803
|
+
* RzlUtilsJs.isFinite(new Number(3));
|
|
1804
|
+
* // ➔ false (Number object is not primitive)
|
|
1805
|
+
* ```
|
|
1806
|
+
* ---
|
|
1807
|
+
*
|
|
1808
|
+
* 2. #### Comparison with `global isFinite()`:
|
|
1809
|
+
* ```ts
|
|
1810
|
+
* isFinite("3");
|
|
1811
|
+
* // ➔ true (global coerces string to number)
|
|
1812
|
+
* isFinite(new Number(3));
|
|
1813
|
+
* // ➔ true (object coerced to primitive number)
|
|
1814
|
+
* ```
|
|
1815
|
+
*/
|
|
1816
|
+
declare const isFinite: (value: unknown) => value is number;
|
|
1412
1817
|
/** ----------------------------------------------------------
|
|
1413
1818
|
* * ***Type guard: `isFunction`.***
|
|
1414
1819
|
* -----------------------------------------------------------
|
|
1415
1820
|
* **Checks if a value is a function.**
|
|
1821
|
+
*
|
|
1822
|
+
* ---
|
|
1416
1823
|
* - **Behavior:**
|
|
1417
|
-
*
|
|
1418
|
-
*
|
|
1419
|
-
*
|
|
1824
|
+
* - Uses `typeof value === "function"` for strict type checking.
|
|
1825
|
+
* - Safe alternative to `Function` type (doesn't trigger ESLint warning).
|
|
1826
|
+
* - Supports TypeScript type narrowing with `value is (...args: any[]) => any`.
|
|
1827
|
+
*
|
|
1828
|
+
* ---
|
|
1420
1829
|
* @param {*} value - The value to check.
|
|
1830
|
+
*
|
|
1831
|
+
* ---
|
|
1421
1832
|
* @returns {boolean} Return `true` if the value is a function.
|
|
1833
|
+
*
|
|
1834
|
+
* ---
|
|
1422
1835
|
* @example
|
|
1423
1836
|
* isFunction(() => {});
|
|
1424
1837
|
* // ➔ true
|
|
@@ -1432,15 +1845,23 @@ declare function isFinite(value: unknown): value is number;
|
|
|
1432
1845
|
declare const isFunction: (value: unknown) => value is AnyFunction;
|
|
1433
1846
|
/** ----------------------------------------------------
|
|
1434
1847
|
* * ***Type guard: `isInfinityNumber`.***
|
|
1435
|
-
*
|
|
1848
|
+
* -----------------------------------------------------
|
|
1436
1849
|
* **Checks if a value is positive or negative
|
|
1437
1850
|
* [`Infinity`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Infinity).**
|
|
1438
|
-
*
|
|
1439
|
-
*
|
|
1440
|
-
*
|
|
1441
|
-
*
|
|
1851
|
+
*
|
|
1852
|
+
* ---
|
|
1853
|
+
* - **Note:**
|
|
1854
|
+
* - This is stricter than the global `isFinite`,
|
|
1855
|
+
* because it only returns `true` for `Infinity` or `-Infinity`,
|
|
1856
|
+
* not other non-finite values.
|
|
1857
|
+
*
|
|
1858
|
+
* ---
|
|
1442
1859
|
* @param {*} value The value to check.
|
|
1860
|
+
*
|
|
1861
|
+
* ---
|
|
1443
1862
|
* @returns {boolean} Returns `true` if `value` is `Infinity` or `-Infinity`, else `false`.
|
|
1863
|
+
*
|
|
1864
|
+
* ---
|
|
1444
1865
|
* @example
|
|
1445
1866
|
* import * as RzlUtilsJs from "@rzl-zone/utils-js/predicates";
|
|
1446
1867
|
*
|
|
@@ -1455,16 +1876,24 @@ declare const isFunction: (value: unknown) => value is AnyFunction;
|
|
|
1455
1876
|
* RzlUtilsJs.isInfinityNumber(123);
|
|
1456
1877
|
* // ➔ false
|
|
1457
1878
|
*/
|
|
1458
|
-
declare
|
|
1879
|
+
declare const isInfinityNumber: (value: unknown) => boolean;
|
|
1459
1880
|
/** ---------------------------------------------------------
|
|
1460
1881
|
* * ***Type guard: `isInteger`.***
|
|
1461
1882
|
* ----------------------------------------------------------
|
|
1462
1883
|
* **Checks if a value is an integer number.**
|
|
1463
|
-
*
|
|
1464
|
-
*
|
|
1465
|
-
*
|
|
1884
|
+
*
|
|
1885
|
+
* ---
|
|
1886
|
+
* - **Note:**
|
|
1887
|
+
* - This method is based on
|
|
1888
|
+
* [`Number.isInteger`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isInteger).
|
|
1889
|
+
*
|
|
1890
|
+
* ---
|
|
1466
1891
|
* @param {*} value The value to check.
|
|
1892
|
+
*
|
|
1893
|
+
* ---
|
|
1467
1894
|
* @returns {boolean} Returns `true` if `value` is an integer, else `false`.
|
|
1895
|
+
*
|
|
1896
|
+
* ---
|
|
1468
1897
|
* @example
|
|
1469
1898
|
* isInteger(3);
|
|
1470
1899
|
* // ➔ true
|
|
@@ -1479,22 +1908,32 @@ declare function isInfinityNumber(value: unknown): boolean;
|
|
|
1479
1908
|
* isInteger('3');
|
|
1480
1909
|
* // ➔ false
|
|
1481
1910
|
*/
|
|
1482
|
-
declare
|
|
1483
|
-
/**
|
|
1911
|
+
declare const isInteger: (value: unknown) => value is number;
|
|
1912
|
+
/** ---------------------------------------------------------
|
|
1484
1913
|
* * ***Predicate: `isLength`.***
|
|
1485
1914
|
* ----------------------------------------------------------
|
|
1486
1915
|
* **Checks whether the given value is a **valid array-like length**.**
|
|
1916
|
+
*
|
|
1917
|
+
* ---
|
|
1487
1918
|
* - **Behavior:**
|
|
1488
|
-
*
|
|
1489
|
-
*
|
|
1490
|
-
*
|
|
1491
|
-
*
|
|
1492
|
-
*
|
|
1493
|
-
*
|
|
1494
|
-
*
|
|
1495
|
-
*
|
|
1919
|
+
* - Ensures the value is a **non-negative integer**.
|
|
1920
|
+
* - Ensures the value is **not greater than `Number.MAX_SAFE_INTEGER`**.
|
|
1921
|
+
* - Excludes non-numeric values, `Infinity`, and fractional numbers.
|
|
1922
|
+
*
|
|
1923
|
+
* ---
|
|
1924
|
+
* - **Note:**
|
|
1925
|
+
* - This method is loosely based-on
|
|
1926
|
+
* [`ToLength`](http://ecma-international.org/ecma-262/7.0/#sec-tolength).
|
|
1927
|
+
* - A valid length must be a non-negative integer and **not greater
|
|
1928
|
+
* than `Number.MAX_SAFE_INTEGER`**.
|
|
1929
|
+
*
|
|
1930
|
+
* ---
|
|
1496
1931
|
* @param {*} value The value to check.
|
|
1932
|
+
*
|
|
1933
|
+
* ---
|
|
1497
1934
|
* @returns {boolean} Returns `true` if `value` is a valid length, else `false`.
|
|
1935
|
+
*
|
|
1936
|
+
* ---
|
|
1498
1937
|
* @example
|
|
1499
1938
|
* isLength(3);
|
|
1500
1939
|
* // ➔ true
|
|
@@ -1515,16 +1954,24 @@ declare function isInteger(value: unknown): value is number;
|
|
|
1515
1954
|
* isLength(Number.MIN_VALUE);
|
|
1516
1955
|
* // ➔ false
|
|
1517
1956
|
*/
|
|
1518
|
-
declare
|
|
1519
|
-
/**
|
|
1957
|
+
declare const isLength: (value: unknown) => boolean;
|
|
1958
|
+
/** ---------------------------------------------------------
|
|
1520
1959
|
* * ***Type guard: `isMap`.***
|
|
1521
1960
|
* ----------------------------------------------------------
|
|
1522
1961
|
* **Checks whether the given value is a **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object**.**
|
|
1962
|
+
*
|
|
1963
|
+
* ---
|
|
1523
1964
|
* - **Behavior:**
|
|
1524
|
-
*
|
|
1525
|
-
*
|
|
1965
|
+
* - Ensures that the provided value is an instance of **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)**.
|
|
1966
|
+
* - Useful in TypeScript for narrowing types when working with collections.
|
|
1967
|
+
*
|
|
1968
|
+
* ---
|
|
1526
1969
|
* @param {*} value The value to check.
|
|
1970
|
+
*
|
|
1971
|
+
* ---
|
|
1527
1972
|
* @returns {boolean} Returns `true` if `value` is instance of **[`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)**, else `false`.
|
|
1973
|
+
*
|
|
1974
|
+
* ---
|
|
1528
1975
|
* @example
|
|
1529
1976
|
* isMap(new Map());
|
|
1530
1977
|
* // ➔ true
|
|
@@ -1537,22 +1984,34 @@ declare function isMap<K = unknown, V = unknown>(value: Map<K, V>): value is Map
|
|
|
1537
1984
|
declare function isMap(value: unknown): value is Map<unknown, unknown>;
|
|
1538
1985
|
/** ----------------------------------------------------
|
|
1539
1986
|
* * ***Predicate: `isMatch`.***
|
|
1540
|
-
*
|
|
1987
|
+
* -----------------------------------------------------
|
|
1541
1988
|
* **Performs a partial deep comparison between `object` and `source`.**
|
|
1989
|
+
*
|
|
1990
|
+
* ---
|
|
1542
1991
|
* @description
|
|
1543
1992
|
* Determines whether `object` contains equivalent property values from `source`.
|
|
1993
|
+
*
|
|
1994
|
+
* ---
|
|
1544
1995
|
* - **Behavior:**
|
|
1545
|
-
*
|
|
1546
|
-
*
|
|
1547
|
-
*
|
|
1996
|
+
* - ✅ Returns `true` if **all properties** in `source` exist in `object` and are deeply equal.
|
|
1997
|
+
* - ❌ Does **not** require `object` and `source` to be the same shape—`object` may have extra properties.
|
|
1998
|
+
* - ⚠️ Arrays are treated as objects: only matching indexed keys are compared.
|
|
1999
|
+
*
|
|
2000
|
+
* ---
|
|
1548
2001
|
* - **Remarks:**
|
|
1549
|
-
*
|
|
1550
|
-
*
|
|
1551
|
-
*
|
|
1552
|
-
*
|
|
2002
|
+
* - This is functionally equivalent to a partially applied `matches(source)` predicate.
|
|
2003
|
+
* - Special cases:
|
|
2004
|
+
* - An empty array (`[]`) in `source` matches any array in `object`.
|
|
2005
|
+
* - An empty object (`{}`) in `source` matches any object in `object`.
|
|
2006
|
+
*
|
|
2007
|
+
* ---
|
|
1553
2008
|
* @param {object} object - The object to inspect.
|
|
1554
2009
|
* @param {object} source - The object containing property values to match.
|
|
2010
|
+
*
|
|
2011
|
+
* ---
|
|
1555
2012
|
* @returns {boolean} Returns `true` if `object` is a match, else `false`.
|
|
2013
|
+
*
|
|
2014
|
+
* ---
|
|
1556
2015
|
* @example
|
|
1557
2016
|
* const object = { a: 1, b: 2 };
|
|
1558
2017
|
*
|
|
@@ -1563,11 +2022,13 @@ declare function isMap(value: unknown): value is Map<unknown, unknown>;
|
|
|
1563
2022
|
* isMatch([1, 2, 3], [1, 2]);
|
|
1564
2023
|
* // ➔ true (treats arrays as objects with index keys)
|
|
1565
2024
|
*/
|
|
1566
|
-
declare
|
|
2025
|
+
declare const isMatch: (object: object, source: object) => boolean;
|
|
1567
2026
|
/** -------------------------------------------------------------------
|
|
1568
2027
|
* * ***Customizer function for `isMatchWith`.***
|
|
1569
|
-
*
|
|
2028
|
+
* --------------------------------------------------------------------
|
|
1570
2029
|
* **Allows customizing how two values are compared for partial/object match.**
|
|
2030
|
+
*
|
|
2031
|
+
* ---
|
|
1571
2032
|
* @param value
|
|
1572
2033
|
* - The current value from the object being tested.
|
|
1573
2034
|
* @param other
|
|
@@ -1578,10 +2039,14 @@ declare function isMatch(object: object, source: object): boolean;
|
|
|
1578
2039
|
* - The parent object containing `value`.
|
|
1579
2040
|
* @param source
|
|
1580
2041
|
* - The parent source object containing `other`.
|
|
2042
|
+
*
|
|
2043
|
+
* ---
|
|
1581
2044
|
* @returns
|
|
1582
|
-
* - `true`
|
|
1583
|
-
* - `false`
|
|
1584
|
-
* - `undefined`
|
|
2045
|
+
* - `true` ➔ Treat the values as matching.
|
|
2046
|
+
* - `false` ➔ Treat the values as not matching.
|
|
2047
|
+
* - `undefined` ➔ Fallback to default match comparison.
|
|
2048
|
+
*
|
|
2049
|
+
* ---
|
|
1585
2050
|
* @example
|
|
1586
2051
|
* ```ts
|
|
1587
2052
|
* const customizer: CustomizerIsMatchWith = (value, other) => {
|
|
@@ -1592,30 +2057,40 @@ declare function isMatch(object: object, source: object): boolean;
|
|
|
1592
2057
|
* };
|
|
1593
2058
|
*
|
|
1594
2059
|
* baseIsMatch({ name: "Alice" }, { name: "alice" }, customizer);
|
|
1595
|
-
* //
|
|
2060
|
+
* // ➔ true
|
|
1596
2061
|
* ```
|
|
1597
2062
|
*/
|
|
1598
2063
|
type CustomizerIsMatchWith = (value: unknown, other: unknown, indexOrKey: PropertyKey, object: object, source: object) => boolean | undefined;
|
|
1599
2064
|
/** ----------------------------------------------------
|
|
1600
2065
|
* * ***Predicate: `isMatchWith`.***
|
|
1601
|
-
*
|
|
2066
|
+
* -----------------------------------------------------
|
|
1602
2067
|
* **Performs a partial deep comparison between `object` and `source`, like `isMatch`, but with a `customizer` function to control comparisons.**
|
|
2068
|
+
*
|
|
2069
|
+
* ---
|
|
1603
2070
|
* @description
|
|
1604
2071
|
* If `customizer` returns a value other than `undefined`, that value is used
|
|
1605
2072
|
* as the result of the comparison for the current property. Otherwise,
|
|
1606
2073
|
* the comparison falls back to the default deep equality logic.
|
|
2074
|
+
*
|
|
2075
|
+
* ---
|
|
1607
2076
|
* - **Behavior:**
|
|
1608
|
-
*
|
|
1609
|
-
*
|
|
1610
|
-
*
|
|
1611
|
-
*
|
|
1612
|
-
*
|
|
1613
|
-
*
|
|
1614
|
-
*
|
|
2077
|
+
* - The `customizer` function is invoked with up to **five** arguments:
|
|
2078
|
+
* - `(objValue, srcValue, keyOrIndex, object, source)`,
|
|
2079
|
+
* see **{@link CustomizerIsMatchWith | `CustomizerIsMatchWith`}**.
|
|
2080
|
+
* - Returning `true` from `customizer` will short-circuit further comparison
|
|
2081
|
+
* for that key.
|
|
2082
|
+
* - Returning `false` will cause `isMatchWith` to return `false` immediately.
|
|
2083
|
+
* - Returning `undefined` allows default comparison to proceed.
|
|
2084
|
+
*
|
|
2085
|
+
* ---
|
|
1615
2086
|
* @param {object} value - The object to inspect.
|
|
1616
2087
|
* @param {object} other - The object of property values to match.
|
|
1617
2088
|
* @param {CustomizerIsMatchWith} [customizer] - The function to customize comparisons.
|
|
2089
|
+
*
|
|
2090
|
+
* ---
|
|
1618
2091
|
* @returns Returns `true` if `object` is a match, else `false`.
|
|
2092
|
+
*
|
|
2093
|
+
* ---
|
|
1619
2094
|
* @example
|
|
1620
2095
|
* function isGreeting(value: unknown) {
|
|
1621
2096
|
* return typeof value === 'string' && /^h(?:i|ello)$/.test(value);
|
|
@@ -1633,19 +2108,27 @@ type CustomizerIsMatchWith = (value: unknown, other: unknown, indexOrKey: Proper
|
|
|
1633
2108
|
* isMatchWith(object, source, customizer);
|
|
1634
2109
|
* // ➔ true
|
|
1635
2110
|
*/
|
|
1636
|
-
declare
|
|
2111
|
+
declare const isMatchWith: (value: object, other: object, customizer?: CustomizerIsMatchWith) => boolean;
|
|
1637
2112
|
/** ----------------------------------------------------
|
|
1638
2113
|
* * ***Type guard: `isNaN`.***
|
|
1639
|
-
*
|
|
2114
|
+
* -----------------------------------------------------
|
|
1640
2115
|
* **Checks if a value is [`NaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NaN).**
|
|
1641
|
-
*
|
|
1642
|
-
*
|
|
1643
|
-
*
|
|
1644
|
-
*
|
|
1645
|
-
*
|
|
1646
|
-
*
|
|
2116
|
+
*
|
|
2117
|
+
* ---
|
|
2118
|
+
* - **Note:**
|
|
2119
|
+
* - This method is based on
|
|
2120
|
+
* [`Number.isNaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isNaN)
|
|
2121
|
+
* and is **not** the same as the global
|
|
2122
|
+
* [`isNaN`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/isNaN),
|
|
2123
|
+
* which returns `true` for `undefined` and other non-number values.
|
|
2124
|
+
*
|
|
2125
|
+
* ---
|
|
1647
2126
|
* @param {*} value The value to check.
|
|
2127
|
+
*
|
|
2128
|
+
* ---
|
|
1648
2129
|
* @returns {boolean} Returns `true` if `value` is `NaN`, else `false`.
|
|
2130
|
+
*
|
|
2131
|
+
* ---
|
|
1649
2132
|
* @example
|
|
1650
2133
|
* import * as RzlUtilsJs from "@rzl-zone/utils-js/predicates";
|
|
1651
2134
|
*
|
|
@@ -1660,20 +2143,28 @@ declare function isMatchWith(value: object, other: object, customizer?: Customiz
|
|
|
1660
2143
|
* isNaN(undefined);
|
|
1661
2144
|
* // ➔ true
|
|
1662
2145
|
*/
|
|
1663
|
-
declare
|
|
1664
|
-
/**
|
|
2146
|
+
declare const isNaN: (value: unknown) => boolean;
|
|
2147
|
+
/** ---------------------------------------------------------
|
|
1665
2148
|
* * ***Type guard: `isNative`.***
|
|
1666
2149
|
* ----------------------------------------------------------
|
|
1667
2150
|
* **Checks if a value is a **pristine native function**.**
|
|
1668
|
-
*
|
|
1669
|
-
*
|
|
1670
|
-
*
|
|
1671
|
-
*
|
|
1672
|
-
*
|
|
1673
|
-
*
|
|
1674
|
-
*
|
|
2151
|
+
*
|
|
2152
|
+
* ---
|
|
2153
|
+
* - **Note:**
|
|
2154
|
+
* - This method may not reliably detect native functions when using packages
|
|
2155
|
+
* like `core-js`, as they override native behavior.
|
|
2156
|
+
* - Attempts to detect native functions in such environments may fail or
|
|
2157
|
+
* throw errors.
|
|
2158
|
+
* - This also affects packages like
|
|
2159
|
+
* **[`babel-polyfill`](https://www.npmjs.com/package/babel-polyfill).**
|
|
2160
|
+
*
|
|
2161
|
+
* ---
|
|
1675
2162
|
* @param {*} value The value to check.
|
|
2163
|
+
*
|
|
2164
|
+
* ---
|
|
1676
2165
|
* @returns {boolean} Returns `true` if `value` is a native function, else `false`.
|
|
2166
|
+
*
|
|
2167
|
+
* ---
|
|
1677
2168
|
* @example
|
|
1678
2169
|
* isNative(Array.prototype.push);
|
|
1679
2170
|
* // ➔ true
|
|
@@ -1682,15 +2173,23 @@ declare function isNaN(value: unknown): boolean;
|
|
|
1682
2173
|
* isNative(RzlUtilsJs);
|
|
1683
2174
|
* // ➔ false
|
|
1684
2175
|
*/
|
|
1685
|
-
declare
|
|
1686
|
-
/**
|
|
2176
|
+
declare const isNative: (value: unknown) => value is AnyFunction;
|
|
2177
|
+
/** ---------------------------------------------------------
|
|
1687
2178
|
* * ***Type guard: `isNil`.***
|
|
1688
2179
|
* ----------------------------------------------------------
|
|
1689
2180
|
* **Checks if a value is **[`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null)** or **[`undefined`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)**.**
|
|
2181
|
+
*
|
|
2182
|
+
* ---
|
|
1690
2183
|
* - **Behavior:**
|
|
1691
|
-
*
|
|
2184
|
+
* - Narrows type to `null` or `undefined` when true.
|
|
2185
|
+
*
|
|
2186
|
+
* ---
|
|
1692
2187
|
* @param {*} value - The value to check.
|
|
2188
|
+
*
|
|
2189
|
+
* ---
|
|
1693
2190
|
* @returns {boolean} Returns `true` if the value is `null` or `undefined`, otherwise `false`.
|
|
2191
|
+
*
|
|
2192
|
+
* ---
|
|
1694
2193
|
* @example
|
|
1695
2194
|
* isNil(null);
|
|
1696
2195
|
* // ➔ true
|
|
@@ -1701,48 +2200,80 @@ declare function isNative(value: unknown): value is AnyFunction;
|
|
|
1701
2200
|
* isNil(NaN);
|
|
1702
2201
|
* // ➔ false
|
|
1703
2202
|
*/
|
|
1704
|
-
declare
|
|
2203
|
+
declare const isNil: (value: unknown) => value is null | undefined;
|
|
1705
2204
|
/** ----------------------------------------------------------
|
|
1706
2205
|
* * ***Type guard: `isNonEmptyArray`.***
|
|
1707
|
-
*
|
|
2206
|
+
* -----------------------------------------------------------
|
|
1708
2207
|
* **Checks if a value is a **non-empty array**.**
|
|
2208
|
+
*
|
|
2209
|
+
* ---
|
|
1709
2210
|
* - **Behavior:**
|
|
1710
|
-
*
|
|
1711
|
-
*
|
|
1712
|
-
*
|
|
2211
|
+
* - Ensures the value is an actual array using **[`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray)**.
|
|
2212
|
+
* - Ensures the array contains at least one item.
|
|
2213
|
+
* - Narrows type to `T[]` (non-empty array) when true.
|
|
2214
|
+
*
|
|
2215
|
+
* ---
|
|
1713
2216
|
* @template T - The type of the value being checked.
|
|
2217
|
+
*
|
|
2218
|
+
* ---
|
|
1714
2219
|
* @param {*} value - The value to check.
|
|
2220
|
+
*
|
|
2221
|
+
* ---
|
|
1715
2222
|
* @returns {boolean} Return `true` if value is a non-empty array.
|
|
2223
|
+
*
|
|
2224
|
+
* ---
|
|
1716
2225
|
* @example
|
|
1717
|
-
* isNonEmptyArray([1, 2, 3]);
|
|
1718
|
-
*
|
|
1719
|
-
* isNonEmptyArray(
|
|
1720
|
-
*
|
|
2226
|
+
* isNonEmptyArray([1, 2, 3]);
|
|
2227
|
+
* // ➔ true
|
|
2228
|
+
* isNonEmptyArray([]);
|
|
2229
|
+
* // ➔ false
|
|
2230
|
+
* isNonEmptyArray(null);
|
|
2231
|
+
* // ➔ false
|
|
2232
|
+
* isNonEmptyArray("test");
|
|
2233
|
+
* // ➔ false
|
|
1721
2234
|
*/
|
|
1722
2235
|
declare function isNonEmptyArray(value: []): value is [];
|
|
1723
2236
|
declare function isNonEmptyArray<T>(value: T): value is ArrayFallback<T>;
|
|
1724
2237
|
declare function isNonEmptyArray(value: unknown): value is unknown[];
|
|
1725
2238
|
type IsNonEmptyStringOptions = {
|
|
1726
|
-
/**
|
|
2239
|
+
/** ----------------------------------------------------------
|
|
2240
|
+
* * ***Whether to trim leading and trailing whitespace before checking.***
|
|
2241
|
+
* -----------------------------------------------------------
|
|
1727
2242
|
*
|
|
2243
|
+
* @note
|
|
2244
|
+
* Non-boolean values fall back to the default behavior.
|
|
2245
|
+
*
|
|
2246
|
+
* ---
|
|
1728
2247
|
* @default true
|
|
1729
2248
|
*/
|
|
1730
2249
|
trim?: boolean;
|
|
1731
2250
|
};
|
|
1732
2251
|
/** ----------------------------------------------------------
|
|
1733
2252
|
* * ***Type guard: `isNonEmptyString`.***
|
|
1734
|
-
*
|
|
2253
|
+
* -----------------------------------------------------------
|
|
1735
2254
|
* **Checks if a value is a **non-empty string**.**
|
|
2255
|
+
*
|
|
2256
|
+
* ---
|
|
1736
2257
|
* @description
|
|
1737
2258
|
* Determines whether the given `value` is a string containing at least one non-whitespace character, with optional trimming behavior.
|
|
2259
|
+
*
|
|
2260
|
+
* ---
|
|
1738
2261
|
* - **Behavior:**
|
|
1739
|
-
*
|
|
1740
|
-
*
|
|
1741
|
-
*
|
|
2262
|
+
* - Ensures the value is a string using ***`isString` utility function***.
|
|
2263
|
+
* - Optionally trims whitespace before checking (`trim` defaults to `true`).
|
|
2264
|
+
* - Narrows type to `string` when true.
|
|
2265
|
+
*
|
|
2266
|
+
* ---
|
|
1742
2267
|
* @param {*} value - The value to test.
|
|
1743
|
-
* @param {IsNonEmptyStringOptions} [options]
|
|
1744
|
-
*
|
|
2268
|
+
* @param {IsNonEmptyStringOptions} [options]
|
|
2269
|
+
* Optional settings (non-plain object values are ignored and replaced with default options).
|
|
2270
|
+
* @param {boolean} options.trim
|
|
2271
|
+
* If `true`, trims the string before checking (non-boolean values fall back to the default behavior), defaults: `true`.
|
|
2272
|
+
*
|
|
2273
|
+
* ---
|
|
1745
2274
|
* @returns {boolean} Return `true` if `value` is a non-empty string, otherwise `false`.
|
|
2275
|
+
*
|
|
2276
|
+
* ---
|
|
1746
2277
|
* @example
|
|
1747
2278
|
* isNonEmptyString("hello");
|
|
1748
2279
|
* // ➔ true
|
|
@@ -1765,7 +2296,9 @@ type IsNonEmptyStringOptions = {
|
|
|
1765
2296
|
*/
|
|
1766
2297
|
declare const isNonEmptyString: (value: unknown, options?: IsNonEmptyStringOptions) => value is string;
|
|
1767
2298
|
type IsNonEmptyValueOptions = {
|
|
1768
|
-
/**
|
|
2299
|
+
/** ----------------------------------------------------------
|
|
2300
|
+
* * ***Whether to check symbol properties when checking empty objects, default: `false`.***
|
|
2301
|
+
* -----------------------------------------------------------
|
|
1769
2302
|
*
|
|
1770
2303
|
* @default false
|
|
1771
2304
|
*/
|
|
@@ -1773,27 +2306,36 @@ type IsNonEmptyValueOptions = {
|
|
|
1773
2306
|
};
|
|
1774
2307
|
/** ----------------------------------------------------------
|
|
1775
2308
|
* * ***Predicated: `isNonEmptyValue`.***
|
|
1776
|
-
*
|
|
2309
|
+
* -----------------------------------------------------------
|
|
1777
2310
|
* **Determines if a value is a **non-empty** object (`{}` with props), **non-empty** array (`[]` with items) or generally truthy.**
|
|
1778
|
-
*
|
|
1779
|
-
*
|
|
1780
|
-
*
|
|
1781
|
-
* -
|
|
1782
|
-
*
|
|
1783
|
-
*
|
|
1784
|
-
*
|
|
1785
|
-
*
|
|
1786
|
-
*
|
|
1787
|
-
*
|
|
1788
|
-
*
|
|
1789
|
-
* -
|
|
1790
|
-
*
|
|
1791
|
-
*
|
|
1792
|
-
*
|
|
1793
|
-
*
|
|
2311
|
+
*
|
|
2312
|
+
* ---
|
|
2313
|
+
* - #### *Behavior:*
|
|
2314
|
+
* - #### Returns `true` for:
|
|
2315
|
+
* - Objects **with properties**.
|
|
2316
|
+
* - Arrays **with items**.
|
|
2317
|
+
* - Non-empty, non-whitespace strings.
|
|
2318
|
+
* - Numbers (except `NaN`, includes `0`).
|
|
2319
|
+
* - Functions.
|
|
2320
|
+
* - `true`.
|
|
2321
|
+
* ---
|
|
2322
|
+
* - #### Returns `false` for:
|
|
2323
|
+
* - Empty objects (`{}`).
|
|
2324
|
+
* - Empty arrays (`[]`).
|
|
2325
|
+
* - `null` or `undefined`.
|
|
2326
|
+
* - Empty strings (`""`) or whitespace-only strings (`" "`).
|
|
2327
|
+
* - `false`.
|
|
2328
|
+
* - `NaN`.
|
|
2329
|
+
* - #### Safely handles `null`, `undefined`, and non-object types without throwing.
|
|
2330
|
+
*
|
|
2331
|
+
* ---
|
|
1794
2332
|
* @param {*} value - The value to evaluate.
|
|
1795
2333
|
* @param {IsNonEmptyValueOptions} [options] - Optional settings.
|
|
2334
|
+
*
|
|
2335
|
+
* ---
|
|
1796
2336
|
* @returns {boolean} Return `true` if the value is considered non-empty/truthy, otherwise `false`.
|
|
2337
|
+
*
|
|
2338
|
+
* ---
|
|
1797
2339
|
* @example
|
|
1798
2340
|
* isNonEmptyValue({});
|
|
1799
2341
|
* // ➔ false
|
|
@@ -1803,8 +2345,6 @@ type IsNonEmptyValueOptions = {
|
|
|
1803
2345
|
* // ➔ true
|
|
1804
2346
|
* isNonEmptyValue({ [Symbol("foo")]: 123 });
|
|
1805
2347
|
* // ➔ false (default `checkSymbols` is `false`)
|
|
1806
|
-
* isNonEmptyValue({ [Symbol("foo")]: 123 }, { checkSymbols: false });
|
|
1807
|
-
* // ➔ false (default `checkSymbols` is `false`)
|
|
1808
2348
|
* isNonEmptyValue({ [Symbol("foo")]: 123 }, { checkSymbols: true });
|
|
1809
2349
|
* // ➔ true
|
|
1810
2350
|
* isNonEmptyValue([1, 2, 3]);
|
|
@@ -1837,100 +2377,161 @@ declare const isNonEmptyValue: (value: unknown, options?: IsNonEmptyValueOptions
|
|
|
1837
2377
|
* * ***Type guard: `isNull`.***
|
|
1838
2378
|
* ----------------------------------------------------------
|
|
1839
2379
|
* **Checks if a value is **[`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null)**.**
|
|
2380
|
+
*
|
|
2381
|
+
* ---
|
|
1840
2382
|
* - **Behavior:**
|
|
1841
|
-
*
|
|
1842
|
-
*
|
|
2383
|
+
* - Narrows type to `null` when true.
|
|
2384
|
+
* - Strictly compares the value against `null`.
|
|
2385
|
+
*
|
|
2386
|
+
* ---
|
|
1843
2387
|
* @param {*} val - The value to check.
|
|
2388
|
+
*
|
|
2389
|
+
* ---
|
|
1844
2390
|
* @returns {boolean} Returns `true` if the value is `null`, otherwise `false`.
|
|
2391
|
+
*
|
|
2392
|
+
* ---
|
|
1845
2393
|
* @example
|
|
1846
|
-
* isNull(null);
|
|
1847
|
-
*
|
|
1848
|
-
* isNull(
|
|
2394
|
+
* isNull(null);
|
|
2395
|
+
* // ➔ true
|
|
2396
|
+
* isNull(0);
|
|
2397
|
+
* // ➔ false
|
|
2398
|
+
* isNull(undefined);
|
|
2399
|
+
* // ➔ false
|
|
1849
2400
|
*/
|
|
1850
2401
|
declare const isNull: (val: unknown) => val is null;
|
|
1851
2402
|
/** ----------------------------------------------------
|
|
1852
2403
|
* * ***Type guard: `isNumberObject`.***
|
|
1853
|
-
*
|
|
2404
|
+
* -----------------------------------------------------
|
|
1854
2405
|
* **Checks if a value is a **`Number` object wrapper**
|
|
1855
2406
|
* (`new Number(...)`), not a primitive number.**
|
|
2407
|
+
*
|
|
2408
|
+
* ---
|
|
1856
2409
|
* @param {*} value The value to check.
|
|
2410
|
+
*
|
|
2411
|
+
* ---
|
|
1857
2412
|
* @returns {boolean} Returns `true` if `value` is a `Number` object.
|
|
2413
|
+
*
|
|
2414
|
+
* ---
|
|
1858
2415
|
* @example
|
|
1859
2416
|
* isNumberObject(new Number(42));
|
|
1860
2417
|
* // ➔ true
|
|
1861
2418
|
* isNumberObject(42);
|
|
1862
2419
|
* // ➔ false
|
|
1863
2420
|
*/
|
|
1864
|
-
declare
|
|
2421
|
+
declare const isNumberObject: (value: unknown) => value is Number;
|
|
1865
2422
|
type IsObject<T> = unknown extends T ? T & Record<PropertyKey, unknown> : T extends object ? T extends AnObjectNonArray ? T : IsHasKeysObject<T> extends false ? T & Record<PropertyKey, unknown> : IsArray<T> extends true ? Exclude<T, unknown[]> : T : never;
|
|
1866
2423
|
/** ---------------------------------------------------------
|
|
1867
2424
|
* * ***Type guard: `isObject`.***
|
|
1868
2425
|
* ----------------------------------------------------------
|
|
1869
2426
|
* **Checks if a value is an **object** (excluding `null` and `arrays`).**
|
|
1870
|
-
*
|
|
1871
|
-
*
|
|
1872
|
-
*
|
|
1873
|
-
*
|
|
1874
|
-
*
|
|
1875
|
-
*
|
|
1876
|
-
*
|
|
1877
|
-
*
|
|
1878
|
-
*
|
|
1879
|
-
*
|
|
1880
|
-
*
|
|
1881
|
-
*
|
|
1882
|
-
*
|
|
1883
|
-
*
|
|
1884
|
-
*
|
|
1885
|
-
*
|
|
1886
|
-
*
|
|
1887
|
-
*
|
|
2427
|
+
*
|
|
2428
|
+
* ---
|
|
2429
|
+
* - #### *Behavior:*
|
|
2430
|
+
* - #### Returns `true` for any non-null object (arrays excluded), including:
|
|
2431
|
+
* - Plain-objects (`{}`, `Object.create(null)`).
|
|
2432
|
+
* - Custom class instances.
|
|
2433
|
+
* - Built-ins:
|
|
2434
|
+
* - `Date`, `RegExp`, `Error`, `URL`, `URLSearchParams`.
|
|
2435
|
+
* - Collections:
|
|
2436
|
+
* - `Map`, `Set`, `WeakMap`, `WeakSet`.
|
|
2437
|
+
* - Binary/typed data:
|
|
2438
|
+
* - `ArrayBuffer`, `DataView`, typed arrays (`Uint8Array`, `Int32Array`, etc.).
|
|
2439
|
+
* - DOM/Node objects:
|
|
2440
|
+
* - `HTMLElement`, `DocumentFragment`, etc.
|
|
2441
|
+
* - Proxies (wrapping any object type).
|
|
2442
|
+
* ---
|
|
2443
|
+
* - #### Returns `false` for:
|
|
2444
|
+
* - `null`.
|
|
2445
|
+
* - Arrays (`[]`, `new Array()`).
|
|
2446
|
+
* - Functions (regular functions, arrow functions, class constructors).
|
|
2447
|
+
* - Primitives:
|
|
2448
|
+
* - `string`, `number`, `boolean`, `symbol`, `bigint`.
|
|
2449
|
+
* - Boxed primitives:
|
|
2450
|
+
* - `new String()`, `new Number()`, `new Boolean()`.
|
|
2451
|
+
* - `undefined` (including `NaN`, which is a primitive number).
|
|
2452
|
+
*
|
|
2453
|
+
* ---
|
|
2454
|
+
* - **Note:**
|
|
2455
|
+
* - If you specifically need to check for ***plain-objects*** only, use ***`isPlainObject` utility function*** instead.
|
|
2456
|
+
* - If you specifically need to check for ***object***, ***plain-objects***, and include ***array***, use ***`isObjectOrArray` utility function*** instead.
|
|
2457
|
+
*
|
|
2458
|
+
* ---
|
|
1888
2459
|
* @template T - The type of the value being checked.
|
|
2460
|
+
*
|
|
2461
|
+
* ---
|
|
1889
2462
|
* @param {*} value - The value to check.
|
|
2463
|
+
*
|
|
2464
|
+
* ---
|
|
1890
2465
|
* @returns {boolean} Returns `true` if the value is a ***plain-objects***, otherwise `false`.
|
|
2466
|
+
*
|
|
2467
|
+
* ---
|
|
1891
2468
|
* @example
|
|
1892
|
-
* isObject({});
|
|
1893
|
-
*
|
|
1894
|
-
* isObject(
|
|
1895
|
-
*
|
|
1896
|
-
* isObject(new
|
|
1897
|
-
*
|
|
1898
|
-
* isObject(
|
|
1899
|
-
*
|
|
1900
|
-
* isObject(
|
|
1901
|
-
*
|
|
1902
|
-
* isObject(()
|
|
2469
|
+
* isObject({});
|
|
2470
|
+
* // ➔ true
|
|
2471
|
+
* isObject(Object.create(null));
|
|
2472
|
+
* // ➔ true
|
|
2473
|
+
* isObject(new Date());
|
|
2474
|
+
* // ➔ true
|
|
2475
|
+
* isObject(new Map());
|
|
2476
|
+
* // ➔ true
|
|
2477
|
+
* isObject(new Uint8Array());
|
|
2478
|
+
* // ➔ true
|
|
2479
|
+
* isObject(new String("x"));
|
|
2480
|
+
* // ➔ true
|
|
2481
|
+
* isObject([]);
|
|
2482
|
+
* // ➔ false
|
|
2483
|
+
* isObject(null);
|
|
2484
|
+
* // ➔ false
|
|
2485
|
+
* isObject(undefined);
|
|
2486
|
+
* // ➔ false
|
|
2487
|
+
* isObject(123);
|
|
2488
|
+
* // ➔ false
|
|
2489
|
+
* isObject(() => {});
|
|
2490
|
+
* // ➔ false
|
|
1903
2491
|
*/
|
|
1904
2492
|
declare function isObject<T extends object>(value: T): value is IsObject<T>;
|
|
1905
2493
|
declare function isObject(value: unknown): value is Record<PropertyKey, unknown>;
|
|
1906
2494
|
/** ----------------------------------------------------------
|
|
1907
2495
|
* * ***Type guard: `isObjectLoose`.***
|
|
1908
|
-
*
|
|
2496
|
+
* -----------------------------------------------------------
|
|
1909
2497
|
* **Checks if a value is the
|
|
1910
|
-
* [ECMAScript language type
|
|
1911
|
-
*
|
|
1912
|
-
*
|
|
1913
|
-
*
|
|
1914
|
-
*
|
|
1915
|
-
*
|
|
1916
|
-
*
|
|
1917
|
-
*
|
|
1918
|
-
*
|
|
1919
|
-
*
|
|
1920
|
-
*
|
|
1921
|
-
*
|
|
1922
|
-
*
|
|
1923
|
-
*
|
|
1924
|
-
* - `
|
|
1925
|
-
*
|
|
1926
|
-
*
|
|
1927
|
-
*
|
|
1928
|
-
*
|
|
1929
|
-
*
|
|
1930
|
-
*
|
|
2498
|
+
* [ECMAScript language type ***`Object`***](http://www.ecma-international.org/ecma-262/7.0/#sec-ecmascript-language-types).**
|
|
2499
|
+
*
|
|
2500
|
+
* ---
|
|
2501
|
+
* - #### *Behavior:*
|
|
2502
|
+
* - #### Returns `true` for:
|
|
2503
|
+
* - Plain objects (`{}`).
|
|
2504
|
+
* - Arrays (`[]`).
|
|
2505
|
+
* - Functions.
|
|
2506
|
+
* - Regexes (`/abc/`).
|
|
2507
|
+
* - Boxed primitives:
|
|
2508
|
+
* - `new Number(0)`.
|
|
2509
|
+
* - `new String("")`.
|
|
2510
|
+
* - `new Boolean(false)`.
|
|
2511
|
+
* ---
|
|
2512
|
+
* - #### Returns `false` for:
|
|
2513
|
+
* - `null`.
|
|
2514
|
+
* - `undefined`.
|
|
2515
|
+
* - Primitives:
|
|
2516
|
+
* - `string`.
|
|
2517
|
+
* - `number`.
|
|
2518
|
+
* - `boolean`.
|
|
2519
|
+
* - `symbol`.
|
|
2520
|
+
* - `bigint`.
|
|
2521
|
+
* ---
|
|
2522
|
+
* - **Note:**
|
|
2523
|
+
* - **For More Strict Object Use ***`isObject`*** or ***`isPlainObject` utility function*** instead.**
|
|
2524
|
+
*
|
|
2525
|
+
* ---
|
|
1931
2526
|
* @template T - The type of the value being checked.
|
|
2527
|
+
*
|
|
2528
|
+
* ---
|
|
1932
2529
|
* @param {*} value The value to check.
|
|
2530
|
+
*
|
|
2531
|
+
* ---
|
|
1933
2532
|
* @returns {boolean} Returns `true` if `value` is an object, else `false`.
|
|
2533
|
+
*
|
|
2534
|
+
* ---
|
|
1934
2535
|
* @example
|
|
1935
2536
|
* isObjectLoose({});
|
|
1936
2537
|
* // ➔ true
|
|
@@ -1943,52 +2544,79 @@ declare function isObject(value: unknown): value is Record<PropertyKey, unknown>
|
|
|
1943
2544
|
* isObjectLoose(undefined);
|
|
1944
2545
|
* // ➔ false
|
|
1945
2546
|
*/
|
|
1946
|
-
declare
|
|
2547
|
+
declare const isObjectLoose: <T = object>(value: unknown) => value is T;
|
|
1947
2548
|
type IsObjectOrArray<T> = OrArr<[IsNever<T>, Extends<T, Record<PropertyKey, unknown>>, Extends<unknown, T>]> extends true ? T & Record<PropertyKey, unknown> & unknown[] : T extends object ? T extends unknown[] ? T : T extends AnObjectNonArray ? T : IsHasKeysObject<T> extends false ? T & Record<PropertyKey, unknown> : T : Extract<T, Record<PropertyKey, unknown> & unknown[]>;
|
|
1948
2549
|
/** ---------------------------------------------------------
|
|
1949
2550
|
* * ***Type guard: `isObjectOrArray`.***
|
|
1950
2551
|
* ----------------------------------------------------------
|
|
1951
2552
|
* **Checks if a value is an **object** or an **array**.**
|
|
1952
|
-
*
|
|
1953
|
-
*
|
|
1954
|
-
*
|
|
1955
|
-
*
|
|
1956
|
-
*
|
|
1957
|
-
*
|
|
1958
|
-
*
|
|
1959
|
-
*
|
|
1960
|
-
*
|
|
1961
|
-
*
|
|
1962
|
-
*
|
|
1963
|
-
*
|
|
1964
|
-
*
|
|
1965
|
-
*
|
|
2553
|
+
*
|
|
2554
|
+
* ---
|
|
2555
|
+
* - #### *Behavior:*
|
|
2556
|
+
* - #### Returns `true` for:
|
|
2557
|
+
* - Plain objects (`{}`, `Object.create(null)`).
|
|
2558
|
+
* - Custom objects.
|
|
2559
|
+
* - Arrays (`[]`, `[1,2,3]`).
|
|
2560
|
+
* ---
|
|
2561
|
+
* - #### Returns `false` for:
|
|
2562
|
+
* - `null`.
|
|
2563
|
+
* - `undefined`.
|
|
2564
|
+
* - Primitives:
|
|
2565
|
+
* - `string`.
|
|
2566
|
+
* - `number`.
|
|
2567
|
+
* - `boolean`.
|
|
2568
|
+
* - `symbol`.
|
|
2569
|
+
* - `bigint`.
|
|
2570
|
+
* - Functions.
|
|
2571
|
+
*
|
|
2572
|
+
* ---
|
|
1966
2573
|
* @template T - The type of the value being checked.
|
|
2574
|
+
*
|
|
2575
|
+
* ---
|
|
1967
2576
|
* @param {*} value - The value to check.
|
|
2577
|
+
*
|
|
2578
|
+
* ---
|
|
1968
2579
|
* @returns {boolean} Returns `true` if the value is an `object` or `array`.
|
|
2580
|
+
*
|
|
2581
|
+
* ---
|
|
1969
2582
|
* @example
|
|
1970
|
-
* isObjectOrArray([1,2,3]);
|
|
1971
|
-
*
|
|
1972
|
-
* isObjectOrArray(
|
|
1973
|
-
*
|
|
1974
|
-
* isObjectOrArray(
|
|
2583
|
+
* isObjectOrArray([1,2,3]);
|
|
2584
|
+
* // ➔ true
|
|
2585
|
+
* isObjectOrArray({ name: "Alice" });
|
|
2586
|
+
* // ➔ true
|
|
2587
|
+
* isObjectOrArray(null);
|
|
2588
|
+
* // ➔ false
|
|
2589
|
+
* isObjectOrArray(undefined);
|
|
2590
|
+
* // ➔ false
|
|
2591
|
+
* isObjectOrArray("hello");
|
|
2592
|
+
* // ➔ false
|
|
1975
2593
|
*/
|
|
1976
2594
|
declare function isObjectOrArray(value: []): value is [];
|
|
1977
2595
|
declare function isObjectOrArray<T>(value: T): value is IsObjectOrArray<T>;
|
|
1978
2596
|
/** ----------------------------------------------------------
|
|
1979
2597
|
* * ***Type guard: `PropertyKey`.***
|
|
1980
|
-
*
|
|
2598
|
+
* -----------------------------------------------------------
|
|
1981
2599
|
* **Checks if a value is a valid `PropertyKey`.**
|
|
1982
|
-
*
|
|
1983
|
-
*
|
|
1984
|
-
*
|
|
1985
|
-
*
|
|
1986
|
-
*
|
|
1987
|
-
*
|
|
1988
|
-
*
|
|
1989
|
-
*
|
|
2600
|
+
*
|
|
2601
|
+
* ---
|
|
2602
|
+
* - #### *Behavior:*
|
|
2603
|
+
* - #### This function ensures the given `value` is one of these types.
|
|
2604
|
+
* - Narrows type to {@link PropertyKey | ***`PropertyKey`***} when true.
|
|
2605
|
+
* - Useful for working with dynamic object keys.
|
|
2606
|
+
* - Strictly rejects `null`, `undefined`, `boolean`, `object`, `function`, etc.
|
|
2607
|
+
* ---
|
|
2608
|
+
* - #### In JavaScript/TypeScript, a **`PropertyKey`** is any of:
|
|
2609
|
+
* - **`string`**.
|
|
2610
|
+
* - **`number`**.
|
|
2611
|
+
* - **`symbol`**.
|
|
2612
|
+
*
|
|
2613
|
+
* ---
|
|
1990
2614
|
* @param {*} value - The value to check.
|
|
2615
|
+
*
|
|
2616
|
+
* ---
|
|
1991
2617
|
* @returns {boolean} Return `true` if `value` is a valid property key, otherwise `false`.
|
|
2618
|
+
*
|
|
2619
|
+
* ---
|
|
1992
2620
|
* @example
|
|
1993
2621
|
* isPropertyKey("foo");
|
|
1994
2622
|
* // ➔ true
|
|
@@ -2001,33 +2629,52 @@ declare function isObjectOrArray<T>(value: T): value is IsObjectOrArray<T>;
|
|
|
2001
2629
|
* isPropertyKey(null);
|
|
2002
2630
|
* // ➔ false
|
|
2003
2631
|
*/
|
|
2004
|
-
declare
|
|
2632
|
+
declare const isPropertyKey: (value: unknown) => value is PropertyKey;
|
|
2005
2633
|
/** ----------------------------------------------------------
|
|
2006
2634
|
* * ***Type guard: `isRegExp`.***
|
|
2007
|
-
*
|
|
2635
|
+
* -----------------------------------------------------------
|
|
2008
2636
|
* **Checks if a value is a [`RegExp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) instance.**
|
|
2637
|
+
*
|
|
2638
|
+
* ---
|
|
2009
2639
|
* @param {*} value - The value to check.
|
|
2640
|
+
*
|
|
2641
|
+
* ---
|
|
2010
2642
|
* @returns {boolean} Return `true` if value is an instance of **`RegExp`**.
|
|
2643
|
+
*
|
|
2644
|
+
* ---
|
|
2011
2645
|
* @example
|
|
2012
|
-
* isRegExp(/abc/);
|
|
2013
|
-
*
|
|
2014
|
-
* isRegExp("abc");
|
|
2646
|
+
* isRegExp(/abc/);
|
|
2647
|
+
* // ➔ true
|
|
2648
|
+
* isRegExp(new RegExp("abc"));
|
|
2649
|
+
* // ➔ true
|
|
2650
|
+
* isRegExp("abc");
|
|
2651
|
+
* // ➔ false
|
|
2015
2652
|
*/
|
|
2016
2653
|
declare const isRegExp: (value: unknown) => value is RegExp;
|
|
2017
2654
|
/** --------------------------------------------------
|
|
2018
2655
|
* * ***Type guard: `isSafeInteger`.***
|
|
2019
|
-
*
|
|
2656
|
+
* ---------------------------------------------------
|
|
2020
2657
|
* **Checks if `value` is a **[`Safe-Integer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger)**.**
|
|
2021
|
-
*
|
|
2022
|
-
*
|
|
2023
|
-
* -
|
|
2024
|
-
*
|
|
2025
|
-
*
|
|
2026
|
-
*
|
|
2027
|
-
* - **
|
|
2028
|
-
*
|
|
2658
|
+
*
|
|
2659
|
+
* ---
|
|
2660
|
+
* - #### Behavior:
|
|
2661
|
+
* - Narrows type to `number` when true.
|
|
2662
|
+
* ---
|
|
2663
|
+
* - #### An integer is considered *safe* if:
|
|
2664
|
+
* - It is an [`IEEE-754` **double precision number**](https://en.wikipedia.org/wiki/Double-precision_floating-point_format).
|
|
2665
|
+
* - It can be exactly represented without rounding errors.
|
|
2666
|
+
* - It lies within the range **-(2^53 - 1) to 2^53 - 1**.
|
|
2667
|
+
* ---
|
|
2668
|
+
* - #### Note:
|
|
2669
|
+
* - This method is based on **{@link Number.isSafeInteger | `Number.isSafeInteger`}**.
|
|
2670
|
+
*
|
|
2671
|
+
* ---
|
|
2029
2672
|
* @param {*} value - The value to check.
|
|
2673
|
+
*
|
|
2674
|
+
* ---
|
|
2030
2675
|
* @returns {boolean} Return `true` if `value` is a safe integer, otherwise `false`.
|
|
2676
|
+
*
|
|
2677
|
+
* ---
|
|
2031
2678
|
* @example
|
|
2032
2679
|
* isSafeInteger(3);
|
|
2033
2680
|
* // ➔ true
|
|
@@ -2038,21 +2685,27 @@ declare const isRegExp: (value: unknown) => value is RegExp;
|
|
|
2038
2685
|
* isSafeInteger('3');
|
|
2039
2686
|
* // ➔ false
|
|
2040
2687
|
*/
|
|
2041
|
-
declare
|
|
2688
|
+
declare const isSafeInteger: (value: unknown) => value is number;
|
|
2042
2689
|
/** ---------------------------------------------------------
|
|
2043
2690
|
* * ***Environment Predicate: `isServer`.***
|
|
2044
|
-
*
|
|
2691
|
+
* ----------------------------------------------------------
|
|
2045
2692
|
* **Detects whether the current code is executing in a
|
|
2046
2693
|
* **non-browser JavaScript runtime** (server-side) rather
|
|
2047
2694
|
* than in a web browser.**
|
|
2695
|
+
*
|
|
2696
|
+
* ---
|
|
2048
2697
|
* @description
|
|
2049
2698
|
* It simply checks for the absence of key browser globals like
|
|
2050
2699
|
* [**`window`**](https://developer.mozilla.org/docs/Web/API/Window/window) and
|
|
2051
2700
|
* [**`document`**](https://developer.mozilla.org/docs/Web/API/Window/document).
|
|
2052
2701
|
* - *If those globals aren’t present, we treat the runtime as a server environment.*
|
|
2702
|
+
*
|
|
2703
|
+
* ---
|
|
2053
2704
|
* @returns {boolean}
|
|
2054
2705
|
* * ***true** – Code is executing on the `server`.*
|
|
2055
2706
|
* * ***false** – Code is executing in a `browser`.*
|
|
2707
|
+
*
|
|
2708
|
+
* ---
|
|
2056
2709
|
* @example
|
|
2057
2710
|
* if (isServer()) {
|
|
2058
2711
|
* console.log("Running on a server-side runtime");
|
|
@@ -2065,12 +2718,22 @@ declare const isServer: () => boolean;
|
|
|
2065
2718
|
* * ***Type guard: `isSet`.***
|
|
2066
2719
|
* ----------------------------------------------------------
|
|
2067
2720
|
* **Checks if a value is a **[`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/Set)** object.**
|
|
2721
|
+
*
|
|
2722
|
+
* ---
|
|
2068
2723
|
* - **Behavior:**
|
|
2069
|
-
*
|
|
2070
|
-
*
|
|
2724
|
+
* - Narrows type to `Set<T>` when true.
|
|
2725
|
+
* - Excludes `WeakSet`, arrays, plain objects, and other non-Set values.
|
|
2726
|
+
*
|
|
2727
|
+
* ---
|
|
2071
2728
|
* @template T - The type of the value being checked.
|
|
2729
|
+
*
|
|
2730
|
+
* ---
|
|
2072
2731
|
* @param {*} value - The value to check.
|
|
2732
|
+
*
|
|
2733
|
+
* ---
|
|
2073
2734
|
* @returns {boolean} Returns `true` if the value is a `Set`, otherwise `false`.
|
|
2735
|
+
*
|
|
2736
|
+
* ---
|
|
2074
2737
|
* @example
|
|
2075
2738
|
* isSet(new Set);
|
|
2076
2739
|
* // ➔ true
|
|
@@ -2084,84 +2747,139 @@ declare function isSet(value: unknown): value is Set<unknown>;
|
|
|
2084
2747
|
* ----------------------------------------------------------
|
|
2085
2748
|
* **Checks if a value is of type
|
|
2086
2749
|
* **[`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**.**
|
|
2750
|
+
*
|
|
2751
|
+
* ---
|
|
2087
2752
|
* - **Behavior:**
|
|
2088
|
-
*
|
|
2089
|
-
*
|
|
2753
|
+
* - Narrows type to `string` when true.
|
|
2754
|
+
* - Uses the `typeof` operator for strict checking.
|
|
2755
|
+
*
|
|
2756
|
+
* ---
|
|
2090
2757
|
* @param {*} value - The value to check.
|
|
2758
|
+
*
|
|
2759
|
+
* ---
|
|
2091
2760
|
* @returns {boolean} Returns `true` if the value is a string, otherwise `false`.
|
|
2092
|
-
* @example
|
|
2093
|
-
* isString("hello"); // ➔ true
|
|
2094
|
-
* isString(123); // ➔ false
|
|
2095
2761
|
*
|
|
2096
|
-
*
|
|
2097
|
-
*
|
|
2098
|
-
*
|
|
2099
|
-
*
|
|
2100
|
-
*
|
|
2101
|
-
*
|
|
2762
|
+
* ---
|
|
2763
|
+
* @example
|
|
2764
|
+
* 1. #### Basic Usage:
|
|
2765
|
+
* ```ts
|
|
2766
|
+
* isString("hello");
|
|
2767
|
+
* // ➔ true
|
|
2768
|
+
* isString(123);
|
|
2769
|
+
* // ➔ false
|
|
2770
|
+
* ```
|
|
2771
|
+
* ---
|
|
2772
|
+
* 2. #### Usage in type narrowing:
|
|
2773
|
+
* ```ts
|
|
2774
|
+
* const value: unknown = getValue();
|
|
2775
|
+
* if (isString(value)) {
|
|
2776
|
+
* // TypeScript now knows `value` is a string
|
|
2777
|
+
* console.log(value.toUpperCase());
|
|
2778
|
+
* }
|
|
2779
|
+
* ```
|
|
2102
2780
|
*/
|
|
2103
2781
|
declare const isString: (value: unknown) => value is string;
|
|
2104
2782
|
/** ----------------------------------------------------
|
|
2105
2783
|
* * ***Type guard: `isStringObject`.***
|
|
2106
|
-
*
|
|
2784
|
+
* -----------------------------------------------------
|
|
2107
2785
|
* **Checks if a value is a **`String` object wrapper**
|
|
2108
2786
|
* (`new String(...)`), not a primitive string.**
|
|
2787
|
+
*
|
|
2788
|
+
* ---
|
|
2109
2789
|
* @param {*} value The value to check.
|
|
2790
|
+
*
|
|
2791
|
+
* ---
|
|
2110
2792
|
* @returns {boolean} Returns `true` if `value` is a `String` object.
|
|
2793
|
+
*
|
|
2794
|
+
* ---
|
|
2111
2795
|
* @example
|
|
2112
2796
|
* isStringObject(new String("hello"));
|
|
2113
2797
|
* // ➔ true
|
|
2114
2798
|
* isStringObject("hello");
|
|
2115
2799
|
* // ➔ false
|
|
2116
2800
|
*/
|
|
2117
|
-
declare
|
|
2801
|
+
declare const isStringObject: (value: unknown) => value is String;
|
|
2118
2802
|
/** ----------------------------------------------------------
|
|
2119
2803
|
* * ***Type guard: `isSymbol`.***
|
|
2120
|
-
*
|
|
2804
|
+
* -----------------------------------------------------------
|
|
2121
2805
|
* **Checks if a value is of type
|
|
2122
2806
|
* **[`symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/Symbol)**.**
|
|
2807
|
+
*
|
|
2808
|
+
* ---
|
|
2123
2809
|
* - **Behavior:**
|
|
2124
|
-
*
|
|
2125
|
-
*
|
|
2810
|
+
* - Narrows type to `symbol` when true.
|
|
2811
|
+
* - Uses the `typeof` operator for strict checking.
|
|
2812
|
+
*
|
|
2813
|
+
* ---
|
|
2126
2814
|
* @param {*} value - The value to check.
|
|
2815
|
+
*
|
|
2816
|
+
* ---
|
|
2127
2817
|
* @returns {boolean} Returns `true` if the value is a symbol, otherwise `false`.
|
|
2818
|
+
*
|
|
2819
|
+
* ---
|
|
2128
2820
|
* @example
|
|
2129
|
-
* isSymbol(Symbol("id"));
|
|
2130
|
-
*
|
|
2131
|
-
* isSymbol(
|
|
2132
|
-
*
|
|
2821
|
+
* isSymbol(Symbol("id"));
|
|
2822
|
+
* // ➔ true
|
|
2823
|
+
* isSymbol("not a symbol");
|
|
2824
|
+
* // ➔ false
|
|
2825
|
+
* isSymbol(123);
|
|
2826
|
+
* // ➔ false
|
|
2827
|
+
* isSymbol(undefined);
|
|
2828
|
+
* // ➔ false
|
|
2133
2829
|
*/
|
|
2134
2830
|
declare const isSymbol: (value: unknown) => value is symbol;
|
|
2135
|
-
/**
|
|
2831
|
+
/** ---------------------------------------------------------
|
|
2136
2832
|
* * ***Type guard: `isTypedArray`.***
|
|
2137
2833
|
* ----------------------------------------------------------
|
|
2138
2834
|
* **Checks if `value` is classified as a
|
|
2139
2835
|
* **[`TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)**.**
|
|
2836
|
+
*
|
|
2837
|
+
* ---
|
|
2140
2838
|
* - **Behavior:**
|
|
2141
|
-
*
|
|
2142
|
-
*
|
|
2143
|
-
*
|
|
2839
|
+
* - Validates that `value` is a non-null object.
|
|
2840
|
+
* - Uses `Object.prototype.toString` tag matching against known typed array tags.
|
|
2841
|
+
* - Narrows type to **{@link TypedArray | `TypedArray`}** when true.
|
|
2842
|
+
*
|
|
2843
|
+
* ---
|
|
2144
2844
|
* @param {*} value - The value to check.
|
|
2845
|
+
*
|
|
2846
|
+
* ---
|
|
2145
2847
|
* @returns {boolean} Returns `true` if the value is a typed array, otherwise `false`.
|
|
2848
|
+
*
|
|
2849
|
+
* ---
|
|
2146
2850
|
* @example
|
|
2147
|
-
* isTypedArray(new Uint8Array);
|
|
2148
|
-
*
|
|
2149
|
-
* isTypedArray(new
|
|
2150
|
-
*
|
|
2151
|
-
* isTypedArray(
|
|
2152
|
-
*
|
|
2851
|
+
* isTypedArray(new Uint8Array);
|
|
2852
|
+
* // ➔ true
|
|
2853
|
+
* isTypedArray(new Uint8Array());
|
|
2854
|
+
* // ➔ true
|
|
2855
|
+
* isTypedArray(new Float32Array());
|
|
2856
|
+
* // ➔ true
|
|
2857
|
+
* isTypedArray(new Uint8ClampedArray());
|
|
2858
|
+
* // ➔ true
|
|
2859
|
+
* isTypedArray([]);
|
|
2860
|
+
* // ➔ false
|
|
2861
|
+
* isTypedArray(Buffer.from("hi"));
|
|
2862
|
+
* // ➔ false
|
|
2153
2863
|
*/
|
|
2154
|
-
declare
|
|
2864
|
+
declare const isTypedArray: (value: unknown) => value is TypedArray;
|
|
2155
2865
|
/** ---------------------------------------------------------
|
|
2156
2866
|
* * ***Type guard: `isURL`.***
|
|
2157
2867
|
* ----------------------------------------------------------
|
|
2158
2868
|
* **Checks if a value is an instance of the
|
|
2159
2869
|
* **[`URL`](https://developer.mozilla.org/docs/Web/API/URL)** class.**
|
|
2870
|
+
*
|
|
2871
|
+
* ---
|
|
2160
2872
|
* - **Behavior:**
|
|
2161
|
-
*
|
|
2162
|
-
*
|
|
2873
|
+
* - Narrows type to `URL` when true.
|
|
2874
|
+
* - Excludes `strings`, `plain-objects`, and `other non-URL values`.
|
|
2875
|
+
*
|
|
2876
|
+
* ---
|
|
2163
2877
|
* @param {*} value - The value to check.
|
|
2878
|
+
*
|
|
2879
|
+
* ---
|
|
2164
2880
|
* @returns {boolean} Returns `true` if the value is an instance of `URL`, otherwise `false`.
|
|
2881
|
+
*
|
|
2882
|
+
* ---
|
|
2165
2883
|
* @example
|
|
2166
2884
|
* isURL(new URL("https://example.com"));
|
|
2167
2885
|
* // ➔ true
|
|
@@ -2174,115 +2892,178 @@ declare const isURL: (value: unknown) => value is URL;
|
|
|
2174
2892
|
* ----------------------------------------------------------
|
|
2175
2893
|
* **Checks if a value is
|
|
2176
2894
|
* **[`undefined`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)**.**
|
|
2895
|
+
*
|
|
2896
|
+
* ---
|
|
2177
2897
|
* - **Behavior:**
|
|
2178
|
-
*
|
|
2179
|
-
*
|
|
2180
|
-
*
|
|
2898
|
+
* - Narrows type to `undefined` when true.
|
|
2899
|
+
* - Excludes `null`, `objects`, `arrays`, `strings`, `numbers`, and
|
|
2900
|
+
* `all other values`.
|
|
2901
|
+
*
|
|
2902
|
+
* ---
|
|
2181
2903
|
* @param {*} value - The value to check.
|
|
2904
|
+
*
|
|
2905
|
+
* ---
|
|
2182
2906
|
* @returns {boolean} Returns `true` if the value is `undefined`, otherwise `false`.
|
|
2907
|
+
*
|
|
2908
|
+
* ---
|
|
2183
2909
|
* @example
|
|
2184
|
-
* isUndefined(undefined);
|
|
2185
|
-
*
|
|
2186
|
-
* isUndefined(
|
|
2187
|
-
*
|
|
2188
|
-
* isUndefined(
|
|
2910
|
+
* isUndefined(undefined);
|
|
2911
|
+
* // ➔ true
|
|
2912
|
+
* isUndefined([]);
|
|
2913
|
+
* // ➔ false
|
|
2914
|
+
* isUndefined(123);
|
|
2915
|
+
* // ➔ false
|
|
2916
|
+
* isUndefined(null);
|
|
2917
|
+
* // ➔ false
|
|
2918
|
+
* isUndefined("abc");
|
|
2919
|
+
* // ➔ false
|
|
2189
2920
|
*/
|
|
2190
2921
|
declare const isUndefined: (value: unknown) => value is undefined;
|
|
2191
2922
|
/** ---------------------------------------------------------
|
|
2192
2923
|
* * ***Options for `isValidDomain` predicate.***
|
|
2193
|
-
*
|
|
2924
|
+
* ----------------------------------------------------------
|
|
2194
2925
|
* **Customize the behavior of domain validation.**
|
|
2195
2926
|
*/
|
|
2196
2927
|
type IsValidDomainOptions = {
|
|
2197
|
-
/**
|
|
2928
|
+
/** ---------------------------------------------------------
|
|
2929
|
+
* * ***Enable conversion of Unicode domains (IDN) to ASCII (punycode).***
|
|
2930
|
+
* ----------------------------------------------------------
|
|
2198
2931
|
*
|
|
2199
|
-
* - Example:
|
|
2932
|
+
* - Example:
|
|
2933
|
+
* - `"пример.рф"` ➔ `"xn--e1afmkfd.xn--p1ai"`.
|
|
2200
2934
|
* - Allows validating Unicode domains correctly.
|
|
2201
|
-
* - Default: `false
|
|
2935
|
+
* - Default: `false`.
|
|
2202
2936
|
*
|
|
2203
|
-
*
|
|
2937
|
+
* ---
|
|
2938
|
+
* @default
|
|
2939
|
+
* ```ts
|
|
2940
|
+
* false
|
|
2941
|
+
* ```
|
|
2204
2942
|
*/
|
|
2205
2943
|
allowUnicode?: boolean;
|
|
2206
|
-
/**
|
|
2944
|
+
/** ---------------------------------------------------------
|
|
2945
|
+
* * ***If `true`, validates **only top-level domains (TLDs)** that are not part of any SLD/second-level domain.***
|
|
2946
|
+
* ----------------------------------------------------------
|
|
2207
2947
|
*
|
|
2208
|
-
* -
|
|
2209
|
-
*
|
|
2210
|
-
*
|
|
2211
|
-
*
|
|
2948
|
+
* - Behavior:
|
|
2949
|
+
* - Accepts country-code TLDs like `"ai"` or `"ai."` ✅.
|
|
2950
|
+
* - Rejects common TLDs that are part of SLDs like `"com"` ❌.
|
|
2951
|
+
* - Only the final label is checked; subdomains are ignored.
|
|
2952
|
+
* - Default: `false`.
|
|
2212
2953
|
*
|
|
2213
|
-
*
|
|
2954
|
+
* ---
|
|
2955
|
+
* @default
|
|
2956
|
+
* ```ts
|
|
2957
|
+
* false
|
|
2958
|
+
* ```
|
|
2214
2959
|
*/
|
|
2215
2960
|
topLevel?: boolean;
|
|
2216
|
-
/**
|
|
2961
|
+
/** ---------------------------------------------------------
|
|
2962
|
+
* * ***Allow or disallow subdomains.***
|
|
2963
|
+
* ----------------------------------------------------------
|
|
2217
2964
|
*
|
|
2218
|
-
* - Example:
|
|
2965
|
+
* - Example:
|
|
2966
|
+
* - `"sub.example.com"` ✅ if `subdomain` is `true`, ❌ if `false`.
|
|
2219
2967
|
* - Wildcards and SLDs are considered when evaluating subdomains.
|
|
2220
|
-
* - Default: `true
|
|
2968
|
+
* - Default: `true`.
|
|
2221
2969
|
*
|
|
2222
|
-
*
|
|
2970
|
+
* ---
|
|
2971
|
+
* @default
|
|
2972
|
+
* ```ts
|
|
2973
|
+
* true
|
|
2974
|
+
* ```
|
|
2223
2975
|
*/
|
|
2224
2976
|
subdomain?: boolean;
|
|
2225
|
-
/**
|
|
2977
|
+
/** ---------------------------------------------------------
|
|
2978
|
+
* * ***Allow a wildcard `*` in the left-most label.***
|
|
2979
|
+
* ----------------------------------------------------------
|
|
2226
2980
|
*
|
|
2227
|
-
* - Example:
|
|
2981
|
+
* - Example:
|
|
2982
|
+
* - `"*.example.com"` ✅ if `wildcard` is `true`, ❌ if `false`.
|
|
2228
2983
|
* - Wildcards are only valid in the first label and require at least one additional label.
|
|
2229
|
-
* - Default: `false
|
|
2984
|
+
* - Default: `false`.
|
|
2230
2985
|
*
|
|
2231
|
-
*
|
|
2986
|
+
* ---
|
|
2987
|
+
* @default
|
|
2988
|
+
* ```ts
|
|
2989
|
+
* false
|
|
2990
|
+
* ```
|
|
2232
2991
|
*/
|
|
2233
2992
|
wildcard?: boolean;
|
|
2234
|
-
/**
|
|
2993
|
+
/** ---------------------------------------------------------
|
|
2994
|
+
* * ***Allow a port after the domain.***
|
|
2995
|
+
* ----------------------------------------------------------
|
|
2235
2996
|
*
|
|
2236
|
-
* - Example:
|
|
2997
|
+
* - Example:
|
|
2998
|
+
* - `"localhost:3000"` or `"example.com:8080"` ✅ if `allowPort` is `true`.
|
|
2237
2999
|
* - Validates that the port is a number between `1` and `65535`.
|
|
2238
3000
|
* - Does not affect domain validation rules otherwise.
|
|
2239
|
-
* - Default: `false
|
|
3001
|
+
* - Default: `false`.
|
|
2240
3002
|
*
|
|
2241
|
-
*
|
|
3003
|
+
* ---
|
|
3004
|
+
* @default
|
|
3005
|
+
* ```ts
|
|
3006
|
+
* false
|
|
3007
|
+
* ```
|
|
2242
3008
|
*/
|
|
2243
3009
|
allowPort?: boolean;
|
|
2244
|
-
/**
|
|
3010
|
+
/** ---------------------------------------------------------
|
|
3011
|
+
* * ***Allow special domains like `localhost`.***
|
|
3012
|
+
* ----------------------------------------------------------
|
|
2245
3013
|
*
|
|
2246
|
-
* - Example:
|
|
3014
|
+
* - Example:
|
|
3015
|
+
* - `"localhost"` ✅ if `allowLocalhost` is `true`.
|
|
2247
3016
|
* - Works with or without a port if `allowPort` is enabled.
|
|
2248
|
-
* - Default: `false
|
|
3017
|
+
* - Default: `false`.
|
|
2249
3018
|
*
|
|
2250
|
-
*
|
|
3019
|
+
* ---
|
|
3020
|
+
* @default
|
|
3021
|
+
* ```ts
|
|
3022
|
+
* false
|
|
3023
|
+
* ```
|
|
2251
3024
|
*/
|
|
2252
3025
|
allowLocalhost?: boolean;
|
|
2253
|
-
/**
|
|
3026
|
+
/** ---------------------------------------------------------
|
|
3027
|
+
* * ***Allow URLs with protocol (`http`/`https`) and automatically extract the hostname.***
|
|
3028
|
+
* ----------------------------------------------------------
|
|
2254
3029
|
*
|
|
2255
|
-
* - Example:
|
|
2256
|
-
*
|
|
2257
|
-
* -
|
|
3030
|
+
* - Example:
|
|
3031
|
+
* - `"https://example.com/foo/bar"` ➔ `"example.com"`.
|
|
3032
|
+
* - The function will validate only the hostname part and ***ignore*** the `path`, `query`, and `fragment`.
|
|
3033
|
+
* - Default: `false`.
|
|
2258
3034
|
*
|
|
2259
|
-
*
|
|
3035
|
+
* ---
|
|
3036
|
+
* @default
|
|
3037
|
+
* ```ts
|
|
3038
|
+
* false
|
|
3039
|
+
* ```
|
|
2260
3040
|
*/
|
|
2261
3041
|
allowProtocol?: boolean;
|
|
2262
3042
|
};
|
|
2263
3043
|
/** ---------------------------------------------------------
|
|
2264
3044
|
* * ***Predicate: `isValidDomain`.***
|
|
2265
|
-
*
|
|
3045
|
+
* ----------------------------------------------------------
|
|
2266
3046
|
* **Validates whether a given string is a properly formatted domain name.**
|
|
2267
3047
|
*
|
|
2268
|
-
*
|
|
2269
|
-
*
|
|
2270
|
-
*
|
|
2271
|
-
*
|
|
2272
|
-
*
|
|
2273
|
-
*
|
|
2274
|
-
*
|
|
2275
|
-
*
|
|
2276
|
-
*
|
|
2277
|
-
*
|
|
2278
|
-
*
|
|
2279
|
-
*
|
|
2280
|
-
*
|
|
2281
|
-
*
|
|
2282
|
-
*
|
|
2283
|
-
*
|
|
2284
|
-
*
|
|
2285
|
-
*
|
|
3048
|
+
* ---
|
|
3049
|
+
* - #### *Behavior:*
|
|
3050
|
+
* - Supports options for:
|
|
3051
|
+
* - `allowUnicode` ➔ allows internationalized domain names (IDN) with Unicode characters.
|
|
3052
|
+
* - `topLevel` ➔ validates **only top-level domains (TLDs)**; ignores subdomains and SLDs.
|
|
3053
|
+
* - `subdomain` ➔ allows or disallows subdomains.
|
|
3054
|
+
* - `wildcard` ➔ allows wildcard (`*`) in the left-most label.
|
|
3055
|
+
* - `allowPort` ➔ allows a port number after the domain (e.g., `example.com:8080`).
|
|
3056
|
+
* - `allowLocalhost` ➔ allows the special domain `"localhost"`.
|
|
3057
|
+
* - `allowProtocol` ➔ allows a URL with protocol (`http`/`https`) and extracts the hostname.
|
|
3058
|
+
* - Converts Unicode to ASCII (punycode) if `allowUnicode` is `true`.
|
|
3059
|
+
* - Checks label lengths (`≤63` chars), valid characters, and punycode consistency.
|
|
3060
|
+
* - Validates port if `allowPort` is `true` (must be 1–65535).
|
|
3061
|
+
* - Accepts `"localhost"` if `allowLocalhost` is `true`.
|
|
3062
|
+
* - Extracts hostname from URLs if `allowProtocol` is `true`.
|
|
3063
|
+
* - Rejects invalid domains, labels starting/ending with `-`, double dots, malformed TLDs, or invalid port numbers.
|
|
3064
|
+
* - Handles both standard domains (`example.com`), URLs with protocols (`https://example.com/foo`), and IDNs (`пример.рф`).
|
|
3065
|
+
*
|
|
3066
|
+
* ---
|
|
2286
3067
|
* @param {*} value - The value to validate; only strings are valid domains.
|
|
2287
3068
|
* @param {IsValidDomainOptions} [options] - Optional configuration for domain validation.
|
|
2288
3069
|
* @param {boolean} [options.allowUnicode=false] - Enable punycode conversion for Unicode domains.
|
|
@@ -2292,8 +3073,11 @@ type IsValidDomainOptions = {
|
|
|
2292
3073
|
* @param {boolean} [options.allowPort=false] - Allow port number after domain (e.g., `:3000`); must be 1–65535.
|
|
2293
3074
|
* @param {boolean} [options.allowLocalhost=false] - Allow special domain `"localhost"`.
|
|
2294
3075
|
* @param {boolean} [options.allowProtocol=false] - Allow URLs with protocol (`http`/`https`) and extract hostname only.
|
|
3076
|
+
*
|
|
3077
|
+
* ---
|
|
2295
3078
|
* @returns {boolean} Returns `true` if the value is a valid domain according to the rules and options; otherwise `false`.
|
|
2296
3079
|
*
|
|
3080
|
+
* ---
|
|
2297
3081
|
* @example
|
|
2298
3082
|
* isValidDomain("google.com");
|
|
2299
3083
|
* // ➔ true
|
|
@@ -2318,19 +3102,27 @@ type IsValidDomainOptions = {
|
|
|
2318
3102
|
* isValidDomain("invalid_domain.com");
|
|
2319
3103
|
* // ➔ false
|
|
2320
3104
|
*/
|
|
2321
|
-
declare
|
|
3105
|
+
declare const isValidDomain: (value: unknown, options?: IsValidDomainOptions) => boolean;
|
|
2322
3106
|
/** ---------------------------------------------------------
|
|
2323
3107
|
* * ***Predicate: `isValidURL`.***
|
|
2324
|
-
*
|
|
3108
|
+
* ----------------------------------------------------------
|
|
2325
3109
|
* **Validates whether a given string is a properly formatted URL.**
|
|
2326
|
-
*
|
|
2327
|
-
*
|
|
2328
|
-
*
|
|
2329
|
-
*
|
|
2330
|
-
*
|
|
2331
|
-
*
|
|
3110
|
+
*
|
|
3111
|
+
* ---
|
|
3112
|
+
* - #### *Behavior:*
|
|
3113
|
+
* - **Ensures that the input is:**
|
|
3114
|
+
* - A non-empty string.
|
|
3115
|
+
* - A valid **[`URL`](https://developer.mozilla.org/docs/Web/API/URL)** with `http://` or `https://` scheme.
|
|
3116
|
+
* - Includes decoding for percent-encoded URLs (e.g., `https%3A%2F%2F...`).
|
|
3117
|
+
* - Rejects invalid strings, unsupported schemes, and malformed domains.
|
|
3118
|
+
*
|
|
3119
|
+
* ---
|
|
2332
3120
|
* @param {*} url - The value to validate.
|
|
3121
|
+
*
|
|
3122
|
+
* ---
|
|
2333
3123
|
* @returns {boolean} Return `true` if the value is a **valid URL string**, otherwise `false`.
|
|
3124
|
+
*
|
|
3125
|
+
* ---
|
|
2334
3126
|
* @example
|
|
2335
3127
|
* isValidURL("https://example.com");
|
|
2336
3128
|
* // ➔ true
|
|
@@ -2340,22 +3132,32 @@ declare function isValidDomain(value: unknown, options?: IsValidDomainOptions):
|
|
|
2340
3132
|
* // ➔ false
|
|
2341
3133
|
*/
|
|
2342
3134
|
declare const isValidURL: (url: unknown) => boolean;
|
|
2343
|
-
/**
|
|
3135
|
+
/** ---------------------------------------------------------
|
|
2344
3136
|
* * ***Type guard: `isWeakMap`.***
|
|
2345
3137
|
* ----------------------------------------------------------
|
|
2346
3138
|
* **Checks if a value is a **[`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap/WeakMap)** object.**
|
|
3139
|
+
*
|
|
3140
|
+
* ---
|
|
2347
3141
|
* - **Behavior:**
|
|
2348
|
-
*
|
|
2349
|
-
*
|
|
3142
|
+
* - Narrows type to `WeakMap<K, V>` when true.
|
|
3143
|
+
* - Excludes `Map`, `arrays`, `plain-objects,` and `other non-WeakMap values`.
|
|
3144
|
+
*
|
|
3145
|
+
* ---
|
|
2350
3146
|
* @template K - Keys must be objects.
|
|
2351
3147
|
* @template V - Type of values stored in the WeakMap.
|
|
3148
|
+
*
|
|
3149
|
+
* ---
|
|
2352
3150
|
* @param {*} value - The value to check.
|
|
3151
|
+
*
|
|
3152
|
+
* ---
|
|
2353
3153
|
* @returns {boolean} Returns `true` if the value is a `WeakMap`, otherwise `false`.
|
|
3154
|
+
*
|
|
3155
|
+
* ---
|
|
2354
3156
|
* @example
|
|
2355
3157
|
* isWeakMap(new WeakMap);
|
|
2356
3158
|
* // ➔ true
|
|
2357
3159
|
* isWeakMap(new Map);
|
|
2358
3160
|
* // ➔ false
|
|
2359
3161
|
*/
|
|
2360
|
-
declare
|
|
3162
|
+
declare const isWeakMap: <K extends object = object, V = unknown>(value: unknown) => value is WeakMap<K, V>;
|
|
2361
3163
|
export { isArrayBuffer as $, isInteger as A, isEmptyDeep as B, isNil as C, isMatch as D, isMatchWith as E, isEqualWith as F, isDate as G, isEmpty as H, isEqual as I, isBooleanObject as J, isCurrencyLike as K, isEmptyValue as L, isFunction as M, isFinite as N, isMap as O, isError as P, isArrayLike as Q, isEmptyString as R, isNonEmptyArray as S, isNaN as T, isElement as U, isEmptyArray as V, isDeepEqual as W, isBigInt as X, isBoolean as Y, isArrayLikeObject as Z, isObject as _, isURL as a, textContainsAny as at, isNonEmptyValue as b, isStringObject as c, areURLsEqualPath as ct, isServer as d, isArray as et, isSafeInteger as f, isObjectLoose as g, isObjectOrArray as h, isUndefined as i, doesKeyExist as it, isInfinityNumber as j, isLength as k, isString as l, areObjectsEqual as lt, isPropertyKey as m, isValidURL as n, hasOwnProp as nt, isTypedArray as o, textContainsAll as ot, isRegExp as p, isBuffer as q, isValidDomain as r, arrayHasAnyMatch as rt, isSymbol as s, areURLsIdentical as st, isWeakMap as t, isArguments as tt, isSet as u, areArraysEqual as ut, isNumberObject as v, isNative as w, isNonEmptyString as x, isNull as y, isEmptyObject as z };
|