@rzl-zone/utils-js 2.0.1 → 3.0.0-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/NumberRangeUnion-DC-C3_Kq.d.ts +26 -0
- package/dist/any-BmdI8UbK.d.ts +67 -0
- package/dist/array-CIZRbqTF.d.ts +223 -0
- package/dist/arrays-normalize-recursive-CnjYJ9xg.d.ts +72 -0
- package/dist/assertions/index.cjs +1 -0
- package/dist/assertions/index.d.ts +428 -0
- package/dist/assertions/index.js +1 -0
- package/dist/chunk-2TRAPBZ7.cjs +1 -0
- package/dist/chunk-3D74QO5D.cjs +1 -0
- package/dist/chunk-4DK3RCC4.js +2 -0
- package/dist/chunk-4JOQ45HL.js +1 -0
- package/dist/chunk-55CZALRS.js +1 -0
- package/dist/chunk-56QBKKRE.js +1 -0
- package/dist/chunk-5JFV3GDE.cjs +4 -0
- package/dist/chunk-5SZUSNGZ.js +1 -0
- package/dist/chunk-62HX5Z45.cjs +1 -0
- package/dist/chunk-7NA6DUHR.cjs +2 -0
- package/dist/chunk-7YWAQOA4.cjs +1 -0
- package/dist/chunk-BVPMMWDL.cjs +1 -0
- package/dist/chunk-BYZAD3XN.cjs +1 -0
- package/dist/chunk-CEFYHEM4.cjs +1 -0
- package/dist/chunk-CN53M4QZ.cjs +1 -0
- package/dist/chunk-D47MHBSD.cjs +1 -0
- package/dist/chunk-DGH75GJD.js +1 -0
- package/dist/chunk-E5NUI7PN.js +1 -0
- package/dist/chunk-ELDDNERR.js +1 -0
- package/dist/chunk-EXZ47NOW.js +1 -0
- package/dist/chunk-FDITZ5C6.cjs +1 -0
- package/dist/chunk-FF76ISQ2.js +1 -0
- package/dist/chunk-FIEZKTAZ.cjs +1 -0
- package/dist/chunk-FSSV24W7.cjs +1 -0
- package/dist/chunk-G5LXIEFO.js +0 -0
- package/dist/chunk-GCGU2WB7.js +1 -0
- package/dist/chunk-GECI2YBP.js +1 -0
- package/dist/chunk-GQE4OVHC.cjs +1 -0
- package/dist/chunk-GRVZXQXL.cjs +1 -0
- package/dist/chunk-I4AVNHPA.cjs +1 -0
- package/dist/chunk-JFRL7NKU.js +4 -0
- package/dist/chunk-JWHM3WZQ.cjs +1 -0
- package/dist/chunk-KCQDDZJE.cjs +1 -0
- package/dist/chunk-L54ZPSYJ.js +1 -0
- package/dist/chunk-LVKAYEZ4.js +1 -0
- package/dist/chunk-MBDWTK54.cjs +1 -0
- package/dist/chunk-MMSYCIJ2.cjs +1 -0
- package/dist/chunk-MNGGDB2G.js +1 -0
- package/dist/chunk-MY7BA4GI.cjs +1 -0
- package/dist/chunk-N2IJPIND.cjs +1 -0
- package/dist/chunk-NIMNTEGV.js +1 -0
- package/dist/chunk-NNM7QCNB.js +1 -0
- package/dist/chunk-PUQXRLZH.cjs +1 -0
- package/dist/chunk-PVJF2JHM.js +1 -0
- package/dist/chunk-QCFXEUKL.js +1 -0
- package/dist/chunk-QFCGBBSY.js +1 -0
- package/dist/chunk-QQYAUPSK.cjs +1 -0
- package/dist/chunk-RN3TP3S3.js +1 -0
- package/dist/chunk-RV2VULM7.cjs +1 -0
- package/dist/chunk-SW6HYEW7.cjs +1 -0
- package/dist/chunk-SYJC7UAW.js +1 -0
- package/dist/chunk-TC4VBE4Y.cjs +1 -0
- package/dist/chunk-TUXDINHF.cjs +1 -0
- package/dist/chunk-U5Y2FXMN.cjs +1 -0
- package/dist/chunk-UUPQI6ND.cjs +1 -0
- package/dist/chunk-VYCGZ2S6.js +1 -0
- package/dist/chunk-W5EDKJK3.js +1 -0
- package/dist/chunk-WHAVUFEU.js +1 -0
- package/dist/chunk-XCFIOTCV.js +1 -0
- package/dist/chunk-XE27XPJR.js +1 -0
- package/dist/chunk-XH6MCRLP.js +1 -0
- package/dist/chunk-XVB3ZZEB.js +1 -0
- package/dist/chunk-ZBSIGJFO.cjs +1 -0
- package/dist/chunk-ZYAML74V.js +1 -0
- package/dist/conversions/index.cjs +1 -0
- package/dist/conversions/index.d.ts +1633 -0
- package/dist/conversions/index.js +1 -0
- package/dist/env/index.cjs +1 -0
- package/dist/env/index.d.ts +19 -0
- package/dist/env/index.js +1 -0
- package/dist/events/index.cjs +1 -0
- package/dist/events/index.d.ts +119 -0
- package/dist/events/index.js +1 -0
- package/dist/extends-Mp81Hq9-.d.ts +145 -0
- package/dist/formatting/index.cjs +1 -0
- package/dist/formatting/index.d.ts +912 -0
- package/dist/formatting/index.js +1 -0
- package/dist/generator/index.cjs +1 -0
- package/dist/generator/index.d.ts +163 -0
- package/dist/generator/index.js +1 -0
- package/dist/if-CvT4R7Kh.d.ts +18 -0
- package/dist/index.cjs +1 -1
- package/dist/index.d.ts +1 -4313
- package/dist/index.js +1 -1
- package/dist/is-array-Ckm_47hw.d.ts +1557 -0
- package/dist/isPlainObject-BKYaI6a8.d.ts +182 -0
- package/dist/never-BfayMBF9.d.ts +75 -0
- package/dist/next/index.cjs +8 -1
- package/dist/next/index.d.ts +169 -169
- package/dist/next/index.js +8 -1
- package/dist/next/server/index.cjs +2 -1
- package/dist/next/server/index.d.ts +37 -37
- package/dist/next/server/index.js +2 -1
- package/dist/nils-DMz3kU7M.d.ts +177 -0
- package/dist/omit-VvmIsZmX.d.ts +28 -0
- package/dist/operations/index.cjs +1 -0
- package/dist/operations/index.d.ts +182 -0
- package/dist/operations/index.js +1 -0
- package/dist/parsers/index.cjs +1 -0
- package/dist/parsers/index.d.ts +37 -0
- package/dist/parsers/index.js +1 -0
- package/dist/predicates/index.cjs +1 -0
- package/dist/predicates/index.d.ts +1839 -0
- package/dist/predicates/index.js +1 -0
- package/dist/prettify-C4xLcYOP.d.ts +353 -0
- package/dist/promise/index.cjs +1 -0
- package/dist/promise/index.d.ts +40 -0
- package/dist/promise/index.js +1 -0
- package/dist/rzl-utils.global.js +4 -1
- package/dist/strings/index.cjs +1 -0
- package/dist/strings/index.d.ts +816 -0
- package/dist/strings/index.js +1 -0
- package/dist/stylings/index.cjs +1 -0
- package/dist/stylings/index.d.ts +49 -0
- package/dist/stylings/index.js +1 -0
- package/dist/type-data-DDs-u2kq.d.ts +261 -0
- package/dist/types/index.d.ts +3589 -2090
- package/dist/urls/index.cjs +1 -0
- package/dist/urls/index.d.ts +418 -0
- package/dist/urls/index.js +1 -0
- package/package.json +147 -21
|
@@ -0,0 +1 @@
|
|
|
1
|
+
'use strict';var chunk3D74QO5D_cjs=require('../chunk-3D74QO5D.cjs');require('../chunk-FIEZKTAZ.cjs'),require('../chunk-TC4VBE4Y.cjs'),require('../chunk-UUPQI6ND.cjs'),require('../chunk-KCQDDZJE.cjs'),require('../chunk-62HX5Z45.cjs'),require('../chunk-FDITZ5C6.cjs');var chunk5JFV3GDE_cjs=require('../chunk-5JFV3GDE.cjs');require('../chunk-N2IJPIND.cjs'),require('../chunk-2TRAPBZ7.cjs'),require('../chunk-PUQXRLZH.cjs'),require('../chunk-U5Y2FXMN.cjs'),require('../chunk-7YWAQOA4.cjs'),require('../chunk-CN53M4QZ.cjs');Object.defineProperty(exports,"constructURL",{enumerable:true,get:function(){return chunk3D74QO5D_cjs.a}});Object.defineProperty(exports,"extractURLs",{enumerable:true,get:function(){return chunk3D74QO5D_cjs.b}});Object.defineProperty(exports,"formatEnvPort",{enumerable:true,get:function(){return chunk5JFV3GDE_cjs.d}});Object.defineProperty(exports,"getFirstPrefixPathname",{enumerable:true,get:function(){return chunk5JFV3GDE_cjs.b}});Object.defineProperty(exports,"getPrefixPathname",{enumerable:true,get:function(){return chunk5JFV3GDE_cjs.a}});Object.defineProperty(exports,"normalizePathname",{enumerable:true,get:function(){return chunk5JFV3GDE_cjs.c}});
|
|
@@ -0,0 +1,418 @@
|
|
|
1
|
+
/** ----------------------------------------------------------
|
|
2
|
+
* * ***Represents a non-empty array of key–value pairs.***
|
|
3
|
+
* ----------------------------------------------------------
|
|
4
|
+
*
|
|
5
|
+
* Type for `queryParams` parameter, the second parameter of **{@link constructURL}**.
|
|
6
|
+
*
|
|
7
|
+
* - Each inner tuple strictly follows the `[string, string | number]` shape.
|
|
8
|
+
* - Ensures the outer array contains **at least one pair** (non-empty).
|
|
9
|
+
* - Commonly used for URL construction parameters,
|
|
10
|
+
* query string segments, or other key–value structured data.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* // ✅ valid usage
|
|
14
|
+
* const params: QueryParamPairs = [
|
|
15
|
+
* ["foo", 1],
|
|
16
|
+
* ["bar", "baz"]
|
|
17
|
+
* ];
|
|
18
|
+
*
|
|
19
|
+
* constructURL("https://example.com", params);
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* // ❌ invalid: must contain at least one item
|
|
23
|
+
* const empty: QueryParamPairs = [];
|
|
24
|
+
*
|
|
25
|
+
* // ❌ invalid: key without value pairs.
|
|
26
|
+
* const empty2: QueryParamPairs = [["key"]];
|
|
27
|
+
*/
|
|
28
|
+
type QueryParamPairs=[[string,string|number],...[string,string|number][]];
|
|
29
|
+
/** ---------------------------------
|
|
30
|
+
* * ***Constructs a valid URL with optional query parameters and allows selective removal of duplicate parameters.***
|
|
31
|
+
* ---------------------------------
|
|
32
|
+
*
|
|
33
|
+
* @param {string | URL} baseUrl
|
|
34
|
+
* The base URL to build upon. Must include protocol (e.g., "https://"),
|
|
35
|
+
* domain, and may include port and existing query parameters.
|
|
36
|
+
*
|
|
37
|
+
* @param {Iterable<[string, string]>|URLSearchParamsIterator<[string, string]>} [queryParams]
|
|
38
|
+
* Additional query parameters to append or overwrite on the URL.
|
|
39
|
+
* Accepts any iterable of key-value pairs (like `new URLSearchParams().entries()` and `[[string, string | number]...]`).
|
|
40
|
+
*
|
|
41
|
+
* @param {string[]} [removeParams]
|
|
42
|
+
* A list of query parameter keys to remove from the final URL,
|
|
43
|
+
* whether they were in the base URL or provided queryParams.
|
|
44
|
+
*
|
|
45
|
+
* @returns {URL}
|
|
46
|
+
* A new URL object representing the constructed URL with merged
|
|
47
|
+
* and cleaned query parameters.
|
|
48
|
+
*
|
|
49
|
+
* @throws {TypeError}
|
|
50
|
+
* Throws if `baseUrl` is not a valid non-empty string or URL object,
|
|
51
|
+
* or if `queryParams` is not iterable, or if `removeParams` is not an array of strings.
|
|
52
|
+
*
|
|
53
|
+
* @example
|
|
54
|
+
* // BASIC USAGE:
|
|
55
|
+
*
|
|
56
|
+
* constructURL("https://example.com/path", new URLSearchParams({ a: "1", b: "2" }).entries());
|
|
57
|
+
* // ➔ URL { href: "https://example.com/path?a=1&b=2", ... }
|
|
58
|
+
*
|
|
59
|
+
* @example
|
|
60
|
+
* // REMOVE PARAMETERS FROM BASE AND ADDED:
|
|
61
|
+
*
|
|
62
|
+
* // with new URLSearchParams({ ... }).entries();
|
|
63
|
+
* constructURL("https://example.com/path?foo=1&bar=2", new URLSearchParams({ bar: "ignored", baz: "3" }).entries(), ["bar"]);
|
|
64
|
+
* // ➔ URL { href: "https://example.com/path?foo=1&baz=3", ... }
|
|
65
|
+
*
|
|
66
|
+
* // with [[string, string | number]...]
|
|
67
|
+
* constructURL("https://example.com/path?foo=1&bar=2", [["bar", "ignored"],["baz", 3]], ["bar"]);
|
|
68
|
+
* // ➔ URL { href: "https://example.com/path?foo=1&baz=3", ... }
|
|
69
|
+
*
|
|
70
|
+
* const params: QueryParamPairs = [
|
|
71
|
+
* ["foo", 1],
|
|
72
|
+
* ["bar", 2],
|
|
73
|
+
* ["baz", 3]
|
|
74
|
+
* ];
|
|
75
|
+
*
|
|
76
|
+
* constructURL("https://example.com", params, ["bar"]);
|
|
77
|
+
* // ➔ URL { href: "https://example.com/?foo=1&baz=3", ... }
|
|
78
|
+
*/
|
|
79
|
+
declare const constructURL:(baseUrl:string|URL,queryParams?:URLSearchParamsIterator<[string,string|number]>|QueryParamPairs,removeParams?:string[])=>URL;
|
|
80
|
+
/** ---------------------------------
|
|
81
|
+
* * ***Extracts all valid URLs from a given string.***
|
|
82
|
+
* ---------------------------------
|
|
83
|
+
*
|
|
84
|
+
* This function scans the input url and returns an array of URLs
|
|
85
|
+
* that match a valid `http` or `https` format.
|
|
86
|
+
*
|
|
87
|
+
* Supports:
|
|
88
|
+
* - Internationalized domain names (IDN), e.g. `https://münich.de`
|
|
89
|
+
* - Unicode & emoji paths, e.g. `https://example.com/🎉/page`
|
|
90
|
+
* - Long URLs with multiple queries & fragments, e.g. `https://example.com/path?foo=1#hash`
|
|
91
|
+
*
|
|
92
|
+
* Ignores:
|
|
93
|
+
* - Non-string inputs
|
|
94
|
+
* - Empty or whitespace-only strings
|
|
95
|
+
* - Non-HTTP(S) protocols (ftp, mailto, etc)
|
|
96
|
+
*
|
|
97
|
+
* @param {string|null|undefined} [url] - The input string containing potential URLs.
|
|
98
|
+
* @returns {string[] | null} An array of extracted URLs or `null` if no URLs are found.
|
|
99
|
+
* @example
|
|
100
|
+
* extractURLs("Visit https://example.com and https://例子.公司");
|
|
101
|
+
* // ➔ ["https://example.com", "https://例子.公司"]
|
|
102
|
+
*
|
|
103
|
+
* @example
|
|
104
|
+
* extractURLs("Here: https://example.com/🎉/page");
|
|
105
|
+
* // ➔ ["https://example.com/🎉/page"]
|
|
106
|
+
*
|
|
107
|
+
* @example
|
|
108
|
+
* extractURLs("ftp://example.com http://example.com");
|
|
109
|
+
* // ➔ ["http://example.com"]
|
|
110
|
+
*/
|
|
111
|
+
declare const extractURLs:(url?:string|null)=>string[]|null;
|
|
112
|
+
/** --------------------------------------------------------
|
|
113
|
+
* * ***Get Prefix from URL with Optional Base or Auto-detection (Supports String or Array of URLs).***
|
|
114
|
+
* --------------------------------------------------------
|
|
115
|
+
*
|
|
116
|
+
* @description
|
|
117
|
+
* This function extracts the prefix from one or more URLs. It can either:
|
|
118
|
+
* - Use a provided `base` string or an array of strings to check and return the matching prefix.
|
|
119
|
+
* - Automatically detect the prefix if no `base` is provided by analyzing the first part of the URL.
|
|
120
|
+
*
|
|
121
|
+
* The function is flexible and can handle both scenarios:
|
|
122
|
+
* 1. **When the base is provided as a single string or an array of strings**: The function will check if the URL starts with one of the provided base(s) and return the matching base.
|
|
123
|
+
* 2. **When the base is not provided**: The function will automatically detect the prefix by splitting the URL or using a regex.
|
|
124
|
+
*
|
|
125
|
+
* **Important Notes**:
|
|
126
|
+
* - If a base (or an array of bases) is provided, the URL must start with one of the given base(s).
|
|
127
|
+
* - If no base is provided, the function will attempt to detect the prefix automatically.
|
|
128
|
+
* - The `url` parameter can be either a string or an array of strings.
|
|
129
|
+
* - Supports deduplication of results (enabled by default).
|
|
130
|
+
* - Automatically returns a single string if only one unique result exists after processing.
|
|
131
|
+
*
|
|
132
|
+
* ---
|
|
133
|
+
*
|
|
134
|
+
* @param {string|string[]} url The full URL(s) from which the prefix should be extracted. Can be a string or an array of strings.
|
|
135
|
+
* @param {string|string[]|null} [base=null] The base URL(s) (e.g., "/settings"). It can be a string, an array of strings, or `null`. If provided, it will be used to check the URL(s). If not provided, the prefix will be auto-detected.
|
|
136
|
+
* @param {{ levels?: number; removeDuplicates?: boolean }} [options] Additional options object:
|
|
137
|
+
* - `levels` (default `1`): The number of segments to include when auto-detecting the prefix (e.g. `/foo/bar` for `levels: 2`).
|
|
138
|
+
* - `removeDuplicates` (default `true`): Whether to remove duplicate prefixes from the final array result.
|
|
139
|
+
*
|
|
140
|
+
* @returns {string|string[]|null}
|
|
141
|
+
* Returns one of:
|
|
142
|
+
* - A single string if only one unique prefix/base is found.
|
|
143
|
+
* - An array of strings if multiple different prefixes/bases are found.
|
|
144
|
+
* - `null` if no matching base is found when using `base`.
|
|
145
|
+
*
|
|
146
|
+
* ---
|
|
147
|
+
*
|
|
148
|
+
* @throws {TypeError}
|
|
149
|
+
* Throws if:
|
|
150
|
+
* - `url` is not a string or an array of strings.
|
|
151
|
+
* - `base` is not a string, array of strings, or `null`.
|
|
152
|
+
* - `options` is not an object.
|
|
153
|
+
* - `levels` is not a number.
|
|
154
|
+
* - `removeDuplicates` is not a boolean.
|
|
155
|
+
*
|
|
156
|
+
* ---
|
|
157
|
+
*
|
|
158
|
+
* #### **🔹 Usage Examples**
|
|
159
|
+
*
|
|
160
|
+
* #### ✅ **Correct Usage (With an Array of URLs and Base)**
|
|
161
|
+
* ```ts
|
|
162
|
+
* const routes = [
|
|
163
|
+
* "/settings/profile",
|
|
164
|
+
* "/settings/password",
|
|
165
|
+
* "/settings/other-path",
|
|
166
|
+
* "/other-path/xyz",
|
|
167
|
+
* ];
|
|
168
|
+
*
|
|
169
|
+
* // With base provided as a string
|
|
170
|
+
* routes.forEach(route => {
|
|
171
|
+
* console.log(getPrefixPathname(route, '/settings'));
|
|
172
|
+
* // ➔ "/settings"
|
|
173
|
+
* });
|
|
174
|
+
*
|
|
175
|
+
* // With base provided as an array
|
|
176
|
+
* routes.forEach(route => {
|
|
177
|
+
* console.log(getPrefixPathname(route, ['/settings', '/admin']));
|
|
178
|
+
* // ➔ "/settings" or "/admin" depending on the current URL.
|
|
179
|
+
* });
|
|
180
|
+
* ```
|
|
181
|
+
*
|
|
182
|
+
* #### ✅ **Correct Usage (With Single URL and Single Base)**
|
|
183
|
+
* ```ts
|
|
184
|
+
* const result = getPrefixPathname("/settings/profile", "/settings");
|
|
185
|
+
* console.log(result); // ➔ "/settings"
|
|
186
|
+
* ```
|
|
187
|
+
*
|
|
188
|
+
* #### ✅ **Correct Usage (With Multiple URLs and Single Base)**
|
|
189
|
+
* ```ts
|
|
190
|
+
* const result = getPrefixPathname(["/settings/profile", "/settings/password"], "/settings");
|
|
191
|
+
* console.log(result); // ➔ "/settings"
|
|
192
|
+
*
|
|
193
|
+
* const result2 = getPrefixPathname(["/settings/profile", "/other/password"], "/other");
|
|
194
|
+
* console.log(result2); // ➔ "/other"
|
|
195
|
+
* ```
|
|
196
|
+
*
|
|
197
|
+
* #### ✅ **Correct Usage (With Multiple URLs and Multiple Bases)**
|
|
198
|
+
* ```ts
|
|
199
|
+
* const result = getPrefixPathname(["/settings/profile", "/admin/password"], ["/settings", "/admin"]);
|
|
200
|
+
* console.log(result); // ➔ ["/settings", "/admin"]
|
|
201
|
+
* ```
|
|
202
|
+
*
|
|
203
|
+
* #### ✅ **Auto-detection of Prefix**
|
|
204
|
+
* ```ts
|
|
205
|
+
* const result = getPrefixPathname("/settings/profile");
|
|
206
|
+
* console.log(result); // ➔ "/settings"
|
|
207
|
+
*
|
|
208
|
+
* const result2 = getPrefixPathname("/settings/profile/info", null, { levels: 2 });
|
|
209
|
+
* console.log(result2); // ➔ "/settings/profile"
|
|
210
|
+
* ```
|
|
211
|
+
*
|
|
212
|
+
* #### ✅ **Multiple URLs with Auto-detection**
|
|
213
|
+
* ```ts
|
|
214
|
+
* const result = getPrefixPathname(["/admin/profile", "/settings/password"]);
|
|
215
|
+
* console.log(result); // ➔ ["/admin", "/settings"]
|
|
216
|
+
* ```
|
|
217
|
+
*
|
|
218
|
+
* #### ✅ **Handling Duplicates**
|
|
219
|
+
* ```ts
|
|
220
|
+
* const result = getPrefixPathname(["/settings/profile", "/settings/password"], "/settings");
|
|
221
|
+
* console.log(result); // ➔ "/settings" (deduped to single string)
|
|
222
|
+
*
|
|
223
|
+
* const result2 = getPrefixPathname(["/settings/profile", "/settings/profile"], "/settings", { removeDuplicates: false });
|
|
224
|
+
* console.log(result2); // ➔ ["/settings", "/settings"]
|
|
225
|
+
* ```
|
|
226
|
+
*
|
|
227
|
+
* #### ❌ **Incorrect Usage (URL Does Not Match Base)**
|
|
228
|
+
* ```ts
|
|
229
|
+
* const result = getPrefixPathname("/other-path/profile", "/settings");
|
|
230
|
+
* console.log(result); // ➔ null
|
|
231
|
+
* ```
|
|
232
|
+
*/
|
|
233
|
+
declare const getPrefixPathname:(url:string|string[],base?:string|string[]|null,options?:{
|
|
234
|
+
/** The number of levels to include in the prefix (default is 1). For example, with `levels = 2`, the function will return the first two parts of the URL. */
|
|
235
|
+
levels?:number;
|
|
236
|
+
/** Whether to remove duplicates from the result if multiple URLs are passed (default is `true`). */
|
|
237
|
+
removeDuplicates?:boolean;})=>string|string[]|null;
|
|
238
|
+
/** --------------------------------------------------------
|
|
239
|
+
* * ***Extract First Valid Prefix from Path Array or String.***
|
|
240
|
+
* --------------------------------------------------------
|
|
241
|
+
*
|
|
242
|
+
* #### 🚀 **Main Purpose:**
|
|
243
|
+
* This function helps extract the first valid URL prefix from various possible inputs.
|
|
244
|
+
* It is especially useful in routing systems, middleware, or frontend apps that
|
|
245
|
+
* need to decide layout, active navigation, or permissions based on the first
|
|
246
|
+
* segment (or prefix) of a pathname.
|
|
247
|
+
*
|
|
248
|
+
* Typical uses include:
|
|
249
|
+
* - Determining which layout to render (e.g., `/admin` vs `/dashboard` vs `/`).
|
|
250
|
+
* - Highlighting the active menu item in a sidebar based on the current URL.
|
|
251
|
+
* - Enforcing route guards or access controls depending on the URL prefix.
|
|
252
|
+
* - Parsing multi-level route prefixes and selecting the most relevant one.
|
|
253
|
+
*
|
|
254
|
+
* ---
|
|
255
|
+
*
|
|
256
|
+
* #### 🔍 Behavior:
|
|
257
|
+
* It works as follows:
|
|
258
|
+
* - If `result` is an array of strings, it normalizes each element and returns
|
|
259
|
+
* the first non-root path (i.e., not just `"/"`). If all items normalize to `"/"`,
|
|
260
|
+
* it returns the `defaultValue` (normalized).
|
|
261
|
+
* - If `result` is a single string, it normalizes it and returns it if valid,
|
|
262
|
+
* otherwise falls back to the normalized `defaultValue`.
|
|
263
|
+
* - If `result` is `null` or `undefined`, it returns the normalized `defaultValue`.
|
|
264
|
+
*
|
|
265
|
+
* ---
|
|
266
|
+
*
|
|
267
|
+
* #### 🔍 Validation & Errors:
|
|
268
|
+
*
|
|
269
|
+
* - Throws a `TypeError` if:
|
|
270
|
+
* - `defaultValue` is not a non-empty string.
|
|
271
|
+
* - `result` is an array that contains non-string elements.
|
|
272
|
+
* - `result` is a value that is neither `string`, `string[]`, nor `null`.
|
|
273
|
+
*
|
|
274
|
+
* ---
|
|
275
|
+
*
|
|
276
|
+
* #### 🛠 Usage Examples:
|
|
277
|
+
*
|
|
278
|
+
* 1. #### For React: *Determining layout*
|
|
279
|
+
* ```ts
|
|
280
|
+
* const prefix = getFirstPrefixPathname(getPrefixPathname("/admin/settings", ["/admin", "/dashboard"]));
|
|
281
|
+
* if (prefix === "/admin") {
|
|
282
|
+
* renderAdminLayout();
|
|
283
|
+
* }
|
|
284
|
+
* ```
|
|
285
|
+
*
|
|
286
|
+
* 2. #### Setting active menu state
|
|
287
|
+
* ```ts
|
|
288
|
+
* const activeSection = getFirstPrefixPathname(["", "/dashboard", "/profile"]);
|
|
289
|
+
* // ➔ "/dashboard"
|
|
290
|
+
* ```
|
|
291
|
+
*
|
|
292
|
+
* 3. #### Providing graceful fallback
|
|
293
|
+
* ```ts
|
|
294
|
+
* const section = getFirstPrefixPathname([], "/home");
|
|
295
|
+
* // ➔ "/home"
|
|
296
|
+
* ```
|
|
297
|
+
* 4. #### ✅ Using with an Array of Pathnames
|
|
298
|
+
* ```ts
|
|
299
|
+
* const result = getPrefixPathname([" ", "/dashboard", "/settings"]);
|
|
300
|
+
* console.log(getFirstPrefixPathname(result));
|
|
301
|
+
* // ➔ "/dashboard"
|
|
302
|
+
* ```
|
|
303
|
+
*
|
|
304
|
+
* 5. #### ✅ Using with Single String:
|
|
305
|
+
* ```ts
|
|
306
|
+
* console.log(getFirstPrefixPathname("/profile/settings"));
|
|
307
|
+
* // ➔ "/profile/settings"
|
|
308
|
+
* console.log(getFirstPrefixPathname(" "));
|
|
309
|
+
* // ➔ "/"
|
|
310
|
+
* ```
|
|
311
|
+
*
|
|
312
|
+
* 6. #### ✅ Fallback to Custom Default:
|
|
313
|
+
* ```ts
|
|
314
|
+
* console.log(getFirstPrefixPathname([" ", ""], "/home"));
|
|
315
|
+
* // ➔ "/home"
|
|
316
|
+
* console.log(getFirstPrefixPathname(null, "/dashboard"));
|
|
317
|
+
* // ➔ "/dashboard"
|
|
318
|
+
* ```
|
|
319
|
+
*
|
|
320
|
+
* 7. #### ✅ Throws on Invalid Input:
|
|
321
|
+
* ```ts
|
|
322
|
+
* getFirstPrefixPathname([1, 2] as any); // ➔ ❌ throws TypeError
|
|
323
|
+
* getFirstPrefixPathname({} as any); // ➔ ❌ throws TypeError
|
|
324
|
+
* getFirstPrefixPathname(null, " "); // ➔ ❌ throws TypeError
|
|
325
|
+
* ```
|
|
326
|
+
*
|
|
327
|
+
* ---
|
|
328
|
+
*
|
|
329
|
+
* @param {string | string[] | null} result
|
|
330
|
+
* The pathname(s) to process, can be:
|
|
331
|
+
* - A string path (e.g. `"/profile"`),
|
|
332
|
+
* - An array of string paths (e.g. `[" ", "/dashboard"]`),
|
|
333
|
+
* - Or `null`.
|
|
334
|
+
*
|
|
335
|
+
* @param {string} [defaultValue="/"]
|
|
336
|
+
* A custom default path to use if `result` is null or no valid prefix is found.
|
|
337
|
+
* - Must be a non-empty string.
|
|
338
|
+
* - Defaults to `"/"`.
|
|
339
|
+
*
|
|
340
|
+
* @returns {string}
|
|
341
|
+
* The first valid normalized pathname, or the normalized default.
|
|
342
|
+
*
|
|
343
|
+
* @throws {TypeError}
|
|
344
|
+
* If `result` is not a valid type, or `defaultValue` is not a non-empty string.
|
|
345
|
+
*/
|
|
346
|
+
declare const getFirstPrefixPathname:(result?:string|string[]|null,defaultValue?:string)=>string;
|
|
347
|
+
/** --------------------------------------------------------
|
|
348
|
+
* * ***Normalizes a given pathname by ensuring consistent formatting.***
|
|
349
|
+
* --------------------------------------------------------
|
|
350
|
+
*
|
|
351
|
+
* @description
|
|
352
|
+
* This function processes and normalizes a given pathname:
|
|
353
|
+
*
|
|
354
|
+
* - If `pathname` is `null`, `undefined`, empty, or only whitespace,
|
|
355
|
+
* the `defaultPath` will be returned instead.
|
|
356
|
+
*
|
|
357
|
+
* - If `pathname` is a full URL (starting with `http://` or `https://`),
|
|
358
|
+
* it extracts and returns the pathname along with any search parameters and hash.
|
|
359
|
+
* Example: `"https://site.com/foo/bar?x=1#sec"` becomes `"/foo/bar?x=1#sec"`.
|
|
360
|
+
*
|
|
361
|
+
* - All spaces inside the pathname are removed.
|
|
362
|
+
*
|
|
363
|
+
* - Multiple consecutive slashes (like `"//"` or `"///"`) are collapsed into a single slash `"/"`.
|
|
364
|
+
*
|
|
365
|
+
* - Ensures the returned string always starts with exactly one `/`.
|
|
366
|
+
*
|
|
367
|
+
* @param {string | null | undefined} pathname - The pathname to normalize.
|
|
368
|
+
* @param {string} [defaultPath="/"] - A fallback value returned if `pathname` is empty or invalid. Must be a non-empty string, default `"/"`.
|
|
369
|
+
*
|
|
370
|
+
* @returns {string} A properly normalized pathname starting with a single `/`,
|
|
371
|
+
* or the `defaultPath` if the input is invalid or empty.
|
|
372
|
+
*
|
|
373
|
+
* @throws {TypeError} If `defaultPath` is not a non-empty string.
|
|
374
|
+
* @throws {NormalizePathnameError} If an unexpected error occurs during normalization (e.g., URL parsing failure).
|
|
375
|
+
*
|
|
376
|
+
* @example
|
|
377
|
+
* normalizePathname(" /foo//bar ");
|
|
378
|
+
* // ➔ "/foo/bar"
|
|
379
|
+
*
|
|
380
|
+
* normalizePathname("https://example.com//path///to/resource?x=1#hash");
|
|
381
|
+
* // ➔ "/path/to/resource?x=1#hash"
|
|
382
|
+
* normalizePathname(" ");
|
|
383
|
+
* // ➔ "/"
|
|
384
|
+
* normalizePathname(null, "/home");
|
|
385
|
+
* // ➔ "/home"
|
|
386
|
+
* normalizePathname("/double//slashes");
|
|
387
|
+
* // ➔ "/double/slashes"
|
|
388
|
+
* normalizePathname(" nested / path / 🚀 ");
|
|
389
|
+
* // ➔ "/nested/path/🚀"
|
|
390
|
+
*/
|
|
391
|
+
declare const normalizePathname:(pathname?:string|null,defaultPath?:string)=>string;
|
|
392
|
+
/** -----------------------------------------------
|
|
393
|
+
* * ***Retrieves and formats an environment port variable.***
|
|
394
|
+
* -----------------------------------------------
|
|
395
|
+
*
|
|
396
|
+
* - Extracts only digits from the input.
|
|
397
|
+
* - If no digits found, returns an empty string.
|
|
398
|
+
* - By default does NOT prefix with a colon.
|
|
399
|
+
* - Use `{ prefixColon: true }` to prefix with a colon.
|
|
400
|
+
*
|
|
401
|
+
* @param envVar The environment variable string.
|
|
402
|
+
* @param options Optional object: `{ prefixColon?: boolean }`.
|
|
403
|
+
* @returns A string like ":8080" or "8080", or "" if no digits.
|
|
404
|
+
*
|
|
405
|
+
* @throws TypeError if `options` is not an object or `prefixColon` is not boolean.
|
|
406
|
+
*
|
|
407
|
+
* @example
|
|
408
|
+
* formatEnvPort("port:8080");
|
|
409
|
+
* // ➔ "8080"
|
|
410
|
+
* formatEnvPort("port:8080", { prefixColon: true });
|
|
411
|
+
* // ➔ ":8080"
|
|
412
|
+
*/
|
|
413
|
+
declare const formatEnvPort:(envVar?:string|null,options?:{
|
|
414
|
+
/** Add prefix with a colon.
|
|
415
|
+
*
|
|
416
|
+
* @default false
|
|
417
|
+
*/
|
|
418
|
+
prefixColon?:boolean;})=>string;export{type QueryParamPairs,constructURL,extractURLs,formatEnvPort,getFirstPrefixPathname,getPrefixPathname,normalizePathname};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export{a as constructURL,b as extractURLs}from'../chunk-L54ZPSYJ.js';import'../chunk-NNM7QCNB.js';import'../chunk-WHAVUFEU.js';import'../chunk-ZYAML74V.js';import'../chunk-W5EDKJK3.js';import'../chunk-QFCGBBSY.js';import'../chunk-4JOQ45HL.js';export{d as formatEnvPort,b as getFirstPrefixPathname,a as getPrefixPathname,c as normalizePathname}from'../chunk-JFRL7NKU.js';import'../chunk-GECI2YBP.js';import'../chunk-NIMNTEGV.js';import'../chunk-ELDDNERR.js';import'../chunk-MNGGDB2G.js';import'../chunk-5SZUSNGZ.js';import'../chunk-XCFIOTCV.js';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rzl-zone/utils-js",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "3.0.0-beta.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"sideEffects": false,
|
|
6
6
|
"engineStrict": true,
|
|
@@ -25,8 +25,7 @@
|
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@eslint/js": "^9.31.0",
|
|
28
|
-
"@
|
|
29
|
-
"@types/node": "^20.19.4",
|
|
28
|
+
"@types/node": "^20.19.11",
|
|
30
29
|
"@types/rollup": "^0.51.4",
|
|
31
30
|
"@vitest/coverage-v8": "^3.2.4",
|
|
32
31
|
"barrelsby": "^2.8.1",
|
|
@@ -35,17 +34,13 @@
|
|
|
35
34
|
"eslint": "^9.31.0",
|
|
36
35
|
"globals": "^16.3.0",
|
|
37
36
|
"jsdom": "^26.1.0",
|
|
38
|
-
"next": "^15.
|
|
37
|
+
"next": "^15.5.2",
|
|
39
38
|
"release-please": "^17.1.1",
|
|
40
|
-
"
|
|
41
|
-
"rollup": "^4.45.1",
|
|
42
|
-
"rollup-plugin-dts": "^6.2.1",
|
|
43
|
-
"rollup-plugin-tsconfig-paths": "^1.5.2",
|
|
39
|
+
"tsc-alias": "^1.8.16",
|
|
44
40
|
"tsup": "^8.5.0",
|
|
45
41
|
"tsx": "^4.20.3",
|
|
46
|
-
"
|
|
47
|
-
"typescript": "^
|
|
48
|
-
"typescript-eslint": "^8.37.0",
|
|
42
|
+
"typescript": "^5.9.2",
|
|
43
|
+
"typescript-eslint": "^8.41.0",
|
|
49
44
|
"vitest": "^3.2.4"
|
|
50
45
|
},
|
|
51
46
|
"engines": {
|
|
@@ -62,6 +57,66 @@
|
|
|
62
57
|
"default": "./dist/index.cjs"
|
|
63
58
|
}
|
|
64
59
|
},
|
|
60
|
+
"./assertions": {
|
|
61
|
+
"import": {
|
|
62
|
+
"types": "./dist/assertions/index.d.ts",
|
|
63
|
+
"default": "./dist/assertions/index.js"
|
|
64
|
+
},
|
|
65
|
+
"require": {
|
|
66
|
+
"types": "./dist/assertions/index.d.ts",
|
|
67
|
+
"default": "./dist/assertions/index.cjs"
|
|
68
|
+
}
|
|
69
|
+
},
|
|
70
|
+
"./conversions": {
|
|
71
|
+
"import": {
|
|
72
|
+
"types": "./dist/conversions/index.d.ts",
|
|
73
|
+
"default": "./dist/conversions/index.js"
|
|
74
|
+
},
|
|
75
|
+
"require": {
|
|
76
|
+
"types": "./dist/conversions/index.d.ts",
|
|
77
|
+
"default": "./dist/conversions/index.cjs"
|
|
78
|
+
}
|
|
79
|
+
},
|
|
80
|
+
"./env": {
|
|
81
|
+
"import": {
|
|
82
|
+
"types": "./dist/env/index.d.ts",
|
|
83
|
+
"default": "./dist/env/index.js"
|
|
84
|
+
},
|
|
85
|
+
"require": {
|
|
86
|
+
"types": "./dist/env/index.d.ts",
|
|
87
|
+
"default": "./dist/env/index.cjs"
|
|
88
|
+
}
|
|
89
|
+
},
|
|
90
|
+
"./events": {
|
|
91
|
+
"import": {
|
|
92
|
+
"types": "./dist/events/index.d.ts",
|
|
93
|
+
"default": "./dist/events/index.js"
|
|
94
|
+
},
|
|
95
|
+
"require": {
|
|
96
|
+
"types": "./dist/events/index.d.ts",
|
|
97
|
+
"default": "./dist/events/index.cjs"
|
|
98
|
+
}
|
|
99
|
+
},
|
|
100
|
+
"./formatting": {
|
|
101
|
+
"import": {
|
|
102
|
+
"types": "./dist/formatting/index.d.ts",
|
|
103
|
+
"default": "./dist/formatting/index.js"
|
|
104
|
+
},
|
|
105
|
+
"require": {
|
|
106
|
+
"types": "./dist/formatting/index.d.ts",
|
|
107
|
+
"default": "./dist/formatting/index.cjs"
|
|
108
|
+
}
|
|
109
|
+
},
|
|
110
|
+
"./generator": {
|
|
111
|
+
"import": {
|
|
112
|
+
"types": "./dist/generator/index.d.ts",
|
|
113
|
+
"default": "./dist/generator/index.js"
|
|
114
|
+
},
|
|
115
|
+
"require": {
|
|
116
|
+
"types": "./dist/generator/index.d.ts",
|
|
117
|
+
"default": "./dist/generator/index.cjs"
|
|
118
|
+
}
|
|
119
|
+
},
|
|
65
120
|
"./next": {
|
|
66
121
|
"import": {
|
|
67
122
|
"types": "./dist/next/index.d.ts",
|
|
@@ -82,6 +137,76 @@
|
|
|
82
137
|
"default": "./dist/next/server/index.cjs"
|
|
83
138
|
}
|
|
84
139
|
},
|
|
140
|
+
"./operations": {
|
|
141
|
+
"import": {
|
|
142
|
+
"types": "./dist/operations/index.d.ts",
|
|
143
|
+
"default": "./dist/operations/index.js"
|
|
144
|
+
},
|
|
145
|
+
"require": {
|
|
146
|
+
"types": "./dist/operations/index.d.ts",
|
|
147
|
+
"default": "./dist/operations/index.cjs"
|
|
148
|
+
}
|
|
149
|
+
},
|
|
150
|
+
"./parsers": {
|
|
151
|
+
"import": {
|
|
152
|
+
"types": "./dist/parsers/index.d.ts",
|
|
153
|
+
"default": "./dist/parsers/index.js"
|
|
154
|
+
},
|
|
155
|
+
"require": {
|
|
156
|
+
"types": "./dist/parsers/index.d.ts",
|
|
157
|
+
"default": "./dist/parsers/index.cjs"
|
|
158
|
+
}
|
|
159
|
+
},
|
|
160
|
+
"./predicates": {
|
|
161
|
+
"import": {
|
|
162
|
+
"types": "./dist/predicates/index.d.ts",
|
|
163
|
+
"default": "./dist/predicates/index.js"
|
|
164
|
+
},
|
|
165
|
+
"require": {
|
|
166
|
+
"types": "./dist/predicates/index.d.ts",
|
|
167
|
+
"default": "./dist/predicates/index.cjs"
|
|
168
|
+
}
|
|
169
|
+
},
|
|
170
|
+
"./promise": {
|
|
171
|
+
"import": {
|
|
172
|
+
"types": "./dist/promise/index.d.ts",
|
|
173
|
+
"default": "./dist/promise/index.js"
|
|
174
|
+
},
|
|
175
|
+
"require": {
|
|
176
|
+
"types": "./dist/promise/index.d.ts",
|
|
177
|
+
"default": "./dist/promise/index.cjs"
|
|
178
|
+
}
|
|
179
|
+
},
|
|
180
|
+
"./strings": {
|
|
181
|
+
"import": {
|
|
182
|
+
"types": "./dist/strings/index.d.ts",
|
|
183
|
+
"default": "./dist/strings/index.js"
|
|
184
|
+
},
|
|
185
|
+
"require": {
|
|
186
|
+
"types": "./dist/strings/index.d.ts",
|
|
187
|
+
"default": "./dist/strings/index.cjs"
|
|
188
|
+
}
|
|
189
|
+
},
|
|
190
|
+
"./stylings": {
|
|
191
|
+
"import": {
|
|
192
|
+
"types": "./dist/stylings/index.d.ts",
|
|
193
|
+
"default": "./dist/stylings/index.js"
|
|
194
|
+
},
|
|
195
|
+
"require": {
|
|
196
|
+
"types": "./dist/stylings/index.d.ts",
|
|
197
|
+
"default": "./dist/stylings/index.cjs"
|
|
198
|
+
}
|
|
199
|
+
},
|
|
200
|
+
"./urls": {
|
|
201
|
+
"import": {
|
|
202
|
+
"types": "./dist/urls/index.d.ts",
|
|
203
|
+
"default": "./dist/urls/index.js"
|
|
204
|
+
},
|
|
205
|
+
"require": {
|
|
206
|
+
"types": "./dist/urls/index.d.ts",
|
|
207
|
+
"default": "./dist/urls/index.cjs"
|
|
208
|
+
}
|
|
209
|
+
},
|
|
85
210
|
"./types": {
|
|
86
211
|
"types": "./dist/types/index.d.ts"
|
|
87
212
|
}
|
|
@@ -127,22 +252,23 @@
|
|
|
127
252
|
"url": "git+https://github.com/rzl-zone/utils-js.git"
|
|
128
253
|
},
|
|
129
254
|
"scripts": {
|
|
130
|
-
"
|
|
131
|
-
"
|
|
132
|
-
"
|
|
133
|
-
"
|
|
134
|
-
"build:types-dts": "dts-bundle-generator --config dts-config.cjs --silent --external-imports next",
|
|
135
|
-
"build:types:bundle": "rollup -c",
|
|
255
|
+
"clean": "del-cli \"dist/*\"",
|
|
256
|
+
"prepublish": "npm run clean",
|
|
257
|
+
"prepare": "npm run build",
|
|
258
|
+
"prepublishOnly": "npm run barrel",
|
|
136
259
|
"check-publish": "npm pack --dry-run",
|
|
137
|
-
"
|
|
260
|
+
"postbuild": "del-cli \"dist/**/*.d.cts\"",
|
|
261
|
+
"barrel:generate": "npx barrelsby --config barrelsby.config.json",
|
|
262
|
+
"barrel": "npm run barrel:generate && npm run barrel:generate && npx tsx scripts/removeBarrelsbyComment.ts ",
|
|
263
|
+
"barrel:remove-comment-dist": "tsx scripts/removeBarrelsbyComment.ts",
|
|
264
|
+
"build": "npm run clean && npm run barrel && tsup && npm run minify-dist && npm run postbuild",
|
|
265
|
+
"build:dts": "tsc -p tsconfig.build.json && tsc-alias",
|
|
266
|
+
"build:types-dts": "dts-bundle-generator --config dts-config.cjs --silent --external-imports next",
|
|
138
267
|
"coverage": "vitest run --coverage",
|
|
139
|
-
"dev": "tsc --watch",
|
|
140
268
|
"format": "prettier --check .",
|
|
141
269
|
"lint": "eslint . --ext .ts,.js",
|
|
142
270
|
"lint:fix": "eslint . --ext .ts,.js --fix",
|
|
143
271
|
"minify-dist": "tsx scripts/minify-dist.ts",
|
|
144
|
-
"postbuild": "del-cli \"dist/**/*.d.cts\"",
|
|
145
|
-
"prepare": "npm run build",
|
|
146
272
|
"release-patch": "npm version patch && git push && git push --tags && npm publish"
|
|
147
273
|
}
|
|
148
274
|
}
|