@rzl-zone/utils-js 3.1.2-beta.0 → 3.2.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 +59 -32
- package/dist/NumberRangeUnion-B6bhM2s7.d.ts +33 -0
- package/dist/{any-BmdI8UbK.d.ts → any-v4TsK9ES.d.ts} +25 -26
- package/dist/{arrays-normalize-recursive-CnjYJ9xg.d.ts → arrays-normalize-recursive-BqmVuFlD.d.ts} +20 -20
- package/dist/assertions/index.cjs +1 -1
- package/dist/assertions/index.d.ts +96 -70
- package/dist/assertions/index.js +1 -1
- package/dist/chunk-2CQX5CBG.js +1 -0
- package/dist/chunk-2IOOEY45.cjs +1 -0
- package/dist/chunk-3IBQ5MOM.js +1 -0
- package/dist/chunk-3VA554KW.js +1 -0
- package/dist/chunk-5757UBXJ.cjs +1 -0
- package/dist/chunk-5IGC6PBH.js +1 -0
- package/dist/chunk-5KJFVIQT.cjs +1 -0
- package/dist/chunk-6JFCSH7J.js +1 -0
- package/dist/chunk-6JFZL7YE.cjs +1 -0
- package/dist/chunk-7ODAAXX5.cjs +1 -0
- package/dist/chunk-BAV5T2E3.cjs +1 -0
- package/dist/chunk-CAH33WOQ.cjs +1 -0
- package/dist/chunk-CKTLUNWX.js +1 -0
- package/dist/chunk-CMW2TBOQ.js +1 -0
- package/dist/chunk-D3ENH7H6.cjs +1 -0
- package/dist/chunk-DEZZUYE2.js +1 -0
- package/dist/chunk-DVMHRLKP.cjs +1 -0
- package/dist/chunk-DWF2R5GD.cjs +1 -0
- package/dist/chunk-E55EQK2U.cjs +1 -0
- package/dist/chunk-E74U6CYP.cjs +1 -0
- package/dist/chunk-EL6A35UR.cjs +1 -0
- package/dist/chunk-F6IPNNSJ.cjs +1 -0
- package/dist/chunk-FJZGG54N.cjs +1 -0
- package/dist/chunk-FWCKOJZM.js +1 -0
- package/dist/chunk-FWHNWL2P.cjs +1 -0
- package/dist/chunk-GGEADHZO.js +1 -0
- package/dist/chunk-GQR4R5WY.js +1 -0
- package/dist/chunk-H66AC7GK.cjs +1 -0
- package/dist/chunk-HQWOFR56.cjs +1 -0
- package/dist/chunk-HYRQMTRH.cjs +1 -0
- package/dist/chunk-IRFL4MAX.js +1 -0
- package/dist/chunk-IVL7CKVH.cjs +1 -0
- package/dist/chunk-IZPBKKPO.js +1 -0
- package/dist/chunk-JBQMXC5I.cjs +1 -0
- package/dist/chunk-JEQEF5WD.js +1 -0
- package/dist/chunk-JMJQCN74.js +1 -0
- package/dist/chunk-JYQTCICM.js +1 -0
- package/dist/chunk-KHO2SBNA.cjs +1 -0
- package/dist/chunk-KVAL5PAG.cjs +1 -0
- package/dist/chunk-L5RDAVVH.js +1 -0
- package/dist/chunk-LS6U7FAY.cjs +1 -0
- package/dist/chunk-NBZWMBO6.js +1 -0
- package/dist/chunk-NRF6LWBC.cjs +1 -0
- package/dist/chunk-OI5XKNZO.js +1 -0
- package/dist/chunk-ONZFBJVW.js +1 -0
- package/dist/chunk-OYTYSY7G.js +1 -0
- package/dist/chunk-PET42Z7W.js +1 -0
- package/dist/chunk-PZQ6I4JJ.cjs +1 -0
- package/dist/chunk-QBKAEVYG.js +1 -0
- package/dist/chunk-QNKGP5DY.js +1 -0
- package/dist/chunk-RIPKY4RU.js +1 -0
- package/dist/chunk-RZW35UN5.cjs +1 -0
- package/dist/chunk-SBFNXGTJ.js +1 -0
- package/dist/chunk-SBKGWRS5.js +1 -0
- package/dist/chunk-SIM77PU4.js +1 -0
- package/dist/chunk-T2T7K3KR.js +1 -0
- package/dist/chunk-T7PU2V7X.cjs +1 -0
- package/dist/chunk-UDA26MCU.cjs +1 -0
- package/dist/chunk-V45XJKHW.cjs +1 -0
- package/dist/chunk-VJDDGRIK.cjs +1 -0
- package/dist/chunk-W2WNBUDE.js +1 -0
- package/dist/chunk-WVSPXFTY.js +1 -0
- package/dist/chunk-XABCB3Y7.cjs +1 -0
- package/dist/chunk-XEDXFSGI.js +1 -0
- package/dist/chunk-YKPSRP5G.js +1 -0
- package/dist/chunk-YLA3DURS.cjs +1 -0
- package/dist/chunk-YWHHVDT4.js +1 -0
- package/dist/chunk-ZETAZZLD.cjs +1 -0
- package/dist/conversions/index.cjs +1 -1
- package/dist/conversions/index.d.ts +515 -321
- package/dist/conversions/index.js +1 -1
- package/dist/events/index.cjs +1 -1
- package/dist/events/index.d.ts +25 -20
- package/dist/events/index.js +1 -1
- package/dist/{extends-Bk_SBGdT.d.ts → extends-DtdRjDyU.d.ts} +63 -87
- package/dist/formatters/index.cjs +1 -0
- package/dist/formatters/index.d.ts +2106 -0
- package/dist/formatters/index.js +1 -0
- package/dist/generators/index.cjs +1 -0
- package/dist/{generator → generators}/index.d.ts +57 -59
- package/dist/generators/index.js +1 -0
- package/dist/{if-CvT4R7Kh.d.ts → if-ChM35c_q.d.ts} +6 -5
- package/dist/{is-array--YjXV-Wx.d.ts → is-array-BJeHxPM3.d.ts} +287 -542
- package/dist/{isPlainObject-BVhBAPHX.d.ts → isPlainObject-DGJkcFYw.d.ts} +6 -6
- package/dist/{never-BfayMBF9.d.ts → never-D89PbPh5.d.ts} +10 -19
- package/dist/next/index.cjs +1 -8
- package/dist/next/index.d.ts +15 -12
- package/dist/next/index.js +1 -8
- package/dist/next/server/index.cjs +1 -2
- package/dist/next/server/index.d.ts +1 -1
- package/dist/next/server/index.js +1 -2
- package/dist/{nils-DMz3kU7M.d.ts → nils-CO8zLHSB.d.ts} +39 -65
- package/dist/operations/index.cjs +1 -1
- package/dist/operations/index.d.ts +4 -4
- package/dist/operations/index.js +1 -1
- package/dist/or-C6qzKt2I.d.ts +82 -0
- package/dist/override-CL2olHE5.d.ts +59 -0
- package/dist/parsers/index.cjs +1 -1
- package/dist/parsers/index.js +1 -1
- package/dist/pick-BSMX6Xe2.d.ts +15 -0
- package/dist/predicates/index.cjs +1 -1
- package/dist/predicates/index.d.ts +425 -106
- package/dist/predicates/index.js +1 -1
- package/dist/prettify-3o8_Kw6b.d.ts +564 -0
- package/dist/promises/index.cjs +1 -0
- package/dist/promises/index.d.ts +107 -0
- package/dist/promises/index.js +1 -0
- package/dist/promises-LU7K00H0.d.ts +72 -0
- package/dist/rzl-utils.global.js +1 -4
- package/dist/{string-XA-til3C.d.ts → string-B1jlOnws.d.ts} +82 -121
- package/dist/strings/index.cjs +1 -1
- package/dist/strings/index.d.ts +209 -210
- package/dist/strings/index.js +1 -1
- package/dist/tailwind/index.cjs +1 -0
- package/dist/tailwind/index.d.ts +571 -0
- package/dist/tailwind/index.js +1 -0
- package/dist/types/index.d.ts +899 -1181
- package/dist/urls/index.cjs +1 -1
- package/dist/urls/index.d.ts +113 -108
- package/dist/urls/index.js +1 -1
- package/package.json +45 -47
- package/dist/NumberRangeUnion-DC-C3_Kq.d.ts +0 -26
- package/dist/chunk-26W3VZIK.cjs +0 -1
- package/dist/chunk-2KRCHXFG.cjs +0 -2
- package/dist/chunk-33ZLH266.js +0 -1
- package/dist/chunk-4L4EJTNZ.js +0 -1
- package/dist/chunk-56QBKKRE.js +0 -1
- package/dist/chunk-5Q37AP7P.js +0 -1
- package/dist/chunk-5SZUSNGZ.js +0 -1
- package/dist/chunk-7CHFAMS2.js +0 -1
- package/dist/chunk-7MMJZ6HS.js +0 -1
- package/dist/chunk-7TC6DE3J.cjs +0 -1
- package/dist/chunk-7VX33E3V.js +0 -1
- package/dist/chunk-7YWAQOA4.cjs +0 -1
- package/dist/chunk-BEZPD44N.cjs +0 -1
- package/dist/chunk-BI263OHW.js +0 -1
- package/dist/chunk-CII6WWLO.cjs +0 -1
- package/dist/chunk-D5TYPCWU.cjs +0 -1
- package/dist/chunk-EEQY5QUG.js +0 -1
- package/dist/chunk-ELDDNERR.js +0 -1
- package/dist/chunk-ESJYBIYH.js +0 -1
- package/dist/chunk-EWYPSKKM.js +0 -1
- package/dist/chunk-EXCOQLWX.cjs +0 -1
- package/dist/chunk-FIEZKTAZ.cjs +0 -1
- package/dist/chunk-FWQVTMYA.cjs +0 -1
- package/dist/chunk-G4EWCRKS.js +0 -1
- package/dist/chunk-G5LXIEFO.js +0 -0
- package/dist/chunk-G7R5XZRM.cjs +0 -1
- package/dist/chunk-GGEV7LXX.cjs +0 -1
- package/dist/chunk-HJOZOENU.cjs +0 -1
- package/dist/chunk-IRDZVLNZ.cjs +0 -1
- package/dist/chunk-IW73G523.cjs +0 -1
- package/dist/chunk-IY5OZAB3.cjs +0 -1
- package/dist/chunk-J4NCYYGS.js +0 -1
- package/dist/chunk-J7JAZAJD.js +0 -1
- package/dist/chunk-JYNSO7ZY.js +0 -1
- package/dist/chunk-K3UVKYEU.js +0 -1
- package/dist/chunk-LQ76EDZG.js +0 -1
- package/dist/chunk-MMSYCIJ2.cjs +0 -1
- package/dist/chunk-MROH35V3.cjs +0 -1
- package/dist/chunk-NJSAV73S.js +0 -1
- package/dist/chunk-NNM7QCNB.js +0 -1
- package/dist/chunk-NR44SNYE.js +0 -1
- package/dist/chunk-NXMTWY77.js +0 -1
- package/dist/chunk-OZCQZO2V.cjs +0 -4
- package/dist/chunk-PUQXRLZH.cjs +0 -1
- package/dist/chunk-Q3NTKN5I.cjs +0 -1
- package/dist/chunk-QDNSC57Z.js +0 -4
- package/dist/chunk-QGXTL5ZH.js +0 -2
- package/dist/chunk-QSQDP7L2.cjs +0 -1
- package/dist/chunk-RV2VULM7.cjs +0 -1
- package/dist/chunk-S5M33A4O.js +0 -1
- package/dist/chunk-SGTHOQQ2.js +0 -1
- package/dist/chunk-SL3RQOWA.js +0 -1
- package/dist/chunk-SW6HYEW7.cjs +0 -1
- package/dist/chunk-SYJC7UAW.js +0 -1
- package/dist/chunk-SZPWZZYG.cjs +0 -1
- package/dist/chunk-UA4B7JBO.cjs +0 -1
- package/dist/chunk-UQDJF5RR.cjs +0 -1
- package/dist/chunk-UTQUYABU.cjs +0 -1
- package/dist/chunk-VPW3DRV5.js +0 -1
- package/dist/chunk-W32WALNU.js +0 -1
- package/dist/chunk-XGZ6K753.cjs +0 -1
- package/dist/chunk-YFTR64N5.cjs +0 -1
- package/dist/chunk-ZFDS7W6B.cjs +0 -1
- package/dist/chunk-ZQOLZE6Z.cjs +0 -1
- package/dist/env/index.cjs +0 -1
- package/dist/env/index.d.ts +0 -16
- package/dist/env/index.js +0 -1
- package/dist/formatting/index.cjs +0 -1
- package/dist/formatting/index.d.ts +0 -950
- package/dist/formatting/index.js +0 -1
- package/dist/generator/index.cjs +0 -1
- package/dist/generator/index.js +0 -1
- package/dist/omit-VvmIsZmX.d.ts +0 -28
- package/dist/prettify-C4xLcYOP.d.ts +0 -353
- package/dist/promise/index.cjs +0 -1
- package/dist/promise/index.d.ts +0 -31
- package/dist/promise/index.js +0 -1
- package/dist/stylings/index.cjs +0 -1
- package/dist/stylings/index.d.ts +0 -41
- package/dist/stylings/index.js +0 -1
- package/dist/type-data-DDs-u2kq.d.ts +0 -261
package/dist/types/index.d.ts
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
|
-
import{A as And,I as IsStringLiteral,P as ParseNumber,a as IsNegative,N as Negate,
|
|
1
|
+
import{A as And,b as Or,O as OrArr,a as AndArr}from'../or-C6qzKt2I.js';import{I as IsStringLiteral,P as ParseNumber,a as IsNegative,N as Negate,A as Abs,b as IsFloat,c as IsUnknown,d as IsNegativeInteger,S as Split,e as IsInteger,R as Repeat,f as Push,g as IfNegative,h as IsPositive,i as IsEven,j as IsReadonlyArray,k as IfPositive}from'../is-array-BJeHxPM3.js';export{C as CharAt,E as Even,q as EvenDigit,F as Float,r as IfEven,s as IfFloat,t as IfInteger,u as IfNegativeFloat,v as IfNegativeInteger,w as IfOdd,x as IfPositiveFloat,y as IfPositiveInteger,Y as IfUnknown,z as Integer,l as IsArray,m as IsMutableArray,B as IsNegativeFloat,D as IsOdd,G as IsPositiveFloat,H as IsPositiveInteger,J as IsScientificNumber,M as Mutable,n as MutableExcept,o as MutableOnly,p as MutableOptions,K as Negative,L as NegativeFloat,O as NegativeInteger,Q as Odd,T as OddDigit,U as ParseScientificNumber,V as Positive,W as PositiveFloat,X as PositiveInteger,Z as UnknownifyProperties,_ as UnknownifyPropertiesOptions}from'../is-array-BJeHxPM3.js';import{a as IsEmptyString,b as IfEmptyString,T as Trim,A as AnyString}from'../string-B1jlOnws.js';export{E as EmptyString,d as IfNonEmptyString,I as IfNot,e as IsNonEmptyString,N as NonEmptyString,f as TrimLeft,g as TrimRight,h as TrimsLower,i as TrimsUpper,W as Whitespace,c as WordSeparator}from'../string-B1jlOnws.js';import{I as IsAny}from'../any-v4TsK9ES.js';export{A as AnifyProperties,a as AnifyPropertiesOptions,b as IfAny}from'../any-v4TsK9ES.js';import{A as AnyFunction,T as TypedArray,P as Prettify,a as PrettifyOptions,D as DefaultPrettifyOptions}from'../prettify-3o8_Kw6b.js';export{g as AnObjectNonArray,B as BoxedPrimitivesTypes,h as DataTypes,i as DeepReplaceType,j as IntlObjects,I as IsArrayOrTuple,b as IsConstructor,c as IsFunction,d as IsPrimitive,e as IsRealPrimitive,N as NonPlainObject,f as Primitive,W as WebApiObjects}from'../prettify-3o8_Kw6b.js';import{I as IfExtends,N as Not,a as NotExtends,b as IsEmptyArray,P as Pop,E as Extends,c as ExtendsArr,d as IfEmptyArray}from'../extends-DtdRjDyU.js';export{A as Arrayable,e as EmptyArray,G as GetArrayElementType,f as IfNonEmptyArray,i as IfNotExtends,g as IsNonEmptyArray,M as MutableArray,h as NonEmptyArray,j as PopOptions}from'../extends-DtdRjDyU.js';export{F as FixNeverArrayRecursive,N as NormalizeEmptyArraysRecursive,R as RemoveEmptyArrayElements}from'../arrays-normalize-recursive-BqmVuFlD.js';import{I as If}from'../if-ChM35c_q.js';import{I as IsNever,a as IfNever}from'../never-D89PbPh5.js';export{N as NeverifyProperties,b as NeverifyPropertiesOptions}from'../never-D89PbPh5.js';export{E as ExtractStrict,O as OmitStrict,a as OverrideTypes}from'../override-CL2olHE5.js';import{N as NonUndefined}from'../nils-CO8zLHSB.js';export{K as KeepNil,a as KeepNull,b as KeepUndef,c as Nilable,d as NonNil,e as NonNull,g as NullToUndefined,f as Nullable,h as Nullish,U as Undefinedable}from'../nils-CO8zLHSB.js';export{N as NumberRangeUnion}from'../NumberRangeUnion-B6bhM2s7.js';export{P as PickStrict}from'../pick-BSMX6Xe2.js';export{A as Awaitable,C as CustomPromiseType}from'../promises-LU7K00H0.js';
|
|
2
|
+
/** @private ***types for {@link AreAnagrams}.*** */
|
|
3
|
+
type _AreAnagrams<Str1 extends string,Str2 extends string>=IsEmptyString<Str1>extends true?IsEmptyString<Str2>extends true?true:false:Str1 extends`${infer First extends string}${infer Rest1 extends string}`?Str2 extends`${infer Prev extends string}${First}${infer Rest2 extends string}`?_AreAnagrams<Rest1,`${Prev}${Rest2}`>:false:never;
|
|
2
4
|
/** -------------------------------------------------------
|
|
3
|
-
* * ***AreAnagrams
|
|
5
|
+
* * ***Utility Type: `AreAnagrams`.***
|
|
4
6
|
* -------------------------------------------------------
|
|
5
|
-
* Determines whether two string literal types are ***anagrams*** of each other
|
|
6
|
-
* -
|
|
7
|
-
*
|
|
8
|
-
*
|
|
7
|
+
* **Determines whether two string literal types are ***anagrams*** of each other.**
|
|
8
|
+
* - **Behavior:**
|
|
9
|
+
* - Returns `true` if both strings contain exactly the same characters in
|
|
10
|
+
* any order.
|
|
11
|
+
* - Returns `false` otherwise.
|
|
9
12
|
* @template Str1 - The first string literal.
|
|
10
13
|
* @template Str2 - The second string literal.
|
|
11
14
|
* @example
|
|
@@ -22,15 +25,12 @@ import{A as And,I as IsStringLiteral,P as ParseNumber,a as IsNegative,N as Negat
|
|
|
22
25
|
*/
|
|
23
26
|
type AreAnagrams<Str1 extends string,Str2 extends string>=And<IsStringLiteral<Str1>,IsStringLiteral<Str2>>extends true?_AreAnagrams<Str1,Str2>:false;
|
|
24
27
|
/** --------------------------------------------------
|
|
25
|
-
* * ***ArgumentTypes
|
|
28
|
+
* * ***Utility Type: `ArgumentTypes`.***
|
|
26
29
|
* --------------------------------------------------
|
|
27
|
-
* Extracts the **argument types** of a given function type `F
|
|
28
|
-
*
|
|
29
|
-
* ✅ Useful when you need to infer or reuse the parameter types
|
|
30
|
+
* **Extracts the **argument types** of a given function type `F`.**
|
|
31
|
+
* - ✅ Useful when you need to infer or reuse the parameter types
|
|
30
32
|
* from an existing function signature.
|
|
31
|
-
*
|
|
32
33
|
* @template F - A function type from which to extract argument types.
|
|
33
|
-
*
|
|
34
34
|
* @example
|
|
35
35
|
* ```ts
|
|
36
36
|
* type Args = ArgumentTypes<(a: number, b: string) => void>;
|
|
@@ -39,12 +39,12 @@ type AreAnagrams<Str1 extends string,Str2 extends string>=And<IsStringLiteral<St
|
|
|
39
39
|
*/
|
|
40
40
|
type ArgumentTypes<F extends AnyFunction>=F extends(...args:infer A)=>any?A:never;
|
|
41
41
|
/** -------------------------------------------------------
|
|
42
|
-
* * ***ArrayElementType
|
|
42
|
+
* * ***Utility Type: `ArrayElementType`.***
|
|
43
43
|
* -------------------------------------------------------
|
|
44
|
-
* A type-level utility that extracts the element type of an array
|
|
45
|
-
* -
|
|
46
|
-
*
|
|
47
|
-
*
|
|
44
|
+
* **A type-level utility that extracts the element type of an array.**
|
|
45
|
+
* - **Behavior:**
|
|
46
|
+
* - Works with both mutable and readonly arrays.
|
|
47
|
+
* - If `T` is not an array, resolves to `never`.
|
|
48
48
|
* @template T - The array type to extract the element type from.
|
|
49
49
|
* @example
|
|
50
50
|
* ```ts
|
|
@@ -56,15 +56,19 @@ type ArgumentTypes<F extends AnyFunction>=F extends(...args:infer A)=>any?A:neve
|
|
|
56
56
|
* // ➔ never
|
|
57
57
|
* ```
|
|
58
58
|
*/
|
|
59
|
-
type ArrayElementType<T extends readonly unknown[]>=T extends Readonly<Array<infer Item>>?Item:never;
|
|
59
|
+
type ArrayElementType<T extends readonly unknown[]>=T extends Readonly<Array<infer Item>>?Item:never;
|
|
60
|
+
/** ---------------------------------------------------------------------------
|
|
61
|
+
* * ***Type Options for {@link LastCharacter | `LastCharacter`}.***
|
|
62
|
+
* ---------------------------------------------------------------------------
|
|
63
|
+
*/
|
|
64
|
+
type LastCharacterOptions={includeRest:boolean;};type _LastCharacter<T extends string,Options extends LastCharacterOptions={includeRest:false;},Previous extends string="">=string extends T?string:T extends`${infer First}${infer Rest}`?IsEmptyString<Rest>extends true?If<Options["includeRest"],[First,Previous],First>:_LastCharacter<Rest,Options,`${Previous}${First}`>:T;
|
|
60
65
|
/** -------------------------------------------------------
|
|
61
|
-
* * ***LastCharacter
|
|
66
|
+
* * ***Utility Type: `LastCharacter`.***
|
|
62
67
|
* -------------------------------------------------------
|
|
63
|
-
* Accepts a string argument and returns its last character
|
|
68
|
+
* **Accepts a string argument and returns its last character.**
|
|
64
69
|
* - If the `includeRest` option is `true`, returns the last character and the rest of the string in the format: `[last, rest]`.
|
|
65
|
-
*
|
|
66
|
-
* @template
|
|
67
|
-
* @template Options - Options to include the rest of the string
|
|
70
|
+
* @template T - The string to get the last character from.
|
|
71
|
+
* @template Options - Options to include the rest of the string.
|
|
68
72
|
* @example
|
|
69
73
|
* type Case1 = LastCharacter<'abc'>;
|
|
70
74
|
* // ➔ 'c'
|
|
@@ -73,21 +77,18 @@ type ArrayElementType<T extends readonly unknown[]>=T extends Readonly<Array<inf
|
|
|
73
77
|
*/
|
|
74
78
|
type LastCharacter<T extends string,Options extends LastCharacterOptions={includeRest:false;}>=IfExtends<Options,LastCharacterOptions,_LastCharacter<T,Options>,_LastCharacter<T>>;
|
|
75
79
|
/** -------------------------------------------------------
|
|
76
|
-
* * ***Stringify
|
|
77
|
-
* -------------------------------------------------------
|
|
78
|
-
* Converts a value of type `number`, `boolean`, `string`, `bigint`, `undefined`, or `null` into a string literal type
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
*
|
|
85
|
-
*
|
|
86
|
-
*
|
|
87
|
-
* - Other types → `never`
|
|
88
|
-
*
|
|
80
|
+
* * ***Utility Type: `Stringify`.***
|
|
81
|
+
* -------------------------------------------------------
|
|
82
|
+
* **Converts a value of type `number`, `boolean`, `string`, `bigint`, `undefined`, or `null` into a string literal type.**
|
|
83
|
+
* - **Behavior:**
|
|
84
|
+
* - `number` ➔ string representation (e.g., `123` ➔ `"123"`)
|
|
85
|
+
* - `boolean` ➔ `"true"` or `"false"`
|
|
86
|
+
* - `string` ➔ itself
|
|
87
|
+
* - `bigint` ➔ string representation with `"n"` suffix (e.g., `123n` ➔ `"123n"`)
|
|
88
|
+
* - `undefined` ➔ `"undefined"`
|
|
89
|
+
* - `null` ➔ `"null"`
|
|
90
|
+
* - Other types ➔ `never`
|
|
89
91
|
* @template T - The value type to stringify.
|
|
90
|
-
*
|
|
91
92
|
* @example
|
|
92
93
|
* ```ts
|
|
93
94
|
* // Boolean
|
|
@@ -121,22 +122,17 @@ type LastCharacter<T extends string,Options extends LastCharacterOptions={includ
|
|
|
121
122
|
*/
|
|
122
123
|
type Stringify<T>=T extends number|boolean|string|bigint|undefined|null?T extends bigint?`${T}n`:`${T}`:never;type DecrementMap=[-1,0,1,2,3,4,5,6,7,8];type NegativeCarryMap={"-1":9;};
|
|
123
124
|
/** -------------------------------------------------------
|
|
124
|
-
* * ***_Decrement (Internal / Deprecated)
|
|
125
|
+
* * ***Internal Utility Type: `_Decrement (Internal / Deprecated)`***
|
|
125
126
|
* -------------------------------------------------------
|
|
126
|
-
*
|
|
127
|
-
*
|
|
128
|
-
*
|
|
129
|
-
*
|
|
130
|
-
* Use the public {@link Decrement} type instead.
|
|
131
|
-
*
|
|
127
|
+
* **Internal type-level utility to decrement a numeric string by 1.**
|
|
128
|
+
* - **⚠️ Deprecated:**
|
|
129
|
+
* - Do **not** use this directly.
|
|
130
|
+
* - Use the public {@link Decrement | **`Decrement`**} type instead.
|
|
132
131
|
* - Processes the string recursively digit by digit.
|
|
133
132
|
* - Handles borrow/carry using internal `DecrementMap` and `NegativeCarryMap`.
|
|
134
|
-
*
|
|
135
133
|
* @template Number - The numeric string to decrement.
|
|
136
134
|
* @template Result - (Internal) Accumulator used during recursion.
|
|
137
|
-
*
|
|
138
|
-
* @deprecated Use {@link Decrement} instead.
|
|
139
|
-
*
|
|
135
|
+
* @deprecated Use {@link Decrement | **`Decrement`**} instead.
|
|
140
136
|
* @example
|
|
141
137
|
* ```ts
|
|
142
138
|
* // ❌ Avoid using _Decrement directly
|
|
@@ -148,11 +144,10 @@ type Stringify<T>=T extends number|boolean|string|bigint|undefined|null?T extend
|
|
|
148
144
|
*/
|
|
149
145
|
type _Decrement<Number extends string,Result extends string="">=Number extends""?ParseNumber<Result>:ParseNumber<LastCharacter<Number>>extends infer LastDigit extends number?DecrementMap[LastDigit] extends infer Decremented extends number?Number extends`${infer Rest}${LastDigit}`?`${Decremented}`extends keyof NegativeCarryMap?_Decrement<Rest,`${NegativeCarryMap[`${Decremented}`]}${Result}`>:`${Rest}${Decremented}${Result}`extends infer FinalResult extends string?ParseNumber<FinalResult extends`0${infer FinalResultWithoutLeadingZero extends string}`?FinalResultWithoutLeadingZero extends""?FinalResult:FinalResultWithoutLeadingZero:FinalResult>:never:never:never:never;type _DecrementNegativeOrZero<T extends number>=_Increment<Stringify<T>>extends infer PositiveDecrementResult extends number?PositiveDecrementResult extends 0?PositiveDecrementResult:Negate<PositiveDecrementResult>:never;
|
|
150
146
|
/** -------------------------------------------------------
|
|
151
|
-
* * ***Decrement
|
|
147
|
+
* * ***Utility Type: `Decrement`.***
|
|
152
148
|
* --------------------------------------------------------
|
|
153
|
-
* A type-level utility that returns the decremented value of an integer
|
|
154
|
-
* Works for numbers in the range `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
155
|
-
*
|
|
149
|
+
* **A type-level utility that returns the decremented value of an integer.**
|
|
150
|
+
* - Works for numbers in the range `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
156
151
|
* @template T - The number type to decrement.
|
|
157
152
|
* @example
|
|
158
153
|
* ```ts
|
|
@@ -165,22 +160,17 @@ type _Decrement<Number extends string,Result extends string="">=Number extends""
|
|
|
165
160
|
*/
|
|
166
161
|
type Decrement<T extends number>=IsNegative<T>extends true?_DecrementNegativeOrZero<Abs<T>>:T extends 0?_DecrementNegativeOrZero<T>:_Decrement<Stringify<T>>;type IncrementMap=[1,2,3,4,5,6,7,8,9,10];type LastDigitMap={10:0;};
|
|
167
162
|
/** -------------------------------------------------------
|
|
168
|
-
* * ***_Increment (Internal / Deprecated)
|
|
163
|
+
* * ***Internal Utility Type: `_Increment (Internal / Deprecated)`***
|
|
169
164
|
* -------------------------------------------------------
|
|
170
|
-
*
|
|
171
|
-
*
|
|
172
|
-
*
|
|
173
|
-
*
|
|
174
|
-
* Use the public {@link Increment} type instead.
|
|
175
|
-
*
|
|
165
|
+
* **Internal type-level utility to increment a numeric string by 1.**
|
|
166
|
+
* - **⚠️ Deprecated:**
|
|
167
|
+
* - Do **not** use this directly.
|
|
168
|
+
* - Use the public {@link Increment | **`Increment`**} type instead.
|
|
176
169
|
* - Processes the string recursively digit by digit.
|
|
177
170
|
* - Handles carry-over using internal `IncrementMap` and `LastDigitMap`.
|
|
178
|
-
*
|
|
179
171
|
* @template Number - The numeric string to increment.
|
|
180
172
|
* @template Result - (Internal) Accumulator used during recursion.
|
|
181
|
-
*
|
|
182
|
-
* @deprecated Use {@link Increment} instead.
|
|
183
|
-
*
|
|
173
|
+
* @deprecated Use {@link Increment | **`Increment`**} instead.
|
|
184
174
|
* @example
|
|
185
175
|
* ```ts
|
|
186
176
|
* // ❌ Avoid using _Increment directly
|
|
@@ -192,49 +182,48 @@ type Decrement<T extends number>=IsNegative<T>extends true?_DecrementNegativeOrZ
|
|
|
192
182
|
*/
|
|
193
183
|
type _Increment<Number extends string,Result extends string="">=IsEmptyString<Number>extends true?ParseNumber<`1${Result}`>:LastCharacter<Number>extends`${infer LastDigit extends number}`?IncrementMap[LastDigit] extends infer Incremented extends number?Number extends`${infer Rest}${LastDigit}`?Incremented extends keyof LastDigitMap?_Increment<Rest,`${LastDigitMap[Incremented]}${Result}`>:ParseNumber<`${Rest}${Incremented}${Result}`>:never:never:never;
|
|
194
184
|
/** -------------------------------------------------------
|
|
195
|
-
* * ***Increment
|
|
185
|
+
* * ***Utility Type: `Increment`.***
|
|
196
186
|
* -------------------------------------------------------
|
|
197
|
-
* Accepts an integer and returns the incremented value of it
|
|
198
|
-
*
|
|
187
|
+
* **Accepts an integer and returns the incremented value of it.**
|
|
188
|
+
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`
|
|
199
189
|
* @template T - The input number to increment.
|
|
200
190
|
* @example
|
|
201
191
|
* ```ts
|
|
202
|
-
* type Case1 = Increment<1>;
|
|
192
|
+
* type Case1 = Increment<1>; // ➔ 2
|
|
203
193
|
* type Case2 = Increment<-10>; // ➔ -9
|
|
204
194
|
* ```
|
|
205
195
|
*/
|
|
206
196
|
type Increment<T extends number>=IsNegative<T>extends true?_Decrement<Stringify<Abs<T>>>extends infer NegativeIncrementResult extends number?NegativeIncrementResult extends 0?NegativeIncrementResult:Negate<NegativeIncrementResult>:never:_Increment<Stringify<T>>;
|
|
207
197
|
/** -------------------------------------------------------
|
|
208
|
-
* * ***GetFloatNumberParts
|
|
198
|
+
* * ***Utility Type: `GetFloatNumberParts`.***
|
|
209
199
|
* -------------------------------------------------------
|
|
210
|
-
* Returns a tuple of the **whole** and **fraction** parts of a float number `T
|
|
211
|
-
*
|
|
212
|
-
*
|
|
213
|
-
*
|
|
214
|
-
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
200
|
+
* **Returns a tuple of the **whole** and **fraction** parts of a float number `T`.**
|
|
201
|
+
* - **Behavior:**
|
|
202
|
+
* - Only works for **float numbers** (i.e., numbers with a fractional part):
|
|
203
|
+
* - If `T` is not a float, the result is `never`.
|
|
204
|
+
* - Preserves the sign on the whole part (e.g. `-12.25` ➔ `[-12, 25]`).
|
|
205
|
+
* - For values like `-0.x`, the TypeScript will normalizes `-0` to `0`,
|
|
206
|
+
* so the result will be `[0, ...]`.
|
|
218
207
|
* @template T - A float number type.
|
|
219
208
|
* @example
|
|
220
209
|
* ```ts
|
|
221
|
-
* type A = GetFloatNumberParts<12.25>;
|
|
222
|
-
* type B = GetFloatNumberParts<-12.25>;
|
|
223
|
-
* type C = GetFloatNumberParts<3.1415>;
|
|
224
|
-
* type D = GetFloatNumberParts<-0.75>;
|
|
225
|
-
* type E = GetFloatNumberParts<42>;
|
|
210
|
+
* type A = GetFloatNumberParts<12.25>; // ➔ [12, 25]
|
|
211
|
+
* type B = GetFloatNumberParts<-12.25>; // ➔ [-12, 25]
|
|
212
|
+
* type C = GetFloatNumberParts<3.1415>; // ➔ [3, 1415]
|
|
213
|
+
* type D = GetFloatNumberParts<-0.75>; // ➔ [0, 75] (`-0` normalized to `0`)
|
|
214
|
+
* type E = GetFloatNumberParts<42>; // ➔ never (not a float)
|
|
226
215
|
* ```
|
|
227
216
|
*/
|
|
228
217
|
type GetFloatNumberParts<T extends number>=IsFloat<T>extends true?`${T}`extends`${infer Whole extends number}.${infer Fraction extends number}`?[IsNegative<T>extends true?Whole:Whole,Fraction]:never:never;
|
|
229
218
|
/** -------------------------------------------------------
|
|
230
|
-
* * ***Ceil
|
|
219
|
+
* * ***Utility Type: `Ceil`.***
|
|
231
220
|
* -------------------------------------------------------
|
|
232
|
-
* A type-level utility that computes the **mathematical ceiling**
|
|
233
|
-
* of a numeric literal type `T`, type version of `Math.ceil()
|
|
234
|
-
* -
|
|
235
|
-
*
|
|
236
|
-
*
|
|
237
|
-
*
|
|
221
|
+
* **A type-level utility that computes the **mathematical ceiling**
|
|
222
|
+
* of a numeric literal type `T`, type version of `Math.ceil()`.**
|
|
223
|
+
* - **Behavior:**
|
|
224
|
+
* - If `T` is an integer, it returns `T` unchanged.
|
|
225
|
+
* - If `T` is a positive float, it rounds up to the nearest integer.
|
|
226
|
+
* - If `T` is a negative float, it rounds up toward zero.
|
|
238
227
|
* @template T - A number literal type.
|
|
239
228
|
* @example
|
|
240
229
|
* ```ts
|
|
@@ -248,41 +237,37 @@ type GetFloatNumberParts<T extends number>=IsFloat<T>extends true?`${T}`extends`
|
|
|
248
237
|
*/
|
|
249
238
|
type Ceil<T extends number>=IsFloat<T>extends true?GetFloatNumberParts<T>extends [infer Whole extends number,unknown]?IsNegative<T>extends true?Negate<Whole>:Increment<Whole>:never:T;
|
|
250
239
|
/** -------------------------------------------------------
|
|
251
|
-
* * ***ColorCssNamed
|
|
240
|
+
* * ***Utility Type: `ColorCssNamed`.***
|
|
252
241
|
* -------------------------------------------------------
|
|
253
|
-
*
|
|
254
|
-
*
|
|
255
|
-
*
|
|
242
|
+
* **Represents a **named CSS color keyword**, including `transparent`.**
|
|
243
|
+
* @description
|
|
256
244
|
* This type includes all standard color names defined in the CSS Color Module Level 4
|
|
257
245
|
* specification, and ensures type safety for string values in strongly typed UI libraries,
|
|
258
246
|
* themes, or design systems.
|
|
259
|
-
*
|
|
260
|
-
* Only recognized, browser-supported named colors are allowed.
|
|
261
|
-
*
|
|
247
|
+
* - **Behavior:**
|
|
248
|
+
* - Only recognized, browser-supported named colors are allowed.
|
|
262
249
|
* @see https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
|
|
263
250
|
* @see https://drafts.csswg.org/css-color-4/#named-colors
|
|
264
|
-
*
|
|
265
251
|
* @example
|
|
266
252
|
* ```ts
|
|
267
|
-
* const textColor1: ColorCssNamed = "rebeccapurple"; // ✅ valid
|
|
268
|
-
* const textColor2: ColorCssNamed = "navy"; // ✅ valid
|
|
269
|
-
* const textColor3: ColorCssNamed = "superblue"; // ❌ Type error
|
|
253
|
+
* const textColor1: ColorCssNamed = "rebeccapurple"; // ➔ ✅ valid
|
|
254
|
+
* const textColor2: ColorCssNamed = "navy"; // ➔ ✅ valid
|
|
255
|
+
* const textColor3: ColorCssNamed = "superblue"; // ➔ ❌ Type error
|
|
270
256
|
*
|
|
271
257
|
* // Usage in a theme object
|
|
272
|
-
* const theme = {
|
|
273
|
-
* primary: "blue"
|
|
274
|
-
* secondary: "goldenrod"
|
|
275
|
-
* highlight: "transparent"
|
|
258
|
+
* const theme: Record<string, ColorCssNamed> = {
|
|
259
|
+
* primary: "blue",
|
|
260
|
+
* secondary: "goldenrod",
|
|
261
|
+
* highlight: "transparent",
|
|
276
262
|
* };
|
|
277
263
|
* ```
|
|
278
264
|
*/
|
|
279
265
|
type ColorCssNamed="aliceblue"|"antiquewhite"|"aqua"|"aquamarine"|"azure"|"beige"|"bisque"|"black"|"blanchedalmond"|"blue"|"blueviolet"|"brown"|"burlywood"|"cadetblue"|"chartreuse"|"chocolate"|"coral"|"cornflowerblue"|"cornsilk"|"crimson"|"cyan"|"darkblue"|"darkcyan"|"darkgoldenrod"|"darkgray"|"darkgreen"|"darkgrey"|"darkkhaki"|"darkmagenta"|"darkolivegreen"|"darkorange"|"darkorchid"|"darkred"|"darksalmon"|"darkseagreen"|"darkslateblue"|"darkslategray"|"darkslategrey"|"darkturquoise"|"darkviolet"|"deeppink"|"deepskyblue"|"dimgray"|"dimgrey"|"dodgerblue"|"firebrick"|"floralwhite"|"forestgreen"|"fuchsia"|"gainsboro"|"ghostwhite"|"gold"|"goldenrod"|"gray"|"green"|"greenyellow"|"grey"|"honeydew"|"hotpink"|"indianred"|"indigo"|"ivory"|"khaki"|"lavender"|"lavenderblush"|"lawngreen"|"lemonchiffon"|"lightblue"|"lightcoral"|"lightcyan"|"lightgoldenrodyellow"|"lightgray"|"lightgreen"|"lightgrey"|"lightpink"|"lightsalmon"|"lightseagreen"|"lightskyblue"|"lightslategray"|"lightslategrey"|"lightsteelblue"|"lightyellow"|"lime"|"limegreen"|"linen"|"magenta"|"maroon"|"mediumaquamarine"|"mediumblue"|"mediumorchid"|"mediumpurple"|"mediumseagreen"|"mediumslateblue"|"mediumspringgreen"|"mediumturquoise"|"mediumvioletred"|"midnightblue"|"mintcream"|"mistyrose"|"moccasin"|"navajowhite"|"navy"|"oldlace"|"olive"|"olivedrab"|"orange"|"orangered"|"orchid"|"palegoldenrod"|"palegreen"|"paleturquoise"|"palevioletred"|"papayawhip"|"peachpuff"|"peru"|"pink"|"plum"|"powderblue"|"purple"|"rebeccapurple"|"red"|"rosybrown"|"royalblue"|"saddlebrown"|"salmon"|"sandybrown"|"seagreen"|"seashell"|"sienna"|"silver"|"skyblue"|"slateblue"|"slategray"|"slategrey"|"snow"|"springgreen"|"steelblue"|"tan"|"teal"|"thistle"|"tomato"|"transparent"|"turquoise"|"violet"|"wheat"|"white"|"whitesmoke"|"yellow"|"yellowgreen";
|
|
280
266
|
/** -------------------------------------------------------
|
|
281
|
-
* * ***IsEqual
|
|
267
|
+
* * ***Utility Type: `IsEqual`.***
|
|
282
268
|
* -------------------------------------------------------
|
|
283
|
-
* A type-level utility that returns a boolean indicating
|
|
284
|
-
* whether the two types are ***equal
|
|
285
|
-
*
|
|
269
|
+
* **A type-level utility that returns a boolean indicating
|
|
270
|
+
* whether the two types are ***equal***.**
|
|
286
271
|
* @template T - The first type to compare.
|
|
287
272
|
* @template U - The second type to compare.
|
|
288
273
|
* @example
|
|
@@ -299,11 +284,10 @@ type ColorCssNamed="aliceblue"|"antiquewhite"|"aqua"|"aquamarine"|"azure"|"beige
|
|
|
299
284
|
*/
|
|
300
285
|
type IsEqual<T,U>=(<F>()=>F extends T?1:2)extends<F>()=>F extends U?1:2?true:false;
|
|
301
286
|
/** -------------------------------------------------------
|
|
302
|
-
* * ***IsNotEqual
|
|
287
|
+
* * ***Utility Type: `IsNotEqual`.***
|
|
303
288
|
* -------------------------------------------------------
|
|
304
|
-
* A type-level utility that returns a boolean indicating
|
|
305
|
-
* whether the two types are ***not equal
|
|
306
|
-
*
|
|
289
|
+
* **A type-level utility that returns a boolean indicating
|
|
290
|
+
* whether the two types are ***not equal***.**
|
|
307
291
|
* @template T - The first type to compare.
|
|
308
292
|
* @template U - The second type to compare.
|
|
309
293
|
* @example
|
|
@@ -316,11 +300,11 @@ type IsEqual<T,U>=(<F>()=>F extends T?1:2)extends<F>()=>F extends U?1:2?true:fal
|
|
|
316
300
|
*/
|
|
317
301
|
type IsNotEqual<T,U>=Not<IsEqual<T,U>>;
|
|
318
302
|
/** -------------------------------------------------------
|
|
319
|
-
* * ***IfEqual
|
|
303
|
+
* * ***Utility Type: `IfEqual`.***
|
|
320
304
|
* -------------------------------------------------------
|
|
321
|
-
* Conditional
|
|
305
|
+
* - **Conditional:**
|
|
306
|
+
* - Selects one of two branches depending on whether `T` and `U` are ***equal***.
|
|
322
307
|
* - Defaults: `IfTrue = true`, `IfFalse = false`.
|
|
323
|
-
*
|
|
324
308
|
* @template T - The first type to compare.
|
|
325
309
|
* @template U - The second type to compare.
|
|
326
310
|
* @template IfTrue - The branch type if condition is met. (default: `true`)
|
|
@@ -333,11 +317,11 @@ type IsNotEqual<T,U>=Not<IsEqual<T,U>>;
|
|
|
333
317
|
*/
|
|
334
318
|
type IfEqual<T,U,IfTrue=true,IfFalse=false>=If<IsEqual<T,U>,IfTrue,IfFalse>;
|
|
335
319
|
/** -------------------------------------------------------
|
|
336
|
-
* * ***IfNotEqual
|
|
320
|
+
* * ***Utility Type: `IfNotEqual`.***
|
|
337
321
|
* -------------------------------------------------------
|
|
338
|
-
* Conditional
|
|
322
|
+
* - **Conditional:**
|
|
323
|
+
* - Selects one of two branches depending on whether `T` and `U` are ***not equal***.
|
|
339
324
|
* - Defaults: `IfTrue = true`, `IfFalse = false`.
|
|
340
|
-
*
|
|
341
325
|
* @template T - The first type to compare.
|
|
342
326
|
* @template U - The second type to compare.
|
|
343
327
|
* @template IfTrue - The branch type if condition is met. (default: `true`)
|
|
@@ -352,14 +336,13 @@ type IfEqual<T,U,IfTrue=true,IfFalse=false>=If<IsEqual<T,U>,IfTrue,IfFalse>;
|
|
|
352
336
|
*/
|
|
353
337
|
type IfNotEqual<T,U,IfTrue=true,IfFalse=false>=If<IsNotEqual<T,U>,IfTrue,IfFalse>;
|
|
354
338
|
/** -------------------------------------------------------
|
|
355
|
-
* * ***IsExactly
|
|
339
|
+
* * ***Utility Type: `IsExactly`.***
|
|
356
340
|
* -------------------------------------------------------
|
|
357
|
-
* A strict equality check between two types `A` and `B`
|
|
358
|
-
* that does **not** collapse when one of them is `any
|
|
359
|
-
*
|
|
360
|
-
*
|
|
361
|
-
*
|
|
362
|
-
*
|
|
341
|
+
* **A strict equality check between two types `A` and `B`
|
|
342
|
+
* that does **not** collapse when one of them is `any`.**
|
|
343
|
+
* - **Behavior:**
|
|
344
|
+
* - Returns `true` only if `A` and `B` are **mutually assignable**.
|
|
345
|
+
* - Returns `false` if either `A` or `B` is `any`.
|
|
363
346
|
* @template A - The first type to compare.
|
|
364
347
|
* @template B - The second type to compare.
|
|
365
348
|
* @example
|
|
@@ -368,18 +351,18 @@ type IfNotEqual<T,U,IfTrue=true,IfFalse=false>=If<IsNotEqual<T,U>,IfTrue,IfFalse
|
|
|
368
351
|
* type B = IsExactly<string, any>; // ➔ false
|
|
369
352
|
* type C = IsExactly<42, number>; // ➔ false
|
|
370
353
|
* type D = IsExactly<never, never>; // ➔ true
|
|
354
|
+
* type E = IsExactly<any, any>; // ➔ false
|
|
371
355
|
* ```
|
|
372
356
|
*/
|
|
373
357
|
type IsExactly<A,B>=IsAny<A>extends true?false:IsAny<B>extends true?false:(<T>()=>T extends A?1:2)extends<T>()=>T extends B?1:2?(<T>()=>T extends B?1:2)extends<T>()=>T extends A?1:2?true:false:false;
|
|
374
358
|
/** -------------------------------------------------------
|
|
375
|
-
* * ***IsGeneralArray
|
|
359
|
+
* * ***Utility Type: `IsGeneralArray`.***
|
|
376
360
|
* -------------------------------------------------------
|
|
377
|
-
* Checks if `T` is a **general array type** (`X[]` or `ReadonlyArray<X>`)
|
|
378
|
-
* instead of a tuple literal
|
|
379
|
-
*
|
|
380
|
-
*
|
|
381
|
-
*
|
|
382
|
-
*
|
|
361
|
+
* **Checks if `T` is a **general array type** (`X[]` or `ReadonlyArray<X>`)
|
|
362
|
+
* instead of a tuple literal.**
|
|
363
|
+
* - **Behavior:**
|
|
364
|
+
* - Returns `true` for `string[]`, `(number | boolean)[]`, `any[]`, etc.
|
|
365
|
+
* - Returns `false` for tuples like `[]`, `[1, 2, 3]`, or `[string, number]`.
|
|
383
366
|
* @template T - The type to check.
|
|
384
367
|
* @example
|
|
385
368
|
* ```ts
|
|
@@ -391,28 +374,26 @@ type IsExactly<A,B>=IsAny<A>extends true?false:IsAny<B>extends true?false:(<T>()
|
|
|
391
374
|
*/
|
|
392
375
|
type IsGeneralArray<T>=T extends readonly unknown[]?number extends T["length"]?true:false:false;
|
|
393
376
|
/** -------------------------------------------------------
|
|
394
|
-
* * ***IsBaseType
|
|
395
|
-
* -------------------------------------------------------
|
|
396
|
-
* Determines whether a type `T` is considered a **base / keyword / built-in type**
|
|
397
|
-
* rather than a literal, tuple, or specific instance
|
|
398
|
-
*
|
|
399
|
-
*
|
|
400
|
-
*
|
|
401
|
-
*
|
|
402
|
-
*
|
|
403
|
-
*
|
|
404
|
-
*
|
|
405
|
-
*
|
|
406
|
-
*
|
|
407
|
-
*
|
|
408
|
-
*
|
|
409
|
-
*
|
|
410
|
-
*
|
|
411
|
-
*
|
|
412
|
-
*
|
|
413
|
-
*
|
|
414
|
-
* - Functions with explicit structure (`() => {}`, `(x: number) => string`)
|
|
415
|
-
*
|
|
377
|
+
* * ***Utility Type: `IsBaseType`.***
|
|
378
|
+
* -------------------------------------------------------
|
|
379
|
+
* **Determines whether a type `T` is considered a **base / keyword / built-in type**
|
|
380
|
+
* rather than a literal, tuple, or specific instance.**
|
|
381
|
+
* - **Behavior:**
|
|
382
|
+
* - ***✅ Considered base types:***
|
|
383
|
+
* - Special keywords: `any`, `unknown`, `never`, `null`, `undefined`, `void`
|
|
384
|
+
* - Primitive keywords: `string`, `number`, `boolean`, `bigint`, `symbol`
|
|
385
|
+
* - Function keyword `Function` and alias `AnyFunction`
|
|
386
|
+
* - General arrays (`X[]`, `ReadonlyArray<X>`) and `TypedArray`
|
|
387
|
+
* - Common built-ins: `Date`, `RegExp`, `Error`
|
|
388
|
+
* - Generic containers: `Promise<any>`, `Map<any,any>`, `WeakMap<object,any>`, `Set<any>`, `WeakSet<object>`
|
|
389
|
+
* - Buffers & views: `ArrayBuffer`, `SharedArrayBuffer`, `DataView`
|
|
390
|
+
* - `object` keyword and `{}` (empty object type)
|
|
391
|
+
* - ***❌ Not considered base types:***
|
|
392
|
+
* - Literal values (`"foo"`, `123`, `true`)
|
|
393
|
+
* - Union literals (`"a" | "b"`)
|
|
394
|
+
* - Tuples (`[1, 2, 3]`, `[]`)
|
|
395
|
+
* - Specific object shapes (`{ a: 1 }`, `{ x: string }`)
|
|
396
|
+
* - Functions with explicit structure (`() => {}`, `(x: number) => string`)
|
|
416
397
|
* @template T - The type to evaluate.
|
|
417
398
|
* @example
|
|
418
399
|
* ```ts
|
|
@@ -460,20 +441,16 @@ type IsBaseType<T>=IsAny<T>extends true?true:IsUnknown<T>extends true?true:IsNev
|
|
|
460
441
|
*/
|
|
461
442
|
type Includes$1<S extends string,Sub extends string>=S extends`${infer _}${Sub}${infer _}`?true:false;
|
|
462
443
|
/** -------------------------------------------------------
|
|
463
|
-
* * ***ReplaceAll
|
|
444
|
+
* * ***Utility Type: `ReplaceAll`.***
|
|
464
445
|
* -------------------------------------------------------
|
|
465
|
-
* A **type-level utility** that replaces all occurrences of a given string (or array of strings)
|
|
466
|
-
*
|
|
467
|
-
*
|
|
468
|
-
*
|
|
469
|
-
*
|
|
470
|
-
* - Replacing multiple substrings (Pivot as array)
|
|
471
|
-
* - Guards against infinite recursion if `ReplaceBy` contains any value in Pivot
|
|
472
|
-
*
|
|
446
|
+
* **A **type-level utility** that replaces all occurrences of a given string (or array of strings) `Pivot` in a string `T` with `ReplaceBy`.**
|
|
447
|
+
* - **Supports:**
|
|
448
|
+
* - Replacing a single substring.
|
|
449
|
+
* - Replacing multiple substrings (Pivot as array).
|
|
450
|
+
* - Guards against infinite recursion if `ReplaceBy` contains any value in Pivot.
|
|
473
451
|
* @template T - The string to process.
|
|
474
452
|
* @template Pivot - A string or readonly array of strings to replace.
|
|
475
453
|
* @template ReplaceBy - The string to replace Pivot with.
|
|
476
|
-
*
|
|
477
454
|
* @example
|
|
478
455
|
* ```ts
|
|
479
456
|
* // Single pivot string
|
|
@@ -492,17 +469,15 @@ type Includes$1<S extends string,Sub extends string>=S extends`${infer _}${Sub}$
|
|
|
492
469
|
* type Case4 = ReplaceAll<'abc', 'a', 'a'>;
|
|
493
470
|
* // ➔ string
|
|
494
471
|
* ```
|
|
495
|
-
*
|
|
496
472
|
* @remarks
|
|
497
473
|
* - Works recursively to replace all instances.
|
|
498
474
|
* - If Pivot is empty (`""`) or empty array (`[]`), returns `T` unchanged.
|
|
499
475
|
*/
|
|
500
476
|
type ReplaceAll<T extends string,Pivot extends string|readonly string[],ReplaceBy extends string>=Pivot extends""|[]?T:Includes$1<ReplaceBy,Pivot extends string?Pivot:never>extends true?string:Pivot extends readonly [infer First extends string,...infer Rest extends string[]]?ReplaceAll<ReplaceAll<T,First,ReplaceBy>,Rest,ReplaceBy>:Pivot extends string?T extends`${infer A}${Pivot}${infer B}`?ReplaceAll<`${A}${ReplaceBy}${B}`,Pivot,ReplaceBy>:T:T;
|
|
501
477
|
/** -------------------------------------------------------
|
|
502
|
-
* * ***IsTuple
|
|
478
|
+
* * ***Utility Type: `IsTuple`.***
|
|
503
479
|
* -------------------------------------------------------
|
|
504
|
-
* Returns a boolean whether the first array argument is fixed length tuple
|
|
505
|
-
*
|
|
480
|
+
* **Returns a boolean whether the first array argument is fixed length tuple.**
|
|
506
481
|
* @template T - The array to check.
|
|
507
482
|
* @example
|
|
508
483
|
* type Case1 = IsTuple<[1, 2, 3]>; // ➔ true
|
|
@@ -510,13 +485,14 @@ type ReplaceAll<T extends string,Pivot extends string|readonly string[],ReplaceB
|
|
|
510
485
|
*/
|
|
511
486
|
type IsTuple<T extends readonly unknown[]>=NotExtends<number,T["length"]>;
|
|
512
487
|
/** -------------------------------------------------------
|
|
513
|
-
* * ***IfTuple
|
|
488
|
+
* * ***Utility Type: `IfTuple`.***
|
|
514
489
|
* -------------------------------------------------------
|
|
515
|
-
* Returns the second argument if the first array argument is fixed length
|
|
516
|
-
*
|
|
490
|
+
* **Returns the second argument if the first array argument is fixed length
|
|
491
|
+
* tuple (defaults to `true`), otherwise returns the third argument (defaults
|
|
492
|
+
* to `false`).**
|
|
517
493
|
* @template T - The array to check.
|
|
518
|
-
* @template IfTrue - The branch type if condition is met. (default: `true`)
|
|
519
|
-
* @template IfFalse - The branch type if condition is not met. (default: `false`)
|
|
494
|
+
* @template IfTrue - The branch type if condition is met. (default: `true`).
|
|
495
|
+
* @template IfFalse - The branch type if condition is not met. (default: `false`).
|
|
520
496
|
* @example
|
|
521
497
|
* type Case1 = IfTuple<[1, 2, 3], 'valid'>;
|
|
522
498
|
* // ➔ 'valid'
|
|
@@ -525,44 +501,35 @@ type IsTuple<T extends readonly unknown[]>=NotExtends<number,T["length"]>;
|
|
|
525
501
|
*/
|
|
526
502
|
type IfTuple<T extends readonly unknown[],IfTrue=true,IfFalse=false>=If<IsTuple<T>,IfTrue,IfFalse>;
|
|
527
503
|
/** -------------------------------------------------------
|
|
528
|
-
* * ***RemoveLeading
|
|
504
|
+
* * ***Utility Type: `RemoveLeading`.***
|
|
529
505
|
* -------------------------------------------------------
|
|
530
|
-
*
|
|
531
|
-
*
|
|
532
|
-
* specified in `Characters`.
|
|
533
|
-
*
|
|
506
|
+
* **Accepts a string type `T` and **recursively removes leading characters**
|
|
507
|
+
* specified in `Characters`.**
|
|
534
508
|
* @template T - The string to process.
|
|
535
509
|
* @template Characters - The characters to remove from the start.
|
|
536
|
-
*
|
|
537
510
|
* @example
|
|
538
511
|
* ```ts
|
|
539
512
|
* type Case1 = RemoveLeading<'aaabc', 'a'>;
|
|
540
513
|
* // ➔ 'bc' (all leading 'a' removed).
|
|
541
|
-
*
|
|
542
514
|
* type Case2 = RemoveLeading<'abc', 'd'>;
|
|
543
515
|
* // ➔ 'abc' (no 'd' at start, unchanged).
|
|
544
|
-
*
|
|
545
516
|
* type Case3 = RemoveLeading<'aaa', 'a'>;
|
|
546
517
|
* // ➔ '' (all 'a' removed).
|
|
547
|
-
*
|
|
548
518
|
* type Case4 = RemoveLeading<'aaa', 'aa'>;
|
|
549
519
|
* // ➔ 'a' (matches 'aa' once, then remaining 'a').
|
|
550
520
|
* ```
|
|
551
521
|
*/
|
|
552
522
|
type RemoveLeading<T extends string,Characters extends string>=T extends`${Characters}${infer Rest extends string}`?IsEmptyString<Rest>extends true?Rest:RemoveLeading<Rest,Characters>:T;type SubDecrementMap={"-9":-10;"-8":-9;"-7":-8;"-6":-7;"-5":-6;"-4":-5;"-3":-4;"-2":-3;"-1":-2;"0":-1;"1":0;"2":1;"3":2;"4":3;"5":4;"6":5;"7":6;"8":7;"9":8;};type SubNegativeCarryMap={"-10":0;"-9":1;"-8":2;"-7":3;"-6":4;"-5":5;"-4":6;"-3":7;"-2":8;"-1":9;};type SubMap={0:[0,-1,-2,-3,-4,-5,-6,-7,-8,-9];1:[1,0,-1,-2,-3,-4,-5,-6,-7,-8];2:[2,1,0,-1,-2,-3,-4,-5,-6,-7];3:[3,2,1,0,-1,-2,-3,-4,-5,-6];4:[4,3,2,1,0,-1,-2,-3,-4,-5];5:[5,4,3,2,1,0,-1,-2,-3,-4];6:[6,5,4,3,2,1,0,-1,-2,-3];7:[7,6,5,4,3,2,1,0,-1,-2];8:[8,7,6,5,4,3,2,1,0,-1];9:[9,8,7,6,5,4,3,2,1,0];};type _RemoveLeadingZeros<T extends string>=ParseNumber<RemoveLeading<T,"0">extends infer WithoutLeadingZeros extends string?IfEmptyString<WithoutLeadingZeros,"0",WithoutLeadingZeros>:never>;type _Sub<Num1 extends string,Num2 extends string,NegativeCarry extends 0|1=0,Result extends string="">=IsEmptyString<Num2>extends true?NegativeCarry extends 0?`${Num1}${Result}`:`${Decrement<ParseNumber<Num1>>}${Result}`:LastCharacter<Num1>extends`${infer Num1LastDigit extends keyof SubMap & number}`?LastCharacter<Num2>extends`${infer Num2LastDigit extends keyof SubMap[Num1LastDigit] & number}`?`${SubMap[Num1LastDigit][Num2LastDigit]}`extends infer DigitsSub extends keyof SubDecrementMap?(NegativeCarry extends 1?Stringify<SubDecrementMap[DigitsSub]>:DigitsSub)extends infer DigitsSubWithCarry extends string?Num1 extends`${infer Num1Rest}${Num1LastDigit}`?Num2 extends`${infer Num2Rest}${Num2LastDigit}`?DigitsSubWithCarry extends keyof SubNegativeCarryMap?_Sub<Num1Rest,Num2Rest,1,`${SubNegativeCarryMap[DigitsSubWithCarry]}${Result}`>:_Sub<Num1Rest,Num2Rest,0,`${DigitsSubWithCarry}${Result}`>:never:never:never:never:never:never;
|
|
553
523
|
/** -------------------------------------------------------
|
|
554
|
-
* * ***Sub
|
|
524
|
+
* * ***Utility Type: `Sub`.***
|
|
555
525
|
* -------------------------------------------------------
|
|
556
|
-
* Computes the subtraction of two integers at the **type level
|
|
557
|
-
*
|
|
558
|
-
*
|
|
559
|
-
*
|
|
560
|
-
*
|
|
561
|
-
* - Internally performs string-based arithmetic to handle carries/borrows.
|
|
562
|
-
*
|
|
526
|
+
* **Computes the subtraction of two integers at the **type level**.**
|
|
527
|
+
* - **Behavior:**
|
|
528
|
+
* - Handles positive and negative numbers.
|
|
529
|
+
* - Supports numbers in the range `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
530
|
+
* - Internally performs string-based arithmetic to handle carries/borrows.
|
|
563
531
|
* @template Num1 - First number (minuend).
|
|
564
532
|
* @template Num2 - Second number (subtrahend).
|
|
565
|
-
*
|
|
566
533
|
* @example
|
|
567
534
|
* ```ts
|
|
568
535
|
* // Positive numbers
|
|
@@ -584,12 +551,11 @@ type RemoveLeading<T extends string,Characters extends string>=T extends`${Chara
|
|
|
584
551
|
*/
|
|
585
552
|
type Sub<Num1 extends number,Num2 extends number>=IsNegativeInteger<Num1>extends true?IsNegativeInteger<Num2>extends true?IsLowerThan<Num1,Num2>extends true?Negate<_RemoveLeadingZeros<_Sub<Stringify<Abs<Num1>>,Stringify<Abs<Num2>>>>>:_RemoveLeadingZeros<_Sub<Stringify<Abs<Num2>>,Stringify<Abs<Num1>>>>:Sum<Abs<Num1>,Num2>extends infer Result extends number?Negate<Result>:never:IsNegativeInteger<Num2>extends true?Sum<Num1,Abs<Num2>>:IsLowerThan<Num1,Num2>extends true?Negate<_RemoveLeadingZeros<_Sub<Stringify<Num2>,Stringify<Num1>>>>:_RemoveLeadingZeros<_Sub<Stringify<Num1>,Stringify<Num2>>>;type SumIncrementMap=[ 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19];type SumLastDigitMap={10:0;11:1;12:2;13:3;14:4;15:5;16:6;17:7;18:8;19:9;};type SumMap={0:[0,1,2,3,4,5,6,7,8,9];1:[1,2,3,4,5,6,7,8,9,10];2:[2,3,4,5,6,7,8,9,10,11];3:[3,4,5,6,7,8,9,10,11,12];4:[4,5,6,7,8,9,10,11,12,13];5:[5,6,7,8,9,10,11,12,13,14];6:[6,7,8,9,10,11,12,13,14,15];7:[7,8,9,10,11,12,13,14,15,16];8:[8,9,10,11,12,13,14,15,16,17];9:[9,10,11,12,13,14,15,16,17,18];};
|
|
586
553
|
/** -------------------------------------------------------
|
|
587
|
-
* * ***_Sum
|
|
554
|
+
* * ***Private Utility Type: `_Sum`.***
|
|
588
555
|
* -------------------------------------------------------
|
|
589
|
-
* Internal helper type for summing two integer numbers represented as strings
|
|
590
|
-
* Performs digit-by-digit addition with carry handling.
|
|
591
|
-
*
|
|
592
|
-
* @deprecated This is internal helper, use `Sum` instead.
|
|
556
|
+
* **Internal helper type for summing two integer numbers represented as strings.**
|
|
557
|
+
* - Performs digit-by-digit addition with carry handling.
|
|
558
|
+
* @deprecated This is internal helper, use {@link Sum | **`Sum`**} instead.
|
|
593
559
|
* @template Num1 - First number as string.
|
|
594
560
|
* @template Num2 - Second number as string.
|
|
595
561
|
* @template Carry - Carry flag (0 or 1), defaults to 0.
|
|
@@ -597,14 +563,13 @@ type Sub<Num1 extends number,Num2 extends number>=IsNegativeInteger<Num1>extends
|
|
|
597
563
|
*/
|
|
598
564
|
type _Sum<Num1 extends string,Num2 extends string,Carry extends 0|1=0,Result extends string="">=IsEmptyString<Num1>extends true?Carry extends 0?ParseNumber<`${Num2}${Result}`>:_Increment<Num2,Result>:IsEmptyString<Num2>extends true?Carry extends 0?ParseNumber<`${Num1}${Result}`>:_Increment<Num1,Result>:LastCharacter<Num1>extends`${infer Num1LastDigit extends keyof SumMap & number}`?LastCharacter<Num2>extends`${infer Num2LastDigit extends keyof SumMap[Num1LastDigit] & number}`?SumMap[Num1LastDigit][Num2LastDigit] extends infer DigitsSum extends number?(Carry extends 1?SumIncrementMap[DigitsSum]:DigitsSum)extends infer DigitsSumWithCarry extends number?Num1 extends`${infer Num1Rest}${Num1LastDigit}`?Num2 extends`${infer Num2Rest}${Num2LastDigit}`?DigitsSumWithCarry extends keyof SumLastDigitMap?_Sum<Num1Rest,Num2Rest,1,`${SumLastDigitMap[DigitsSumWithCarry]}${Result}`>:_Sum<Num1Rest,Num2Rest,0,`${DigitsSumWithCarry}${Result}`>:never:never:never:never:never:never;
|
|
599
565
|
/** -------------------------------------------------------
|
|
600
|
-
* * ***Sum
|
|
566
|
+
* * ***Utility Type: `Sum`.***
|
|
601
567
|
* -------------------------------------------------------
|
|
602
|
-
* Adds two integers at the type level. Handles positive and negative numbers
|
|
603
|
-
* Supports numbers in the range
|
|
604
|
-
*
|
|
568
|
+
* **Adds two integers at the type level. Handles positive and negative numbers.**
|
|
569
|
+
* - Supports numbers in the range:
|
|
570
|
+
* - `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
605
571
|
* @template Num1 - First number.
|
|
606
572
|
* @template Num2 - Second number.
|
|
607
|
-
*
|
|
608
573
|
* @example
|
|
609
574
|
* ```ts
|
|
610
575
|
* // Positive + positive
|
|
@@ -624,16 +589,14 @@ type Sum<Num1 extends number,Num2 extends number>=IsNegativeInteger<Num1>extends
|
|
|
624
589
|
/** @ts-expect-error this still safe not to much deep */
|
|
625
590
|
_SumArr<Rest,Sum<CurrentSum,Num1>>;type _SumArr<T extends readonly number[],CurrentSum extends number=0>=IsEmptyArray<T>extends true?CurrentSum:Pop<T,{includeRemoved:true;}>extends infer PopResult?IsNever<PopResult>extends true?CurrentSum:PopResult extends [infer Rest extends number[],infer Num1 extends number]?_safeSumArr<Rest,CurrentSum,Num1>:never:CurrentSum;
|
|
626
591
|
/** -------------------------------------------------------
|
|
627
|
-
* * ***SumArr
|
|
592
|
+
* * ***Utility Type: `SumArr`.***
|
|
628
593
|
* -------------------------------------------------------
|
|
629
|
-
* Accepts a tuple of numbers and returns their sum
|
|
630
|
-
*
|
|
631
|
-
*
|
|
632
|
-
*
|
|
633
|
-
*
|
|
634
|
-
*
|
|
594
|
+
* **Accepts a tuple of numbers and returns their sum.**
|
|
595
|
+
* - **Behavior:**
|
|
596
|
+
* - Only works on tuple types (not general arrays).
|
|
597
|
+
* - Supports numbers in the range:
|
|
598
|
+
* -`[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
635
599
|
* @template T - Tuple of numbers to sum.
|
|
636
|
-
*
|
|
637
600
|
* @example
|
|
638
601
|
* ```ts
|
|
639
602
|
* // Sum all elements in a tuple
|
|
@@ -647,13 +610,11 @@ type SumArr<T extends readonly number[]>=IsTuple<T>extends true?_SumArr<T>:never
|
|
|
647
610
|
/** @ts-expect-error this still safe not to much deep */
|
|
648
611
|
type _safeSum<Parts extends [string[],string[],string[],string[]]=[[],[],[],[]]>=Sum<Sum<Parts[0]["length"],Parts[1]["length"]>,Sum<Parts[2]["length"],Parts[3]["length"]>>;type _StringLength<S extends string,Parts extends [string[],string[],string[],string[]]=[[],[],[],[]]>=S extends""?_safeSum<Parts>:S extends`${infer C1 extends string}${infer Rest1 extends string}`?Rest1 extends`${infer C2 extends string}${infer Rest2 extends string}`?Rest2 extends`${infer C3 extends string}${infer Rest3 extends string}`?Rest3 extends`${infer C4 extends string}${infer Rest4 extends string}`?_StringLength<Rest4,[ [...Parts[0],C1],[...Parts[1],C2],[...Parts[2],C3],[...Parts[3],C4]]>:_StringLength<Rest3,[ [...Parts[0],C1],[...Parts[1],C2],[...Parts[2],C3],Parts[3]]>:_StringLength<Rest2,[[...Parts[0],C1],[...Parts[1],C2],Parts[2],Parts[3]]>:_StringLength<Rest1,[[...Parts[0],C1],Parts[1],Parts[2],Parts[3]]>:_StringLength<S,Parts>;
|
|
649
612
|
/** -------------------------------------------------------
|
|
650
|
-
* * ***StringLength
|
|
613
|
+
* * ***Utility Type: `StringLength`.***
|
|
651
614
|
* -------------------------------------------------------
|
|
652
|
-
* Returns the length of a string at the type level
|
|
653
|
-
* Supports string length in range `[0, 3968]`.
|
|
654
|
-
*
|
|
615
|
+
* **Returns the length of a string at the type level.**
|
|
616
|
+
* - Supports string length in range `[0, 3968]`.
|
|
655
617
|
* @template S - The string to measure.
|
|
656
|
-
*
|
|
657
618
|
* @example
|
|
658
619
|
* ```ts
|
|
659
620
|
* type Case1 = StringLength<''>;
|
|
@@ -664,21 +625,18 @@ type _safeSum<Parts extends [string[],string[],string[],string[]]=[[],[],[],[]]>
|
|
|
664
625
|
*/
|
|
665
626
|
type StringLength<S extends string>=_StringLength<S>;
|
|
666
627
|
/** -------------------------------------------------------
|
|
667
|
-
* * ***CompareStringLength
|
|
628
|
+
* * ***Utility Type: `CompareStringLength`.***
|
|
668
629
|
* -------------------------------------------------------
|
|
669
|
-
* Compares the lengths of two strings and returns one of three possible type values
|
|
670
|
-
*
|
|
671
|
-
*
|
|
672
|
-
*
|
|
673
|
-
*
|
|
674
|
-
* Defaults to `never` if not provided.
|
|
675
|
-
*
|
|
630
|
+
* - **Compares the lengths of two strings and returns one of three possible type values:**
|
|
631
|
+
* - `IfStr1Shorter` if the first string is shorter.
|
|
632
|
+
* - `IfStr2Shorter` if the second string is shorter.
|
|
633
|
+
* - `IfEqual` if both strings have the same length.
|
|
634
|
+
* - Defaults to `never` if not provided.
|
|
676
635
|
* @template Str1 - First string.
|
|
677
636
|
* @template Str2 - Second string.
|
|
678
637
|
* @template IfStr1Shorter - Type to return if Str1 is shorter (default `never`).
|
|
679
638
|
* @template IfStr2Shorter - Type to return if Str2 is shorter (default `never`).
|
|
680
639
|
* @template IfEqual - Type to return if both strings have equal length (default `never`).
|
|
681
|
-
*
|
|
682
640
|
* @example
|
|
683
641
|
* ```ts
|
|
684
642
|
* type Case1 = CompareStringLength<'a', 'ab', 'first shorter'>;
|
|
@@ -691,13 +649,11 @@ type StringLength<S extends string>=_StringLength<S>;
|
|
|
691
649
|
*/
|
|
692
650
|
type CompareStringLength<Str1 extends string,Str2 extends string,IfStr1Shorter=never,IfStr2Shorter=never,IfEqual=never>=IsEmptyString<Str1>extends true?IsEmptyString<Str2>extends true?IfEqual:IfStr1Shorter:IsEmptyString<Str2>extends true?IfStr2Shorter:Str1 extends`${string}${infer Str1Rest extends string}`?Str2 extends`${string}${infer Str2Rest extends string}`?CompareStringLength<Str1Rest,Str2Rest,IfStr1Shorter,IfStr2Shorter,IfEqual>:never:never;
|
|
693
651
|
/** -------------------------------------------------------
|
|
694
|
-
* * ***IsShorterString
|
|
652
|
+
* * ***Utility Type: `IsShorterString`.***
|
|
695
653
|
* -------------------------------------------------------
|
|
696
|
-
* Returns `true` if the first string is shorter than the second string; otherwise `false
|
|
697
|
-
*
|
|
654
|
+
* **Returns `true` if the first string is shorter than the second string; otherwise `false`.**
|
|
698
655
|
* @template Str1 - First string.
|
|
699
656
|
* @template Str2 - Second string.
|
|
700
|
-
*
|
|
701
657
|
* @example
|
|
702
658
|
* ```ts
|
|
703
659
|
* type Case1 = IsShorterString<'a', 'ab'>;
|
|
@@ -708,13 +664,11 @@ type CompareStringLength<Str1 extends string,Str2 extends string,IfStr1Shorter=n
|
|
|
708
664
|
*/
|
|
709
665
|
type IsShorterString<Str1 extends string,Str2 extends string>=CompareStringLength<Str1,Str2,true,false,false>;
|
|
710
666
|
/** -------------------------------------------------------
|
|
711
|
-
* * ***IsLongerString
|
|
667
|
+
* * ***Utility Type: `IsLongerString`.***
|
|
712
668
|
* -------------------------------------------------------
|
|
713
|
-
* Returns `true` if the first string is longer than the second string; otherwise `false
|
|
714
|
-
*
|
|
669
|
+
* **Returns `true` if the first string is longer than the second string; otherwise `false`.**
|
|
715
670
|
* @template Str1 - First string.
|
|
716
671
|
* @template Str2 - Second string.
|
|
717
|
-
*
|
|
718
672
|
* @example
|
|
719
673
|
* ```ts
|
|
720
674
|
* type Case1 = IsLongerString<'ab', 'a'>; // ➔ true
|
|
@@ -723,13 +677,11 @@ type IsShorterString<Str1 extends string,Str2 extends string>=CompareStringLengt
|
|
|
723
677
|
*/
|
|
724
678
|
type IsLongerString<Str1 extends string,Str2 extends string>=CompareStringLength<Str1,Str2,false,true,false>;
|
|
725
679
|
/** -------------------------------------------------------
|
|
726
|
-
* * ***IsSameLengthString
|
|
680
|
+
* * ***Utility Type: `IsSameLengthString`.***
|
|
727
681
|
* -------------------------------------------------------
|
|
728
|
-
* Returns `true` if two strings have the same length; otherwise `false
|
|
729
|
-
*
|
|
682
|
+
* **Returns `true` if two strings have the same length; otherwise `false`.**
|
|
730
683
|
* @template Str1 - First string.
|
|
731
684
|
* @template Str2 - Second string.
|
|
732
|
-
*
|
|
733
685
|
* @example
|
|
734
686
|
* ```ts
|
|
735
687
|
* type Case1 = IsSameLengthString<'ab', 'ab'>; // ➔ true
|
|
@@ -738,57 +690,48 @@ type IsLongerString<Str1 extends string,Str2 extends string>=CompareStringLength
|
|
|
738
690
|
*/
|
|
739
691
|
type IsSameLengthString<Str1 extends string,Str2 extends string>=CompareStringLength<Str1,Str2,false,false,true>;
|
|
740
692
|
/** -------------------------------------------------------
|
|
741
|
-
* Options for {@link NumberLength}
|
|
693
|
+
* * ***Type Options for {@link NumberLength | **`NumberLength`**}.***
|
|
742
694
|
*/
|
|
743
695
|
type TypeNumberLengthOptions={
|
|
744
|
-
/** Removes the leading minus `-` from negative numbers
|
|
745
|
-
*
|
|
746
|
-
* Default: `true`.
|
|
696
|
+
/** * ***Removes the leading minus `-` from negative numbers, default: `true`.***
|
|
747
697
|
*
|
|
748
698
|
* @default true
|
|
749
699
|
*/
|
|
750
700
|
stripSign?:boolean;
|
|
751
|
-
/** Removes the decimal point `.` from floats
|
|
752
|
-
*
|
|
753
|
-
* Default: `true`.
|
|
701
|
+
/** * ***Removes the decimal point `.` from floats, default: `true`.***
|
|
754
702
|
*
|
|
755
703
|
* @default true
|
|
756
704
|
*/
|
|
757
705
|
stripDot?:boolean;
|
|
758
|
-
/** Removes the trailing `n` from BigInt literals
|
|
759
|
-
*
|
|
760
|
-
* Default: `true`.
|
|
706
|
+
/** * ***Removes the trailing `n` from BigInt literals, default: `true`.***
|
|
761
707
|
*
|
|
762
708
|
* @default true
|
|
763
709
|
*/
|
|
764
710
|
stripBigInt?:boolean;};
|
|
765
711
|
/** -------------------------------------------------------
|
|
766
|
-
* Default options for {@link NumberLength} (all true)
|
|
712
|
+
* * ***Default options for {@link NumberLength | **`NumberLength`**} (all `true`).***
|
|
767
713
|
*/
|
|
768
714
|
type DefaultNumberLengthOptions={stripSign:true;stripDot:true;stripBigInt:true;};
|
|
769
715
|
/** -------------------------------------------------------
|
|
770
|
-
* Merge provided options with defaults for {@link NumberLength}
|
|
716
|
+
* * ***Merge provided options with defaults for {@link NumberLength | **`NumberLength`**}.***
|
|
771
717
|
*/
|
|
772
718
|
type MergeOptions<Opts extends TypeNumberLengthOptions>={[K in keyof DefaultNumberLengthOptions]:K extends keyof Opts?Opts[K]:DefaultNumberLengthOptions[K];};
|
|
773
719
|
/** -------------------------------------------------------
|
|
774
|
-
* * ***NumberLength
|
|
720
|
+
* * ***Utility Type: `NumberLength`.***
|
|
775
721
|
* -------------------------------------------------------
|
|
776
|
-
* A type-level utility that returns the **number of digits/characters**
|
|
777
|
-
* of a numeric literal type, with optional cleaning
|
|
778
|
-
*
|
|
779
|
-
*
|
|
780
|
-
*
|
|
781
|
-
*
|
|
782
|
-
*
|
|
783
|
-
* - BigInts (`n` suffix optionally removed)
|
|
784
|
-
*
|
|
722
|
+
* **A type-level utility that returns the **number of digits/characters**
|
|
723
|
+
* of a numeric literal type, with optional cleaning.**
|
|
724
|
+
* - **Supports:**
|
|
725
|
+
* - Integers (positive & negative).
|
|
726
|
+
* - Floats (`.` optionally removed).
|
|
727
|
+
* - Scientific notation (`e`/`E`, TypeScript normalizes to number).
|
|
728
|
+
* - BigInts (`n` suffix optionally removed).
|
|
785
729
|
* @template T - A numeric literal (`number` or `bigint`).
|
|
786
730
|
* @template Options - Optional configuration (default: all `true`):
|
|
787
|
-
* - `stripSign`
|
|
788
|
-
* - `stripDot`
|
|
789
|
-
* - `stripBigInt`
|
|
790
|
-
*
|
|
791
|
-
* ---
|
|
731
|
+
* - `stripSign` ➔ Removes the leading `-` (default `true`).
|
|
732
|
+
* - `stripDot` ➔ Removes the decimal point `.` (default `true`).
|
|
733
|
+
* - `stripBigInt` ➔ Removes trailing `n` (default `true`).
|
|
734
|
+
* @example
|
|
792
735
|
* #### ✅ _Valid Examples:_
|
|
793
736
|
* ```ts
|
|
794
737
|
* // Integers
|
|
@@ -816,7 +759,6 @@ type MergeOptions<Opts extends TypeNumberLengthOptions>={[K in keyof DefaultNumb
|
|
|
816
759
|
* type N = NumberLength<-123n, { stripBigInt: false, stripSign: false }>;
|
|
817
760
|
* // ➔ 5 (minus & n kept ➔ -123n)
|
|
818
761
|
* ```
|
|
819
|
-
*
|
|
820
762
|
* ---
|
|
821
763
|
* #### ❌ _Invalid Examples:_
|
|
822
764
|
* ```ts
|
|
@@ -829,7 +771,6 @@ type MergeOptions<Opts extends TypeNumberLengthOptions>={[K in keyof DefaultNumb
|
|
|
829
771
|
* type Invalid7 = NumberLength<unknown>; // ➔ never
|
|
830
772
|
* type Invalid8 = NumberLength<never>; // ➔ never
|
|
831
773
|
* ```
|
|
832
|
-
*
|
|
833
774
|
* ---
|
|
834
775
|
* @remarks
|
|
835
776
|
* - Uses type-level string manipulation to "clean" numeric literal according to options.
|
|
@@ -839,26 +780,21 @@ type MergeOptions<Opts extends TypeNumberLengthOptions>={[K in keyof DefaultNumb
|
|
|
839
780
|
*/
|
|
840
781
|
type NumberLength<T extends number|bigint,Options extends Partial<TypeNumberLengthOptions>=DefaultNumberLengthOptions>=If<OrArr<[IsBaseType<T>,Extends<T,string>,Not<Extends<T,number|bigint>>]>>extends true?never:StringLength<ReplaceAll<Stringify<T>,[ MergeOptions<Options>["stripSign"] extends true?"-":"",MergeOptions<Options>["stripDot"] extends true?".":"",MergeOptions<Options>["stripBigInt"] extends true?"n":""],"">>;
|
|
841
782
|
/** -------------------------------------------------------
|
|
842
|
-
* * ***CompareNumberLength
|
|
783
|
+
* * ***Utility Type: `CompareNumberLength`.***
|
|
843
784
|
* -------------------------------------------------------
|
|
844
|
-
*
|
|
845
|
-
*
|
|
846
|
-
*
|
|
847
|
-
*
|
|
848
|
-
*
|
|
849
|
-
* -
|
|
850
|
-
*
|
|
851
|
-
*
|
|
852
|
-
* **Important:** This utility only works with **literal numbers**.
|
|
853
|
-
* Using non-literal numbers (`number`) will return `never`.
|
|
854
|
-
*
|
|
785
|
+
* **Compares the **number of digits** of two numeric literal types.**
|
|
786
|
+
* - **Returns:**
|
|
787
|
+
* - `IfNum1Shorter` if the first number has fewer digits than the second (default: `never`).
|
|
788
|
+
* - `IfNum2Shorter` if the second number has fewer digits than the first (default: `never`).
|
|
789
|
+
* - `IfEqual` if both numbers have the same number of digits (default: `never`).
|
|
790
|
+
* - **Important:**
|
|
791
|
+
* - This utility only works with **literal numbers**.
|
|
792
|
+
* - Using non-literal numbers (`number`) will return `never`.
|
|
855
793
|
* @template Num1 - The first number literal to compare.
|
|
856
794
|
* @template Num2 - The second number literal to compare.
|
|
857
795
|
* @template IfNum1Shorter - Return type if the first number is shorter (default: `never`).
|
|
858
796
|
* @template IfNum2Shorter - Return type if the second number is shorter (default: `never`).
|
|
859
797
|
* @template IfEqual - Return type if both numbers have the same length (default: `never`).
|
|
860
|
-
*
|
|
861
|
-
* ---
|
|
862
798
|
* @example
|
|
863
799
|
* ```ts
|
|
864
800
|
* // First number shorter than second
|
|
@@ -883,30 +819,24 @@ type NumberLength<T extends number|bigint,Options extends Partial<TypeNumberLeng
|
|
|
883
819
|
* type Case4 = CompareNumberLength<NumA, NumB, 'first shorter', 'first longer', 'equal'>;
|
|
884
820
|
* // ➔ never
|
|
885
821
|
* ```
|
|
886
|
-
*
|
|
887
822
|
* ---
|
|
888
823
|
* @remarks
|
|
889
|
-
* - Internally uses {@link Stringify} and {@link CompareStringLength}.
|
|
890
|
-
* - Works for positive
|
|
824
|
+
* - Internally uses {@link Stringify | **`Stringify`**} and {@link CompareStringLength | **`CompareStringLength`**}.
|
|
825
|
+
* - Works for `positive`, `negative`, and `floating-point literal numbers`.
|
|
891
826
|
*/
|
|
892
827
|
type CompareNumberLength<Num1 extends number,Num2 extends number,IfNum1Shorter=never,IfNum2Shorter=never,IfEqual=never>=If<Or<Extends<number,Num1>,Extends<number,Num2>>>extends true?never:CompareStringLength<Stringify<Num1>,Stringify<Num2>,IfNum1Shorter,IfNum2Shorter,IfEqual>;
|
|
893
828
|
/** -------------------------------------------------------
|
|
894
|
-
* * ***IsShorterNumber
|
|
829
|
+
* * ***Utility Type: `IsShorterNumber`.***
|
|
895
830
|
* -------------------------------------------------------
|
|
896
|
-
*
|
|
897
|
-
*
|
|
898
|
-
*
|
|
899
|
-
*
|
|
900
|
-
* -
|
|
901
|
-
*
|
|
902
|
-
*
|
|
903
|
-
* **Important:** This utility only works with **literal numbers**.
|
|
904
|
-
* Using non-literal numbers (`number`) will return `never`.
|
|
905
|
-
*
|
|
831
|
+
* **Compares the number of digits of two numeric literal types and returns a **boolean**.**
|
|
832
|
+
* - **Returns:**
|
|
833
|
+
* - `true` if the first number has fewer digits than the second.
|
|
834
|
+
* - `false` otherwise (including when numbers have equal length).
|
|
835
|
+
* - **Important:**
|
|
836
|
+
* - This utility only works with **literal numbers**.
|
|
837
|
+
* - Using non-literal numbers (`number`) will return `never`.
|
|
906
838
|
* @template Num1 - The first number literal to compare.
|
|
907
839
|
* @template Num2 - The second number literal to compare.
|
|
908
|
-
*
|
|
909
|
-
* ---
|
|
910
840
|
* @example
|
|
911
841
|
* ```ts
|
|
912
842
|
* // Literal numbers
|
|
@@ -925,28 +855,24 @@ type CompareNumberLength<Num1 extends number,Num2 extends number,IfNum1Shorter=n
|
|
|
925
855
|
* type Case4 = IsShorterNumber<NumA, NumB>;
|
|
926
856
|
* // ➔ never
|
|
927
857
|
* ```
|
|
928
|
-
*
|
|
858
|
+
* ---
|
|
929
859
|
* @remarks
|
|
930
|
-
* - Internally uses {@link CompareNumberLength}.
|
|
931
|
-
* - Works for positive
|
|
860
|
+
* - Internally uses {@link CompareNumberLength | **`CompareNumberLength`**}.
|
|
861
|
+
* - Works for `positive`, `negative`, and `floating-point literal numbers`.
|
|
932
862
|
*/
|
|
933
863
|
type IsShorterNumber<Num1 extends number,Num2 extends number>=CompareNumberLength<Num1,Num2,true,false,false>;
|
|
934
864
|
/** -------------------------------------------------------
|
|
935
|
-
* * ***IsLongerNumber
|
|
865
|
+
* * ***Utility Type: `IsLongerNumber`.***
|
|
936
866
|
* -------------------------------------------------------
|
|
937
|
-
*
|
|
938
|
-
*
|
|
939
|
-
*
|
|
940
|
-
*
|
|
941
|
-
* -
|
|
942
|
-
*
|
|
943
|
-
*
|
|
944
|
-
* **Important:** Only works with **literal numbers**. Non-literal numbers (`number`) return `never`.
|
|
945
|
-
*
|
|
867
|
+
* **Compares the number of digits of two numeric literal types and returns a **boolean**.**
|
|
868
|
+
* - **Returns:**
|
|
869
|
+
* - `true` if the first number has more digits than the second.
|
|
870
|
+
* - `false` otherwise (including when numbers have equal length).
|
|
871
|
+
* - **Important:**
|
|
872
|
+
* - Only works with **literal numbers**.
|
|
873
|
+
* - Non-literal numbers (`number`) return `never`.
|
|
946
874
|
* @template Num1 - The first number literal to compare.
|
|
947
875
|
* @template Num2 - The second number literal to compare.
|
|
948
|
-
*
|
|
949
|
-
* ---
|
|
950
876
|
* @example
|
|
951
877
|
* ```ts
|
|
952
878
|
* type Case1 = IsLongerNumber<10, 1>;
|
|
@@ -964,28 +890,24 @@ type IsShorterNumber<Num1 extends number,Num2 extends number>=CompareNumberLengt
|
|
|
964
890
|
* type Case4 = IsLongerNumber<NumA, NumB>;
|
|
965
891
|
* // ➔ never
|
|
966
892
|
* ```
|
|
967
|
-
*
|
|
893
|
+
* ---
|
|
968
894
|
* @remarks
|
|
969
|
-
* - Internally uses {@link CompareNumberLength}.
|
|
970
|
-
* - Works for positive
|
|
895
|
+
* - Internally uses {@link CompareNumberLength | **`CompareNumberLength`**}.
|
|
896
|
+
* - Works for `positive`, `negative`, and `floating-point literal numbers`.
|
|
971
897
|
*/
|
|
972
898
|
type IsLongerNumber<Num1 extends number,Num2 extends number>=CompareNumberLength<Num1,Num2,false,true,false>;
|
|
973
899
|
/** -------------------------------------------------------
|
|
974
|
-
* * ***IsSameLengthNumber
|
|
900
|
+
* * ***Utility Type: `IsSameLengthNumber`.***
|
|
975
901
|
* -------------------------------------------------------
|
|
976
|
-
*
|
|
977
|
-
*
|
|
978
|
-
*
|
|
979
|
-
*
|
|
980
|
-
* -
|
|
981
|
-
*
|
|
982
|
-
*
|
|
983
|
-
* **Important:** Only works with **literal numbers**. Non-literal numbers (`number`) return `never`.
|
|
984
|
-
*
|
|
902
|
+
* **Compares the number of digits of two numeric literal types and returns a **boolean**.**
|
|
903
|
+
* - **Returns:**
|
|
904
|
+
* - `true` if the numbers have the same number of digits.
|
|
905
|
+
* - `false` otherwise.
|
|
906
|
+
* - **Important:**
|
|
907
|
+
* - Only works with **literal numbers**.
|
|
908
|
+
* - Non-literal numbers (`number`) return `never`.
|
|
985
909
|
* @template Num1 - The first number literal to compare.
|
|
986
910
|
* @template Num2 - The second number literal to compare.
|
|
987
|
-
*
|
|
988
|
-
* ---
|
|
989
911
|
* @example
|
|
990
912
|
* ```ts
|
|
991
913
|
* type Case1 = IsSameLengthNumber<10, 10>;
|
|
@@ -1000,37 +922,33 @@ type IsLongerNumber<Num1 extends number,Num2 extends number>=CompareNumberLength
|
|
|
1000
922
|
* type Case3 = IsSameLengthNumber<NumA, NumB>;
|
|
1001
923
|
* // ➔ never
|
|
1002
924
|
* ```
|
|
1003
|
-
*
|
|
925
|
+
* ---
|
|
1004
926
|
* @remarks
|
|
1005
|
-
* - Internally uses {@link CompareNumberLength}.
|
|
1006
|
-
* - Works for positive
|
|
927
|
+
* - Internally uses {@link CompareNumberLength | **`CompareNumberLength`**}.
|
|
928
|
+
* - Works for `positive`, `negative`, and `floating-point literal numbers`.
|
|
1007
929
|
*/
|
|
1008
930
|
type IsSameLengthNumber<Num1 extends number,Num2 extends number>=CompareNumberLength<Num1,Num2,false,false,true>;type LowerThanMap={"0":["1","2","3","4","5","6","7","8","9"];"1":["2","3","4","5","6","7","8","9"];"2":["3","4","5","6","7","8","9"];"3":["4","5","6","7","8","9"];"4":["5","6","7","8","9"];"5":["6","7","8","9"];"6":["7","8","9"];"7":["8","9"];"8":["9"];"9":[];};type _IsLowerThan<Num1 extends string,Num2 extends string>=Num1 extends`${infer Num1Character extends keyof LowerThanMap}${infer Num1Rest extends string}`?Num2 extends`${infer Num2Character extends string}${infer Num2Rest extends string}`?IsEqual<Num1Character,Num2Character>extends true?_IsLowerThan<Num1Rest,Num2Rest>:Num2Character extends LowerThanMap[Num1Character][number]?true:false:true:false;
|
|
1009
931
|
/** -------------------------------------------------------
|
|
1010
|
-
* * ***IsLowerThan
|
|
932
|
+
* * ***Utility Type: `IsLowerThan`.***
|
|
1011
933
|
* -------------------------------------------------------
|
|
1012
|
-
* Returns a boolean indicating whether `Num1` is strictly lower than `Num2
|
|
934
|
+
* **Returns a boolean indicating whether `Num1` is strictly lower than `Num2`.**
|
|
1013
935
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
1014
|
-
*
|
|
1015
936
|
* @template Num1 - The first integer to compare.
|
|
1016
937
|
* @template Num2 - The second integer to compare.
|
|
1017
|
-
*
|
|
1018
938
|
* @example
|
|
1019
939
|
* type Case1 = IsLowerThan<1, 10>; // ➔ true
|
|
1020
940
|
* type Case2 = IsLowerThan<1, -10>; // ➔ false
|
|
1021
941
|
*/
|
|
1022
942
|
type IsLowerThan<Num1 extends number,Num2 extends number>=IsEqual<Num1,Num2>extends true?false:IsNegative<Num1>extends true?IsNegative<Num2>extends false?true:CompareNumberLength<Num1,Num2,false,true,Not<_IsLowerThan<Stringify<Abs<Num1>>,Stringify<Abs<Num2>>>>>:IsNegative<Num2>extends true?false:CompareNumberLength<Num1,Num2,true,false,_IsLowerThan<Stringify<Abs<Num1>>,Stringify<Abs<Num2>>>>;
|
|
1023
943
|
/** -------------------------------------------------------
|
|
1024
|
-
* * ***IfLowerThan
|
|
944
|
+
* * ***Utility Type: `IfLowerThan`.***
|
|
1025
945
|
* -------------------------------------------------------
|
|
1026
|
-
* Returns `IfTrue` if `Num1` is lower than `Num2`, otherwise returns `IfFalse
|
|
946
|
+
* **Returns `IfTrue` if `Num1` is lower than `Num2`, otherwise returns `IfFalse`.**
|
|
1027
947
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
1028
|
-
*
|
|
1029
948
|
* @template Num1 - The first integer to compare.
|
|
1030
949
|
* @template Num2 - The second integer to compare.
|
|
1031
950
|
* @template IfTrue - Value to return if `Num1 < Num2`.
|
|
1032
951
|
* @template IfFalse - Value to return if `Num1 >= Num2`.
|
|
1033
|
-
*
|
|
1034
952
|
* @example
|
|
1035
953
|
* type Case1 = IfLowerThan<1, 10, 'valid'>;
|
|
1036
954
|
* // ➔ 'valid'
|
|
@@ -1039,11 +957,10 @@ type IsLowerThan<Num1 extends number,Num2 extends number>=IsEqual<Num1,Num2>exte
|
|
|
1039
957
|
*/
|
|
1040
958
|
type IfLowerThan<Num1 extends number,Num2 extends number,IfTrue=true,IfFalse=false>=If<IsLowerThan<Num1,Num2>,IfTrue,IfFalse>;
|
|
1041
959
|
/** -------------------------------------------------------
|
|
1042
|
-
* * ***IsLowerOrEqual
|
|
960
|
+
* * ***Utility Type: `IsLowerOrEqual`.***
|
|
1043
961
|
* -------------------------------------------------------
|
|
1044
|
-
* Returns a boolean indicating whether `Num1` is lower than or equal to `Num2
|
|
962
|
+
* **Returns a boolean indicating whether `Num1` is lower than or equal to `Num2`.**
|
|
1045
963
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
1046
|
-
*
|
|
1047
964
|
* @template Num1 - The first integer to compare.
|
|
1048
965
|
* @template Num2 - The second integer to compare.
|
|
1049
966
|
* @example
|
|
@@ -1054,11 +971,12 @@ type IfLowerThan<Num1 extends number,Num2 extends number,IfTrue=true,IfFalse=fal
|
|
|
1054
971
|
*/
|
|
1055
972
|
type IsLowerOrEqual<Num1 extends number,Num2 extends number>=IsEqual<Num1,Num2>extends true?true:IsLowerThan<Num1,Num2>;
|
|
1056
973
|
/** -------------------------------------------------------
|
|
1057
|
-
* * ***IfLowerOrEqual
|
|
974
|
+
* * ***Utility Type: `IfLowerOrEqual`.***
|
|
1058
975
|
* -------------------------------------------------------
|
|
1059
|
-
* Returns the third argument if the first argument (integer) is lower than
|
|
976
|
+
* **Returns the third argument if the first argument (integer) is lower than
|
|
977
|
+
* the second argument (integer) or equal (defaults to `true`), otherwise returns
|
|
978
|
+
* the fourth argument (defaults to `false`).**
|
|
1060
979
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
1061
|
-
*
|
|
1062
980
|
* @template Num1 - The first integer to compare.
|
|
1063
981
|
* @template Num2 - The second integer to compare.
|
|
1064
982
|
* @template IfTrue - Value to return if `Num1 <= Num2`.
|
|
@@ -1071,11 +989,12 @@ type IsLowerOrEqual<Num1 extends number,Num2 extends number>=IsEqual<Num1,Num2>e
|
|
|
1071
989
|
*/
|
|
1072
990
|
type IfLowerOrEqual<Num1 extends number,Num2 extends number,IfTrue=true,IfFalse=false>=If<IsEqual<Num1,Num2>extends true?true:IsLowerThan<Num1,Num2>,IfTrue,IfFalse>;
|
|
1073
991
|
/** -------------------------------------------------------
|
|
1074
|
-
* * ***IsGreaterThan
|
|
992
|
+
* * ***Utility Type: `IsGreaterThan`.***
|
|
1075
993
|
* -------------------------------------------------------
|
|
1076
|
-
* Returns a boolean indicating whether the first integer
|
|
1077
|
-
*
|
|
1078
|
-
*
|
|
994
|
+
* **Returns a boolean indicating whether the first integer
|
|
995
|
+
* is ***greater than*** the second integer.**
|
|
996
|
+
* - **Behavior:**
|
|
997
|
+
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
1079
998
|
* @template Num1 - The first integer.
|
|
1080
999
|
* @template Num2 - The second integer.
|
|
1081
1000
|
* @example
|
|
@@ -1086,12 +1005,14 @@ type IfLowerOrEqual<Num1 extends number,Num2 extends number,IfTrue=true,IfFalse=
|
|
|
1086
1005
|
*/
|
|
1087
1006
|
type IsGreaterThan<Num1 extends number,Num2 extends number>=IsLowerThan<Num2,Num1>;
|
|
1088
1007
|
/** -------------------------------------------------------
|
|
1089
|
-
* * ***IfGreaterThan
|
|
1008
|
+
* * ***Utility Type: `IfGreaterThan`.***
|
|
1090
1009
|
* -------------------------------------------------------
|
|
1091
|
-
* Conditional
|
|
1092
|
-
*
|
|
1093
|
-
*
|
|
1094
|
-
*
|
|
1010
|
+
* - **Conditional:**
|
|
1011
|
+
* - Returns the third argument if the first integer is ***greater than*** the
|
|
1012
|
+
* second integer, otherwise returns the fourth argument.
|
|
1013
|
+
* - **Behavior:**
|
|
1014
|
+
* - Defaults: `IfTrue = true`, `IfFalse = false`.
|
|
1015
|
+
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
1095
1016
|
* @template Num1 - The first integer.
|
|
1096
1017
|
* @template Num2 - The second integer.
|
|
1097
1018
|
* @template IfTrue - The branch type if condition is met. (default: `true`)
|
|
@@ -1106,12 +1027,12 @@ type IsGreaterThan<Num1 extends number,Num2 extends number>=IsLowerThan<Num2,Num
|
|
|
1106
1027
|
*/
|
|
1107
1028
|
type IfGreaterThan<Num1 extends number,Num2 extends number,IfTrue=true,IfFalse=false>=IfLowerThan<Num2,Num1,IfTrue,IfFalse>;
|
|
1108
1029
|
/** -------------------------------------------------------
|
|
1109
|
-
* * ***IsGreaterOrEqual
|
|
1030
|
+
* * ***Utility Type: `IsGreaterOrEqual`.***
|
|
1110
1031
|
* -------------------------------------------------------
|
|
1111
|
-
*
|
|
1112
|
-
*
|
|
1113
|
-
*
|
|
1114
|
-
*
|
|
1032
|
+
* **Returns a boolean indicating whether the first integer
|
|
1033
|
+
* is ***greater than or equal*** to the second integer.**
|
|
1034
|
+
* - **Behavior:**
|
|
1035
|
+
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
1115
1036
|
* @template Num1 - The first integer.
|
|
1116
1037
|
* @template Num2 - The second integer.
|
|
1117
1038
|
* @example
|
|
@@ -1123,13 +1044,14 @@ type IfGreaterThan<Num1 extends number,Num2 extends number,IfTrue=true,IfFalse=f
|
|
|
1123
1044
|
*/
|
|
1124
1045
|
type IsGreaterOrEqual<Num1 extends number,Num2 extends number>=IsEqual<Num1,Num2>extends true?true:IsGreaterThan<Num1,Num2>;
|
|
1125
1046
|
/** -------------------------------------------------------
|
|
1126
|
-
* * ***IfGreaterOrEqual
|
|
1047
|
+
* * ***Utility Type: `IfGreaterOrEqual`.***
|
|
1127
1048
|
* -------------------------------------------------------
|
|
1128
|
-
*
|
|
1129
|
-
*
|
|
1130
|
-
*
|
|
1131
|
-
* -
|
|
1132
|
-
*
|
|
1049
|
+
* - **Conditional:**
|
|
1050
|
+
* - Returns the third argument if the first integer is ***greater than or
|
|
1051
|
+
* equal*** to the second integer, otherwise returns the fourth argument.
|
|
1052
|
+
* - **Behavior:**
|
|
1053
|
+
* - Defaults: `IfTrue = true`, `IfFalse = false`.
|
|
1054
|
+
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
1133
1055
|
* @template Num1 - The first integer.
|
|
1134
1056
|
* @template Num2 - The second integer.
|
|
1135
1057
|
* @template IfTrue - The branch type if condition is met. (default: `true`)
|
|
@@ -1145,71 +1067,59 @@ type IsGreaterOrEqual<Num1 extends number,Num2 extends number>=IsEqual<Num1,Num2
|
|
|
1145
1067
|
* ```
|
|
1146
1068
|
*/
|
|
1147
1069
|
type IfGreaterOrEqual<Num1 extends number,Num2 extends number,IfTrue=true,IfFalse=false>=If<IsEqual<Num1,Num2>extends true?true:IsGreaterThan<Num1,Num2>,IfTrue,IfFalse>;
|
|
1148
|
-
/**
|
|
1149
|
-
* * ***
|
|
1150
|
-
*
|
|
1151
|
-
*
|
|
1152
|
-
*
|
|
1153
|
-
* when using {@link IsBetween}.
|
|
1154
|
-
*
|
|
1155
|
-
* @property minIncluded - Whether to include the lower border (`Min`) in the comparison.
|
|
1156
|
-
* @default true
|
|
1157
|
-
* @property maxIncluded - Whether to include the upper border (`Max`) in the comparison.
|
|
1158
|
-
* @default true
|
|
1159
|
-
*
|
|
1160
|
-
* @example
|
|
1161
|
-
* ```ts
|
|
1162
|
-
* type Opt1 = IsBetweenOptions;
|
|
1163
|
-
* // ➔ { minIncluded?: boolean; maxIncluded?: boolean }
|
|
1164
|
-
* ```
|
|
1070
|
+
/** ---------------------------------------------------------------------------
|
|
1071
|
+
* * ***Type Options for {@link IsBetween | `IsBetween`}.***
|
|
1072
|
+
* ---------------------------------------------------------------------------
|
|
1073
|
+
* **Options to configure whether the borders of the interval are included
|
|
1074
|
+
* when using {@link IsBetween | **`IsBetween`**}.**
|
|
1165
1075
|
*/
|
|
1166
1076
|
type IsBetweenOptions={
|
|
1167
|
-
/** Whether to include the lower border (`Min`) in the comparison
|
|
1077
|
+
/** * ***Whether to include the lower border (`Min`) in the comparison.***
|
|
1168
1078
|
*
|
|
1169
|
-
* - `true`
|
|
1170
|
-
* - `false`
|
|
1079
|
+
* - `true` ➔ include `Min` (**default**).
|
|
1080
|
+
* - `false` ➔ exclude `Min`.
|
|
1171
1081
|
*
|
|
1172
1082
|
* @default true
|
|
1173
1083
|
*/
|
|
1174
1084
|
minIncluded?:boolean;
|
|
1175
|
-
/** Whether to include the upper border (`Max`) in the comparison
|
|
1085
|
+
/** * ***Whether to include the upper border (`Max`) in the comparison.***
|
|
1176
1086
|
*
|
|
1177
|
-
* - `true`
|
|
1178
|
-
* - `false`
|
|
1087
|
+
* - `true` ➔ include `Max` (**default**).
|
|
1088
|
+
* - `false` ➔ exclude `Max`.
|
|
1179
1089
|
*
|
|
1180
1090
|
* @default true
|
|
1181
1091
|
*/
|
|
1182
1092
|
maxIncluded?:boolean;};
|
|
1183
1093
|
/** -------------------------------------------------------
|
|
1184
|
-
* * ***IsBetween
|
|
1094
|
+
* * ***Utility Type: `IsBetween`.***
|
|
1185
1095
|
* -------------------------------------------------------
|
|
1186
|
-
* Returns a boolean whether the first integer argument is between the second and the third integer argument, by default, borders of the interval are included, which can be modified by the second argument
|
|
1187
|
-
* -
|
|
1188
|
-
*
|
|
1096
|
+
* **Returns a boolean whether the first integer argument is between the second and the third integer argument, by default, borders of the interval are included, which can be modified by the second argument.**
|
|
1097
|
+
* - **Behavior:**
|
|
1098
|
+
* - `minIncluded`, `maxIncluded` options show whether to include the lower and the higher borders
|
|
1099
|
+
* respectively.
|
|
1100
|
+
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
1189
1101
|
* @example
|
|
1190
|
-
* // truthy
|
|
1191
1102
|
* type Case1 = IsBetween<1, 1, 10>;
|
|
1192
1103
|
* // ➔ true
|
|
1193
|
-
*
|
|
1194
|
-
* // falsy
|
|
1195
1104
|
* type Case2 = IsBetween<1, 1, 10, {minIncluded: false}>;
|
|
1196
1105
|
* // ➔ false
|
|
1197
1106
|
* type Case3 = IsBetween<10, 1, 10, {maxIncluded: false}>;
|
|
1198
1107
|
* // ➔ false
|
|
1199
1108
|
*/
|
|
1200
1109
|
type IsBetween<Num extends number,Min extends number,Max extends number,Options extends IsBetweenOptions={minIncluded:true;maxIncluded:true;}>=IsEqual<Num,Min>extends true?Options["minIncluded"]:IsEqual<Num,Max>extends true?Options["maxIncluded"]:And<IsGreaterThan<Num,Min>,IsLowerThan<Num,Max>>;type _IsValidRGBParameter<T extends number>=IsInteger<T>extends true?IsBetween<T,0,255>:false;
|
|
1201
|
-
/** Configuration options for a type-level utility
|
|
1110
|
+
/** * ***Configuration options for a type-level utility
|
|
1111
|
+
* {@link RGB | `RGB`} | {@link IsRGB | `IsRGB` } | {@link IfRGB | `IfRGB` }.*** */
|
|
1202
1112
|
type RGBOptions={
|
|
1203
|
-
/** Separator character(s) used between the RGB components (`r`, `g`, `b`)
|
|
1113
|
+
/** * ***Separator character(s) used between the RGB components (`r`, `g`, `b`).***
|
|
1204
1114
|
*
|
|
1205
|
-
* For example
|
|
1206
|
-
*
|
|
1207
|
-
*
|
|
1115
|
+
* - **For example:**
|
|
1116
|
+
* - `","` ➔ `"rgb(23,242,0)"`.
|
|
1117
|
+
* - `", "` ➔ `"rgb(23, 242, 0)"`.
|
|
1208
1118
|
*
|
|
1209
1119
|
* @default ", "
|
|
1210
1120
|
*/
|
|
1211
1121
|
separator:string;};
|
|
1212
|
-
/** Default configuration for the `RGBOptions
|
|
1122
|
+
/** * ***Default configuration for the {@link RGBOptions | `RGBOptions`}.***
|
|
1213
1123
|
*
|
|
1214
1124
|
* @example
|
|
1215
1125
|
* ```ts
|
|
@@ -1218,20 +1128,19 @@ separator:string;};
|
|
|
1218
1128
|
* ```
|
|
1219
1129
|
*/
|
|
1220
1130
|
type DefaultRGBOptions={
|
|
1221
|
-
/**
|
|
1222
|
-
* Default separator for RGB components.
|
|
1131
|
+
/** * ***Default separator for RGB components.***
|
|
1223
1132
|
*
|
|
1224
|
-
* Produces strings like `"rgb(23, 242, 0)"
|
|
1133
|
+
* **Produces strings like `"rgb(23, 242, 0)"`.**
|
|
1225
1134
|
*/
|
|
1226
1135
|
separator:", ";};
|
|
1227
1136
|
/** -------------------------------------------------------
|
|
1228
|
-
* * ***RGB
|
|
1137
|
+
* * ***Utility Type: `RGB`.***
|
|
1229
1138
|
* -------------------------------------------------------
|
|
1230
|
-
* A type-level utility that validates an **RGB color string
|
|
1231
|
-
* -
|
|
1232
|
-
*
|
|
1233
|
-
*
|
|
1234
|
-
*
|
|
1139
|
+
* **A type-level utility that validates an **RGB color string**.**
|
|
1140
|
+
* - **Behavior:**
|
|
1141
|
+
* - Accepts `rgb(r, g, b)` format with customizable separators.
|
|
1142
|
+
* - Each parameter `r`, `g`, `b` must be an integer between `0` and `255`.
|
|
1143
|
+
* - Returns `T` if valid, otherwise `never`.
|
|
1235
1144
|
* @template T - A string to check.
|
|
1236
1145
|
* @template Options - Options with `separator` (defaults to `", "`).
|
|
1237
1146
|
* @example
|
|
@@ -1246,11 +1155,10 @@ separator:", ";};
|
|
|
1246
1155
|
*/
|
|
1247
1156
|
type RGB<T extends string,Options extends RGBOptions=DefaultRGBOptions>=T extends`rgb(${infer R extends number}${Options["separator"]}${infer G extends number}${Options["separator"]}${infer B extends number})`?AndArr<[ _IsValidRGBParameter<R>,_IsValidRGBParameter<G>,_IsValidRGBParameter<B>]>extends true?T:never:never;
|
|
1248
1157
|
/** -------------------------------------------------------
|
|
1249
|
-
* * ***IsRGB
|
|
1158
|
+
* * ***Utility Type: `IsRGB`.***
|
|
1250
1159
|
* -------------------------------------------------------
|
|
1251
|
-
* A type-level utility that checks if a string is a valid **RGB color
|
|
1160
|
+
* **A type-level utility that checks if a string is a valid **RGB color**.**
|
|
1252
1161
|
* - Returns `true` if valid, otherwise `false`.
|
|
1253
|
-
*
|
|
1254
1162
|
* @template T - A string to check.
|
|
1255
1163
|
* @template Options - Options with `separator` (defaults to `", "`).
|
|
1256
1164
|
* @example
|
|
@@ -1265,11 +1173,10 @@ type RGB<T extends string,Options extends RGBOptions=DefaultRGBOptions>=T extend
|
|
|
1265
1173
|
*/
|
|
1266
1174
|
type IsRGB<T extends string,Options extends RGBOptions=DefaultRGBOptions>=Not<IsNever<RGB<T,Options>>>;
|
|
1267
1175
|
/** -------------------------------------------------------
|
|
1268
|
-
* * ***IfRGB
|
|
1176
|
+
* * ***Utility Type: `IfRGB`.***
|
|
1269
1177
|
* -------------------------------------------------------
|
|
1270
|
-
* A conditional type that returns `IfTrue` if `T` is a valid **RGB color**,
|
|
1271
|
-
* otherwise returns `IfFalse
|
|
1272
|
-
*
|
|
1178
|
+
* **A conditional type that returns `IfTrue` if `T` is a valid **RGB color**,
|
|
1179
|
+
* otherwise returns `IfFalse`.**
|
|
1273
1180
|
* @template T - A string to check.
|
|
1274
1181
|
* @template IfTrue - Return type if valid (defaults to `true`).
|
|
1275
1182
|
* @template IfFalse - Return type if invalid (defaults to `false`).
|
|
@@ -1288,13 +1195,13 @@ type IsRGB<T extends string,Options extends RGBOptions=DefaultRGBOptions>=Not<Is
|
|
|
1288
1195
|
*/
|
|
1289
1196
|
type IfRGB<T extends string,IfTrue=true,IfFalse=false,Options extends RGBOptions=DefaultRGBOptions>=If<IsRGB<T,Options>,IfTrue,IfFalse>;type _ValidHEXCharacters=["0","1","2","3","4","5","6","7","8","9","A","B","C","D","E","F"];type _AllowedHEXLength=3|4|6|8;
|
|
1290
1197
|
/** -------------------------------------------------------
|
|
1291
|
-
* * ***HEX
|
|
1198
|
+
* * ***Utility Type: `HEX`.***
|
|
1292
1199
|
* -------------------------------------------------------
|
|
1293
|
-
* A type-level utility that validates a **HEX color string
|
|
1294
|
-
* -
|
|
1295
|
-
*
|
|
1296
|
-
*
|
|
1297
|
-
*
|
|
1200
|
+
* **A type-level utility that validates a **HEX color string**.**
|
|
1201
|
+
* - **Behavior:**
|
|
1202
|
+
* - Accepts `#RGB`, `#RGBA`, `#RRGGBB`, or `#RRGGBBAA` formats.
|
|
1203
|
+
* - Characters must be `[0-9A-F]` (**case-insensitive**).
|
|
1204
|
+
* - Returns `T` if valid, otherwise `never`.
|
|
1298
1205
|
* @template T - A string to check.
|
|
1299
1206
|
* @example
|
|
1300
1207
|
* ```ts
|
|
@@ -1308,11 +1215,10 @@ type IfRGB<T extends string,IfTrue=true,IfFalse=false,Options extends RGBOptions
|
|
|
1308
1215
|
*/
|
|
1309
1216
|
type HEX<T extends string>=(Uppercase<T>extends`#${infer HEXWithoutHashTag extends string}`?StringLength<HEXWithoutHashTag>extends _AllowedHEXLength?ExtendsArr<Split<HEXWithoutHashTag,"">,_ValidHEXCharacters[number]>:false:false)extends true?T:never;
|
|
1310
1217
|
/** -------------------------------------------------------
|
|
1311
|
-
* * ***IsHEX
|
|
1218
|
+
* * ***Utility Type: `IsHEX`.***
|
|
1312
1219
|
* -------------------------------------------------------
|
|
1313
|
-
* A type-level utility that checks if a string is a valid **HEX color
|
|
1220
|
+
* **A type-level utility that checks if a string is a valid **HEX color**.**
|
|
1314
1221
|
* - Returns `true` if valid, otherwise `false`.
|
|
1315
|
-
*
|
|
1316
1222
|
* @template T - A string to check.
|
|
1317
1223
|
* @example
|
|
1318
1224
|
* ```ts
|
|
@@ -1322,11 +1228,10 @@ type HEX<T extends string>=(Uppercase<T>extends`#${infer HEXWithoutHashTag exten
|
|
|
1322
1228
|
*/
|
|
1323
1229
|
type IsHEX<T extends string>=Not<IsNever<HEX<T>>>;
|
|
1324
1230
|
/** -------------------------------------------------------
|
|
1325
|
-
* * ***IfHEX
|
|
1231
|
+
* * ***Utility Type: `IfHEX`.***
|
|
1326
1232
|
* -------------------------------------------------------
|
|
1327
|
-
* A conditional type that returns `IfTrue` if `T` is a valid **HEX color**,
|
|
1328
|
-
* otherwise returns `IfFalse
|
|
1329
|
-
*
|
|
1233
|
+
* **A conditional type that returns `IfTrue` if `T` is a valid **HEX color**,
|
|
1234
|
+
* otherwise returns `IfFalse`.**
|
|
1330
1235
|
* @template T - A string to check.
|
|
1331
1236
|
* @template IfTrue - Return type if valid (defaults to `true`).
|
|
1332
1237
|
* @template IfFalse - Return type if invalid (defaults to `false`).
|
|
@@ -1343,18 +1248,19 @@ type IsHEX<T extends string>=Not<IsNever<HEX<T>>>;
|
|
|
1343
1248
|
* ```
|
|
1344
1249
|
*/
|
|
1345
1250
|
type IfHEX<T extends string,IfTrue=true,IfFalse=false>=If<IsHEX<T>,IfTrue,IfFalse>;
|
|
1346
|
-
/** Configuration options for a type-level utility
|
|
1251
|
+
/** * ***Configuration options for a type-level utility
|
|
1252
|
+
* {@link HSL | `HSL` } | {@link IsHSL | `IsHSL` } | {@link IfHSL | `IfHSL` }.*** */
|
|
1347
1253
|
type HSLOptions={
|
|
1348
|
-
/** Separator character(s) used between the HSL components (`h`, `s`, `l`)
|
|
1254
|
+
/** * ***Separator character(s) used between the HSL components (`h`, `s`, `l`).***
|
|
1349
1255
|
*
|
|
1350
|
-
* For example
|
|
1351
|
-
*
|
|
1352
|
-
*
|
|
1256
|
+
* - **For example:**
|
|
1257
|
+
* - `","` ➔ `"hsl(180,100%,50%)"`.
|
|
1258
|
+
* - `", "` ➔ `"hsl(180, 100%, 50%)"`.
|
|
1353
1259
|
*
|
|
1354
1260
|
* @default ", "
|
|
1355
1261
|
*/
|
|
1356
1262
|
separator:string;};
|
|
1357
|
-
/** Default configuration for the `HSLOptions
|
|
1263
|
+
/** * ***Default configuration for the {@link HSLOptions | `HSLOptions`}.***
|
|
1358
1264
|
*
|
|
1359
1265
|
* @example
|
|
1360
1266
|
* ```ts
|
|
@@ -1363,19 +1269,19 @@ separator:string;};
|
|
|
1363
1269
|
* ```
|
|
1364
1270
|
*/
|
|
1365
1271
|
type DefaultHSLOptions={
|
|
1366
|
-
/** Default separator for HSL components
|
|
1272
|
+
/** * ***Default separator for HSL components.***
|
|
1367
1273
|
*
|
|
1368
|
-
* Produces strings like `"hsl(180, 100%, 50%)"
|
|
1274
|
+
* **Produces strings like `"hsl(180, 100%, 50%)"`.**
|
|
1369
1275
|
*/
|
|
1370
1276
|
separator:", ";};
|
|
1371
1277
|
/** -------------------------------------------------------
|
|
1372
|
-
* * ***HSL
|
|
1278
|
+
* * ***Utility Type: `HSL`.***
|
|
1373
1279
|
* -------------------------------------------------------
|
|
1374
|
-
* A type-level utility that validates an **HSL color string
|
|
1375
|
-
* -
|
|
1376
|
-
*
|
|
1377
|
-
*
|
|
1378
|
-
*
|
|
1280
|
+
* **A type-level utility that validates an **HSL color string**.**
|
|
1281
|
+
* - **Behavior:**
|
|
1282
|
+
* - Accepts `hsl(h, s%, l%)` format with customizable separators.
|
|
1283
|
+
* - `h` must be an integer, `s` and `l` must be integers between `0` and `100`.
|
|
1284
|
+
* - Returns `T` if valid, otherwise `never`.
|
|
1379
1285
|
* @template T - A string to check.
|
|
1380
1286
|
* @template Options - Options with `separator` (defaults to `", "`).
|
|
1381
1287
|
* @example
|
|
@@ -1390,11 +1296,10 @@ separator:", ";};
|
|
|
1390
1296
|
*/
|
|
1391
1297
|
type HSL<T extends string,Options extends HSLOptions=DefaultHSLOptions>=(T extends`hsl(${infer H extends number}${Options["separator"]}${infer S extends number}%${Options["separator"]}${infer L extends number}%)`?AndArr<[IsInteger<H>,IsInteger<S>,IsInteger<L>]>extends true?AndArr<[IsBetween<S,0,100>,IsBetween<L,0,100>]>:false:false)extends true?T:never;
|
|
1392
1298
|
/** -------------------------------------------------------
|
|
1393
|
-
* * ***IsHSL
|
|
1299
|
+
* * ***Utility Type: `IsHSL`.***
|
|
1394
1300
|
* -------------------------------------------------------
|
|
1395
|
-
* A type-level utility that checks if a string is a valid **HSL color
|
|
1301
|
+
* **A type-level utility that checks if a string is a valid **HSL color**.**
|
|
1396
1302
|
* - Returns `true` if valid, otherwise `false`.
|
|
1397
|
-
*
|
|
1398
1303
|
* @template T - A string to check.
|
|
1399
1304
|
* @template Options - Options with `separator` (defaults to `", "`).
|
|
1400
1305
|
* @example
|
|
@@ -1409,11 +1314,10 @@ type HSL<T extends string,Options extends HSLOptions=DefaultHSLOptions>=(T exten
|
|
|
1409
1314
|
*/
|
|
1410
1315
|
type IsHSL<T extends string,Options extends HSLOptions=DefaultHSLOptions>=Not<IsNever<HSL<T,Options>>>;
|
|
1411
1316
|
/** -------------------------------------------------------
|
|
1412
|
-
* * ***IfHSL
|
|
1317
|
+
* * ***Utility Type: `IfHSL`.***
|
|
1413
1318
|
* -------------------------------------------------------
|
|
1414
|
-
* A conditional type that returns `IfTrue` if `T` is a valid **HSL color**,
|
|
1415
|
-
* otherwise returns `IfFalse
|
|
1416
|
-
*
|
|
1319
|
+
* **A conditional type that returns `IfTrue` if `T` is a valid **HSL color**,
|
|
1320
|
+
* otherwise returns `IfFalse`.**
|
|
1417
1321
|
* @template T - A string to check.
|
|
1418
1322
|
* @template IfTrue - Return type if valid (defaults to `true`).
|
|
1419
1323
|
* @template IfFalse - Return type if invalid (defaults to `false`).
|
|
@@ -1429,18 +1333,17 @@ type IsHSL<T extends string,Options extends HSLOptions=DefaultHSLOptions>=Not<Is
|
|
|
1429
1333
|
* ```
|
|
1430
1334
|
*/
|
|
1431
1335
|
type IfHSL<T extends string,IfTrue=true,IfFalse=false,Options extends HSLOptions=DefaultHSLOptions>=If<IsHSL<T,Options>,IfTrue,IfFalse>;
|
|
1432
|
-
/** High-level configuration for
|
|
1336
|
+
/** * ***High-level configuration for {@link Color | `Color`} parsing utilities.***
|
|
1433
1337
|
*
|
|
1434
|
-
* Allows customizing **RGB** and **HSL** parsing behavior independently
|
|
1338
|
+
* **Allows customizing **RGB** and **HSL** parsing behavior independently.**
|
|
1435
1339
|
*/
|
|
1436
1340
|
type ColorOptions={
|
|
1437
|
-
/** Options for handling RGB color strings
|
|
1438
|
-
*
|
|
1439
|
-
* - Controls parsing and formatting behavior of RGB values.
|
|
1440
|
-
* - By default uses {@link DefaultRGBOptions}.
|
|
1341
|
+
/** * ***Options for handling RGB color strings.***
|
|
1441
1342
|
*
|
|
1343
|
+
* - **Behavior:**
|
|
1344
|
+
* - Controls parsing and formatting behavior of RGB values.
|
|
1345
|
+
* - By default uses {@link DefaultRGBOptions | **`DefaultRGBOptions`**}.
|
|
1442
1346
|
* @default DefaultRGBOptions
|
|
1443
|
-
*
|
|
1444
1347
|
* @example
|
|
1445
1348
|
* ```ts
|
|
1446
1349
|
* type Opt = ColorOptions["rgbOptions"];
|
|
@@ -1452,13 +1355,12 @@ type ColorOptions={
|
|
|
1452
1355
|
* ```
|
|
1453
1356
|
*/
|
|
1454
1357
|
rgbOptions?:RGBOptions;
|
|
1455
|
-
/** Options for handling HSL color strings
|
|
1456
|
-
*
|
|
1457
|
-
* - Controls parsing and formatting behavior of HSL values.
|
|
1458
|
-
* - By default uses {@link DefaultHSLOptions}.
|
|
1358
|
+
/** * ***Options for handling HSL color strings.***
|
|
1459
1359
|
*
|
|
1360
|
+
* - **Behavior:**
|
|
1361
|
+
* - Controls parsing and formatting behavior of HSL values.
|
|
1362
|
+
* - By default uses {@link DefaultHSLOptions | **`DefaultHSLOptions`**}.
|
|
1460
1363
|
* @default DefaultHSLOptions
|
|
1461
|
-
*
|
|
1462
1364
|
* @example
|
|
1463
1365
|
* ```ts
|
|
1464
1366
|
* type Opt = ColorOptions["hslOptions"];
|
|
@@ -1470,7 +1372,7 @@ rgbOptions?:RGBOptions;
|
|
|
1470
1372
|
* ```
|
|
1471
1373
|
*/
|
|
1472
1374
|
hslOptions?:HSLOptions;};
|
|
1473
|
-
/** Default configuration for the `
|
|
1375
|
+
/** * ***Default configuration for the {@link ColorOptions |`ColorOptions`}.***
|
|
1474
1376
|
*
|
|
1475
1377
|
* @example
|
|
1476
1378
|
* ```ts
|
|
@@ -1479,11 +1381,11 @@ hslOptions?:HSLOptions;};
|
|
|
1479
1381
|
* ```
|
|
1480
1382
|
*/
|
|
1481
1383
|
type DefaultColorOptions={
|
|
1482
|
-
/** Default configuration for `RGBOptions
|
|
1483
|
-
*
|
|
1484
|
-
* - Provides the default separator for RGB strings.
|
|
1485
|
-
* - By default: `", "`
|
|
1384
|
+
/** * ***Default configuration for `RGBOptions`.***
|
|
1486
1385
|
*
|
|
1386
|
+
* - **Behavior:**
|
|
1387
|
+
* - Provides the default separator for RGB strings.
|
|
1388
|
+
* - By default: `", "`
|
|
1487
1389
|
* @example
|
|
1488
1390
|
* ```ts
|
|
1489
1391
|
* type RGBOpt = DefaultColorOptions["rgbOptions"];
|
|
@@ -1491,11 +1393,11 @@ type DefaultColorOptions={
|
|
|
1491
1393
|
* ```
|
|
1492
1394
|
*/
|
|
1493
1395
|
rgbOptions:DefaultRGBOptions;
|
|
1494
|
-
/** Default configuration for `HSLOptions
|
|
1495
|
-
*
|
|
1496
|
-
* - Provides the default separator for HSL strings.
|
|
1497
|
-
* - By default: `", "`
|
|
1396
|
+
/** * ***Default configuration for `HSLOptions`.***
|
|
1498
1397
|
*
|
|
1398
|
+
* - **Behavior:**
|
|
1399
|
+
* - Provides the default separator for HSL strings.
|
|
1400
|
+
* - By default: `", "`
|
|
1499
1401
|
* @example
|
|
1500
1402
|
* ```ts
|
|
1501
1403
|
* type HSLOpt = DefaultColorOptions["hslOptions"];
|
|
@@ -1504,16 +1406,15 @@ rgbOptions:DefaultRGBOptions;
|
|
|
1504
1406
|
*/
|
|
1505
1407
|
hslOptions:DefaultHSLOptions;};type ResolveRGBOptions<O extends ColorOptions>=O["rgbOptions"] extends RGBOptions?O["rgbOptions"]:DefaultRGBOptions;type ResolveHSLOptions<O extends ColorOptions>=O["hslOptions"] extends HSLOptions?O["hslOptions"]:DefaultHSLOptions;
|
|
1506
1408
|
/** -------------------------------------------------------
|
|
1507
|
-
* * ***Color
|
|
1409
|
+
* * ***Utility Type: `Color`.***
|
|
1508
1410
|
* -------------------------------------------------------
|
|
1509
|
-
* A type-level utility that validates a string as a **Color** in
|
|
1510
|
-
*
|
|
1511
|
-
*
|
|
1512
|
-
*
|
|
1513
|
-
*
|
|
1411
|
+
* - **A type-level utility that validates a string as a **Color** in:**
|
|
1412
|
+
* - **`RGB`**.
|
|
1413
|
+
* - **`HEX`**.
|
|
1414
|
+
* - **`HSL`**.
|
|
1514
1415
|
* @returns {T} Returns `T` if valid, otherwise `never`.
|
|
1515
1416
|
* @template T - A string to check.
|
|
1516
|
-
* @template Options - Options to pass down to RGB
|
|
1417
|
+
* @template Options - Options to pass down to `RGB`/`HSL` validation.
|
|
1517
1418
|
* @example
|
|
1518
1419
|
* ```ts
|
|
1519
1420
|
* type A = Color<"rgb(23, 242, 0)">;
|
|
@@ -1522,17 +1423,16 @@ hslOptions:DefaultHSLOptions;};type ResolveRGBOptions<O extends ColorOptions>=O[
|
|
|
1522
1423
|
* // ➔ never
|
|
1523
1424
|
* type C = Color<"#000000">;
|
|
1524
1425
|
* // ➔ "#000000"
|
|
1525
|
-
* type D = Color<"hsl(100,34%,56%)", { hslOptions: { separator: "," }
|
|
1426
|
+
* type D = Color<"hsl(100,34%,56%)", { hslOptions: { separator: "," }}>;
|
|
1526
1427
|
* // ➔ "hsl(100,34%,56%)"
|
|
1527
1428
|
* ```
|
|
1528
1429
|
*/
|
|
1529
1430
|
type Color<T extends string,Options extends ColorOptions=DefaultColorOptions>=HEX<T>|HSL<T,ResolveHSLOptions<Options>>|RGB<T,ResolveRGBOptions<Options>>;
|
|
1530
1431
|
/** -------------------------------------------------------
|
|
1531
|
-
* * ***IsColor
|
|
1432
|
+
* * ***Utility Type: `IsColor`.***
|
|
1532
1433
|
* -------------------------------------------------------
|
|
1533
|
-
* A type-level utility that checks if a string is a valid **Color**
|
|
1534
|
-
* (RGB | HEX | HSL)
|
|
1535
|
-
*
|
|
1434
|
+
* **A type-level utility that checks if a string is a valid **Color**
|
|
1435
|
+
* (`RGB` | `HEX` | `HSL`).**
|
|
1536
1436
|
* @returns {T} - Returns `true` if valid, otherwise `false`.
|
|
1537
1437
|
* @template T - A string to check.
|
|
1538
1438
|
* @template Options - Options to pass down to RGB/HSL validation.
|
|
@@ -1550,18 +1450,17 @@ type Color<T extends string,Options extends ColorOptions=DefaultColorOptions>=HE
|
|
|
1550
1450
|
*/
|
|
1551
1451
|
type IsColor<T extends string,Options extends ColorOptions=DefaultColorOptions>=Not<IsNever<Color<T,Options>>>;
|
|
1552
1452
|
/** -------------------------------------------------------
|
|
1553
|
-
* * ***IfColor
|
|
1453
|
+
* * ***Utility Type: `IfColor`.***
|
|
1554
1454
|
* -------------------------------------------------------
|
|
1555
|
-
* A conditional type that returns `IfTrue` if `T` is a valid **Color**
|
|
1556
|
-
* (RGB | HEX | HSL), otherwise returns `IfFalse
|
|
1557
|
-
*
|
|
1455
|
+
* **A conditional type that returns `IfTrue` if `T` is a valid **Color**
|
|
1456
|
+
* (`RGB` | `HEX` | `HSL`), otherwise returns `IfFalse`.**
|
|
1558
1457
|
* @template T - A string to check.
|
|
1559
1458
|
* @template IfTrue - Return type if valid (defaults to `true`).
|
|
1560
1459
|
* @template IfFalse - Return type if invalid (defaults to `false`).
|
|
1561
1460
|
* @template Options - Options to pass down to RGB/HSL validation.
|
|
1562
1461
|
* @example
|
|
1563
1462
|
* ```ts
|
|
1564
|
-
* type A = IfColor<"rgb(23, 242, 0)", { rgbOptions: { separator: ", " }
|
|
1463
|
+
* type A = IfColor<"rgb(23, 242, 0)", { rgbOptions: { separator: ", " }}, "valid">;
|
|
1565
1464
|
* // ➔ "valid"
|
|
1566
1465
|
* type B = IfColor<"rgb(324, 123, 3)", DefaultColorOptions, "valid","invalid">;
|
|
1567
1466
|
* // ➔ "invalid"
|
|
@@ -1571,10 +1470,9 @@ type IsColor<T extends string,Options extends ColorOptions=DefaultColorOptions>=
|
|
|
1571
1470
|
*/
|
|
1572
1471
|
type IfColor<T extends string,Options extends ColorOptions=DefaultColorOptions,IfTrue=true,IfFalse=false>=If<IsColor<T,Options>,IfTrue,IfFalse>;
|
|
1573
1472
|
/** -------------------------------------------------------
|
|
1574
|
-
* * ***Concat
|
|
1473
|
+
* * ***Utility Type: `Concat`.***
|
|
1575
1474
|
* -------------------------------------------------------
|
|
1576
|
-
* A type-level utility that concatenates `two arrays` into `one
|
|
1577
|
-
*
|
|
1475
|
+
* **A type-level utility that concatenates `two arrays` into `one`.**
|
|
1578
1476
|
* @template T - The first array type.
|
|
1579
1477
|
* @template U - The second array type, or a single element.
|
|
1580
1478
|
* @example
|
|
@@ -1593,30 +1491,25 @@ type IfColor<T extends string,Options extends ColorOptions=DefaultColorOptions,I
|
|
|
1593
1491
|
*/
|
|
1594
1492
|
type Concat<T extends readonly unknown[],U>=[ ...T,...(U extends readonly unknown[]?U:[U])];
|
|
1595
1493
|
/** -------------------------------------------------------
|
|
1596
|
-
* * ***DigitsTuple
|
|
1597
|
-
* -------------------------------------------------------
|
|
1598
|
-
* A **type-level utility** that converts a numeric literal (number or bigint) into
|
|
1599
|
-
* structured representation of its digits
|
|
1600
|
-
*
|
|
1601
|
-
*
|
|
1602
|
-
*
|
|
1603
|
-
*
|
|
1604
|
-
*
|
|
1605
|
-
*
|
|
1606
|
-
*
|
|
1607
|
-
*
|
|
1608
|
-
*
|
|
1609
|
-
*
|
|
1610
|
-
*
|
|
1611
|
-
*
|
|
1612
|
-
* - Floating-point numbers (decimal points are ignored)
|
|
1613
|
-
* - BigInt values
|
|
1614
|
-
*
|
|
1494
|
+
* * ***Utility Type: `DigitsTuple`.***
|
|
1495
|
+
* -------------------------------------------------------
|
|
1496
|
+
* **A **type-level utility** that converts a numeric literal (number or bigint) into
|
|
1497
|
+
* a structured representation of its digits.**
|
|
1498
|
+
* - **The resulting type is an **object** with the following properties:**
|
|
1499
|
+
* - `negative`: boolean flag indicating if the number is negative.
|
|
1500
|
+
* - `bigint`: boolean flag indicating if the value is a bigint.
|
|
1501
|
+
* - `float`: boolean flag indicating if the value is a floating-point number.
|
|
1502
|
+
* - `digits`: a tuple of digits (each as a `number`), with decimal points and
|
|
1503
|
+
* bigint suffix `n` removed.
|
|
1504
|
+
* - **Works with:**
|
|
1505
|
+
* - Positive integers
|
|
1506
|
+
* - Negative integers
|
|
1507
|
+
* - Zero and negative zero
|
|
1508
|
+
* - Floating-point numbers (decimal points are ignored)
|
|
1509
|
+
* - BigInt values
|
|
1615
1510
|
* **Note:** TypeScript automatically normalizes scientific notation numeric literals
|
|
1616
|
-
* (e.g., `5e3`
|
|
1617
|
-
*
|
|
1511
|
+
* (e.g., `5e3` ➔ `5000`), so the `digits` tuple will reflect the expanded value.
|
|
1618
1512
|
* @template T - A numeric literal type (`number` or `bigint`) to convert.
|
|
1619
|
-
*
|
|
1620
1513
|
* @example
|
|
1621
1514
|
* ```ts
|
|
1622
1515
|
* // Single digit
|
|
@@ -1650,31 +1543,27 @@ type Concat<T extends readonly unknown[],U>=[ ...T,...(U extends readonly unknow
|
|
|
1650
1543
|
* // ➔ { negative: true; bigint: true; float: false; digits: [9, 8, 7, 6, 5] }
|
|
1651
1544
|
*
|
|
1652
1545
|
* // Scientific notation numeric literals (auto-expanded)
|
|
1653
|
-
* type J = DigitsTuple<5e3>;
|
|
1546
|
+
* type J = DigitsTuple<5e3>; // `5e3` is same like `5000`
|
|
1654
1547
|
* // ➔ { negative: false; bigint: false; float: false; digits: [5, 0, 0, 0] }
|
|
1655
|
-
* type K = DigitsTuple<-2.5e2>;
|
|
1548
|
+
* type K = DigitsTuple<-2.5e2>; // `-2.5e2` is same like `-250`
|
|
1656
1549
|
* // ➔ { negative: true; bigint: false; float: true; digits: [2, 5, 0] }
|
|
1657
1550
|
* ```
|
|
1658
1551
|
*/
|
|
1659
1552
|
type DigitsTuple<T extends number|bigint>={negative:`${T}`extends`-${string}`?true:false;float:IsFloat<Extract<T,number>>extends true?true:false;bigint:T extends bigint?true:false;digits:Split<ReplaceAll<Stringify<Abs<T>>,[".","n"],"">>extends infer R?{[K in keyof R]:R[K] extends string?ParseNumber<R[K]>:never;}:never;};
|
|
1660
1553
|
/** -------------------------------------------------------
|
|
1661
|
-
* * ***ReturnItselfIfExtends
|
|
1554
|
+
* * ***Utility Type: `ReturnItselfIfExtends`.***
|
|
1662
1555
|
* -------------------------------------------------------
|
|
1663
|
-
*
|
|
1664
|
-
* A conditional type that returns:
|
|
1665
|
-
* - `Else` if `T` extends `Base`,
|
|
1666
|
-
* - `T` itself if `T` does **not** extend `Base`,
|
|
1667
|
-
* - `IfANever` if `T` is `never`.
|
|
1668
|
-
*
|
|
1669
|
-
* This utility is useful when you want to **narrow types by extension**,
|
|
1556
|
+
* **This utility is useful when you want to **narrow types by extension**,
|
|
1670
1557
|
* replacing them with a fallback if they match a given base constraint,
|
|
1671
|
-
* while preserving them otherwise
|
|
1672
|
-
*
|
|
1558
|
+
* while preserving them otherwise.**
|
|
1559
|
+
* - **A conditional type that returns:**
|
|
1560
|
+
* - `Else` if `T` extends `Base`.
|
|
1561
|
+
* - `T` itself if `T` does extend `Base`.
|
|
1562
|
+
* - `IfANever` if `T` is `never`.
|
|
1673
1563
|
* @template T - The type to check.
|
|
1674
1564
|
* @template Base - The base type to test against.
|
|
1675
1565
|
* @template Else - The type to return if `T` extends `Base`.
|
|
1676
1566
|
* @template IfANever - The type to return if `T` or `Base` is `never` (default: `never`).
|
|
1677
|
-
*
|
|
1678
1567
|
* @example
|
|
1679
1568
|
* ```ts
|
|
1680
1569
|
* type Case1 = ReturnItselfIfExtends<1, number, 2>
|
|
@@ -1693,22 +1582,18 @@ type DigitsTuple<T extends number|bigint>={negative:`${T}`extends`-${string}`?tr
|
|
|
1693
1582
|
*/
|
|
1694
1583
|
type ReturnItselfIfExtends<T,Base,Else,IfANever=never>=IfNever<If<Extends<Or<Base,T>,true>,never>,IfANever,T extends Base?T:Else>;
|
|
1695
1584
|
/** -------------------------------------------------------
|
|
1696
|
-
* * ***ReturnItselfIfNotExtends
|
|
1585
|
+
* * ***Utility Type: `ReturnItselfIfNotExtends`.***
|
|
1697
1586
|
* -------------------------------------------------------
|
|
1698
|
-
*
|
|
1699
|
-
*
|
|
1700
|
-
* -
|
|
1701
|
-
*
|
|
1702
|
-
*
|
|
1703
|
-
*
|
|
1704
|
-
* This utility is useful for preserving a type unless it matches
|
|
1705
|
-
* a broader constraint, in which case it is replaced with a fallback.
|
|
1706
|
-
*
|
|
1587
|
+
* **This utility is useful for preserving a type unless it matches
|
|
1588
|
+
* a broader constraint, in which case it is replaced with a fallback.**
|
|
1589
|
+
* - **A conditional type that returns:**
|
|
1590
|
+
* - `Else` if `T` extends `Base`.
|
|
1591
|
+
* - `T` itself if `T` does **not** extend `Base`.
|
|
1592
|
+
* - `IfANever` if `T` is `never`.
|
|
1707
1593
|
* @template T - The type to check.
|
|
1708
1594
|
* @template Base - The base type to test against.
|
|
1709
1595
|
* @template Else - The type to return if `T` extends `Base`.
|
|
1710
1596
|
* @template IfANever - The type to return if `T` or `Base` is `never` (default: `never`).
|
|
1711
|
-
*
|
|
1712
1597
|
* @example
|
|
1713
1598
|
* ```ts
|
|
1714
1599
|
* type Case1 = ReturnItselfIfNotExtends<'1', number, 2>
|
|
@@ -1725,14 +1610,15 @@ type ReturnItselfIfExtends<T,Base,Else,IfANever=never>=IfNever<If<Extends<Or<Bas
|
|
|
1725
1610
|
*/
|
|
1726
1611
|
type ReturnItselfIfNotExtends<T,Base,Else,IfANever=never>=IfNever<If<Extends<Or<Base,T>,true>,never>,IfANever,T extends Base?Else:T>;type MultiplicationMap={0:[0,0,0,0,0,0,0,0,0,0];1:[0,1,2,3,4,5,6,7,8,9];2:[0,2,4,6,8,10,12,14,16,18];3:[0,3,6,9,12,15,18,21,24,27];4:[0,4,8,12,16,20,24,28,32,36];5:[0,5,10,15,20,25,30,35,40,45];6:[0,6,12,18,24,30,36,42,48,54];7:[0,7,14,21,28,35,42,49,56,63];8:[0,8,16,24,32,40,48,56,64,72];9:[0,9,18,27,36,45,54,63,72,81];};type _MultiSingle<Num1 extends string,DigitOfNum2 extends keyof MultiplicationMap,Carry extends number=0,Result extends string="">=IsEmptyString<Num1>extends true?ReturnItselfIfNotExtends<RemoveLeading<`${Carry}${Result}`,"0">,"","0">:IsEqual<Num1,0>extends true?"0":IsEqual<DigitOfNum2,0>extends true?"0":LastCharacter<Num1,{includeRest:true;}>extends [ infer Num1LastCharacter extends string,infer Num1Rest extends string]?Stringify<Sum<MultiplicationMap[DigitOfNum2][ParseNumber<Num1LastCharacter>& keyof MultiplicationMap[DigitOfNum2]],Carry>>extends infer Multiplied extends string?LastCharacter<Multiplied,{includeRest:true;}>extends [ infer MultipliedLastDigit extends string,infer MultipliedRest extends string]?_MultiSingle<Num1Rest,DigitOfNum2,If<IsNever<ParseNumber<MultipliedRest>>,0,ParseNumber<MultipliedRest>>,`${MultipliedLastDigit}${Result}`>:never:never:never;type _Multi<Num1 extends string,Num2 extends string,Result extends string="",Iteration extends unknown[]=[]>=IsEmptyString<Num2>extends true?Result:LastCharacter<Num2,{includeRest:true;}>extends [ infer Num2LastCharacter extends string,infer Num2Rest extends string]?ParseNumber<Num2LastCharacter>extends infer Num2Digit extends keyof MultiplicationMap?_Multi<Num1,Num2Rest,Stringify<_Sum<Result,ReturnItselfIfNotExtends<RemoveLeading<`${_MultiSingle<Num1, Num2Digit>}${Repeat<"0", Iteration["length"]>}`,"0">,"","0">>>,Push<Iteration,unknown>>:never:Result;
|
|
1727
1612
|
/** -------------------------------------------------------
|
|
1728
|
-
* * ***Multi
|
|
1613
|
+
* * ***Utility Type: `Multi`.***
|
|
1729
1614
|
* -------------------------------------------------------
|
|
1730
|
-
* Accepts two integers and returns their **multiplication
|
|
1731
|
-
*
|
|
1732
|
-
*
|
|
1733
|
-
* -
|
|
1734
|
-
*
|
|
1735
|
-
*
|
|
1615
|
+
* **Accepts two integers and returns their **multiplication**.**
|
|
1616
|
+
* - **Behavior:**
|
|
1617
|
+
* - Handles negative numbers automatically.
|
|
1618
|
+
* - Uses internal type-level recursion to simulate multiplication of
|
|
1619
|
+
* digit strings.
|
|
1620
|
+
* - Works with integers within the range:
|
|
1621
|
+
* - `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
1736
1622
|
* @template Num1 - The first integer (can be negative).
|
|
1737
1623
|
* @template Num2 - The second integer (can be negative).
|
|
1738
1624
|
* @example
|
|
@@ -1744,20 +1630,19 @@ type ReturnItselfIfNotExtends<T,Base,Else,IfANever=never>=IfNever<If<Extends<Or<
|
|
|
1744
1630
|
* type Case5 = Multi<123, 45>; // ➔ 5535
|
|
1745
1631
|
* ```
|
|
1746
1632
|
* @note
|
|
1747
|
-
* Internal helpers
|
|
1748
|
-
*
|
|
1749
|
-
*
|
|
1633
|
+
* - ***Internal helpers:***
|
|
1634
|
+
* - `_Multi` ➔ Recursively multiplies digit strings and accumulates the result.
|
|
1635
|
+
* - `_MultiSingle` ➔ Multiplies a string-number with a single digit, handling carry.
|
|
1750
1636
|
*/
|
|
1751
1637
|
type Multi<Num1 extends number,Num2 extends number>=IsEqual<Num1,0>extends true?0:IsEqual<Num2,0>extends true?0:ParseNumber<_Multi<Stringify<Abs<Num1>>,Stringify<Abs<Num2>>>>extends infer Result extends number?IfNegative<Num1,IfNegative<Num2,Result,Negate<Result>>,IfNegative<Num2,Negate<Result>,Result>>:never;type _FindQuotient<Dividend extends number,Divisor extends number,CurrentQuotient extends number>=Multi<Divisor,CurrentQuotient>extends infer Product extends number?IsEqual<Dividend,Product>extends true?CurrentQuotient:IsLowerThan<Dividend,Product>extends true?_FindQuotient<Dividend,Divisor,Decrement<CurrentQuotient>>:CurrentQuotient:never;type _Div<Dividend extends string,Divisor extends number,Result extends string="",CurrentDividend extends string="",IterationsWithoutDivision extends number=0,HadFirstDivision extends boolean=false>=Or<IsEmptyString<CurrentDividend>,IsLowerThan<ParseNumber<CurrentDividend>,Divisor>>extends true?IsEmptyString<Dividend>extends true?ParseNumber<If<And<HadFirstDivision,IsNotEqual<IterationsWithoutDivision,0>>,`${Result}0`,Result>>:Dividend extends`${infer FirstDigit extends string}${infer Rest extends string}`?_Div<Rest,Divisor,If<And<HadFirstDivision,IsNotEqual<IterationsWithoutDivision,0>>,`${Result}0`,Result>,IfEqual<CurrentDividend,"0",FirstDigit,`${CurrentDividend}${FirstDigit}`>,Increment<IterationsWithoutDivision>,HadFirstDivision>:never:_FindQuotient<ParseNumber<CurrentDividend>,Divisor,10>extends infer Quotient extends number?IsNever<Quotient>extends true?ParseNumber<Result>:Sub<ParseNumber<CurrentDividend>,Multi<Quotient,Divisor>>extends infer Remainder extends number?_Div<Dividend,Divisor,`${Result}${Quotient}`,IfGreaterThan<Remainder,0,`${Remainder}`,"">,0,true>:never:never;
|
|
1752
1638
|
/** -------------------------------------------------------
|
|
1753
|
-
* * ***Div
|
|
1639
|
+
* * ***Utility Type: `Div`.***
|
|
1754
1640
|
* -------------------------------------------------------
|
|
1755
|
-
* A type-level utility that returns the integer division of two numbers.
|
|
1756
|
-
* Handles negative numbers correctly and returns `never` if dividing by zero
|
|
1757
|
-
*
|
|
1758
|
-
*
|
|
1759
|
-
*
|
|
1760
|
-
*
|
|
1641
|
+
* **A type-level utility that returns the integer division of two numbers.
|
|
1642
|
+
* Handles negative numbers correctly and returns `never` if dividing by zero.**
|
|
1643
|
+
* - **Behavior:**
|
|
1644
|
+
* - Returns `0` if the absolute value of dividend is smaller than divisor.
|
|
1645
|
+
* - Preserves the sign according to standard integer division rules.
|
|
1761
1646
|
* @template Dividend - The dividend number.
|
|
1762
1647
|
* @template Divisor - The divisor number.
|
|
1763
1648
|
* @example
|
|
@@ -1774,14 +1659,15 @@ type Multi<Num1 extends number,Num2 extends number>=IsEqual<Num1,0>extends true?
|
|
|
1774
1659
|
*/
|
|
1775
1660
|
type Div<Dividend extends number,Divisor extends number>=IsEqual<Divisor,0>extends true?never:IsEqual<Dividend,0>extends true?0:IsEqual<Dividend,Divisor>extends true?1:IsLowerThan<Abs<Dividend>,Abs<Divisor>>extends true?0:_Div<Stringify<Abs<Dividend>>,Abs<Divisor>>extends infer Quotient extends number?If<Or<And<IsNegative<Dividend>,IsNegative<Divisor>>,And<IsPositive<Dividend>,IsPositive<Divisor>>>,Quotient,Negate<Quotient>>:never;
|
|
1776
1661
|
/** -------------------------------------------------------
|
|
1777
|
-
* * ***Dot
|
|
1662
|
+
* * ***Utility Type: `Dot`.***
|
|
1778
1663
|
* -------------------------------------------------------
|
|
1779
|
-
* A type-level utility that concatenates two string literals with a
|
|
1780
|
-
* -
|
|
1781
|
-
*
|
|
1782
|
-
*
|
|
1783
|
-
*
|
|
1784
|
-
*
|
|
1664
|
+
* **A type-level utility that concatenates two string literals with a `.`.**
|
|
1665
|
+
* - **Behavior:**
|
|
1666
|
+
* - If the `Trims` flag is `true` (default), leading and trailing spaces in
|
|
1667
|
+
* both strings are trimmed before concatenation.
|
|
1668
|
+
* - If the second string literal is empty, it returns the first string literal.
|
|
1669
|
+
* - If the first string literal is empty, it returns the second string literal.
|
|
1670
|
+
* - Otherwise, it returns `${T}.${U}` (trimmed if `Trims` is `true`).
|
|
1785
1671
|
* @template T - The first string literal.
|
|
1786
1672
|
* @template U - The second string literal.
|
|
1787
1673
|
* @template Trims - Whether to trim whitespace from the inputs before concatenation (default: `true`).
|
|
@@ -1801,13 +1687,13 @@ type Div<Dividend extends number,Divisor extends number>=IsEqual<Divisor,0>exten
|
|
|
1801
1687
|
*/
|
|
1802
1688
|
type Dot<T extends string,U extends string,Trims extends boolean=true>=Extends<Trims,true>extends true?""extends Trim<U>?Trim<T>:""extends Trim<T>?`${Trim<U>}`:`${Trim<T>}.${Trim<U>}`:""extends U?T:`${T}.${U}`;
|
|
1803
1689
|
/** -------------------------------------------------------
|
|
1804
|
-
* * ***DotArray
|
|
1690
|
+
* * ***Utility Type: `DotArray`.***
|
|
1805
1691
|
* -------------------------------------------------------
|
|
1806
|
-
* A type-level utility that concatenates an array of string literals with a
|
|
1807
|
-
* -
|
|
1808
|
-
*
|
|
1809
|
-
*
|
|
1810
|
-
*
|
|
1692
|
+
* **A type-level utility that concatenates an array of string literals with a `.`.**
|
|
1693
|
+
* - **Behavior:**
|
|
1694
|
+
* - Skips empty strings in the array.
|
|
1695
|
+
* - If `Trims` is `true` (default), trims whitespace from each element.
|
|
1696
|
+
* - Returns a single string literal.
|
|
1811
1697
|
* @template Arr - An array of string literals.
|
|
1812
1698
|
* @template Trims - Whether to trim whitespace from each element (default: `true`).
|
|
1813
1699
|
* @example
|
|
@@ -1826,11 +1712,10 @@ type Dot<T extends string,U extends string,Trims extends boolean=true>=Extends<T
|
|
|
1826
1712
|
*/
|
|
1827
1713
|
type DotArray<Arr extends string[],Trims extends boolean=true>=Arr extends [ infer Head extends string,...infer Tail extends string[]]?Head extends""?DotArray<Tail,Trims>:`${Trims extends true ? Trim<Head> : Head}${Tail extends [] ? "" : `.${DotArray<Tail,Trims>}`}`:"";
|
|
1828
1714
|
/** -------------------------------------------------------
|
|
1829
|
-
* * ***EndsWith
|
|
1715
|
+
* * ***Utility Type: `EndsWith`.***
|
|
1830
1716
|
* -------------------------------------------------------
|
|
1831
|
-
* A type-level utility that returns a boolean indicating
|
|
1832
|
-
* whether the first string literal ends with the ***second one
|
|
1833
|
-
*
|
|
1717
|
+
* **A type-level utility that returns a boolean indicating
|
|
1718
|
+
* whether the first string literal ends with the ***second one***.**
|
|
1834
1719
|
* @template T - The string to check.
|
|
1835
1720
|
* @template C - The ***ending string*** to match.
|
|
1836
1721
|
* @example
|
|
@@ -1843,16 +1728,13 @@ type DotArray<Arr extends string[],Trims extends boolean=true>=Arr extends [ inf
|
|
|
1843
1728
|
*/
|
|
1844
1729
|
type EndsWith<T extends string,C extends string>=T extends`${infer _}${C}`?true:false;
|
|
1845
1730
|
/** --------------------------------------------------
|
|
1846
|
-
* * ***ExcludeStrict
|
|
1731
|
+
* * ***Utility Type: `ExcludeStrict`.***
|
|
1847
1732
|
* --------------------------------------------------
|
|
1848
|
-
* Performs a stricter version of `Exclude<T, U>` with improved type narrowing
|
|
1849
|
-
*
|
|
1850
|
-
* ✅ Especially useful in generic libraries or utility types
|
|
1733
|
+
* **Performs a stricter version of `Exclude<T, U>` with improved type narrowing.**
|
|
1734
|
+
* - ✅ Especially useful in generic libraries or utility types
|
|
1851
1735
|
* where standard `Exclude` may collapse or widen types unintentionally.
|
|
1852
|
-
*
|
|
1853
1736
|
* @template T - The full union or set of types.
|
|
1854
1737
|
* @template U - The type(s) to be excluded from `T`.
|
|
1855
|
-
*
|
|
1856
1738
|
* @example
|
|
1857
1739
|
* ```ts
|
|
1858
1740
|
* type A = 'a' | 'b' | 'c';
|
|
@@ -1862,12 +1744,12 @@ type EndsWith<T extends string,C extends string>=T extends`${infer _}${C}`?true:
|
|
|
1862
1744
|
*/
|
|
1863
1745
|
type ExcludeStrict<T,U extends T>=T extends unknown?0 extends(U extends T?([T] extends [U]?0:never):never)?never:T:never;type _Factorial<T extends number,CurrentNum extends number=1,CurrentProduct extends number=1>=IsEqual<T,CurrentNum>extends true?Multi<CurrentProduct,CurrentNum>:_Factorial<T,Increment<CurrentNum>,Multi<CurrentProduct,CurrentNum>>;
|
|
1864
1746
|
/** -------------------------------------------------------
|
|
1865
|
-
* * ***Factorial
|
|
1747
|
+
* * ***Utility Type: `Factorial`.***
|
|
1866
1748
|
* -------------------------------------------------------
|
|
1867
|
-
* Accepts an integer argument and returns its ***mathematical factorial
|
|
1868
|
-
* -
|
|
1869
|
-
*
|
|
1870
|
-
*
|
|
1749
|
+
* **Accepts an integer argument and returns its ***mathematical factorial***.**
|
|
1750
|
+
* - **Behavior:**
|
|
1751
|
+
* - Valid range: `[0, 21]`.
|
|
1752
|
+
* - Negative numbers or `number` type result in `never`.
|
|
1871
1753
|
* @template T - The integer to compute factorial for.
|
|
1872
1754
|
* @example
|
|
1873
1755
|
* ```ts
|
|
@@ -1883,12 +1765,13 @@ type ExcludeStrict<T,U extends T>=T extends unknown?0 extends(U extends T?([T] e
|
|
|
1883
1765
|
*/
|
|
1884
1766
|
type Factorial<T extends number>=number extends T?never:IsNegative<T>extends true?never:IsEqual<T,0>extends true?1:_Factorial<T>;
|
|
1885
1767
|
/** -------------------------------------------------------
|
|
1886
|
-
* * ***Fibonacci
|
|
1768
|
+
* * ***Utility Type: `Fibonacci`.***
|
|
1887
1769
|
* -------------------------------------------------------
|
|
1888
|
-
* A type-level utility that computes the ***Fibonacci number*** at a given
|
|
1889
|
-
*
|
|
1890
|
-
* -
|
|
1891
|
-
*
|
|
1770
|
+
* **A type-level utility that computes the ***Fibonacci number*** at a given
|
|
1771
|
+
* index `T`.**
|
|
1772
|
+
* - **Behavior:**
|
|
1773
|
+
* - Returns `never` for negative numbers.
|
|
1774
|
+
* - Supports indices in the range `[0, 78]` due to TypeScript recursion limits.
|
|
1892
1775
|
* @template T - The index of the Fibonacci sequence.
|
|
1893
1776
|
* @example
|
|
1894
1777
|
* ```ts
|
|
@@ -1901,29 +1784,17 @@ type Factorial<T extends number>=number extends T?never:IsNegative<T>extends tru
|
|
|
1901
1784
|
* ```
|
|
1902
1785
|
*/
|
|
1903
1786
|
type Fibonacci<T extends number>=IsNegative<T>extends true?never:IsLowerThan<T,2>extends true?T:Fibonacci<Decrement<T>>extends infer NMinusOne extends number?Fibonacci<Sub<T,2>>extends infer NMinusTwo extends number?Sum<NMinusOne,NMinusTwo>:never:never;
|
|
1904
|
-
/**
|
|
1905
|
-
* * ***
|
|
1906
|
-
*
|
|
1907
|
-
*
|
|
1908
|
-
* Configuration options for the {@link FirstCharacter} type-level utility.
|
|
1909
|
-
*
|
|
1910
|
-
* @default
|
|
1911
|
-
* ```ts
|
|
1912
|
-
* { includeRest: false }
|
|
1913
|
-
* ```
|
|
1914
|
-
*
|
|
1915
|
-
* @example
|
|
1916
|
-
* ```ts
|
|
1917
|
-
* type Opt1 = FirstCharacterOptions;
|
|
1918
|
-
* // ➔ { includeRest: boolean }
|
|
1919
|
-
* ```
|
|
1787
|
+
/** ---------------------------------------------------------------------------
|
|
1788
|
+
* * ***Type Options for {@link FirstCharacter | `FirstCharacter`}.***
|
|
1789
|
+
* ---------------------------------------------------------------------------
|
|
1790
|
+
* **Configuration options for the {@link FirstCharacter | `FirstCharacter`} type-level utility.**
|
|
1920
1791
|
*/
|
|
1921
1792
|
type FirstCharacterOptions={
|
|
1922
|
-
/** Whether to include the rest of the string in the result tuple
|
|
1923
|
-
*
|
|
1924
|
-
* - `true` → returns `[first character, rest of string]`
|
|
1925
|
-
* - `false` → returns only the first character
|
|
1793
|
+
/** * ***Whether to include the rest of the string in the result tuple.***
|
|
1926
1794
|
*
|
|
1795
|
+
* - **Behavior:**
|
|
1796
|
+
* - `true` ➔ returns `[first character, rest of string]`.
|
|
1797
|
+
* - `false` ➔ returns only the first character.
|
|
1927
1798
|
* @default false
|
|
1928
1799
|
* @example
|
|
1929
1800
|
* ```ts
|
|
@@ -1933,12 +1804,13 @@ type FirstCharacterOptions={
|
|
|
1933
1804
|
*/
|
|
1934
1805
|
includeRest:boolean;};
|
|
1935
1806
|
/** -------------------------------------------------------
|
|
1936
|
-
* * ***FirstCharacter
|
|
1807
|
+
* * ***Utility Type: `FirstCharacter`.***
|
|
1937
1808
|
* -------------------------------------------------------
|
|
1938
|
-
* Accepts a string literal and returns its first character
|
|
1939
|
-
* -
|
|
1940
|
-
*
|
|
1941
|
-
*
|
|
1809
|
+
* **Accepts a string literal and returns its first character.**
|
|
1810
|
+
* - **Behavior:**
|
|
1811
|
+
* - If `Options["includeRest"]` is `true`, it returns a
|
|
1812
|
+
* tuple: `[first character, rest of string]`.
|
|
1813
|
+
* - Otherwise, it returns only the first character.
|
|
1942
1814
|
* @template T - The string literal to process.
|
|
1943
1815
|
* @template Options - Configuration options (default: `{ includeRest: false }`).
|
|
1944
1816
|
* - `includeRest: boolean` — Whether to include the rest of the string in a tuple.
|
|
@@ -1956,21 +1828,18 @@ includeRest:boolean;};
|
|
|
1956
1828
|
*/
|
|
1957
1829
|
type FirstCharacter<T extends string,Options extends FirstCharacterOptions={includeRest:false;}>=T extends`${infer First extends string}${infer Rest extends string}`?If<Options["includeRest"],[First,Rest],First>:never;
|
|
1958
1830
|
/** -------------------------------------------------------
|
|
1959
|
-
* * ***FirstDigit
|
|
1831
|
+
* * ***Utility Type: `FirstDigit`.***
|
|
1960
1832
|
* -------------------------------------------------------
|
|
1961
|
-
* Extracts the **first digit** of a given number `T
|
|
1962
|
-
*
|
|
1833
|
+
* **Extracts the **first digit** of a given number `T`.**
|
|
1834
|
+
* - **Behavior:**
|
|
1835
|
+
* - Works with integers and decimals.
|
|
1836
|
+
* - Handles negative numbers (`-123` ➔ `-1`).
|
|
1837
|
+
* - Handles `0` and `-0` correctly (always returns `0`).
|
|
1838
|
+
* - Works with bigint literals too.
|
|
1963
1839
|
* @template T - A number or bigint to extract the first digit from.
|
|
1964
1840
|
* @template Options - Optional settings.
|
|
1965
1841
|
* - `alwaysPositive?: boolean` (default: `false`)
|
|
1966
1842
|
* If `true`, the result is always positive regardless of the sign.
|
|
1967
|
-
*
|
|
1968
|
-
* ### Behavior
|
|
1969
|
-
* - Works with integers and decimals.
|
|
1970
|
-
* - Handles negative numbers (`-123` → `-1`).
|
|
1971
|
-
* - Handles `0` and `-0` correctly (always returns `0`).
|
|
1972
|
-
* - Works with bigint literals too.
|
|
1973
|
-
*
|
|
1974
1843
|
* @example
|
|
1975
1844
|
* ```ts
|
|
1976
1845
|
* type A = FirstDigit<0>; // ➔ 0
|
|
@@ -1995,10 +1864,10 @@ type FirstDigit<T extends number|bigint,Options extends{
|
|
|
1995
1864
|
*/
|
|
1996
1865
|
alwaysPositive?:boolean;}={alwaysPositive:false;}>=DigitsTuple<T>["digits"] extends readonly [infer First extends number,...unknown[]]?Options["alwaysPositive"] extends true?First:DigitsTuple<T>["negative"] extends true?Negate<First>:First:never;
|
|
1997
1866
|
/** -------------------------------------------------------
|
|
1998
|
-
* * ***Floor
|
|
1867
|
+
* * ***Utility Type: `Floor`.***
|
|
1999
1868
|
* -------------------------------------------------------
|
|
2000
|
-
* Type-level equivalent of `Math.floor()
|
|
2001
|
-
*
|
|
1869
|
+
* **Type-level equivalent of `Math.floor()`.**
|
|
1870
|
+
* - Returns the ***floored value*** of the passed number.
|
|
2002
1871
|
* @template T - A number type.
|
|
2003
1872
|
* @example
|
|
2004
1873
|
* ```ts
|
|
@@ -2010,15 +1879,12 @@ alwaysPositive?:boolean;}={alwaysPositive:false;}>=DigitsTuple<T>["digits"] exte
|
|
|
2010
1879
|
*/
|
|
2011
1880
|
type Floor<T extends number>=IsFloat<T>extends true?GetFloatNumberParts<T>extends [infer Whole extends number,unknown]?IsNegative<T>extends true?Negate<Increment<Whole>>:Whole:never:T;
|
|
2012
1881
|
/** --------------------------------------------------
|
|
2013
|
-
* * ***Identity
|
|
1882
|
+
* * ***Utility Type: `Identity`.***
|
|
2014
1883
|
* --------------------------------------------------
|
|
2015
|
-
* Identity utility type that preserves the structure and inference of type `T
|
|
2016
|
-
*
|
|
2017
|
-
* ✅ Commonly used to force TypeScript to expand a mapped or intersection type
|
|
1884
|
+
* **Identity utility type that preserves the structure and inference of type `T`.**
|
|
1885
|
+
* - ✅ Commonly used to force TypeScript to expand a mapped or intersection type
|
|
2018
1886
|
* into a more readable and usable shape.
|
|
2019
|
-
*
|
|
2020
1887
|
* @template T - The type to preserve and normalize.
|
|
2021
|
-
*
|
|
2022
1888
|
* @example
|
|
2023
1889
|
* ```ts
|
|
2024
1890
|
* type A = { a: string; b: number };
|
|
@@ -2026,7 +1892,12 @@ type Floor<T extends number>=IsFloat<T>extends true?GetFloatNumberParts<T>extend
|
|
|
2026
1892
|
* // ➔ { a: string; b: number }
|
|
2027
1893
|
* ```
|
|
2028
1894
|
*/
|
|
2029
|
-
type Identity<T>={[P in keyof T]:T[P];};
|
|
1895
|
+
type Identity<T>={[P in keyof T]:T[P];};
|
|
1896
|
+
/** ---------------------------------------------------------------------------
|
|
1897
|
+
* * ***Type Options for {@link Shift | `Shift`}.***
|
|
1898
|
+
* ---------------------------------------------------------------------------
|
|
1899
|
+
*/
|
|
1900
|
+
type ShiftOptions={
|
|
2030
1901
|
/**
|
|
2031
1902
|
* If `true`, return both the rest of the array and the removed element
|
|
2032
1903
|
* as a tuple `[Rest, Removed]`.
|
|
@@ -2037,19 +1908,16 @@ type Identity<T>={[P in keyof T]:T[P];};type ShiftOptions={
|
|
|
2037
1908
|
*/
|
|
2038
1909
|
includeRemoved:boolean;};
|
|
2039
1910
|
/** -------------------------------------------------------
|
|
2040
|
-
* * ***Shift
|
|
1911
|
+
* * ***Utility Type: `Shift`.***
|
|
2041
1912
|
* -------------------------------------------------------
|
|
2042
|
-
* Removes the first element from the array type `T
|
|
2043
|
-
*
|
|
2044
|
-
*
|
|
2045
|
-
*
|
|
2046
|
-
*
|
|
2047
|
-
*
|
|
2048
|
-
* - `Removed`: the removed first element
|
|
2049
|
-
*
|
|
1913
|
+
* **Removes the first element from the array type `T`.**
|
|
1914
|
+
* - **Behavior:**
|
|
1915
|
+
* - By default (`includeRemoved: false`), returns the array without the first element.
|
|
1916
|
+
* - If `includeRemoved: true`, returns a tuple `[Rest, Removed]`:
|
|
1917
|
+
* - `Rest`: the remaining array.
|
|
1918
|
+
* - `Removed`: the removed first element.
|
|
2050
1919
|
* @template T - The array type to operate on.
|
|
2051
1920
|
* @template Options - Optional flags. Default `{ includeRemoved: false }`.
|
|
2052
|
-
*
|
|
2053
1921
|
* @example
|
|
2054
1922
|
* ```ts
|
|
2055
1923
|
* // Default: just remove first element
|
|
@@ -2067,26 +1935,23 @@ includeRemoved:boolean;};
|
|
|
2067
1935
|
*/
|
|
2068
1936
|
type Shift<T extends readonly unknown[],Options extends ShiftOptions={includeRemoved:false;}>=T extends readonly [infer Removed,...infer Rest extends readonly unknown[]]?If<Options["includeRemoved"],[Rest,Removed],Rest>:never;
|
|
2069
1937
|
/** -------------------------------------------------------
|
|
2070
|
-
* * ***Includes
|
|
1938
|
+
* * ***Utility Type: `Includes`.***
|
|
2071
1939
|
* -------------------------------------------------------
|
|
2072
|
-
* Returns a boolean whether the second argument is in the first array argument
|
|
2073
|
-
*
|
|
1940
|
+
* **Returns a boolean whether the second argument is in the first array argument.**
|
|
2074
1941
|
* @template T - The array to check.
|
|
2075
1942
|
* @template Pivot - The value to look for.
|
|
2076
1943
|
* @example
|
|
2077
1944
|
* ```ts
|
|
2078
|
-
* // true
|
|
2079
|
-
* type
|
|
2080
|
-
* // false
|
|
2081
|
-
* type Case2 = Includes<[1, 2, 3], 4>; // ➔ false
|
|
1945
|
+
* type Case1 = Includes<[1, 2, 3], 1>; // ➔ true
|
|
1946
|
+
* type Case2 = Includes<[1, 2, 3], 4>; // ➔ false
|
|
2082
1947
|
* ```
|
|
2083
1948
|
*/
|
|
2084
1949
|
type Includes<T extends readonly unknown[],Pivot>=IsEmptyArray<T>extends true?false:Shift<T,{includeRemoved:true;}>extends [ infer Rest extends readonly unknown[],infer Removed]?IfEqual<Pivot,Removed,true,Includes<Rest,Pivot>>:false;type _IndexOfArray<T extends readonly unknown[],Pivot,Index extends number=0>=T extends readonly [infer First,...infer Rest extends unknown[]]?IsEqual<First,Pivot>extends true?Index:_IndexOfArray<Rest,Pivot,Increment<Index>>:-1;type _IndexOfString<T extends string,Pivot,Index extends number=0>=T extends`${infer First}${infer Rest extends string}`?IsEqual<First,Pivot>extends true?Index:_IndexOfString<Rest,Pivot,Increment<Index>>:-1;
|
|
2085
1950
|
/** -------------------------------------------------------
|
|
2086
|
-
* * ***IndexOf
|
|
1951
|
+
* * ***Utility Type: `IndexOf`.***
|
|
2087
1952
|
* --------------------------------------------------------
|
|
2088
|
-
* Type version of `Array.prototype.indexOf()` and `String.prototype.indexOf()
|
|
2089
|
-
*
|
|
1953
|
+
* **Type version of `Array.prototype.indexOf()` and `String.prototype.indexOf()`.**
|
|
1954
|
+
* - Returns the index of the second argument in the first argument.
|
|
2090
1955
|
* @example
|
|
2091
1956
|
* ```ts
|
|
2092
1957
|
* type Case1 = IndexOf<[1, 2, 3], 2>; // ➔ 1
|
|
@@ -2097,30 +1962,27 @@ type Includes<T extends readonly unknown[],Pivot>=IsEmptyArray<T>extends true?fa
|
|
|
2097
1962
|
*/
|
|
2098
1963
|
type IndexOf<T extends readonly unknown[]|string,Pivot extends T extends string?string:unknown>=T extends string?IsStringLiteral<T>extends true?_IndexOfString<T,Pivot>:never:T extends readonly unknown[]?IsTuple<T>extends true?_IndexOfArray<T,Pivot>:never:never;
|
|
2099
1964
|
/** -------------------------------------------------------
|
|
2100
|
-
* * ***IsArrayIndex
|
|
1965
|
+
* * ***Utility Type: `IsArrayIndex`.***
|
|
2101
1966
|
* -------------------------------------------------------
|
|
2102
|
-
* Returns a boolean whether the passed argument is a valid array index
|
|
2103
|
-
*
|
|
1967
|
+
* **Returns a boolean whether the passed argument is a valid array index.**
|
|
2104
1968
|
* @example
|
|
2105
1969
|
* ```ts
|
|
2106
|
-
* // truthy
|
|
2107
1970
|
* type Case1 = IsArrayIndex<1>; // ➔ true
|
|
2108
1971
|
* type Case2 = IsArrayIndex<'1'>; // ➔ true
|
|
2109
|
-
*
|
|
2110
|
-
* // falsy
|
|
2111
1972
|
* type Case3 = IsArrayIndex<-1>; // ➔ false
|
|
2112
1973
|
* type Case4 = IsArrayIndex<"a">; // ➔ false
|
|
2113
1974
|
* ```
|
|
2114
1975
|
*/
|
|
2115
1976
|
type IsArrayIndex<T>=T extends number?And<IsInteger<T>,IsGreaterOrEqual<T,0>>:T extends string?ParseNumber<T>extends infer NumT extends number?Not<IsNever<NumT>>extends true?And<IsInteger<NumT>,IsGreaterOrEqual<NumT,0>>:false:false:never;
|
|
2116
1977
|
/** -------------------------------------------------------
|
|
2117
|
-
* * ***Mod
|
|
1978
|
+
* * ***Utility Type: `Mod`.***
|
|
2118
1979
|
* -------------------------------------------------------
|
|
2119
|
-
* Returns the **remainder** of the division of two numbers (`Dividend % Divisor`)
|
|
2120
|
-
*
|
|
2121
|
-
*
|
|
2122
|
-
*
|
|
2123
|
-
*
|
|
1980
|
+
* **Returns the **remainder** of the division of two numbers (`Dividend % Divisor`).**
|
|
1981
|
+
* - **Behavior:**
|
|
1982
|
+
* - Computes the remainder using type-level arithmetic:
|
|
1983
|
+
* - `Dividend - (Divisor * (Dividend / Divisor))`.
|
|
1984
|
+
* - Works with integers within the range:
|
|
1985
|
+
* - `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2124
1986
|
* @template Dividend - The dividend (numerator).
|
|
2125
1987
|
* @template Divisor - The divisor (denominator).
|
|
2126
1988
|
* @example
|
|
@@ -2133,113 +1995,114 @@ type IsArrayIndex<T>=T extends number?And<IsInteger<T>,IsGreaterOrEqual<T,0>>:T
|
|
|
2133
1995
|
*/
|
|
2134
1996
|
type Mod<Dividend extends number,Divisor extends number>=Div<Dividend,Divisor>extends infer Quotient extends number?Multi<Quotient,Divisor>extends infer Product extends number?Sub<Dividend,Product>:never:never;
|
|
2135
1997
|
/** -------------------------------------------------------
|
|
2136
|
-
* * ***IsDivisibleByTwo
|
|
1998
|
+
* * ***Utility Type: `IsDivisibleByTwo`.***
|
|
2137
1999
|
* -------------------------------------------------------
|
|
2138
|
-
* Accepts an integer argument and returns a boolean whether it is divisible by two
|
|
2000
|
+
* **Accepts an integer argument and returns a boolean whether it is divisible by two.**
|
|
2139
2001
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2140
|
-
*
|
|
2141
2002
|
* @example
|
|
2142
2003
|
* // truthy
|
|
2143
2004
|
* type Case1 = IsDivisibleByTwo<4>; // ➔ true
|
|
2144
|
-
* type Case2 = IsDivisibleByTwo<-
|
|
2005
|
+
* type Case2 = IsDivisibleByTwo<-6>; // ➔ true
|
|
2145
2006
|
*
|
|
2146
2007
|
* // falsy
|
|
2147
|
-
* type Case3 = IsDivisibleByTwo
|
|
2008
|
+
* type Case3 = IsDivisibleByTwo<3>; // ➔ false
|
|
2009
|
+
* type Case4 = IsDivisibleByTwo<-5>; // ➔ false
|
|
2148
2010
|
*/
|
|
2149
2011
|
type IsDivisibleByTwo<T extends number>=IsEven<T>;type DivisibleByThreeMap={3:true;6:true;9:true;};type _IsDivisibleByThree<T extends number>=DigitsTuple<Abs<T>>["digits"] extends infer Digits extends readonly number[]?IsEqual<Digits["length"],1>extends true?Digits[0] extends keyof DivisibleByThreeMap?true:false:SumArr<Digits>extends infer DigitsSum extends number?IfLowerThan<DigitsSum,3>extends true?false:_IsDivisibleByThree<DigitsSum>:never:never;
|
|
2150
2012
|
/** -------------------------------------------------------
|
|
2151
|
-
* * ***IsDivisibleByThree
|
|
2013
|
+
* * ***Utility Type: `IsDivisibleByThree`.***
|
|
2152
2014
|
* -------------------------------------------------------
|
|
2153
|
-
* Accepts an integer argument and returns a boolean whether it is divisible by three
|
|
2015
|
+
* **Accepts an integer argument and returns a boolean whether it is divisible by three.**
|
|
2154
2016
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2155
|
-
*
|
|
2156
2017
|
* @example
|
|
2157
2018
|
* // truthy
|
|
2158
2019
|
* type Case1 = IsDivisibleByThree<123>; // ➔ true
|
|
2159
|
-
* type Case2 = IsDivisibleByThree<-
|
|
2020
|
+
* type Case2 = IsDivisibleByThree<-126>; // ➔ true
|
|
2160
2021
|
*
|
|
2161
2022
|
* // falsy
|
|
2162
|
-
* type Case3 = IsDivisibleByThree<124>;
|
|
2023
|
+
* type Case3 = IsDivisibleByThree<124>; // ➔ false
|
|
2024
|
+
* type Case4 = IsDivisibleByThree<-128>; // ➔ false
|
|
2163
2025
|
*/
|
|
2164
2026
|
type IsDivisibleByThree<T extends number>=_IsDivisibleByThree<T>;
|
|
2165
2027
|
/** -------------------------------------------------------
|
|
2166
|
-
* * ***IsDivisibleByFive
|
|
2028
|
+
* * ***Utility Type: `IsDivisibleByFive`.***
|
|
2167
2029
|
* -------------------------------------------------------
|
|
2168
|
-
* Accepts an integer argument and returns a boolean whether it is divisible by five
|
|
2030
|
+
* **Accepts an integer argument and returns a boolean whether it is divisible by five.**
|
|
2169
2031
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2170
|
-
*
|
|
2171
2032
|
* @example
|
|
2172
2033
|
* // truthy
|
|
2173
2034
|
* type Case1 = IsDivisibleByFive<125>; // ➔ true
|
|
2174
|
-
* type Case2 = IsDivisibleByFive<-
|
|
2035
|
+
* type Case2 = IsDivisibleByFive<-115>; // ➔ true
|
|
2175
2036
|
*
|
|
2176
2037
|
* // falsy
|
|
2177
|
-
* type Case3 = IsDivisibleByFive
|
|
2038
|
+
* type Case3 = IsDivisibleByFive<13>; // ➔ false
|
|
2039
|
+
* type Case4 = IsDivisibleByFive<-17>; // ➔ false
|
|
2178
2040
|
*/
|
|
2179
2041
|
type IsDivisibleByFive<T extends number>=EndsWith<Stringify<T>,"0"|"5">;
|
|
2180
2042
|
/** -------------------------------------------------------
|
|
2181
|
-
* * ***IsDivisibleBySix
|
|
2043
|
+
* * ***Utility Type: `IsDivisibleBySix`.***
|
|
2182
2044
|
* -------------------------------------------------------
|
|
2183
|
-
* Accepts an integer argument and returns a boolean whether it is divisible by six
|
|
2045
|
+
* **Accepts an integer argument and returns a boolean whether it is divisible by six.**
|
|
2184
2046
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2185
|
-
*
|
|
2186
2047
|
* @example
|
|
2187
2048
|
* // truthy
|
|
2188
2049
|
* type Case1 = IsDivisibleBySix<126>; // ➔ true
|
|
2189
|
-
* type Case2 = IsDivisibleBySix<-
|
|
2050
|
+
* type Case2 = IsDivisibleBySix<-156>; // ➔ true
|
|
2190
2051
|
*
|
|
2191
2052
|
* // falsy
|
|
2192
|
-
* type Case3 = IsDivisibleBySix<124>;
|
|
2053
|
+
* type Case3 = IsDivisibleBySix<124>; // ➔ false
|
|
2054
|
+
* type Case4 = IsDivisibleBySix<-139>; // ➔ false
|
|
2193
2055
|
*/
|
|
2194
2056
|
type IsDivisibleBySix<T extends number>=And<IsDivisibleByTwo<T>,IsDivisibleByThree<T>>;
|
|
2195
2057
|
/** -------------------------------------------------------
|
|
2196
|
-
* * ***IsDivisibleByTen
|
|
2058
|
+
* * ***Utility Type: `IsDivisibleByTen`.***
|
|
2197
2059
|
* -------------------------------------------------------
|
|
2198
|
-
* Accepts an integer argument and returns a boolean whether it is divisible by ten
|
|
2060
|
+
* **Accepts an integer argument and returns a boolean whether it is divisible by ten.**
|
|
2199
2061
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2200
|
-
*
|
|
2201
2062
|
* @example
|
|
2202
2063
|
* // truthy
|
|
2203
|
-
* type Case1 = IsDivisibleByTen<100>;
|
|
2204
|
-
* type Case2 = IsDivisibleByTen<-
|
|
2064
|
+
* type Case1 = IsDivisibleByTen<100>; // ➔ true
|
|
2065
|
+
* type Case2 = IsDivisibleByTen<-80>; // ➔ true
|
|
2205
2066
|
*
|
|
2206
2067
|
* // falsy
|
|
2207
2068
|
* type Case3 = IsDivisibleByTen<101>; // ➔ false
|
|
2069
|
+
* type Case4 = IsDivisibleByTen<-72>; // ➔ false
|
|
2208
2070
|
*/
|
|
2209
2071
|
type IsDivisibleByTen<T extends number>=EndsWith<Stringify<T>,"0">;
|
|
2210
2072
|
/** -------------------------------------------------------
|
|
2211
|
-
* * ***IsDivisibleByHundred
|
|
2073
|
+
* * ***Utility Type: `IsDivisibleByHundred`.***
|
|
2212
2074
|
* -------------------------------------------------------
|
|
2213
|
-
* Accepts an integer argument and returns a boolean whether it is divisible by hundred
|
|
2075
|
+
* **Accepts an integer argument and returns a boolean whether it is divisible by hundred.**
|
|
2214
2076
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2215
|
-
*
|
|
2216
2077
|
* @example
|
|
2217
2078
|
* // truthy
|
|
2218
2079
|
* type Case1 = IsDivisibleByHundred<100>; // ➔ true
|
|
2219
|
-
* type Case2 = IsDivisibleByHundred<-
|
|
2080
|
+
* type Case2 = IsDivisibleByHundred<-300>; // ➔ true
|
|
2220
2081
|
*
|
|
2221
2082
|
* // falsy
|
|
2222
|
-
* type Case3 = IsDivisibleByHundred<101>;
|
|
2083
|
+
* type Case3 = IsDivisibleByHundred<101>; // ➔ false
|
|
2084
|
+
* type Case4 = IsDivisibleByHundred<-210>; // ➔ false
|
|
2223
2085
|
*/
|
|
2224
2086
|
type IsDivisibleByHundred<T extends number>=EndsWith<Stringify<T>,"00">;
|
|
2225
2087
|
/** -------------------------------------------------------
|
|
2226
|
-
* * ***IsDivisible
|
|
2088
|
+
* * ***Utility Type: `IsDivisible`.***
|
|
2227
2089
|
* -------------------------------------------------------
|
|
2228
|
-
* Returns a boolean whether the first integer argument is divisible by the
|
|
2229
|
-
*
|
|
2090
|
+
* **Returns a boolean whether the first integer argument is divisible by the
|
|
2091
|
+
* second integer argument.**
|
|
2230
2092
|
* @example
|
|
2231
2093
|
* // truthy
|
|
2232
2094
|
* type Case1 = IsDivisible<1024, 2>; // ➔ true
|
|
2095
|
+
* type Case2 = IsDivisible<2034, 3>; // ➔ true
|
|
2233
2096
|
*
|
|
2234
2097
|
* // falsy
|
|
2235
|
-
* type
|
|
2098
|
+
* type Case3 = IsDivisible<1023, 2>; // ➔ false
|
|
2099
|
+
* type Case4 = IsDivisible<3034, 3>; // ➔ false
|
|
2236
2100
|
*/
|
|
2237
2101
|
type IsDivisible<Dividend extends number,Divisor extends number>=IsEqual<Mod<Dividend,Divisor>,0>;
|
|
2238
2102
|
/** -------------------------------------------------------
|
|
2239
|
-
* * ***IsLetter
|
|
2103
|
+
* * ***Utility Type: `IsLetter`.***
|
|
2240
2104
|
* -------------------------------------------------------
|
|
2241
|
-
* Returns a boolean whether the passed argument is a letter (Only for letters that have both upper and lower case)
|
|
2242
|
-
*
|
|
2105
|
+
* **Returns a boolean whether the passed argument is a letter (Only for letters that have both upper and lower case).**
|
|
2243
2106
|
* @template T - The string to check.
|
|
2244
2107
|
* @example
|
|
2245
2108
|
* type Case1 = IsLetter<'a'>; // ➔ true
|
|
@@ -2247,10 +2110,9 @@ type IsDivisible<Dividend extends number,Divisor extends number>=IsEqual<Mod<Div
|
|
|
2247
2110
|
*/
|
|
2248
2111
|
type IsLetter<T extends string>=Uppercase<T>extends Lowercase<T>?false:true;type _IsUnion<T,U=T>=IsNever<T>extends true?false:T extends U?Not<IsNever<Exclude<U,T>>>:false;
|
|
2249
2112
|
/** -------------------------------------------------------
|
|
2250
|
-
* * ***IsUnion
|
|
2113
|
+
* * ***Utility Type: `IsUnion`.***
|
|
2251
2114
|
* -------------------------------------------------------
|
|
2252
|
-
* Returns a boolean whether the passed argument is a union
|
|
2253
|
-
*
|
|
2115
|
+
* **Returns a boolean whether the passed argument is a union.**
|
|
2254
2116
|
* @template T - The type to check.
|
|
2255
2117
|
* @example
|
|
2256
2118
|
* type Case1 = IsUnion<'a' | 'b'>;
|
|
@@ -2260,12 +2122,11 @@ type IsLetter<T extends string>=Uppercase<T>extends Lowercase<T>?false:true;type
|
|
|
2260
2122
|
*/
|
|
2261
2123
|
type IsUnion<T>=_IsUnion<T,T>;
|
|
2262
2124
|
/** -------------------------------------------------------
|
|
2263
|
-
* * ***Join
|
|
2125
|
+
* * ***Utility Type: `Join`.***
|
|
2264
2126
|
* -------------------------------------------------------
|
|
2265
|
-
* Type version of `Array.prototype.join()
|
|
2127
|
+
* **Type version of `Array.prototype.join()`.**
|
|
2266
2128
|
* - Joins the first array argument by the second argument.
|
|
2267
|
-
*
|
|
2268
|
-
* @template T - The array to join
|
|
2129
|
+
* @template T - The array to join.
|
|
2269
2130
|
* @template Glue - The string or number to join with, defaultValue: `""`.
|
|
2270
2131
|
* @example
|
|
2271
2132
|
* type Case0 = Join<["p", "e", "a", "r"]>;
|
|
@@ -2281,15 +2142,13 @@ type IsUnion<T>=_IsUnion<T,T>;
|
|
|
2281
2142
|
*/
|
|
2282
2143
|
type Join<T extends readonly(string|number)[],Glue extends string|number="">=IsTuple<T>extends true?T extends readonly [ infer First extends string|number,...infer Rest extends readonly(string|number)[]]?IfEmptyArray<Rest,First,`${First}${Glue}${Join<Rest, Glue>}`>:never:never;
|
|
2283
2144
|
/** --------------------------------------------------
|
|
2284
|
-
* * ***AnyRecord
|
|
2145
|
+
* * ***Utility Type: `AnyRecord`.***
|
|
2285
2146
|
* --------------------------------------------------
|
|
2286
|
-
* Represents an object with arbitrary string keys and values of **any** type
|
|
2287
|
-
*
|
|
2288
|
-
*
|
|
2289
|
-
*
|
|
2290
|
-
* ✅ Commonly used as a fallback for flexible key-value structures
|
|
2147
|
+
* **Represents an object with arbitrary string keys and values of **any** type.**
|
|
2148
|
+
* - ⚠️ **Use with caution — `any`** disables type safety.
|
|
2149
|
+
* - Prefer stricter like {@link UnknownRecord | **`UnknownRecord`**} typing when possible.
|
|
2150
|
+
* - ✅ Commonly used as a fallback for flexible key-value structures
|
|
2291
2151
|
* such as query parameters, configuration maps, or JSON-like data.
|
|
2292
|
-
*
|
|
2293
2152
|
* @example
|
|
2294
2153
|
* ```ts
|
|
2295
2154
|
* const config: AnyRecord = {
|
|
@@ -2301,16 +2160,13 @@ type Join<T extends readonly(string|number)[],Glue extends string|number="">=IsT
|
|
|
2301
2160
|
*/
|
|
2302
2161
|
type AnyRecord=Record<string,any>;
|
|
2303
2162
|
/** --------------------------------------------------
|
|
2304
|
-
* * ***UnknownRecord
|
|
2163
|
+
* * ***Utility Type: `UnknownRecord`.***
|
|
2305
2164
|
* --------------------------------------------------
|
|
2306
|
-
* Represents an object with arbitrary string keys and values of **unknown** type
|
|
2307
|
-
*
|
|
2308
|
-
*
|
|
2309
|
-
*
|
|
2310
|
-
*
|
|
2311
|
-
* ✅ Suitable for working with untyped external data sources
|
|
2312
|
-
* (e.g., JSON APIs, parsed configs) where values must be validated first.
|
|
2313
|
-
*
|
|
2165
|
+
* **Represents an object with arbitrary string keys and values of **unknown** type.**
|
|
2166
|
+
* - ✅ Safer alternative to `AnyRecord` — forces explicit type narrowing
|
|
2167
|
+
* before values can be used, maintaining type safety.
|
|
2168
|
+
* - ✅ Suitable for working with untyped external data sources
|
|
2169
|
+
* (e.g., JSON APIs, parsed configs) where values must be validated first.
|
|
2314
2170
|
* @example
|
|
2315
2171
|
* ```ts
|
|
2316
2172
|
* const data: UnknownRecord = JSON.parse("{}");
|
|
@@ -2319,17 +2175,22 @@ type AnyRecord=Record<string,any>;
|
|
|
2319
2175
|
* if (typeof data.id === "string") {
|
|
2320
2176
|
* console.log(data.id.toUpperCase());
|
|
2321
2177
|
* }
|
|
2178
|
+
*
|
|
2179
|
+
* // Or:
|
|
2180
|
+
* const unknownObject: UnknownRecord = {
|
|
2181
|
+
* mode: "dark",
|
|
2182
|
+
* retries: 3,
|
|
2183
|
+
* debug: true,
|
|
2184
|
+
* };
|
|
2322
2185
|
* ```
|
|
2323
2186
|
*/
|
|
2324
2187
|
type UnknownRecord=Record<string,unknown>;
|
|
2325
2188
|
/** -------------------------------------------------------
|
|
2326
|
-
* * ***AnyStringRecord
|
|
2189
|
+
* * ***Utility Type: `AnyStringRecord`.***
|
|
2327
2190
|
* -------------------------------------------------------
|
|
2328
|
-
*
|
|
2329
|
-
*
|
|
2330
|
-
*
|
|
2331
|
-
* in generic inference scenarios.
|
|
2332
|
-
*
|
|
2191
|
+
* **Same as **{@link AnyString | **`AnyString`**}** but uses `Record<never, never>` as the intersection.**
|
|
2192
|
+
* - This approach is often more reliable in preserving literal types
|
|
2193
|
+
* in generic inference scenarios.
|
|
2333
2194
|
* @example
|
|
2334
2195
|
* ```ts
|
|
2335
2196
|
* declare function acceptsAnyStringRecord<T extends AnyStringRecord>(value: T): T;
|
|
@@ -2343,39 +2204,36 @@ type UnknownRecord=Record<string,unknown>;
|
|
|
2343
2204
|
*/
|
|
2344
2205
|
type AnyStringRecord=Record<never,never>& string;
|
|
2345
2206
|
/** -------------------------------------------------------
|
|
2346
|
-
* * ***LooseLiteral
|
|
2207
|
+
* * ***Utility Type: `LooseLiteral`.***
|
|
2347
2208
|
* -------------------------------------------------------
|
|
2348
|
-
*
|
|
2349
|
-
*
|
|
2350
|
-
*
|
|
2209
|
+
* **Improves the autocompletion and inference of **loose literal types**.**
|
|
2210
|
+
* @description
|
|
2351
2211
|
* Ensures that specified literal types are preserved while still
|
|
2352
2212
|
* allowing assignment of a broader base type.
|
|
2353
|
-
*
|
|
2354
|
-
*
|
|
2355
|
-
*
|
|
2356
|
-
*
|
|
2357
|
-
* - You want stricter typing in generics while preserving literals.
|
|
2358
|
-
*
|
|
2213
|
+
* - **Useful in scenarios where:**
|
|
2214
|
+
* - You want to accept **specific literal values** but still allow
|
|
2215
|
+
* any value of a base type (like `string` or `number`).
|
|
2216
|
+
* - You want stricter typing in generics while preserving literals.
|
|
2359
2217
|
* @template Literal - The literal type(s) to preserve.
|
|
2360
2218
|
* @template BaseType - The base type to extend when not matching literal.
|
|
2361
|
-
*
|
|
2362
2219
|
* @example
|
|
2363
2220
|
* ```ts
|
|
2364
2221
|
* type T0 = LooseLiteral<"a" | "b" | "c", string>;
|
|
2365
2222
|
* // ➔ "a" | "b" | "c" | (string & {})
|
|
2366
2223
|
*
|
|
2367
2224
|
* declare function acceptsLoose<T extends LooseLiteral<"x" | "y", string>>(value: T): T;
|
|
2368
|
-
* const a = acceptsLoose("x");
|
|
2369
|
-
*
|
|
2225
|
+
* const a = acceptsLoose("x");
|
|
2226
|
+
* // ➔ "x"
|
|
2227
|
+
* const b = acceptsLoose("any string");
|
|
2228
|
+
* // ➔ string
|
|
2370
2229
|
* ```
|
|
2371
2230
|
*/
|
|
2372
2231
|
type LooseLiteral<Literal,BaseType>=Literal|(BaseType & AnyStringRecord);
|
|
2373
2232
|
/** -------------------------------------------------------
|
|
2374
|
-
* * ***Max
|
|
2233
|
+
* * ***Utility Type: `Max`.***
|
|
2375
2234
|
* -------------------------------------------------------
|
|
2376
|
-
* Accepts two integers and returns the **maximum** among them
|
|
2235
|
+
* **Accepts two integers and returns the **maximum** among them.**
|
|
2377
2236
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2378
|
-
*
|
|
2379
2237
|
* @template Num1 - First integer to compare.
|
|
2380
2238
|
* @template Num2 - Second integer to compare.
|
|
2381
2239
|
* @example
|
|
@@ -2385,20 +2243,20 @@ type LooseLiteral<Literal,BaseType>=Literal|(BaseType & AnyStringRecord);
|
|
|
2385
2243
|
* ```
|
|
2386
2244
|
*/
|
|
2387
2245
|
type Max<Num1 extends number,Num2 extends number>=IfLowerThan<Num1,Num2,Num2,Num1>;
|
|
2388
|
-
/**
|
|
2389
|
-
* Recursively computes the maximum number in a tuple of integers.
|
|
2246
|
+
/** * ***Recursively computes the maximum number in a tuple of integers.***
|
|
2390
2247
|
*
|
|
2248
|
+
* @private ***Private internal type for {@link MaxArr | **`MaxArr`**}.***
|
|
2391
2249
|
* @template T - Tuple of numbers to process.
|
|
2392
2250
|
* @template CurrentMax - Current maximum value, defaults to the first element of T.
|
|
2393
2251
|
*/
|
|
2394
2252
|
type _MaxArr<T extends readonly number[],CurrentMax extends number=ReturnItselfIfNotExtends<T[0],undefined,never>>=IsEmptyArray<T>extends true?CurrentMax:Shift<T,{includeRemoved:true;}>extends [ infer Rest extends number[],infer First extends number]?_MaxArr<Rest,Max<First,CurrentMax>>:never;
|
|
2395
2253
|
/** -------------------------------------------------------
|
|
2396
|
-
* * ***MaxArr
|
|
2254
|
+
* * ***Utility Type: `MaxArr`.***
|
|
2397
2255
|
* -------------------------------------------------------
|
|
2398
|
-
* Accepts a tuple of integers and returns the **maximum** among its elements
|
|
2399
|
-
* Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2400
|
-
*
|
|
2401
|
-
*
|
|
2256
|
+
* **Accepts a tuple of integers and returns the **maximum** among its elements.**
|
|
2257
|
+
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2258
|
+
* @template T - Tuple of numbers to evaluate.
|
|
2259
|
+
* - Only tuples are supported; arrays of unknown length will return `never`.
|
|
2402
2260
|
* @example
|
|
2403
2261
|
* ```ts
|
|
2404
2262
|
* type Case1 = MaxArr<[1, 2, 4, 10]>; // ➔ 10
|
|
@@ -2408,14 +2266,12 @@ type _MaxArr<T extends readonly number[],CurrentMax extends number=ReturnItselfI
|
|
|
2408
2266
|
*/
|
|
2409
2267
|
type MaxArr<T extends readonly number[]>=IsTuple<T>extends true?_MaxArr<T>:never;
|
|
2410
2268
|
/** -------------------------------------------------------
|
|
2411
|
-
* * ***DeepMergeArrayUnion
|
|
2269
|
+
* * ***Utility Type: `DeepMergeArrayUnion`.***
|
|
2412
2270
|
* -------------------------------------------------------
|
|
2413
|
-
* Recursively merges element types of nested arrays inside an array type,
|
|
2414
|
-
* **preserving the nested array structure
|
|
2415
|
-
*
|
|
2271
|
+
* **Recursively merges element types of nested arrays inside an array type,
|
|
2272
|
+
* **preserving the nested array structure**.**
|
|
2416
2273
|
* - Converts an array of nested arrays into a union of its element types,
|
|
2417
2274
|
* while keeping the nested arrays intact.
|
|
2418
|
-
*
|
|
2419
2275
|
* @template T - The outer array type.
|
|
2420
2276
|
* @returns The nested array type with merged element types.
|
|
2421
2277
|
* @example
|
|
@@ -2431,11 +2287,10 @@ type MaxArr<T extends readonly number[]>=IsTuple<T>extends true?_MaxArr<T>:never
|
|
|
2431
2287
|
*/
|
|
2432
2288
|
type DeepMergeArrayUnion<T extends any[]>=T extends(infer U)[]?U extends any[]?DeepMergeArrayUnionHelper<U>[]:U[]:never;type DeepMergeArrayUnionHelper<T>=T extends(infer U)[]?DeepMergeArrayUnionHelper<U>|Exclude<T,any[]>:T;
|
|
2433
2289
|
/** -------------------------------------------------------
|
|
2434
|
-
* * ***Min
|
|
2290
|
+
* * ***Utility Type: `Min`.***
|
|
2435
2291
|
* -------------------------------------------------------
|
|
2436
|
-
* Accepts two integers and returns the **minimum** among them
|
|
2292
|
+
* **Accepts two integers and returns the **minimum** among them.**
|
|
2437
2293
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2438
|
-
*
|
|
2439
2294
|
* @template Num1 - First integer.
|
|
2440
2295
|
* @template Num2 - Second integer.
|
|
2441
2296
|
* @example
|
|
@@ -2445,19 +2300,18 @@ type DeepMergeArrayUnion<T extends any[]>=T extends(infer U)[]?U extends any[]?D
|
|
|
2445
2300
|
* ```
|
|
2446
2301
|
*/
|
|
2447
2302
|
type Min<Num1 extends number,Num2 extends number>=IfLowerThan<Num1,Num2,Num1,Num2>;
|
|
2448
|
-
/**
|
|
2449
|
-
* Helper type for computing the minimum of a tuple of numbers recursively.
|
|
2303
|
+
/** * ***Helper type for computing the minimum of a tuple of numbers recursively.***
|
|
2450
2304
|
*
|
|
2305
|
+
* @private ***Private internal type for {@link MinArr | **`MinArr`**}.***
|
|
2451
2306
|
* @template T - Array of numbers
|
|
2452
2307
|
* @template CurrentMin - Current minimum in recursion
|
|
2453
2308
|
*/
|
|
2454
2309
|
type _MinArr<T extends readonly number[],CurrentMin extends number=ReturnItselfIfNotExtends<T[0],undefined,never>>=IsEmptyArray<T>extends true?CurrentMin:Shift<T,{includeRemoved:true;}>extends [ infer Rest extends number[],infer First extends number]?_MinArr<Rest,Min<First,CurrentMin>>:never;
|
|
2455
2310
|
/** -------------------------------------------------------
|
|
2456
|
-
* * ***MinArr
|
|
2311
|
+
* * ***Utility Type: `MinArr`.***
|
|
2457
2312
|
* -------------------------------------------------------
|
|
2458
|
-
* Accepts an array of integers and returns the **minimum** among its elements
|
|
2313
|
+
* **Accepts an array of integers and returns the **minimum** among its elements.**
|
|
2459
2314
|
* - Range: `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`.
|
|
2460
|
-
*
|
|
2461
2315
|
* @template T - Tuple of numbers.
|
|
2462
2316
|
* @example
|
|
2463
2317
|
* ```ts
|
|
@@ -2467,12 +2321,10 @@ type _MinArr<T extends readonly number[],CurrentMin extends number=ReturnItselfI
|
|
|
2467
2321
|
*/
|
|
2468
2322
|
type MinArr<T extends readonly number[]>=IsTuple<T>extends true?_MinArr<T>:never;
|
|
2469
2323
|
/** -------------------------------------------------------
|
|
2470
|
-
* * ***NonNullableObject
|
|
2324
|
+
* * ***Utility Type: `NonNullableObject`.***
|
|
2471
2325
|
* -------------------------------------------------------
|
|
2472
|
-
* Makes all properties of the object type `T` non-nullable
|
|
2473
|
-
*
|
|
2326
|
+
* **Makes all properties of the object type `T` non-nullable.**
|
|
2474
2327
|
* @template T - Object type to transform.
|
|
2475
|
-
*
|
|
2476
2328
|
* @example
|
|
2477
2329
|
* ```ts
|
|
2478
2330
|
* type A = NonNullableObject<{ a: string | null; b: number | undefined }>;
|
|
@@ -2481,13 +2333,11 @@ type MinArr<T extends readonly number[]>=IsTuple<T>extends true?_MinArr<T>:never
|
|
|
2481
2333
|
*/
|
|
2482
2334
|
type NonNullableObject<T>={[K in keyof T]:NonNullable<T[K]>;};
|
|
2483
2335
|
/** -------------------------------------------------------
|
|
2484
|
-
* * ***NonNullableObjectOnly
|
|
2336
|
+
* * ***Utility Type: `NonNullableObjectOnly`.***
|
|
2485
2337
|
* -------------------------------------------------------
|
|
2486
|
-
* Makes only the specified properties `K` of the object type `T` non-nullable
|
|
2487
|
-
*
|
|
2338
|
+
* **Makes only the specified properties `K` of the object type `T` non-nullable.**
|
|
2488
2339
|
* @template T - Object type to transform.
|
|
2489
2340
|
* @template K - Keys of `T` to make non-nullable.
|
|
2490
|
-
*
|
|
2491
2341
|
* @example
|
|
2492
2342
|
* ```ts
|
|
2493
2343
|
* type A = NonNullableObjectOnly<
|
|
@@ -2499,13 +2349,11 @@ type NonNullableObject<T>={[K in keyof T]:NonNullable<T[K]>;};
|
|
|
2499
2349
|
*/
|
|
2500
2350
|
type NonNullableObjectOnly<T,K extends keyof T>=Prettify<Pick<T,Exclude<keyof T,K>>&{[P in K]:NonNullable<T[P]>;}>;
|
|
2501
2351
|
/** -------------------------------------------------------
|
|
2502
|
-
* * ***NonNullableObjectExcept
|
|
2352
|
+
* * ***Utility Type: `NonNullableObjectExcept`.***
|
|
2503
2353
|
* -------------------------------------------------------
|
|
2504
|
-
* Makes all properties of the object type `T` non-nullable except for the specified properties `K
|
|
2505
|
-
*
|
|
2354
|
+
* **Makes all properties of the object type `T` non-nullable except for the specified properties `K`.**
|
|
2506
2355
|
* @template T - Object type to transform.
|
|
2507
2356
|
* @template K - Keys of `T` to leave unchanged.
|
|
2508
|
-
*
|
|
2509
2357
|
* @example
|
|
2510
2358
|
* ```ts
|
|
2511
2359
|
* type A = NonNullableObjectExcept<
|
|
@@ -2517,62 +2365,48 @@ type NonNullableObjectOnly<T,K extends keyof T>=Prettify<Pick<T,Exclude<keyof T,
|
|
|
2517
2365
|
*/
|
|
2518
2366
|
type NonNullableObjectExcept<T,K extends keyof T>=Prettify<Pick<T,K>&{[P in Exclude<keyof T,K>]:NonNullable<T[P]>;}>;
|
|
2519
2367
|
/** --------------------------------------------------
|
|
2520
|
-
* * ***
|
|
2368
|
+
* * ***Internal Utility Type for: {@link NumberRangeLimit | `NumberRangeLimit`}.***
|
|
2521
2369
|
* --------------------------------------------------
|
|
2522
|
-
*
|
|
2523
2370
|
* @template From - Starting number of the range (inclusive).
|
|
2524
2371
|
* @template To - Ending number of the range (inclusive).
|
|
2525
2372
|
* @template Result - Internal accumulator for recursion (do not set manually).
|
|
2526
|
-
|
|
2373
|
+
*/
|
|
2374
|
+
type _NumberRangeLimit<From extends number,To extends number,Result extends number[]=[From]>=IsGreaterThan<From,To>extends true?[...Result,To][number] extends infer R extends number?R extends R?IsGreaterThan<R,To>extends true?never:R:never:never:_NumberRangeLimit<Sum<From,7>,To,[ ...Result,From,Sum<From,1>,Sum<From,2>,Sum<From,3>,Sum<From,4>,Sum<From,5>,Sum<From,6>]>;
|
|
2375
|
+
/** --------------------------------------------------
|
|
2376
|
+
* * ***Utility Type: `NumberRangeLimit`.***
|
|
2377
|
+
* --------------------------------------------------
|
|
2378
|
+
* **Generate a union type of numbers within a specified range (optimized recursive batching).**
|
|
2527
2379
|
* @description
|
|
2528
2380
|
* Produces a **numeric union type** from `From` to `To` (inclusive),
|
|
2529
|
-
* using
|
|
2381
|
+
* using ***batched recursive expansion*** (**adds up to `7` numbers at a time**).
|
|
2530
2382
|
*
|
|
2531
|
-
* This batching allows generating larger ranges efficiently without
|
|
2383
|
+
* This batching allows generating **larger ranges** (`≥ 101`) efficiently without
|
|
2532
2384
|
* hitting TypeScript’s recursion limits too quickly.
|
|
2533
|
-
*
|
|
2534
2385
|
* - ✅ Optimized for **performance** (fewer recursive steps).
|
|
2535
2386
|
* - ⚠️ Supports up to `To = 999` safely.
|
|
2536
|
-
* - ⚙️ Best used when you need **arbitrary ranges** within `0–999`.
|
|
2537
|
-
*
|
|
2387
|
+
* - ⚙️ Best used for **larger ranges** (`≥ 101`) or when you need **arbitrary ranges** within `0–999`.
|
|
2388
|
+
* - ℹ️ For **smaller ranges** (`≤ 100`) or when readability matters use {@link NumberRangeUnion | **`NumberRangeUnion`**} instead.
|
|
2389
|
+
* @template From - Starting number of the range (inclusive).
|
|
2390
|
+
* @template To - Ending number of the range (inclusive).
|
|
2538
2391
|
* @example
|
|
2539
2392
|
* ```ts
|
|
2540
2393
|
* type RangeA = NumberRangeLimit<5, 8>;
|
|
2541
|
-
* //
|
|
2542
|
-
*
|
|
2394
|
+
* // ➔ 5 | 6 | 7 | 8
|
|
2543
2395
|
* type RangeB = NumberRangeLimit<10, 15>;
|
|
2544
|
-
* //
|
|
2545
|
-
*
|
|
2546
|
-
|
|
2547
|
-
|
|
2548
|
-
|
|
2549
|
-
* * ***OverrideTypes.***
|
|
2550
|
-
* --------------------------------------------------
|
|
2551
|
-
* Overrides properties in type `T` with properties from type `U`, based on matching keys.
|
|
2552
|
-
*
|
|
2553
|
-
* ✅ Ensures the result retains all properties from `T`, but values from `U` override corresponding keys.
|
|
2554
|
-
*
|
|
2555
|
-
* @template T - The base object type to override.
|
|
2556
|
-
* @template U - The object type containing overriding properties.
|
|
2557
|
-
*
|
|
2558
|
-
* @example
|
|
2559
|
-
* ```ts
|
|
2560
|
-
* type A = { a: number; b: string };
|
|
2561
|
-
* type B = { b: boolean };
|
|
2562
|
-
* type C = OverrideTypes<A, B>;
|
|
2563
|
-
* // ➔ { a: number; b: boolean }
|
|
2396
|
+
* // ➔ 10 | 11 | 12 | 13 | 14 | 15
|
|
2397
|
+
* type RangeC = NumberRangeLimit<8, 8>;
|
|
2398
|
+
* // ➔ 8
|
|
2399
|
+
* type RangeD = NumberRangeLimit<20, 10>;
|
|
2400
|
+
* // ➔ 10
|
|
2564
2401
|
* ```
|
|
2565
2402
|
*/
|
|
2566
|
-
type
|
|
2403
|
+
type NumberRangeLimit<From extends number,To extends number>=_NumberRangeLimit<From,To>;type _IsPalindrome<T extends string>=IsEmptyString<T>extends true?true:Not<IsStringLiteral<T>>extends true?false:T extends`${infer First extends string}${infer Rest extends string}`?IsEmptyString<Rest>extends true?true:Rest extends`${infer NewRest extends string}${First}`?_IsPalindrome<NewRest>:false:false;
|
|
2567
2404
|
/** -------------------------------------------------------
|
|
2568
|
-
* * ***IsPalindrome
|
|
2405
|
+
* * ***Utility Type: `IsPalindrome`.***
|
|
2569
2406
|
* -------------------------------------------------------
|
|
2570
|
-
*
|
|
2571
|
-
*
|
|
2572
|
-
* A palindrome reads the same forwards and backwards (e.g., `"racecar"`).
|
|
2573
|
-
*
|
|
2407
|
+
* **Determines if a string or number is a **palindrome** at type-level.
|
|
2408
|
+
* A palindrome reads the same forwards and backwards (e.g., `"racecar"`).**
|
|
2574
2409
|
* @template T - A string or number to check.
|
|
2575
|
-
*
|
|
2576
2410
|
* @example
|
|
2577
2411
|
* ```ts
|
|
2578
2412
|
* type T0 = IsPalindrome<"racecar">; // true
|
|
@@ -2580,28 +2414,25 @@ type OverrideTypes<T,U extends Partial<Record<keyof T,unknown>>>=OmitStrict<T,Ex
|
|
|
2580
2414
|
* type T2 = IsPalindrome<12321>; // true
|
|
2581
2415
|
* type T3 = IsPalindrome<12345>; // false
|
|
2582
2416
|
* ```
|
|
2583
|
-
*
|
|
2584
2417
|
* @remarks
|
|
2585
|
-
* - Converts numbers to strings using {@link Stringify}.
|
|
2586
|
-
* - Uses {@link IsEmptyString
|
|
2418
|
+
* - Converts numbers to strings using {@link Stringify | **`Stringify`**}.
|
|
2419
|
+
* - Uses {@link IsEmptyString | **`IsEmptyString`**},
|
|
2420
|
+
* {@link IsStringLiteral | **`IsStringLiteral`**},
|
|
2421
|
+
* and {@link Not | **`Not`**} for type-level logic.
|
|
2587
2422
|
* - Returns `true` if the input is a palindrome, otherwise `false`.
|
|
2588
2423
|
*/
|
|
2589
2424
|
type IsPalindrome<T extends string|number>=_IsPalindrome<Stringify<T>>;
|
|
2590
2425
|
/** -------------------------------------------------------
|
|
2591
|
-
* * ***UnionToIntersection
|
|
2426
|
+
* * ***Utility Type: `UnionToIntersection`.***
|
|
2592
2427
|
* -------------------------------------------------------
|
|
2593
|
-
*
|
|
2594
|
-
*
|
|
2595
|
-
*
|
|
2596
|
-
* 📖 Reference: ***[StackOverflow](https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type/50375286#50375286).***
|
|
2597
|
-
*
|
|
2428
|
+
* **Converts a union type into an **intersection**.**
|
|
2429
|
+
* @description
|
|
2430
|
+
* 📖 Reference: ***[`StackOverflow`](https://stackoverflow.com/questions/50374908/transform-union-type-to-intersection-type/50375286#50375286).***
|
|
2598
2431
|
* @template U - The union type to be converted.
|
|
2599
|
-
*
|
|
2600
2432
|
* @example
|
|
2601
2433
|
* ```ts
|
|
2602
2434
|
* type A = UnionToIntersection<{ a: string } | { b: number }>;
|
|
2603
2435
|
* // ➔ { a: string } & { b: number }
|
|
2604
|
-
*
|
|
2605
2436
|
* type B = UnionToIntersection<
|
|
2606
2437
|
* { a: string } | { b: number } | { c: boolean }
|
|
2607
2438
|
* >;
|
|
@@ -2610,31 +2441,28 @@ type IsPalindrome<T extends string|number>=_IsPalindrome<Stringify<T>>;
|
|
|
2610
2441
|
*/
|
|
2611
2442
|
type UnionToIntersection<U>=(U extends any?(k:U)=>void:never)extends(k:infer I)=>void?I:never;
|
|
2612
2443
|
/** -------------------------------------------------------
|
|
2613
|
-
* * ***PrettifyUnionIntersection
|
|
2444
|
+
* * ***Utility Type: `PrettifyUnionIntersection`.***
|
|
2614
2445
|
* -------------------------------------------------------
|
|
2615
|
-
*
|
|
2616
|
-
*
|
|
2617
|
-
*
|
|
2618
|
-
*
|
|
2619
|
-
*
|
|
2446
|
+
* **Converts a union type into an **intersection** using ***{@link UnionToIntersection | `UnionToIntersection`}***, and then
|
|
2447
|
+
* applies ***{@link Prettify | `Prettify`}*** to simplify the resulting intersection
|
|
2448
|
+
* for better readability in IntelliSense and tooltips.**
|
|
2449
|
+
* @description
|
|
2620
2450
|
* Useful when the raw intersection of union types produces
|
|
2621
2451
|
* deeply nested or hard-to-read structures.
|
|
2622
|
-
*
|
|
2623
2452
|
* @template T - The union type to be converted.
|
|
2624
2453
|
* @template Options - Optional formatting options for `Prettify`.
|
|
2625
|
-
*
|
|
2626
2454
|
* @example
|
|
2627
2455
|
* ```ts
|
|
2628
|
-
* // Basic union
|
|
2456
|
+
* // Basic union ➔ intersection
|
|
2629
2457
|
* type A = { a: string } | { b: number };
|
|
2630
2458
|
* type B = PrettifyUnionIntersection<A>;
|
|
2631
|
-
* // ➔
|
|
2459
|
+
* // ➔ { a: string } & { b: number }
|
|
2632
2460
|
* // final result become ➔ { a: string b: number }
|
|
2633
2461
|
*
|
|
2634
2462
|
* // Larger union
|
|
2635
2463
|
* type C = { a: string } | { b: number } | { c: boolean };
|
|
2636
2464
|
* type D = PrettifyUnionIntersection<C>;
|
|
2637
|
-
* // ➔
|
|
2465
|
+
* // ➔ { a: string } & { b: number } & { c: boolean }
|
|
2638
2466
|
* // final result become ➔ { a: string b: number c: boolean }
|
|
2639
2467
|
*
|
|
2640
2468
|
* // With PrettifyOptions (custom formatting)
|
|
@@ -2655,15 +2483,12 @@ type RequiredKeysOf<U>=Exclude<keyof U,OptionalKeys<U>>;
|
|
|
2655
2483
|
/** Force re-evaluation / cleaner display */
|
|
2656
2484
|
|
|
2657
2485
|
/** -------------------------------------------------------
|
|
2658
|
-
* * ***PartialOnly
|
|
2486
|
+
* * ***Utility Type: `PartialOnly`.***
|
|
2659
2487
|
* -------------------------------------------------------
|
|
2660
|
-
*
|
|
2661
|
-
*
|
|
2662
|
-
* while keeping all other properties required.
|
|
2663
|
-
*
|
|
2488
|
+
* **Make only the specified properties in `T` **optional**, while keeping all
|
|
2489
|
+
* other properties required.**
|
|
2664
2490
|
* @template T - The object type to transform.
|
|
2665
2491
|
* @template K - Keys of `T` that should become optional.
|
|
2666
|
-
*
|
|
2667
2492
|
* @example
|
|
2668
2493
|
* ```ts
|
|
2669
2494
|
* // Only "a" is optional, "b" and "c" remain required
|
|
@@ -2690,20 +2515,17 @@ type RequiredKeysOf<U>=Exclude<keyof U,OptionalKeys<U>>;
|
|
|
2690
2515
|
*/
|
|
2691
2516
|
type PartialOnly<T extends object,K extends keyof T|AnyString>=IsNever<K>extends true?T:PrettifyUnionIntersection<{[P in Exclude<RequiredKeys<T>,Extract<keyof T,K>>]-?:T[P];}&{[P in Exclude<OptionalKeys<T>,Extract<keyof T,K>>]+?:CleanOptional$1<T[P]>;}&{[P in Extract<keyof T,K>]+?:CleanOptional$1<T[P]>;}>;
|
|
2692
2517
|
/** -------------------------------------------------------
|
|
2693
|
-
* * ***PartialExcept
|
|
2518
|
+
* * ***Utility Type: `PartialExcept`.***
|
|
2694
2519
|
* -------------------------------------------------------
|
|
2695
|
-
*
|
|
2696
|
-
*
|
|
2697
|
-
*
|
|
2698
|
-
*
|
|
2699
|
-
*
|
|
2700
|
-
*
|
|
2701
|
-
*
|
|
2702
|
-
* - Duplicate `undefined` types are cleaned up automatically.
|
|
2703
|
-
*
|
|
2520
|
+
* **Make all properties in `T` **optional**, except for the ones specified
|
|
2521
|
+
* in `K`, which remain as-is.**
|
|
2522
|
+
* - **Behavior:**
|
|
2523
|
+
* - If a property in `K` is originally required ➔ it stays required.
|
|
2524
|
+
* - If a property in `K` is originally optional ➔ it stays optional.
|
|
2525
|
+
* - All other properties become optional.
|
|
2526
|
+
* - Duplicate `undefined` types are cleaned up automatically.
|
|
2704
2527
|
* @template T - The object type to transform.
|
|
2705
2528
|
* @template K - Keys of `T` that should remain as-is (not forced optional).
|
|
2706
|
-
*
|
|
2707
2529
|
* @example
|
|
2708
2530
|
* ```ts
|
|
2709
2531
|
* // "a" remains required, "b" and "c" become optional
|
|
@@ -2719,7 +2541,7 @@ type PartialOnly<T extends object,K extends keyof T|AnyString>=IsNever<K>extends
|
|
|
2719
2541
|
* type T2 = PartialExcept<{ a: string; b?: number; c: boolean }, "a" | "b">;
|
|
2720
2542
|
* // ➔ { a: string; b?: number; c?: boolean }
|
|
2721
2543
|
*
|
|
2722
|
-
* // none of the keys match
|
|
2544
|
+
* // none of the keys match ➔ everything optional
|
|
2723
2545
|
* type T3 = PartialExcept<{ a: string; b: number; c: boolean }, "x">;
|
|
2724
2546
|
* // ➔ { a?: string; b?: number; c?: boolean }
|
|
2725
2547
|
* ```
|
|
@@ -2731,31 +2553,74 @@ type PartialOnly<T extends object,K extends keyof T|AnyString>=IsNever<K>extends
|
|
|
2731
2553
|
*/
|
|
2732
2554
|
type PartialExcept<T extends object,K extends keyof T|AnyString>=IsNever<K>extends true?Partial<T>:PrettifyUnionIntersection<Identity<{[P in RequiredKeysOf<Identity<Pick<T,Extract<keyof T,K>>&{[P in Exclude<keyof T,K>]?:T[P];}>>]-?:CleanOptional$1<Identity<Pick<T,Extract<keyof T,K>>&{[P in Exclude<keyof T,K>]?:T[P];}>[P]>;}&{[P in OptionalKeys<Identity<Pick<T,Extract<keyof T,K>>&{[P in Exclude<keyof T,K>]?:T[P];}>>]+?:CleanOptional$1<Identity<Pick<T,Extract<keyof T,K>>&{[P in Exclude<keyof T,K>]?:T[P];}>[P]>;}>>;
|
|
2733
2555
|
/** -------------------------------------------------------
|
|
2734
|
-
* * ***
|
|
2556
|
+
* * ***Utility Type: `ValueOf`.***
|
|
2735
2557
|
* -------------------------------------------------------
|
|
2736
|
-
*
|
|
2737
|
-
*
|
|
2738
|
-
*
|
|
2739
|
-
*
|
|
2558
|
+
* **Gets the types of all property values in an object `T`.**
|
|
2559
|
+
* @template T - The object type.
|
|
2560
|
+
* @example
|
|
2561
|
+
* ```ts
|
|
2562
|
+
* type Case1 = ValueOf<{ a: string, b: number }>;
|
|
2563
|
+
* // ➔ string | number
|
|
2564
|
+
* ```
|
|
2565
|
+
*/
|
|
2566
|
+
type ValueOf<T>=T[keyof T];
|
|
2567
|
+
/** -------------------------------------------------------
|
|
2568
|
+
* * ***Utility Type: `ValueOfOnly`.***
|
|
2569
|
+
* -------------------------------------------------------
|
|
2570
|
+
* **Gets the types of properties in object `T` specified by `K`.**
|
|
2571
|
+
* @template T - The object type.
|
|
2572
|
+
* @template K - Keys of `T` to extract values from.
|
|
2573
|
+
* @example
|
|
2574
|
+
* ```ts
|
|
2575
|
+
* type Case1 = ValueOfOnly<{ a: string, b: number }, "a">;
|
|
2576
|
+
* // ➔ string
|
|
2577
|
+
* ```
|
|
2578
|
+
*/
|
|
2579
|
+
type ValueOfOnly<T,K extends keyof T>=T[K];
|
|
2580
|
+
/** -------------------------------------------------------
|
|
2581
|
+
* * ***Utility Type: `ValueOfExcept`.***
|
|
2582
|
+
* -------------------------------------------------------
|
|
2583
|
+
* **Gets the types of properties in object `T` **except** for keys in `K`.**
|
|
2584
|
+
* @template T - The object type.
|
|
2585
|
+
* @template K - Keys of `T` to exclude.
|
|
2586
|
+
* @example
|
|
2587
|
+
* ```ts
|
|
2588
|
+
* type Case1 = ValueOfExcept<{ a: string, b: number }, "a">;
|
|
2589
|
+
* // ➔ number
|
|
2590
|
+
* ```
|
|
2591
|
+
*/
|
|
2592
|
+
type ValueOfExcept<T,K extends keyof T>=T[keyof Omit<T,K>];
|
|
2593
|
+
/** -------------------------------------------------------
|
|
2594
|
+
* * ***Utility Type: `ValueOfArray`.***
|
|
2595
|
+
* -------------------------------------------------------
|
|
2596
|
+
* **Gets the types of elements in a tuple or array `T`.**
|
|
2597
|
+
* @template T - The tuple or array type.
|
|
2598
|
+
* @example
|
|
2599
|
+
* ```ts
|
|
2600
|
+
* type Case1 = ValueOfArray<[string, number]>;
|
|
2601
|
+
* // ➔ string | number
|
|
2602
|
+
* ```
|
|
2603
|
+
*/
|
|
2604
|
+
type ValueOfArray<T extends readonly unknown[]>=T[number];
|
|
2605
|
+
/** -------------------------------------------------------
|
|
2606
|
+
* * ***Utility Type: `OverWritable`.***
|
|
2607
|
+
* -------------------------------------------------------
|
|
2608
|
+
* **Option type to signal that some properties can be overwritten when
|
|
2609
|
+
* applying default options.**
|
|
2740
2610
|
* @property overwriteDefault - If true, all options in the passed `Options`
|
|
2741
2611
|
* object will **overwrite** defaults, even if rules say otherwise.
|
|
2742
2612
|
*/
|
|
2743
2613
|
type OverWritable={
|
|
2744
|
-
/**
|
|
2745
|
-
* If true, all options in the passed `Options` object will **overwrite** defaults, even if rules say otherwise, defaultValue: `false`.
|
|
2614
|
+
/** If true, all options in the passed `Options` object will **overwrite** defaults, even if rules say otherwise, defaultValue: `false`.
|
|
2746
2615
|
*
|
|
2747
2616
|
* @default false
|
|
2748
2617
|
*/
|
|
2749
2618
|
overwriteDefault?:boolean;};
|
|
2750
2619
|
/** -------------------------------------------------------
|
|
2751
|
-
* * ***ApplyDefaultOptions
|
|
2620
|
+
* * ***Utility Type: `ApplyDefaultOptions`.***
|
|
2752
2621
|
* -------------------------------------------------------
|
|
2753
|
-
*
|
|
2754
|
-
*
|
|
2755
|
-
*
|
|
2756
|
-
* Type-level utility that merges a user-specified `Options` object
|
|
2757
|
-
* with a `DefaultOptions` object using a set of `OverwriteRules`.
|
|
2758
|
-
*
|
|
2622
|
+
* **Type-level utility that merges a user-specified `Options` object
|
|
2623
|
+
* with a `DefaultOptions` object using a set of `OverwriteRules`.**
|
|
2759
2624
|
* @template BaseOptions - The base type of all options.
|
|
2760
2625
|
* @template Options - User-specified options that may override defaults.
|
|
2761
2626
|
* @template DefaultOptions - Default values for options.
|
|
@@ -2763,14 +2628,12 @@ overwriteDefault?:boolean;};
|
|
|
2763
2628
|
* should always allow overwriting defaults.
|
|
2764
2629
|
* @template OverwriteDefault - If true, all options in `Options`
|
|
2765
2630
|
* overwrite defaults regardless of rules.
|
|
2766
|
-
*
|
|
2767
2631
|
* @remarks
|
|
2768
2632
|
* - Recursively applies defaults for nested objects.
|
|
2769
2633
|
* - Only objects that are non-nullable and non-unknown are recursively merged.
|
|
2770
2634
|
* - If a property is **not an object** or recursion is not needed,
|
|
2771
2635
|
* it either takes the value from `Options` or merges `Options[K] | DefaultOptions[K]`.
|
|
2772
2636
|
* - Helps safely build strongly typed configuration objects with defaults.
|
|
2773
|
-
*
|
|
2774
2637
|
* @example
|
|
2775
2638
|
* ```ts
|
|
2776
2639
|
* type Base = {
|
|
@@ -2793,91 +2656,69 @@ overwriteDefault?:boolean;};
|
|
|
2793
2656
|
* // b: boolean;
|
|
2794
2657
|
* // }
|
|
2795
2658
|
* ```
|
|
2796
|
-
*
|
|
2797
2659
|
*/
|
|
2798
2660
|
type ApplyDefaultOptions<BaseOptions,Options extends BaseOptions,DefaultOptions extends BaseOptions,OverwriteRules,OverwriteDefault extends boolean=false>=Prettify<{[K in keyof BaseOptions]-?:K extends keyof Options?AndArr<[ Extends<NonNullable<BaseOptions[K]>,object>,Not<IsNever<DefaultOptions[K]>>,Not<IsUnknown<BaseOptions[K]>>]>extends true?ApplyDefaultOptions<NonNullable<BaseOptions[K]>,Extract<Options[K],NonNullable<BaseOptions[K]>>,Extract<DefaultOptions[K],NonNullable<BaseOptions[K]>>,OverwriteRules[K & keyof OverwriteRules],OverwriteDefault>&{tra:"test";}:Or<IsEqual<OverwriteDefault,true>,And<Extends<K,keyof OverwriteRules>,Extends<OverwriteRules[K & keyof OverwriteRules],true>>>extends true?Options[K]:Options[K]|DefaultOptions[K]:DefaultOptions[K];}>;
|
|
2799
|
-
/**
|
|
2800
|
-
* * ***
|
|
2801
|
-
*
|
|
2802
|
-
*
|
|
2803
|
-
*
|
|
2804
|
-
* @template
|
|
2805
|
-
*
|
|
2806
|
-
* @
|
|
2807
|
-
*
|
|
2808
|
-
* type Case1 = ValueOf<{ a: string, b: number }>;
|
|
2809
|
-
* // ➔ string | number
|
|
2810
|
-
* ```
|
|
2661
|
+
/** --------------------------------------------------------------
|
|
2662
|
+
* * ***Options for {@link PathToFields | **`PathToFields`**} type-level utility.***
|
|
2663
|
+
* --------------------------------------------------------------
|
|
2664
|
+
* @template ignoredTypes - Types to ignore completely.
|
|
2665
|
+
* @template stopTypes - Types at which recursion stops and returns `[]`.
|
|
2666
|
+
* @template limit - Max recursion depth.
|
|
2667
|
+
* @template format - Output format, `"dot"` or `"array"`.
|
|
2668
|
+
* @template ignoredKeys - Keys to ignore when generating paths.
|
|
2669
|
+
* @template arrayIndexing - Options for handling array paths.
|
|
2811
2670
|
*/
|
|
2812
|
-
type
|
|
2813
|
-
/**
|
|
2814
|
-
* * ***ValueOfOnly.***
|
|
2815
|
-
* -------------------------------------------------------
|
|
2816
|
-
* Gets the types of properties in object `T` specified by `K`.
|
|
2671
|
+
type PathToFieldsOptions=Prettify<OverWritable &{
|
|
2672
|
+
/** Types to ignored completely (default: `undefined`).
|
|
2817
2673
|
*
|
|
2818
|
-
* @
|
|
2819
|
-
|
|
2674
|
+
* @default undefined
|
|
2675
|
+
*/
|
|
2676
|
+
ignoredTypes?:unknown;
|
|
2677
|
+
/** Types at which recursion stops (default: `undefined`).
|
|
2820
2678
|
*
|
|
2821
|
-
* @
|
|
2822
|
-
* ```ts
|
|
2823
|
-
* type Case1 = ValueOfOnly<{ a: string, b: number }, "a">;
|
|
2824
|
-
* // ➔ string
|
|
2825
|
-
* ```
|
|
2679
|
+
* @default undefined
|
|
2826
2680
|
*/
|
|
2827
|
-
|
|
2828
|
-
/**
|
|
2829
|
-
* * ***ValueOfExcept.***
|
|
2830
|
-
* -------------------------------------------------------
|
|
2831
|
-
* Gets the types of properties in object `T` **except** for keys in `K`.
|
|
2681
|
+
stopTypes?:unknown;
|
|
2682
|
+
/** Max recursion depth (default: `10`).
|
|
2832
2683
|
*
|
|
2833
|
-
* @
|
|
2834
|
-
|
|
2684
|
+
* @default 10
|
|
2685
|
+
*/
|
|
2686
|
+
limit?:number;
|
|
2687
|
+
/** Format Output Options:
|
|
2688
|
+
* - `"dot"` ➔ dot-notation strings, default output (`"a.b.c"`).
|
|
2689
|
+
* - `"array"` ➔ array of path segments (`["a", "b", "c"]`).
|
|
2835
2690
|
*
|
|
2836
|
-
* @
|
|
2837
|
-
* ```ts
|
|
2838
|
-
* type Case1 = ValueOfExcept<{ a: string, b: number }, "a">;
|
|
2839
|
-
* // ➔ number
|
|
2840
|
-
* ```
|
|
2691
|
+
* @default "dot"
|
|
2841
2692
|
*/
|
|
2842
|
-
|
|
2843
|
-
/**
|
|
2844
|
-
* * ***ValueOfArray.***
|
|
2845
|
-
* -------------------------------------------------------
|
|
2846
|
-
* Gets the types of elements in a tuple or array `T`.
|
|
2693
|
+
format?:"dot"|"array";
|
|
2694
|
+
/** Keys to skip when generating paths (default: `undefined`).
|
|
2847
2695
|
*
|
|
2848
|
-
* @
|
|
2696
|
+
* @default undefined
|
|
2697
|
+
*/
|
|
2698
|
+
ignoredKeys?:PropertyKey;
|
|
2699
|
+
/** Options for array Indexing (default: `{ exactIndexes: false }`).
|
|
2849
2700
|
*
|
|
2850
|
-
*
|
|
2851
|
-
*
|
|
2852
|
-
* type Case1 = ValueOfArray<[string, number]>;
|
|
2853
|
-
* // ➔ string | number
|
|
2854
|
-
* ```
|
|
2701
|
+
* When `arrayIndexing.exactIndexes = true` ➔ outputs exact tuple indexes (`"arr.0"`), otherwise generic `"arr.${number}"`.
|
|
2702
|
+
* @default undefined
|
|
2855
2703
|
*/
|
|
2856
|
-
|
|
2857
|
-
/**
|
|
2858
|
-
* * ***Options for {@link PathToFields} type-level utility.***
|
|
2859
|
-
* --------------------------------------------------------------
|
|
2704
|
+
arrayIndexing?:{
|
|
2705
|
+
/** Options for array Exact Indexing (default: `false`).
|
|
2860
2706
|
*
|
|
2861
|
-
*
|
|
2862
|
-
*
|
|
2863
|
-
*
|
|
2864
|
-
* @
|
|
2865
|
-
* @template ignoredKeys - Keys to ignore when generating paths.
|
|
2866
|
-
* @template arrayIndexing - Options for handling array paths.
|
|
2707
|
+
* When `exactIndexes = true` ➔ outputs exact tuple indexes (`"arr.0"`), otherwise generic `"arr.${number}"`.
|
|
2708
|
+
* - For increase limit indexing, you can set `limit` options, default
|
|
2709
|
+
* limit is: `10`.
|
|
2710
|
+
* @default false
|
|
2867
2711
|
*/
|
|
2868
|
-
|
|
2712
|
+
exactIndexes:boolean;};},{recursive:true;}>;
|
|
2869
2713
|
/** * ***Default options for {@link PathToFields}.*** */
|
|
2870
2714
|
type DefaultPathToFieldsOptions={ignoredTypes:never;stopTypes:string|number|boolean|symbol|Date|AnyFunction;format:"dot";limit:10;ignoredKeys:never;arrayIndexing:{exactIndexes:false;};};type OverwriteRules={limit:true;format:true;arrayIndexing:{exactIndexes:true;};};type Booleanize<T>=T extends true?true:false;type _PathToFieldsArray<T extends readonly unknown[],Options extends PathToFieldsOptions,Iteration extends number=0>=And<IsTuple<T>,IsEqual<Booleanize<Options["arrayIndexing"] extends{exactIndexes:infer E;}?E:false>,true>>extends true?ValueOfArray<{[K in keyof T]:IsArrayIndex<K>extends true?[K,..._PathToFields<T[K],Options,Increment<Iteration>>]:never;}>:ArrayElementType<T>extends infer ElementType?[`${number}`,...(ElementType extends ElementType?_PathToFields<ElementType,Options,Increment<Iteration>>:never)]:never;type _PathToFields<T,Options extends PathToFieldsOptions,Iteration extends number=0>=T extends Options["ignoredTypes"]?never:T extends Options["stopTypes"]?[]:IsEqual<Iteration,Options["limit"]>extends true?never:T extends readonly unknown[]?_PathToFieldsArray<T,Options,Iteration>:ValueOf<{[K in Exclude<keyof T,symbol|Options["ignoredKeys"]>]:NonNullable<T[K]>extends infer NonNullableFields?NonNullableFields extends readonly unknown[]?[K,..._PathToFieldsArray<NonNullableFields,Options,Iteration>]:[K,..._PathToFields<NonNullableFields,Options,Increment<Iteration>>]:never;}>;
|
|
2871
2715
|
/** -------------------------------------------------------
|
|
2872
|
-
* * ***PathToFields
|
|
2716
|
+
* * ***Utility Type: `PathToFields`.***
|
|
2873
2717
|
* -------------------------------------------------------
|
|
2874
|
-
*
|
|
2875
|
-
*
|
|
2876
|
-
* Supports nested objects, arrays, tuples, and optional configuration.
|
|
2877
|
-
*
|
|
2718
|
+
* **Generates **all possible property paths** within a type `T`.
|
|
2719
|
+
* Supports nested objects, arrays, tuples, and optional configuration.**
|
|
2878
2720
|
* @template T - Object type to extract paths from.
|
|
2879
|
-
* @template Options - Optional configuration.
|
|
2880
|
-
*
|
|
2721
|
+
* @template Options - Optional configuration.
|
|
2881
2722
|
* @example
|
|
2882
2723
|
* ```ts
|
|
2883
2724
|
* // Nested object
|
|
@@ -2909,113 +2750,42 @@ type DefaultPathToFieldsOptions={ignoredTypes:never;stopTypes:string|number|bool
|
|
|
2909
2750
|
* >;
|
|
2910
2751
|
* // Result: "settings" | "nested.inner"
|
|
2911
2752
|
* ```
|
|
2912
|
-
*
|
|
2913
2753
|
* @remarks
|
|
2914
|
-
* - `Options.format = "dot"`
|
|
2915
|
-
* - `Options.format = "array"`
|
|
2916
|
-
* - `Options.limit`
|
|
2917
|
-
* - `Options.stopTypes`
|
|
2918
|
-
* - `Options.ignoredTypes`
|
|
2919
|
-
* - `Options.ignoredKeys`
|
|
2920
|
-
* - `Options.arrayIndexing.exactIndexes = true`
|
|
2921
|
-
*/
|
|
2922
|
-
type PathToFields<T,Options extends PathToFieldsOptions &{overwriteDefault?:boolean;}=never>=(IsNever<Options>extends true?DefaultPathToFieldsOptions:ApplyDefaultOptions<Omit<PathToFieldsOptions,keyof OverWritable>,Options,DefaultPathToFieldsOptions,OverwriteRules,PathToFieldsOptions["overwriteDefault"] extends boolean?PathToFieldsOptions["overwriteDefault"]:false>)extends infer MergedOptions extends PathToFieldsOptions?_PathToFields<T,MergedOptions>extends infer Paths extends readonly(string|number)[]?IsEqual<MergedOptions["format"],"dot">extends true?Paths extends Paths?Join<Paths,".">:never:Paths:never:never;
|
|
2923
|
-
/** --------------------------------------------------
|
|
2924
|
-
* * ***PickStrict.***
|
|
2925
|
-
* --------------------------------------------------
|
|
2926
|
-
* Utility type that behaves exactly like the native `Pick<T, K>`,
|
|
2927
|
-
* but can help with type inference and IDE autocomplete in stricter scenarios.
|
|
2928
|
-
*
|
|
2929
|
-
* @template T - The base object type.
|
|
2930
|
-
* @template K - The keys from `T` to be picked.
|
|
2931
|
-
*
|
|
2932
|
-
* @example
|
|
2933
|
-
* ```ts
|
|
2934
|
-
* type A = { a: number; b: string; c: boolean };
|
|
2935
|
-
* type B = PickStrict<A, 'a' | 'c'>;
|
|
2936
|
-
* // ➔ { a: number; c: boolean }
|
|
2937
|
-
* ```
|
|
2754
|
+
* - `Options.format = "dot"` ➔ dot-notation strings, default output (`"a.b.c"`).
|
|
2755
|
+
* - `Options.format = "array"` ➔ array of path segments (`["a", "b", "c"]`).
|
|
2756
|
+
* - `Options.limit` ➔ max recursion depth (default 10).
|
|
2757
|
+
* - `Options.stopTypes` ➔ types at which recursion stops.
|
|
2758
|
+
* - `Options.ignoredTypes` ➔ types ignored completely.
|
|
2759
|
+
* - `Options.ignoredKeys` ➔ keys to skip when generating paths.
|
|
2760
|
+
* - `Options.arrayIndexing.exactIndexes = true` ➔ outputs exact tuple indexes (`"arr.0"`), otherwise generic `"arr.${number}"`.
|
|
2938
2761
|
*/
|
|
2939
|
-
type
|
|
2762
|
+
type PathToFields<T,Options extends PathToFieldsOptions=never>=(IsNever<Options>extends true?DefaultPathToFieldsOptions:ApplyDefaultOptions<Omit<PathToFieldsOptions,keyof OverWritable>,Options,DefaultPathToFieldsOptions,OverwriteRules,PathToFieldsOptions["overwriteDefault"] extends boolean?PathToFieldsOptions["overwriteDefault"]:false>)extends infer MergedOptions extends PathToFieldsOptions?_PathToFields<T,MergedOptions>extends infer Paths extends readonly(string|number)[]?IsEqual<MergedOptions["format"],"dot">extends true?Paths extends Paths?Join<Paths,".">:never:Paths:never:never;type _Pow<Num extends number,Factor extends number,CurrentProduct extends number=1,Iteration extends unknown[]=[]>=IsEqual<Iteration["length"],Factor>extends true?CurrentProduct:_Pow<Num,Factor,Multi<CurrentProduct,Num>,Push<Iteration,unknown>>;
|
|
2940
2763
|
/** -------------------------------------------------------
|
|
2941
|
-
* * ***Pow
|
|
2764
|
+
* * ***Utility Type: `Pow`.***
|
|
2942
2765
|
* -------------------------------------------------------
|
|
2943
|
-
*
|
|
2944
|
-
*
|
|
2945
|
-
*
|
|
2946
|
-
*
|
|
2766
|
+
* **Returns a type-level **exponentiation** result:**
|
|
2767
|
+
* - Raises the first integer parameter (`Num`) to the power of the second
|
|
2768
|
+
* integer parameter (`Factor`).
|
|
2947
2769
|
* @template Num - The base number (integer).
|
|
2948
2770
|
* @template Factor - The exponent number (integer, >= 0).
|
|
2949
|
-
*
|
|
2950
2771
|
* @example
|
|
2951
2772
|
* ```ts
|
|
2952
|
-
* // 100
|
|
2953
2773
|
* type Case1 = Pow<10, 2>
|
|
2954
|
-
*
|
|
2955
|
-
* // 1
|
|
2774
|
+
* // ➔ 100
|
|
2956
2775
|
* type Case2 = Pow<5, 0>
|
|
2957
|
-
*
|
|
2958
|
-
* // 8
|
|
2776
|
+
* // ➔ 1
|
|
2959
2777
|
* type Case3 = Pow<2, 3>
|
|
2778
|
+
* // ➔ 8
|
|
2960
2779
|
* ```
|
|
2961
2780
|
*/
|
|
2962
2781
|
type Pow<Num extends number,Factor extends number>=_Pow<Num,Factor>;
|
|
2963
|
-
/** --------------------------------------------------
|
|
2964
|
-
* * ***Awaitable.***
|
|
2965
|
-
* --------------------------------------------------
|
|
2966
|
-
* Represents a type that can be awaited:
|
|
2967
|
-
* either a plain value `T` or a `PromiseLike<T>`.
|
|
2968
|
-
*
|
|
2969
|
-
* @template T - The inner value type.
|
|
2970
|
-
*
|
|
2971
|
-
* @example
|
|
2972
|
-
* ```ts
|
|
2973
|
-
* async function wrap<T>(v: Awaitable<T>): Promise<T> {
|
|
2974
|
-
* return await v;
|
|
2975
|
-
* }
|
|
2976
|
-
*
|
|
2977
|
-
* const a = wrap(42); // Promise<number>
|
|
2978
|
-
* const b = wrap(Promise.resolve("hi")); // Promise<string>
|
|
2979
|
-
* ```
|
|
2980
|
-
*/
|
|
2981
|
-
type Awaitable<T>=T|PromiseLike<T>;
|
|
2982
|
-
/** --------------------------------------------------
|
|
2983
|
-
* * ***CustomPromise.***
|
|
2984
|
-
* --------------------------------------------------
|
|
2985
|
-
* A custom extension of the native `Promise` type that allows explicit typing
|
|
2986
|
-
* for both the resolved (`onSuccess`) and rejected (`onError`) values.
|
|
2987
|
-
*
|
|
2988
|
-
* ✅ Useful for strongly typing both success and error cases in async operations.
|
|
2989
|
-
* Example: server actions, RPC, or custom async wrappers.
|
|
2990
|
-
*
|
|
2991
|
-
* @template onSuccess - The type of the resolved value when fulfilled.
|
|
2992
|
-
* @template onError - The type of the rejection reason when rejected. Defaults to `any`.
|
|
2993
|
-
*
|
|
2994
|
-
* @example
|
|
2995
|
-
* ```ts
|
|
2996
|
-
* const fetchUser = (): CustomPromise<User, ApiError> => {
|
|
2997
|
-
* return customRequest().catch(err => {
|
|
2998
|
-
* handleError(err); // `err` is typed as ApiError
|
|
2999
|
-
* return fallbackUser;
|
|
3000
|
-
* });
|
|
3001
|
-
* };
|
|
3002
|
-
*
|
|
3003
|
-
* fetchUser().then(user => {
|
|
3004
|
-
* // ➔ user is typed as User
|
|
3005
|
-
* });
|
|
3006
|
-
* ```
|
|
3007
|
-
*/
|
|
3008
|
-
type CustomPromise<onSuccess,onError=any>={catch<TResult=never>(onrejected?:((reason:onError)=>TResult|PromiseLike<TResult>)|undefined|null):Promise<onSuccess|TResult>;}& Promise<onSuccess>;
|
|
3009
2782
|
/** -------------------------------------------------------
|
|
3010
|
-
* * ***ReadonlyOnly
|
|
2783
|
+
* * ***Utility Type: `ReadonlyOnly`.***
|
|
3011
2784
|
* -------------------------------------------------------
|
|
3012
|
-
*
|
|
3013
|
-
*
|
|
3014
|
-
* while leaving the other properties mutable.
|
|
3015
|
-
*
|
|
2785
|
+
* **Makes the specified keys `K` of an object type `T` readonly,
|
|
2786
|
+
* while leaving the other properties mutable.**
|
|
3016
2787
|
* @template T - The object type.
|
|
3017
2788
|
* @template K - Keys of `T` to make readonly.
|
|
3018
|
-
*
|
|
3019
2789
|
* @example
|
|
3020
2790
|
* ```ts
|
|
3021
2791
|
* type T0 = ReadonlyOnly<{ a: string; b: number }, 'a'>;
|
|
@@ -3027,15 +2797,12 @@ type CustomPromise<onSuccess,onError=any>={catch<TResult=never>(onrejected?:((re
|
|
|
3027
2797
|
*/
|
|
3028
2798
|
type ReadonlyOnly<T extends object,K extends keyof T>=Prettify<Pick<T,Exclude<keyof T,K>>&{readonly [P in K]:T[P];}>;
|
|
3029
2799
|
/** -------------------------------------------------------
|
|
3030
|
-
* * ***ReadonlyExcept
|
|
2800
|
+
* * ***Utility Type: `ReadonlyExcept`.***
|
|
3031
2801
|
* -------------------------------------------------------
|
|
3032
|
-
*
|
|
3033
|
-
*
|
|
3034
|
-
* except for the specified keys `K` which remain mutable.
|
|
3035
|
-
*
|
|
2802
|
+
* **Makes all properties of an object type `T` readonly,
|
|
2803
|
+
* except for the specified keys `K` which remain mutable.**
|
|
3036
2804
|
* @template T - The object type.
|
|
3037
2805
|
* @template K - Keys of `T` to remain mutable.
|
|
3038
|
-
*
|
|
3039
2806
|
* @example
|
|
3040
2807
|
* ```ts
|
|
3041
2808
|
* type T0 = ReadonlyExcept<{ a: string; b: number }, 'a'>;
|
|
@@ -3047,14 +2814,11 @@ type ReadonlyOnly<T extends object,K extends keyof T>=Prettify<Pick<T,Exclude<ke
|
|
|
3047
2814
|
*/
|
|
3048
2815
|
type ReadonlyExcept<T extends object,K extends keyof T>=Prettify<Pick<T,K>&{readonly [P in Exclude<keyof T,K>]:T[P];}>;
|
|
3049
2816
|
/** -------------------------------------------------------
|
|
3050
|
-
* * ***RemoveIndexSignature
|
|
2817
|
+
* * ***Utility Type: `RemoveIndexSignature`.***
|
|
3051
2818
|
* -------------------------------------------------------
|
|
3052
|
-
*
|
|
3053
|
-
*
|
|
3054
|
-
* leaving only explicitly declared properties.
|
|
3055
|
-
*
|
|
2819
|
+
* **Removes **index signatures** (e.g., `[key: string]: any`) from an object
|
|
2820
|
+
* type `T`, leaving only explicitly declared properties.**
|
|
3056
2821
|
* @template T - The object type to process.
|
|
3057
|
-
*
|
|
3058
2822
|
* @example
|
|
3059
2823
|
* ```ts
|
|
3060
2824
|
* type Case1 = RemoveIndexSignature<{ [key: string]: number | string; a: string }>;
|
|
@@ -3069,44 +2833,35 @@ type ReadonlyExcept<T extends object,K extends keyof T>=Prettify<Pick<T,K>&{read
|
|
|
3069
2833
|
*/
|
|
3070
2834
|
type RemoveIndexSignature<T>={[Key in keyof T as Key extends`${infer _}`?Key:never]:T[Key];};
|
|
3071
2835
|
/** -------------------------------------------------------
|
|
3072
|
-
* * ***Replace
|
|
2836
|
+
* * ***Utility Type: `Replace`.***
|
|
3073
2837
|
* -------------------------------------------------------
|
|
3074
|
-
*
|
|
3075
|
-
*
|
|
3076
|
-
* inside a string (`T`) with another substring (`ReplaceBy`).
|
|
3077
|
-
*
|
|
2838
|
+
* **Replaces the **first occurrence** of a substring (`Pivot`)
|
|
2839
|
+
* inside a string (`T`) with another substring (`ReplaceBy`).**
|
|
3078
2840
|
* @template T - The source string.
|
|
3079
2841
|
* @template Pivot - The substring to replace.
|
|
3080
2842
|
* @template ReplaceBy - The substring that replaces `Pivot`.
|
|
3081
|
-
*
|
|
3082
2843
|
* @example
|
|
3083
2844
|
* ```ts
|
|
3084
2845
|
* type Case1 = Replace<'remove me me', 'me', 'him'>;
|
|
3085
2846
|
* // ➔ 'remove him me'
|
|
3086
|
-
*
|
|
3087
2847
|
* type Case2 = Replace<'remove me me', 'us', 'him'>;
|
|
3088
2848
|
* // ➔ 'remove me me'
|
|
3089
|
-
*
|
|
3090
2849
|
* type Case3 = Replace<'aaaa', 'a', 'b'>;
|
|
3091
2850
|
* // ➔ 'baaa'
|
|
3092
|
-
*
|
|
3093
2851
|
* type Case4 = Replace<'hello', 'x', 'y'>;
|
|
3094
2852
|
* // ➔ 'hello' (no match found)
|
|
3095
2853
|
* ```
|
|
3096
2854
|
*/
|
|
3097
2855
|
type Replace<T extends string,Pivot extends string,ReplaceBy extends string>=T extends`${infer A}${Pivot}${infer B}`?`${A}${ReplaceBy}${B}`:T;
|
|
3098
2856
|
/** --------------------------------------------------
|
|
3099
|
-
* * ***ReplaceToPartial
|
|
2857
|
+
* * ***Utility Type: `ReplaceToPartial`.***
|
|
3100
2858
|
* --------------------------------------------------
|
|
3101
|
-
* Replaces specified keys in a type with a new value type, making them optional
|
|
3102
|
-
*
|
|
3103
|
-
*
|
|
3104
|
-
* while keeping the rest of the structure intact.
|
|
3105
|
-
*
|
|
2859
|
+
* **Replaces specified keys in a type with a new value type, making them optional.**
|
|
2860
|
+
* - ✅ Useful when certain properties in a type should allow partial overrides
|
|
2861
|
+
* while keeping the rest of the structure intact.
|
|
3106
2862
|
* @template TypeToBeChecked - The original object type.
|
|
3107
2863
|
* @template KeyToBeReplaced - The keys in the original type to be replaced.
|
|
3108
2864
|
* @template NewValueToUse - The new type to assign to the replaced keys.
|
|
3109
|
-
*
|
|
3110
2865
|
* @example
|
|
3111
2866
|
* ```ts
|
|
3112
2867
|
* type A = { name: string; age: number };
|
|
@@ -3116,19 +2871,16 @@ type Replace<T extends string,Pivot extends string,ReplaceBy extends string>=T e
|
|
|
3116
2871
|
*/
|
|
3117
2872
|
type ReplaceToPartial<TypeToBeChecked,KeyToBeReplaced extends keyof TypeToBeChecked,NewValueToUse>=Identity<Pick<TypeToBeChecked,Exclude<keyof TypeToBeChecked,KeyToBeReplaced>>&{[P in KeyToBeReplaced]?:NewValueToUse;}>;
|
|
3118
2873
|
/** --------------------------------------------------
|
|
3119
|
-
* * ***ReplaceToRequired
|
|
2874
|
+
* * ***Utility Type: `ReplaceToRequired`.***
|
|
3120
2875
|
* --------------------------------------------------
|
|
3121
|
-
* Replaces specified keys in a type with a new value type, making them required
|
|
3122
|
-
*
|
|
3123
|
-
* ✅ Useful when redefining a property’s type while ensuring it's required.
|
|
3124
|
-
*
|
|
2876
|
+
* **Replaces specified keys in a type with a new value type, making them required.**
|
|
2877
|
+
* - ✅ Useful when redefining a property’s type while ensuring it's required.
|
|
3125
2878
|
* @template TypeToBeChecked - The original object type.
|
|
3126
2879
|
* @template KeyToBeReplaced - The keys in the original type to be replaced.
|
|
3127
2880
|
* @template NewValueToUse - The new type to assign to the replaced keys.
|
|
3128
|
-
*
|
|
3129
2881
|
* @example
|
|
3130
2882
|
* ```ts
|
|
3131
|
-
* type A = { name?: string|string[]; age: number };
|
|
2883
|
+
* type A = { name?: string | string[]; age: number };
|
|
3132
2884
|
* type B = ReplaceToRequired<A, 'name', string>;
|
|
3133
2885
|
* // ➔ { name: string; age: number }
|
|
3134
2886
|
* ```
|
|
@@ -3139,13 +2891,11 @@ type ReplaceToRequired<TypeToBeChecked,KeyToBeReplaced extends keyof TypeToBeChe
|
|
|
3139
2891
|
/** Remove duplicate `undefined` from a type */
|
|
3140
2892
|
type CleanOptional<T>=[T] extends [undefined]?undefined:T;
|
|
3141
2893
|
/** -------------------------------------------------------
|
|
3142
|
-
* * ***RequiredOnly
|
|
2894
|
+
* * ***Utility Type: `RequiredOnly`.***
|
|
3143
2895
|
* -------------------------------------------------------
|
|
3144
|
-
* Make only the specified properties in `T` **required**, while keeping the rest unchanged (remain optional if optional)
|
|
3145
|
-
*
|
|
2896
|
+
* **Make only the specified properties in `T` **required**, while keeping the rest unchanged (remain optional if optional).**
|
|
3146
2897
|
* @template T - The object type to transform.
|
|
3147
2898
|
* @template K - Keys of `T` that should become required.
|
|
3148
|
-
*
|
|
3149
2899
|
* @example
|
|
3150
2900
|
* ```ts
|
|
3151
2901
|
* // Only "a" is required, "b" and "c" remain optional
|
|
@@ -3171,13 +2921,11 @@ type CleanOptional<T>=[T] extends [undefined]?undefined:T;
|
|
|
3171
2921
|
*/
|
|
3172
2922
|
type RequiredOnly<T extends object,K extends keyof T|AnyString>=IsNever<K>extends true?T:PrettifyUnionIntersection<{[P in Exclude<keyof T,K>]?:CleanOptional<T[P]>;}&{[P in Extract<keyof T,K>]-?:NonUndefined<CleanOptional<T[P]>>;}>;
|
|
3173
2923
|
/** -------------------------------------------------------
|
|
3174
|
-
* * ***RequiredExcept
|
|
2924
|
+
* * ***Utility Type: `RequiredExcept`.***
|
|
3175
2925
|
* -------------------------------------------------------
|
|
3176
|
-
* Make **all properties** in `T` required, except the specified keys which remain optional
|
|
3177
|
-
*
|
|
2926
|
+
* **Make **all properties** in `T` required, except the specified keys which remain optional.**
|
|
3178
2927
|
* @template T - The object type to transform.
|
|
3179
2928
|
* @template K - Keys of `T` that should remain optional.
|
|
3180
|
-
*
|
|
3181
2929
|
* @example
|
|
3182
2930
|
* ```ts
|
|
3183
2931
|
* // All required except "a"
|
|
@@ -3204,24 +2952,21 @@ type RequiredOnly<T extends object,K extends keyof T|AnyString>=IsNever<K>extend
|
|
|
3204
2952
|
*/
|
|
3205
2953
|
type RequiredExcept<T extends object,K extends keyof T|AnyString>=IsNever<K>extends true?Required<T>:PrettifyUnionIntersection<{[P in Exclude<keyof T,K>]-?:NonUndefined<CleanOptional<T[P]>>;}&{[P in Extract<keyof T,K>]?:CleanOptional<T[P]>;}>;type _Reverse<T extends readonly unknown[],Result extends readonly unknown[]=[]>=T extends readonly [infer First,...infer Rest]?_Reverse<Rest,[First,...Result]>:Result;type FilterByType$1<T extends readonly unknown[],U>=T extends readonly [ infer Head,...infer Tail]?Head extends U?[Head,...FilterByType$1<Tail,U>]:FilterByType$1<Tail,U>:[];type Grouped<T extends readonly unknown[]>=[ ...FilterByType$1<T,number>,...FilterByType$1<T,string>,...FilterByType$1<T,boolean>,...FilterByType$1<T,Exclude<T[number],number|string|boolean>>];type MaybeReadonly<T extends readonly unknown[],R extends readonly unknown[]>=IsTuple<T>extends true?(IsReadonlyArray<T>extends true?Readonly<R>:R):R;
|
|
3206
2954
|
/** -------------------------------------------------------
|
|
3207
|
-
* * ***Reverse
|
|
3208
|
-
* -------------------------------------------------------
|
|
3209
|
-
* Returns a new tuple or readonly array type with the elements in reverse order
|
|
3210
|
-
*
|
|
3211
|
-
*
|
|
3212
|
-
*
|
|
3213
|
-
*
|
|
3214
|
-
*
|
|
3215
|
-
*
|
|
3216
|
-
*
|
|
3217
|
-
*
|
|
3218
|
-
*
|
|
3219
|
-
*
|
|
3220
|
-
*
|
|
3221
|
-
* while other types remain at the end in their original order before reverse.
|
|
3222
|
-
*
|
|
2955
|
+
* * ***Utility Type: `Reverse`.***
|
|
2956
|
+
* -------------------------------------------------------
|
|
2957
|
+
* **Returns a new tuple or readonly array type with the elements in reverse order.**
|
|
2958
|
+
* - **Behavior:**
|
|
2959
|
+
* 1. **Tuple**: The reversed result preserves tuple properties,
|
|
2960
|
+
* including `readonly` if applicable.
|
|
2961
|
+
* - Elements are **grouped in this order before reversing**:
|
|
2962
|
+
* `number`, `string`, `boolean`, then any other types.
|
|
2963
|
+
* 2. **Normal array (non-tuple)**: The type is returned as-is (no reversal).
|
|
2964
|
+
* - ℹ️ **Notes:**
|
|
2965
|
+
* - Supports arbitrary types in the tuple, including objects, Date, symbol, etc.
|
|
2966
|
+
* - Grouping ensures that numbers, strings, and booleans are reversed in logical
|
|
2967
|
+
* groups, while other types remain at the end in their original order before
|
|
2968
|
+
* reverse.
|
|
3223
2969
|
* @template T - The array or tuple type to reverse.
|
|
3224
|
-
*
|
|
3225
2970
|
* @example
|
|
3226
2971
|
* ```ts
|
|
3227
2972
|
* // Mutable tuple of numbers
|
|
@@ -3275,19 +3020,16 @@ type RequiredExcept<T extends object,K extends keyof T|AnyString>=IsNever<K>exte
|
|
|
3275
3020
|
*/
|
|
3276
3021
|
type Reverse<T extends readonly unknown[]>=T extends readonly [ unknown,...unknown[]]?_Reverse<Grouped<T>>extends infer R extends readonly unknown[]?MaybeReadonly<T,R>:never:T;
|
|
3277
3022
|
/** -------------------------------------------------------
|
|
3278
|
-
* * ***Round
|
|
3023
|
+
* * ***Utility Type: `Round`.***
|
|
3279
3024
|
* -------------------------------------------------------
|
|
3280
|
-
* Type-level version of `Math.round()`.
|
|
3281
|
-
* Returns the value of a number rounded to the **nearest integer
|
|
3282
|
-
*
|
|
3283
|
-
*
|
|
3284
|
-
*
|
|
3285
|
-
*
|
|
3286
|
-
*
|
|
3287
|
-
* - If `T` is already an integer, it returns `T` as-is.
|
|
3288
|
-
*
|
|
3025
|
+
* **Type-level version of `Math.round()`.
|
|
3026
|
+
* Returns the value of a number rounded to the **nearest integer**.**
|
|
3027
|
+
* - **Behavior:**
|
|
3028
|
+
* - If `T` is a float, it rounds to the nearest whole number:
|
|
3029
|
+
* - Fraction `≥ 0.5` ➔ rounds up.
|
|
3030
|
+
* - Fraction `< 0.5` ➔ rounds down.
|
|
3031
|
+
* - If `T` is already an integer, it returns `T` as-is.
|
|
3289
3032
|
* @template T - The number type to round.
|
|
3290
|
-
*
|
|
3291
3033
|
* @example
|
|
3292
3034
|
* ```ts
|
|
3293
3035
|
* // Positive float
|
|
@@ -3309,22 +3051,20 @@ type Reverse<T extends readonly unknown[]>=T extends readonly [ unknown,...unkno
|
|
|
3309
3051
|
*/
|
|
3310
3052
|
type Round<T extends number>=IsFloat<T>extends true?GetFloatNumberParts<T>extends [ infer Whole extends number,infer Fraction extends number]?IsGreaterThan<FirstDigit<Fraction>,4>extends true?Increment<Whole>:Whole:never:T;type SliceRemovedItemValue=Record<"__type-rzl_internal__",symbol>;type FilterRemoved<T extends readonly unknown[],Result extends unknown[]=[]>=T extends readonly [infer First,...infer Rest extends unknown[]]?FilterRemoved<Rest,First extends SliceRemovedItemValue?Result:Push<Result,First>>:Result;
|
|
3311
3053
|
/** -------------------------------------------------------
|
|
3312
|
-
* * ***Slice
|
|
3054
|
+
* * ***Utility Type: `Slice`.***
|
|
3313
3055
|
* -------------------------------------------------------
|
|
3314
|
-
* Type-level version of `Array.prototype.slice()
|
|
3056
|
+
* **Type-level version of `Array.prototype.slice()`.**
|
|
3057
|
+
* @description
|
|
3315
3058
|
* Returns a shallow copy of a portion of an array, selected from `Start` to `End` (not including `End`).
|
|
3316
|
-
*
|
|
3317
|
-
*
|
|
3318
|
-
*
|
|
3319
|
-
*
|
|
3320
|
-
*
|
|
3321
|
-
*
|
|
3322
|
-
* - If the full range is selected, returns `T` as-is.
|
|
3323
|
-
*
|
|
3059
|
+
* - **Behavior:**
|
|
3060
|
+
* - `Start` defaults to `0`.
|
|
3061
|
+
* - `End` defaults to `T["length"]`.
|
|
3062
|
+
* - Negative indices are interpreted as `T["length"] + index`.
|
|
3063
|
+
* - If `Start >= T["length"]` or `End <= Start`, returns an empty array `[]`.
|
|
3064
|
+
* - If the full range is selected, returns `T` as-is.
|
|
3324
3065
|
* @template T - The array type to slice.
|
|
3325
3066
|
* @template Start - The start index (inclusive). Defaults to `0`.
|
|
3326
3067
|
* @template End - The end index (exclusive). Defaults to `T["length"]`.
|
|
3327
|
-
*
|
|
3328
3068
|
* @example
|
|
3329
3069
|
* ```ts
|
|
3330
3070
|
* // Slice from index 1 to end
|
|
@@ -3354,19 +3094,16 @@ type Round<T extends number>=IsFloat<T>extends true?GetFloatNumberParts<T>extend
|
|
|
3354
3094
|
*/
|
|
3355
3095
|
type Slice<T extends readonly unknown[],Start extends number=0,End extends number=T["length"]>=(IsEmptyArray<T>extends true?"self":IsGreaterOrEqual<Start,T["length"]>extends true?"empty":IsNegative<End>extends true?IsGreaterOrEqual<Abs<End>,T["length"]>extends true?"empty":[IfPositive<Start,Start,Sum<T["length"],Start>>,Sum<T["length"],End>]:And<Or<IsEqual<Start,0>,IsGreaterOrEqual<Abs<Start>,T["length"]>>,IsGreaterOrEqual<End,T["length"]>>extends true?"self":[IfPositive<Start,Start,Sum<T["length"],Start>>,End])extends infer Indexes?Indexes extends"self"?T:Indexes extends"empty"?[]:Indexes extends [infer NewStart extends number,infer NewEnd extends number]?IfGreaterOrEqual<NewStart,NewEnd>extends true?[]:FilterRemoved<{[K in keyof T]:IsArrayIndex<K>extends true?If<And<IsGreaterOrEqual<ParseNumber<K>,NewStart>,IsLowerThan<ParseNumber<K>,NewEnd>>,T[K],SliceRemovedItemValue>:T[K];}>:T:T;
|
|
3356
3096
|
/** -------------------------------------------------------
|
|
3357
|
-
* * ***Swap
|
|
3097
|
+
* * ***Utility Type: `Swap`.***
|
|
3358
3098
|
* -------------------------------------------------------
|
|
3359
|
-
* Swaps the positions of two elements in a tuple at the type level
|
|
3360
|
-
*
|
|
3361
|
-
*
|
|
3362
|
-
*
|
|
3363
|
-
*
|
|
3364
|
-
* - If `FromIndex` and `ToIndex` are equal, the tuple remains unchanged.
|
|
3365
|
-
*
|
|
3099
|
+
* **Swaps the positions of two elements in a tuple at the type level.**
|
|
3100
|
+
* - **Behavior:**
|
|
3101
|
+
* - Only works on tuple types. Non-tuple arrays are returned as-is.
|
|
3102
|
+
* - Validates that `FromIndex` and `ToIndex` are within bounds of the tuple.
|
|
3103
|
+
* - If `FromIndex` and `ToIndex` are equal, the tuple remains unchanged.
|
|
3366
3104
|
* @template T - The tuple type.
|
|
3367
3105
|
* @template FromIndex - The index of the first element to swap.
|
|
3368
3106
|
* @template ToIndex - The index of the second element to swap.
|
|
3369
|
-
*
|
|
3370
3107
|
* @example
|
|
3371
3108
|
* ```ts
|
|
3372
3109
|
* // Swap first and last element
|
|
@@ -3388,16 +3125,13 @@ type Slice<T extends readonly unknown[],Start extends number=0,End extends numbe
|
|
|
3388
3125
|
*/
|
|
3389
3126
|
type Swap<T extends readonly unknown[],FromIndex extends number,ToIndex extends number>=IsTuple<T>extends true?And<IsBetween<FromIndex,0,T["length"]>,IsBetween<ToIndex,0,T["length"]>>extends true?T[FromIndex] extends infer From?T[ToIndex] extends infer To?{[K in keyof T]:ParseNumber<K>extends infer NumK?IsEqual<FromIndex,NumK>extends true?To:IsEqual<ToIndex,NumK>extends true?From:T[K]:never;}:never:never:never:T;type _SortSingle<Result extends readonly number[],PivotIndex extends number,CurrentIndex extends number>=IsEqual<PivotIndex,CurrentIndex>extends true?Result:Increment<CurrentIndex>extends infer NextCurrentIndex extends number?_SortSingle<IsGreaterThan<Result[CurrentIndex],Result[NextCurrentIndex]>extends true?Swap<Result,CurrentIndex,NextCurrentIndex>extends infer NewResult extends readonly number[]?NewResult:Result:Result,PivotIndex,NextCurrentIndex>:never;type _Sort<T extends readonly number[],CurrentIndex extends number>=IsLowerOrEqual<CurrentIndex,0>extends true?T:_SortSingle<T,CurrentIndex,0>extends infer NewT extends readonly number[]?_Sort<NewT,Decrement<CurrentIndex>>:T;
|
|
3390
3127
|
/** -------------------------------------------------------
|
|
3391
|
-
* * ***Sort
|
|
3128
|
+
* * ***Utility Type: `Sort`.***
|
|
3392
3129
|
* -------------------------------------------------------
|
|
3393
|
-
* Type-level function that sorts a **tuple of numbers** in **ascending order
|
|
3394
|
-
*
|
|
3395
|
-
*
|
|
3396
|
-
*
|
|
3397
|
-
* - Works only on **tuple literal types**, not on general arrays (`number[]`).
|
|
3398
|
-
*
|
|
3130
|
+
* **Type-level function that sorts a **tuple of numbers** in **ascending order**.**
|
|
3131
|
+
* - **Behavior:**
|
|
3132
|
+
* - Tuples with length `< 2` are returned as-is.
|
|
3133
|
+
* - Works only on **tuple literal types**, not on general arrays (`number[]`).
|
|
3399
3134
|
* @template T - Tuple of numbers to sort.
|
|
3400
|
-
*
|
|
3401
3135
|
* @example
|
|
3402
3136
|
* ```ts
|
|
3403
3137
|
* // Sort positive numbers
|
|
@@ -3423,18 +3157,15 @@ type Swap<T extends readonly unknown[],FromIndex extends number,ToIndex extends
|
|
|
3423
3157
|
*/
|
|
3424
3158
|
type Sort<T extends readonly number[]>=IsLowerThan<T["length"],2>extends true?T:_Sort<T,Decrement<T["length"]>>;
|
|
3425
3159
|
/** -------------------------------------------------------
|
|
3426
|
-
* * ***StartsWith
|
|
3160
|
+
* * ***Utility Type: `StartsWith`.***
|
|
3427
3161
|
* -------------------------------------------------------
|
|
3428
|
-
* Type-level utility that determines whether a string `Str`
|
|
3429
|
-
* starts with the substring `Pivot
|
|
3430
|
-
*
|
|
3431
|
-
*
|
|
3432
|
-
*
|
|
3433
|
-
* - Returns `true` if `Str` starts with `Pivot`, otherwise `false`.
|
|
3434
|
-
*
|
|
3162
|
+
* **Type-level utility that determines whether a string `Str`
|
|
3163
|
+
* starts with the substring `Pivot`.**
|
|
3164
|
+
* - **Behavior:**
|
|
3165
|
+
* - Supports `Pivot` as either `string` or `number`.
|
|
3166
|
+
* - Returns `true` if `Str` starts with `Pivot`, otherwise `false`.
|
|
3435
3167
|
* @template Str - The string to check.
|
|
3436
3168
|
* @template Pivot - The substring or number to check as the prefix.
|
|
3437
|
-
*
|
|
3438
3169
|
* @example
|
|
3439
3170
|
* ```ts
|
|
3440
3171
|
* // Check string prefix
|
|
@@ -3461,28 +3192,25 @@ type Sort<T extends readonly number[]>=IsLowerThan<T["length"],2>extends true?T:
|
|
|
3461
3192
|
*/
|
|
3462
3193
|
type StartsWith<Str extends string,Pivot extends string|number>=Str extends`${Pivot}${string}`?true:false;
|
|
3463
3194
|
/** -------------------------------------------------------
|
|
3464
|
-
* * ***Switch
|
|
3195
|
+
* * ***Utility Type: `Switch`.***
|
|
3465
3196
|
* -------------------------------------------------------
|
|
3466
|
-
* Type-level version of a `switch` statement
|
|
3467
|
-
*
|
|
3468
|
-
*
|
|
3469
|
-
*
|
|
3470
|
-
*
|
|
3471
|
-
* - Returns `Default` if the key does not exist.
|
|
3472
|
-
*
|
|
3197
|
+
* **Type-level version of a `switch` statement.**
|
|
3198
|
+
* - **Behavior:**
|
|
3199
|
+
* - Checks if `Condition` exists as a key in `Cases`.
|
|
3200
|
+
* - Returns the corresponding value if the key exists.
|
|
3201
|
+
* - Returns `Default` if the key does not exist.
|
|
3473
3202
|
* @template Condition - The value to match against case keys.
|
|
3474
3203
|
* @template Cases - An object mapping keys to corresponding values.
|
|
3475
3204
|
* @template Default - The default value returned if `Condition` is not a key in `Cases` (defaults to `never`).
|
|
3476
|
-
*
|
|
3477
3205
|
* @example
|
|
3478
3206
|
* ```ts
|
|
3479
3207
|
* const a = 'const';
|
|
3480
3208
|
*
|
|
3481
|
-
* // Matches 'const' key
|
|
3209
|
+
* // Matches 'const' key ➔ 'bar'
|
|
3482
3210
|
* type Result1 = Switch<typeof a, { number: 'foo', const: 'bar' }, 'foobar'>;
|
|
3483
3211
|
* // ➔ 'bar'
|
|
3484
3212
|
*
|
|
3485
|
-
* // Condition not present
|
|
3213
|
+
* // Condition not present ➔ returns default
|
|
3486
3214
|
* type Result2 = Switch<'other', { number: 'foo', const: 'bar' }, 'default'>;
|
|
3487
3215
|
* // ➔ 'default'
|
|
3488
3216
|
*
|
|
@@ -3493,22 +3221,19 @@ type StartsWith<Str extends string,Pivot extends string|number>=Str extends`${Pi
|
|
|
3493
3221
|
*/
|
|
3494
3222
|
type Switch<Condition extends PropertyKey,Cases extends Record<PropertyKey,unknown>,Default=never>=Condition extends keyof Cases?Cases[Condition]:Default;
|
|
3495
3223
|
/** -------------------------------------------------------
|
|
3496
|
-
* * ***ToPrimitive
|
|
3497
|
-
* -------------------------------------------------------
|
|
3498
|
-
* Converts a literal type to its corresponding primitive type
|
|
3499
|
-
*
|
|
3500
|
-
*
|
|
3501
|
-
*
|
|
3502
|
-
*
|
|
3503
|
-
*
|
|
3504
|
-
*
|
|
3505
|
-
*
|
|
3506
|
-
*
|
|
3507
|
-
*
|
|
3508
|
-
* - Objects → recursively converts all properties to their primitive types
|
|
3509
|
-
*
|
|
3224
|
+
* * ***Utility Type: `ToPrimitive`.***
|
|
3225
|
+
* -------------------------------------------------------
|
|
3226
|
+
* **Converts a literal type to its corresponding primitive type.**
|
|
3227
|
+
* - **Behavior:**
|
|
3228
|
+
* - `string literal` ➔ `string`.
|
|
3229
|
+
* - `number literal` ➔ `number`.
|
|
3230
|
+
* - `boolean literal` ➔ `boolean`.
|
|
3231
|
+
* - `bigint literal` ➔ `bigint`.
|
|
3232
|
+
* - `symbol literal` ➔ `symbol`.
|
|
3233
|
+
* - `null` ➔ `null`.
|
|
3234
|
+
* - `undefined` ➔ `undefined`.
|
|
3235
|
+
* - Objects ➔ recursively converts all properties to their primitive types.
|
|
3510
3236
|
* @template T - The literal type to convert to a primitive type.
|
|
3511
|
-
*
|
|
3512
3237
|
* @example
|
|
3513
3238
|
* ```ts
|
|
3514
3239
|
* // Number literal
|
|
@@ -3544,19 +3269,17 @@ type Switch<Condition extends PropertyKey,Cases extends Record<PropertyKey,unkno
|
|
|
3544
3269
|
*/
|
|
3545
3270
|
type ToPrimitive<T>=T extends string?string:T extends number?number:T extends null?null:T extends undefined?undefined:T extends boolean?boolean:T extends bigint?bigint:T extends symbol?symbol:{[K in keyof T]:ToPrimitive<T[K]>;};
|
|
3546
3271
|
/** -------------------------------------------------------
|
|
3547
|
-
* * ***Trunc
|
|
3272
|
+
* * ***Utility Type: `Trunc`.***
|
|
3548
3273
|
* -------------------------------------------------------
|
|
3549
|
-
* Type version of `Math.trunc()
|
|
3550
|
-
*
|
|
3551
|
-
*
|
|
3552
|
-
* Behavior
|
|
3553
|
-
*
|
|
3554
|
-
*
|
|
3555
|
-
*
|
|
3556
|
-
*
|
|
3557
|
-
*
|
|
3274
|
+
* **Type version of `Math.trunc()`.**
|
|
3275
|
+
* @description
|
|
3276
|
+
* Returns the **integer part** of a number by removing any fractional digits.
|
|
3277
|
+
* - **Behavior:**
|
|
3278
|
+
* - If `T` is a floating-point number, returns the integer part.
|
|
3279
|
+
* - Preserves the sign for negative numbers.
|
|
3280
|
+
* - If `T` is already an integer, returns `T`.
|
|
3281
|
+
* - If `T` is `number` (general type), returns `T`.
|
|
3558
3282
|
* @template T - The number type to truncate.
|
|
3559
|
-
*
|
|
3560
3283
|
* @example
|
|
3561
3284
|
* ```ts
|
|
3562
3285
|
* // Positive float
|
|
@@ -3578,17 +3301,14 @@ type ToPrimitive<T>=T extends string?string:T extends number?number:T extends nu
|
|
|
3578
3301
|
*/
|
|
3579
3302
|
type Trunc<T extends number>=number extends T?T:IsFloat<T>extends true?GetFloatNumberParts<T>[0] extends infer IntegerPart extends number?IsNegative<T>extends true?Negate<IntegerPart>:IntegerPart:never:T;type FilterByType<T extends readonly unknown[],U>=T extends readonly [ infer Head,...infer Tail]?Head extends U?[Head,...FilterByType<Tail,U>]:FilterByType<Tail,U>:[];type GroupedKeys<T extends readonly PropertyKey[]>=[ ...FilterByType<T,symbol>,...FilterByType<T,string>,...FilterByType<T,number>];
|
|
3580
3303
|
/** -------------------------------------------------------
|
|
3581
|
-
* * ***TupleToObject
|
|
3304
|
+
* * ***Utility Type: `TupleToObject`.***
|
|
3582
3305
|
* -------------------------------------------------------
|
|
3583
|
-
* Accepts a tuple of `string`, `number`, or `symbol` and returns an object type
|
|
3584
|
-
* where each key **and its value** are the elements of the tuple
|
|
3585
|
-
*
|
|
3586
|
-
*
|
|
3587
|
-
*
|
|
3588
|
-
* - The resulting object has keys and values identical to the tuple elements.
|
|
3589
|
-
*
|
|
3306
|
+
* **Accepts a tuple of `string`, `number`, or `symbol` and returns an object type
|
|
3307
|
+
* where each key **and its value** are the elements of the tuple.**
|
|
3308
|
+
* - **Behavior:**
|
|
3309
|
+
* - Tuple elements must extend `PropertyKey` (`string | number | symbol`).
|
|
3310
|
+
* - The resulting object has keys and values identical to the tuple elements.
|
|
3590
3311
|
* @template T - The tuple of property keys.
|
|
3591
|
-
*
|
|
3592
3312
|
* @example
|
|
3593
3313
|
* ```ts
|
|
3594
3314
|
* // Tuple of strings
|
|
@@ -3606,13 +3326,11 @@ type Trunc<T extends number>=number extends T?T:IsFloat<T>extends true?GetFloatN
|
|
|
3606
3326
|
*/
|
|
3607
3327
|
type TupleToObject<T extends readonly PropertyKey[]>={[K in GroupedKeys<T>[number]]:K;};
|
|
3608
3328
|
/** -------------------------------------------------------
|
|
3609
|
-
* * ***Unshift
|
|
3329
|
+
* * ***Utility Type: `Unshift`.***
|
|
3610
3330
|
* -------------------------------------------------------
|
|
3611
|
-
* Adds the specified element `U` to the **beginning** of the tuple/array `T
|
|
3612
|
-
*
|
|
3331
|
+
* **Adds the specified element `U` to the **beginning** of the tuple/array `T`.**
|
|
3613
3332
|
* @template T - The original tuple or array.
|
|
3614
3333
|
* @template U - The element to add at the start.
|
|
3615
|
-
*
|
|
3616
3334
|
* @example
|
|
3617
3335
|
* ```ts
|
|
3618
3336
|
* // Adding string to a tuple
|
|
@@ -3624,4 +3342,4 @@ type TupleToObject<T extends readonly PropertyKey[]>={[K in GroupedKeys<T>[numbe
|
|
|
3624
3342
|
* // ➔ [1]
|
|
3625
3343
|
* ```
|
|
3626
3344
|
*/
|
|
3627
|
-
type Unshift<T extends readonly unknown[],U>=[U,...T];export{Abs,And,AndArr,AnyFunction,type AnyRecord,AnyString,type AnyStringRecord,type AreAnagrams,type ArgumentTypes,type ArrayElementType,type
|
|
3345
|
+
type Unshift<T extends readonly unknown[],U>=[U,...T];export{Abs,And,AndArr,AnyFunction,type AnyRecord,AnyString,type AnyStringRecord,type AreAnagrams,type ArgumentTypes,type ArrayElementType,type Ceil,type Color,type ColorCssNamed,type ColorOptions,type CompareNumberLength,type CompareStringLength,type Concat,type Decrement,type DeepMergeArrayUnion,type DefaultColorOptions,type DefaultHSLOptions,type DefaultNumberLengthOptions,type DefaultPathToFieldsOptions,DefaultPrettifyOptions,type DefaultRGBOptions,type DigitsTuple,type Div,type Dot,type DotArray,type EndsWith,type ExcludeStrict,Extends,ExtendsArr,type Factorial,type Fibonacci,type FirstCharacter,type FirstCharacterOptions,type FirstDigit,type Floor,type GetFloatNumberParts,type HEX,type HSL,type HSLOptions,type Identity,If,type IfColor,IfEmptyArray,IfEmptyString,type IfEqual,IfExtends,type IfGreaterOrEqual,type IfGreaterThan,type IfHEX,type IfHSL,type IfLowerOrEqual,type IfLowerThan,IfNegative,IfNever,type IfNotEqual,IfPositive,type IfRGB,type IfTuple,type Includes,type Increment,type IndexOf,IsAny,type IsArrayIndex,type IsBaseType,type IsBetween,type IsBetweenOptions,type IsColor,type IsDivisible,type IsDivisibleByFive,type IsDivisibleByHundred,type IsDivisibleBySix,type IsDivisibleByTen,type IsDivisibleByThree,type IsDivisibleByTwo,IsEmptyArray,IsEmptyString,type IsEqual,IsEven,type IsExactly,IsFloat,type IsGreaterOrEqual,type IsGreaterThan,type IsHEX,type IsHSL,IsInteger,type IsLetter,type IsLongerNumber,type IsLongerString,type IsLowerOrEqual,type IsLowerThan,IsNegative,IsNegativeInteger,IsNever,type IsNotEqual,type IsPalindrome,IsPositive,type IsRGB,IsReadonlyArray,type IsSameLengthNumber,type IsSameLengthString,type IsShorterNumber,type IsShorterString,IsStringLiteral,type IsTuple,type IsUnion,IsUnknown,type Join,type LastCharacter,type LastCharacterOptions,type LooseLiteral,type Max,type MaxArr,type Min,type MinArr,type Mod,type Multi,Negate,type NonNullableObject,type NonNullableObjectExcept,type NonNullableObjectOnly,NonUndefined,Not,NotExtends,type NumberLength,type NumberRangeLimit,Or,OrArr,ParseNumber,type PartialExcept,type PartialOnly,type PathToFields,type PathToFieldsOptions,Pop,type Pow,Prettify,PrettifyOptions,type PrettifyUnionIntersection,Push,type RGB,type RGBOptions,type ReadonlyExcept,type ReadonlyOnly,type RemoveIndexSignature,type RemoveLeading,Repeat,type Replace,type ReplaceAll,type ReplaceToPartial,type ReplaceToRequired,type RequiredExcept,type RequiredOnly,type ReturnItselfIfExtends,type ReturnItselfIfNotExtends,type Reverse,type Round,type Shift,type ShiftOptions,type Slice,type Sort,Split,type StartsWith,type StringLength,type Stringify,type Sub,type Sum,type SumArr,type Swap,type Switch,type ToPrimitive,Trim,type Trunc,type TupleToObject,type TypeNumberLengthOptions,TypedArray,type UnionToIntersection,type UnknownRecord,type Unshift,type ValueOf,type ValueOfArray,type ValueOfExcept,type ValueOfOnly};
|