@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.
Files changed (128) hide show
  1. package/dist/NumberRangeUnion-DC-C3_Kq.d.ts +26 -0
  2. package/dist/any-BmdI8UbK.d.ts +67 -0
  3. package/dist/array-CIZRbqTF.d.ts +223 -0
  4. package/dist/arrays-normalize-recursive-CnjYJ9xg.d.ts +72 -0
  5. package/dist/assertions/index.cjs +1 -0
  6. package/dist/assertions/index.d.ts +428 -0
  7. package/dist/assertions/index.js +1 -0
  8. package/dist/chunk-2TRAPBZ7.cjs +1 -0
  9. package/dist/chunk-3D74QO5D.cjs +1 -0
  10. package/dist/chunk-4DK3RCC4.js +2 -0
  11. package/dist/chunk-4JOQ45HL.js +1 -0
  12. package/dist/chunk-55CZALRS.js +1 -0
  13. package/dist/chunk-56QBKKRE.js +1 -0
  14. package/dist/chunk-5JFV3GDE.cjs +4 -0
  15. package/dist/chunk-5SZUSNGZ.js +1 -0
  16. package/dist/chunk-62HX5Z45.cjs +1 -0
  17. package/dist/chunk-7NA6DUHR.cjs +2 -0
  18. package/dist/chunk-7YWAQOA4.cjs +1 -0
  19. package/dist/chunk-BVPMMWDL.cjs +1 -0
  20. package/dist/chunk-BYZAD3XN.cjs +1 -0
  21. package/dist/chunk-CEFYHEM4.cjs +1 -0
  22. package/dist/chunk-CN53M4QZ.cjs +1 -0
  23. package/dist/chunk-D47MHBSD.cjs +1 -0
  24. package/dist/chunk-DGH75GJD.js +1 -0
  25. package/dist/chunk-E5NUI7PN.js +1 -0
  26. package/dist/chunk-ELDDNERR.js +1 -0
  27. package/dist/chunk-EXZ47NOW.js +1 -0
  28. package/dist/chunk-FDITZ5C6.cjs +1 -0
  29. package/dist/chunk-FF76ISQ2.js +1 -0
  30. package/dist/chunk-FIEZKTAZ.cjs +1 -0
  31. package/dist/chunk-FSSV24W7.cjs +1 -0
  32. package/dist/chunk-G5LXIEFO.js +0 -0
  33. package/dist/chunk-GCGU2WB7.js +1 -0
  34. package/dist/chunk-GECI2YBP.js +1 -0
  35. package/dist/chunk-GQE4OVHC.cjs +1 -0
  36. package/dist/chunk-GRVZXQXL.cjs +1 -0
  37. package/dist/chunk-I4AVNHPA.cjs +1 -0
  38. package/dist/chunk-JFRL7NKU.js +4 -0
  39. package/dist/chunk-JWHM3WZQ.cjs +1 -0
  40. package/dist/chunk-KCQDDZJE.cjs +1 -0
  41. package/dist/chunk-L54ZPSYJ.js +1 -0
  42. package/dist/chunk-LVKAYEZ4.js +1 -0
  43. package/dist/chunk-MBDWTK54.cjs +1 -0
  44. package/dist/chunk-MMSYCIJ2.cjs +1 -0
  45. package/dist/chunk-MNGGDB2G.js +1 -0
  46. package/dist/chunk-MY7BA4GI.cjs +1 -0
  47. package/dist/chunk-N2IJPIND.cjs +1 -0
  48. package/dist/chunk-NIMNTEGV.js +1 -0
  49. package/dist/chunk-NNM7QCNB.js +1 -0
  50. package/dist/chunk-PUQXRLZH.cjs +1 -0
  51. package/dist/chunk-PVJF2JHM.js +1 -0
  52. package/dist/chunk-QCFXEUKL.js +1 -0
  53. package/dist/chunk-QFCGBBSY.js +1 -0
  54. package/dist/chunk-QQYAUPSK.cjs +1 -0
  55. package/dist/chunk-RN3TP3S3.js +1 -0
  56. package/dist/chunk-RV2VULM7.cjs +1 -0
  57. package/dist/chunk-SW6HYEW7.cjs +1 -0
  58. package/dist/chunk-SYJC7UAW.js +1 -0
  59. package/dist/chunk-TC4VBE4Y.cjs +1 -0
  60. package/dist/chunk-TUXDINHF.cjs +1 -0
  61. package/dist/chunk-U5Y2FXMN.cjs +1 -0
  62. package/dist/chunk-UUPQI6ND.cjs +1 -0
  63. package/dist/chunk-VYCGZ2S6.js +1 -0
  64. package/dist/chunk-W5EDKJK3.js +1 -0
  65. package/dist/chunk-WHAVUFEU.js +1 -0
  66. package/dist/chunk-XCFIOTCV.js +1 -0
  67. package/dist/chunk-XE27XPJR.js +1 -0
  68. package/dist/chunk-XH6MCRLP.js +1 -0
  69. package/dist/chunk-XVB3ZZEB.js +1 -0
  70. package/dist/chunk-ZBSIGJFO.cjs +1 -0
  71. package/dist/chunk-ZYAML74V.js +1 -0
  72. package/dist/conversions/index.cjs +1 -0
  73. package/dist/conversions/index.d.ts +1633 -0
  74. package/dist/conversions/index.js +1 -0
  75. package/dist/env/index.cjs +1 -0
  76. package/dist/env/index.d.ts +19 -0
  77. package/dist/env/index.js +1 -0
  78. package/dist/events/index.cjs +1 -0
  79. package/dist/events/index.d.ts +119 -0
  80. package/dist/events/index.js +1 -0
  81. package/dist/extends-Mp81Hq9-.d.ts +145 -0
  82. package/dist/formatting/index.cjs +1 -0
  83. package/dist/formatting/index.d.ts +912 -0
  84. package/dist/formatting/index.js +1 -0
  85. package/dist/generator/index.cjs +1 -0
  86. package/dist/generator/index.d.ts +163 -0
  87. package/dist/generator/index.js +1 -0
  88. package/dist/if-CvT4R7Kh.d.ts +18 -0
  89. package/dist/index.cjs +1 -1
  90. package/dist/index.d.ts +1 -4313
  91. package/dist/index.js +1 -1
  92. package/dist/is-array-Ckm_47hw.d.ts +1557 -0
  93. package/dist/isPlainObject-BKYaI6a8.d.ts +182 -0
  94. package/dist/never-BfayMBF9.d.ts +75 -0
  95. package/dist/next/index.cjs +8 -1
  96. package/dist/next/index.d.ts +169 -169
  97. package/dist/next/index.js +8 -1
  98. package/dist/next/server/index.cjs +2 -1
  99. package/dist/next/server/index.d.ts +37 -37
  100. package/dist/next/server/index.js +2 -1
  101. package/dist/nils-DMz3kU7M.d.ts +177 -0
  102. package/dist/omit-VvmIsZmX.d.ts +28 -0
  103. package/dist/operations/index.cjs +1 -0
  104. package/dist/operations/index.d.ts +182 -0
  105. package/dist/operations/index.js +1 -0
  106. package/dist/parsers/index.cjs +1 -0
  107. package/dist/parsers/index.d.ts +37 -0
  108. package/dist/parsers/index.js +1 -0
  109. package/dist/predicates/index.cjs +1 -0
  110. package/dist/predicates/index.d.ts +1839 -0
  111. package/dist/predicates/index.js +1 -0
  112. package/dist/prettify-C4xLcYOP.d.ts +353 -0
  113. package/dist/promise/index.cjs +1 -0
  114. package/dist/promise/index.d.ts +40 -0
  115. package/dist/promise/index.js +1 -0
  116. package/dist/rzl-utils.global.js +4 -1
  117. package/dist/strings/index.cjs +1 -0
  118. package/dist/strings/index.d.ts +816 -0
  119. package/dist/strings/index.js +1 -0
  120. package/dist/stylings/index.cjs +1 -0
  121. package/dist/stylings/index.d.ts +49 -0
  122. package/dist/stylings/index.js +1 -0
  123. package/dist/type-data-DDs-u2kq.d.ts +261 -0
  124. package/dist/types/index.d.ts +3589 -2090
  125. package/dist/urls/index.cjs +1 -0
  126. package/dist/urls/index.d.ts +418 -0
  127. package/dist/urls/index.js +1 -0
  128. 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": "2.0.1",
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
- "@rollup/plugin-typescript": "^12.1.4",
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.4.5",
37
+ "next": "^15.5.2",
39
38
  "release-please": "^17.1.1",
40
- "rimraf": "^6.0.1",
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
- "type-samurai": "^1.1.1",
47
- "typescript": "^5.8.3",
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
- "barrel": "npx barrelsby --config barrelsby.config.json",
131
- "build": "npm run clean && npm run barrel && tsup && npm run build:types && npm run minify-dist && npm run postbuild",
132
- "build:types": "npm run build:types-dts && npm run build:types:bundle",
133
- "build:types-all": "npm run build:types-dts && npm run build:types:bundle",
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
- "clean": "rimraf dist",
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
  }