radashi 12.2.0-beta.cd4d01e → 12.2.0-beta.cf2d48e

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/radashi.d.ts CHANGED
@@ -1,34 +1,86 @@
1
1
  /**
2
2
  * Sort an array without modifying it and return the newly sorted
3
3
  * value. Allows for a string sorting value.
4
+ *
5
+ * @see https://radashi-org.github.io/reference/array/alphabetical
4
6
  */
5
- declare function alphabetical<T>(array: readonly T[], getter: (item: T) => string, dir?: 'asc' | 'desc'): T[];
7
+ declare function alphabetical<T>(array: readonly T[], getter: (item: T) => string, direction?: 'asc' | 'desc'): T[];
6
8
 
7
9
  /**
8
10
  * Go through a list of items, starting with the first item, and
9
11
  * comparing with the second. Keep the one you want then compare that
10
- * to the next item in the list with the same
12
+ * to the next item in the list with the same.
11
13
  *
14
+ * @see https://radashi-org.github.io/reference/array/boil
15
+ * @example
12
16
  * ```ts
13
17
  * boil([1, 2, 3, 0], (a, b) => a > b ? a : b) // 3
14
18
  * ```
15
19
  */
16
20
  declare function boil<T>(array: readonly T[], compareFunc: (a: T, b: T) => T): T | null;
17
21
 
22
+ /**
23
+ * Casts the given value to an array. If the value is already an
24
+ * array, a shallow copy is returned. Otherwise, a new array
25
+ * containing the value is returned.
26
+ *
27
+ * @see https://radashi-org.github.io/reference/array/castArray
28
+ * @example
29
+ * ```ts
30
+ * castArray(1) // => [1]
31
+ * castArray([1, 2]) // => [1, 2]
32
+ * castArray(null) // => [null]
33
+ * castArray(undefined) // => [undefined]
34
+ * ```
35
+ */
36
+ declare function castArray<T>(value: T): CastArray<T>;
37
+ /**
38
+ * The return type of the {@link castArray} function.
39
+ *
40
+ * @see https://radashi-org.github.io/reference/array/castArray
41
+ */
42
+ type CastArray<T> = [T] extends [never] ? never[] : [unknown] extends [T] ? unknown[] : (T extends any ? T extends readonly (infer U)[] ? U[] : never : never) | (Exclude<T, readonly any[]> extends never ? never : Exclude<T, readonly any[]>[]);
43
+
44
+ /**
45
+ * Casts the given value to an array if it's not equal to `null` or
46
+ * `undefined`. If the value is an array, it returns a shallow copy of
47
+ * the array. Otherwise, it returns a new array containing the value.
48
+ *
49
+ * @see https://radashi-org.github.io/reference/array/castArrayIfExists
50
+ * @example
51
+ * ```ts
52
+ * castArrayIfExists(1) // => [1]
53
+ * castArrayIfExists(null) // => null
54
+ * castArrayIfExists(undefined) // => undefined
55
+ * castArrayIfExists([1, 2, 3]) // => [1, 2, 3]
56
+ * ```
57
+ */
58
+ declare function castArrayIfExists<T>(value: T): CastArrayIfExists<T>;
59
+ /**
60
+ * The return type of the {@link castArrayIfExists} function.
61
+ *
62
+ * @see https://radashi-org.github.io/reference/array/castArrayIfExists
63
+ */
64
+ type CastArrayIfExists<T> = [T] extends [never] ? never[] : [unknown] extends [T] ? unknown[] | null | undefined : (T extends any ? T extends readonly (infer U)[] ? U[] : never : never) | (Exclude<T, readonly any[] | null | undefined> extends never ? never : Exclude<T, readonly any[] | null | undefined>[]) | Extract<T, null | undefined>;
65
+
18
66
  /**
19
67
  * Splits a single list into many lists of the desired size.
20
68
  *
69
+ * @see https://radashi-org.github.io/reference/array/cluster
70
+ * @example
21
71
  * ```ts
22
72
  * cluster([1, 2, 3, 4, 5, 6], 2)
23
73
  * // [[1, 2], [3, 4], [5, 6]]
24
74
  * ```
25
75
  */
26
- declare function cluster<T>(list: readonly T[], size?: number): T[][];
76
+ declare function cluster<T>(array: readonly T[], size?: number): T[][];
27
77
 
28
78
  /**
29
79
  * Counts the occurrences of each unique value returned by the `identity`
30
80
  * function when applied to each item in the array.
31
81
  *
82
+ * @see https://radashi-org.github.io/reference/array/counting
83
+ * @example
32
84
  * ```ts
33
85
  * counting([1, 2, 3, 4], (n) => n % 2 === 0 ? 'even' : 'odd')
34
86
  * // { even: 2, odd: 2 }
@@ -40,6 +92,8 @@ declare function counting<T, TId extends string | number | symbol>(array: readon
40
92
  * Returns all items from the first list that do not exist in the
41
93
  * second list.
42
94
  *
95
+ * @see https://radashi-org.github.io/reference/array/diff
96
+ * @example
43
97
  * ```ts
44
98
  * diff([1, 2, 3, 4], [2, 4])
45
99
  * // [1, 3]
@@ -51,8 +105,10 @@ declare function counting<T, TId extends string | number | symbol>(array: readon
51
105
  declare function diff<T>(root: readonly T[], other: readonly T[], identity?: (item: T) => string | number | symbol): T[];
52
106
 
53
107
  /**
54
- * Get the first item in an array or a default value
108
+ * Get the first item in an array or a default value.
55
109
  *
110
+ * @see https://radashi-org.github.io/reference/array/first
111
+ * @example
56
112
  * ```ts
57
113
  * first([1, 2, 3, 4])
58
114
  * // 1
@@ -68,6 +124,8 @@ declare function first<T, U>(array: readonly T[], defaultValue: U): T | U;
68
124
  * Given an array of arrays, returns a single dimensional array with
69
125
  * all items in it.
70
126
  *
127
+ * @see https://radashi-org.github.io/reference/array/flat
128
+ * @example
71
129
  * ```ts
72
130
  * flat([[1, 2], [[3], 4], [5]])
73
131
  * // [1, 2, [3], 4, 5]
@@ -77,8 +135,10 @@ declare function flat<T>(lists: readonly T[][]): T[];
77
135
 
78
136
  /**
79
137
  * Split an array into two array based on a true/false condition
80
- * function
138
+ * function.
81
139
  *
140
+ * @see https://radashi-org.github.io/reference/array/fork
141
+ * @example
82
142
  * ```ts
83
143
  * fork([1, 2, 3, 4], (n) => n % 2 === 0)
84
144
  * // [[2, 4], [1, 3]]
@@ -91,6 +151,8 @@ declare function fork<T>(array: readonly T[], condition: (item: T) => boolean):
91
151
  * where the keys are the group IDs the given `getGroupId` function
92
152
  * produced and the value is an array of each item in that group.
93
153
  *
154
+ * @see https://radashi-org.github.io/reference/array/group
155
+ * @example
94
156
  * ```ts
95
157
  * group([1, 2, 3, 4], (n) => n % 2 === 0 ? 'even' : 'odd')
96
158
  * // { even: [2], odd: [1, 3, 4] }
@@ -103,6 +165,8 @@ declare function group<T, Key extends string | number | symbol>(array: readonly
103
165
  /**
104
166
  * Given two arrays, returns true if any elements intersect.
105
167
  *
168
+ * @see https://radashi-org.github.io/reference/array/intersects
169
+ * @example
106
170
  * ```ts
107
171
  * intersects([1, 2, 3], [4, 5, 6])
108
172
  * // false
@@ -118,8 +182,10 @@ declare function intersects<T, K>(listA: readonly T[], listB: readonly T[], iden
118
182
  * will iterate the function as many times as specified.
119
183
  *
120
184
  * NOTE: This is NOT zero indexed. If you pass count=5 you will get 1,
121
- * 2, 3, 4, 5 iteration in the callback function
185
+ * 2, 3, 4, 5 iteration in the callback function.
122
186
  *
187
+ * @see https://radashi-org.github.io/reference/array/iterate
188
+ * @example
123
189
  * ```ts
124
190
  * iterate(3, (total, i) => total + i, 0)
125
191
  * // 6
@@ -128,8 +194,10 @@ declare function intersects<T, K>(listA: readonly T[], listB: readonly T[], iden
128
194
  declare function iterate<T>(count: number, func: (currentValue: T, iteration: number) => T, initValue: T): T;
129
195
 
130
196
  /**
131
- * Get the last item in an array or a default value
197
+ * Get the last item in an array or a default value.
132
198
  *
199
+ * @see https://radashi-org.github.io/reference/array/last
200
+ * @example
133
201
  * ```ts
134
202
  * last([1, 2, 3, 4])
135
203
  * // 4
@@ -144,6 +212,8 @@ declare function last<T, U>(array: readonly T[], defaultValue: U): T | U;
144
212
  /**
145
213
  * Creates a list of given start, end, value, and step parameters.
146
214
  *
215
+ * @see https://radashi-org.github.io/reference/array/list
216
+ * @example
147
217
  * ```ts
148
218
  * list(3) // 0, 1, 2, 3
149
219
  * list(0, 3) // 0, 1, 2, 3
@@ -158,22 +228,33 @@ declare function last<T, U>(array: readonly T[], defaultValue: U): T | U;
158
228
  declare function list<T = number>(startOrLength: number, end?: number, valueOrMapper?: T | ((i: number) => T), step?: number): T[];
159
229
 
160
230
  /**
161
- * Max gets the greatest value from a list
231
+ * Create a new `Map` instance from an array.
162
232
  *
233
+ * @see https://radashi-org.github.io/reference/array/mapify
234
+ * @example
163
235
  * ```ts
164
- * max([2, 3, 5]) // => 5
165
- * max([{ num: 1 }, { num: 2 }], x => x.num) // => { num: 2 }
236
+ * const array = [
237
+ * { id: 1, name: 'Fred' },
238
+ * { id: 2, name: 'Annie' },
239
+ * ]
240
+ *
241
+ * mapify(
242
+ * array,
243
+ * item => item.id,
244
+ * item => item.name,
245
+ * )
246
+ * // Map(2) { 1 => 'Fred', 2 => 'Annie' }
166
247
  * ```
167
248
  */
168
- declare function max(array: readonly [number, ...number[]]): number;
169
- declare function max(array: readonly number[]): number | null;
170
- declare function max<T>(array: readonly T[], getter: (item: T) => number): T | null;
249
+ declare function mapify<T, Key, Value = T>(array: readonly T[], getKey: (item: T, index: number) => Key, getValue?: (item: T, index: number) => Value): Map<Key, Value>;
171
250
 
172
251
  /**
173
252
  * Given two arrays of the same type, iterate the first list and
174
253
  * replace items matched by the `matcher` function in the first place.
175
254
  * The given arrays are never modified.
176
255
  *
256
+ * @see https://radashi-org.github.io/reference/array/merge
257
+ * @example
177
258
  * ```ts
178
259
  * merge(
179
260
  * [{id: 1}, {id: 2}],
@@ -183,24 +264,14 @@ declare function max<T>(array: readonly T[], getter: (item: T) => number): T | n
183
264
  * // [{id: 1, name: 'John'}, {id: 2}]
184
265
  * ```
185
266
  */
186
- declare function merge<T>(root: readonly T[], others: readonly T[], matcher: (item: T) => any): T[];
187
-
188
- /**
189
- * Min gets the smallest value from a list
190
- *
191
- * ```ts
192
- * min([1, 2, 3, 4]) // => 1
193
- * min([{ num: 1 }, { num: 2 }], x => x.num) // => { num: 1 }
194
- * ```
195
- */
196
- declare function min(array: readonly [number, ...number[]]): number;
197
- declare function min(array: readonly number[]): number | null;
198
- declare function min<T>(array: readonly T[], getter: (item: T) => number): T | null;
267
+ declare function merge<T>(prev: readonly T[], array: readonly T[], toKey: (item: T) => any): T[];
199
268
 
200
269
  /**
201
270
  * Convert an array to a dictionary by mapping each item into a
202
- * dictionary key & value
271
+ * dictionary key & value.
203
272
  *
273
+ * @see https://radashi-org.github.io/reference/array/objectify
274
+ * @example
204
275
  * ```ts
205
276
  * objectify([1, 2, 3], (n) => '#' + n)
206
277
  * // { '#1': 1, '#2': 2, '#3': 3 }
@@ -215,39 +286,26 @@ declare function min<T>(array: readonly T[], getter: (item: T) => number): T | n
215
286
  */
216
287
  declare function objectify<T, Key extends string | number | symbol, Value = T>(array: readonly T[], getKey: (item: T) => Key, getValue?: (item: T) => Value): Record<Key, Value>;
217
288
 
218
- /**
219
- * Creates a generator that will produce an iteration through the
220
- * range of number as requested.
221
- *
222
- * ```ts
223
- * range(3) // yields 0, 1, 2, 3
224
- * range(0, 3) // yields 0, 1, 2, 3
225
- * range(0, 3, 'y') // yields y, y, y, y
226
- * range(0, 3, () => 'y') // yields y, y, y, y
227
- * range(0, 3, i => i) // yields 0, 1, 2, 3
228
- * range(0, 3, i => `y${i}`) // yields y0, y1, y2, y3
229
- * range(0, 3, obj) // yields obj, obj, obj, obj
230
- * range(0, 6, i => i, 2) // yields 0, 2, 4, 6
231
- * ```
232
- */
233
- declare function range<T = number>(startOrLength: number, end?: number, valueOrMapper?: T | ((i: number) => T), step?: number): Generator<T>;
234
-
235
289
  /**
236
290
  * Replace an element in an array with a new item without modifying
237
- * the array and return the new value
291
+ * the array and return the new value.
238
292
  *
293
+ * @see https://radashi-org.github.io/reference/array/replace
294
+ * @example
239
295
  * ```ts
240
296
  * replace([1, 2, 3], 4, (n) => n === 2)
241
297
  * // [1, 4, 3]
242
298
  * ```
243
299
  */
244
- declare function replace<T>(list: readonly T[], newItem: T, match: (item: T, idx: number) => boolean): T[];
300
+ declare function replace<T>(array: readonly T[], newItem: T, match: (item: T, idx: number) => boolean): T[];
245
301
 
246
302
  /**
247
303
  * Replace the first occurrence of an item in an array where the
248
304
  * `match` function returns true. If no items match, append the new
249
305
  * item to the end of the list.
250
306
  *
307
+ * @see https://radashi-org.github.io/reference/array/replaceOrAppend
308
+ * @example
251
309
  * ```ts
252
310
  * replaceOrAppend([1, 2, 3], 4, (n) => n > 1)
253
311
  * // [1, 4, 3]
@@ -256,12 +314,15 @@ declare function replace<T>(list: readonly T[], newItem: T, match: (item: T, idx
256
314
  * // [1, 2, 3, 4]
257
315
  * ```
258
316
  */
259
- declare function replaceOrAppend<T>(list: readonly T[], newItem: T, match: (a: T, idx: number) => boolean): T[];
317
+ declare function replaceOrAppend<T>(array: readonly T[], newItem: T, match: (a: T, idx: number) => boolean): T[];
260
318
 
261
319
  /**
262
320
  * Select performs a filter and a mapper inside of a reduce, only
263
- * iterating the list one time.
321
+ * iterating the list one time. If condition is omitted, will
322
+ * select all mapped values that are non-nullish.
264
323
  *
324
+ * @see https://radashi-org.github.io/reference/array/select
325
+ * @example
265
326
  * ```ts
266
327
  * select(
267
328
  * [1, 2, 3, 4],
@@ -271,13 +332,34 @@ declare function replaceOrAppend<T>(list: readonly T[], newItem: T, match: (a: T
271
332
  * // => [9, 16]
272
333
  * ```
273
334
  */
274
- declare function select<T, U>(array: readonly T[], mapper: (item: T, index: number) => U, condition?: (item: T, index: number) => boolean): U[];
335
+ declare function select<T, U>(array: readonly T[], mapper: (item: T, index: number) => U, condition: ((item: T, index: number) => boolean) | null | undefined): U[];
336
+ declare function select<T, U>(array: readonly T[], mapper: (item: T, index: number) => U | null | undefined): U[];
337
+
338
+ /**
339
+ * Select performs a find + map operation, short-circuiting on the first
340
+ * element that satisfies the prescribed condition. If condition is omitted,
341
+ * will select the first mapped value which is non-nullish.
342
+ *
343
+ * @see https://radashi-org.github.io/reference/array/selectFirst
344
+ * @example
345
+ * ```ts
346
+ * selectFirst(
347
+ * [1, 2, 3, 4],
348
+ * x => x * x,
349
+ * x => x > 2
350
+ * )
351
+ * // => 9
352
+ * ```
353
+ */
354
+ declare function selectFirst<T, U>(array: readonly T[], mapper: (item: T, index: number) => U, condition?: (item: T, index: number) => boolean): U | undefined;
275
355
 
276
356
  /**
277
357
  * Shifts array items by `n` steps. If `n` is greater than 0, items
278
358
  * will shift `n` steps to the right. If `n` is less than 0, items
279
359
  * will shift `n` steps to the left.
280
360
  *
361
+ * @see https://radashi-org.github.io/reference/array/shift
362
+ * @example
281
363
  * ```ts
282
364
  * shift([1, 2, 3], 1) // [3, 1, 2]
283
365
  * shift([1, 2, 3], -1) // [2, 3, 1]
@@ -287,19 +369,23 @@ declare function shift<T>(arr: T[], n: number): T[];
287
369
 
288
370
  type Falsy = null | undefined | false | '' | 0 | 0n;
289
371
  /**
290
- * Given a list returns a new list with only truthy values
372
+ * Given a list returns a new list with only truthy values.
291
373
  *
374
+ * @see https://radashi-org.github.io/reference/array/sift
375
+ * @example
292
376
  * ```ts
293
377
  * sift([0, 1, undefined, null, 2, false, 3, ''])
294
378
  * // => [1, 2, 3]
295
379
  * ```
296
380
  */
297
- declare function sift<T>(list: readonly (T | Falsy)[]): T[];
381
+ declare function sift<T>(array: readonly (T | Falsy)[]): T[];
298
382
 
299
383
  /**
300
384
  * Sort an array without modifying it and return the newly sorted
301
- * value
385
+ * value.
302
386
  *
387
+ * @see https://radashi-org.github.io/reference/array/sort
388
+ * @example
303
389
  * ```ts
304
390
  * const fish = [
305
391
  * { name: 'Marlin', weight: 105 },
@@ -313,29 +399,12 @@ declare function sift<T>(list: readonly (T | Falsy)[]): T[];
313
399
  */
314
400
  declare function sort<T>(array: readonly T[], getter: (item: T) => number, desc?: boolean): T[];
315
401
 
316
- /**
317
- * Sum all numbers in an array. Optionally provide a function to
318
- * convert objects in the array to number values.
319
- *
320
- * ```ts
321
- * sum([1, 2, 3])
322
- * // => 6
323
- *
324
- * sum([
325
- * {value: 1},
326
- * {value: 2},
327
- * {value: 3}
328
- * ], (item) => item.value)
329
- * // => 6
330
- * ```
331
- */
332
- declare function sum<T extends number>(array: readonly T[]): number;
333
- declare function sum<T extends object>(array: readonly T[], fn: (item: T) => number): number;
334
-
335
402
  /**
336
403
  * If the item matching the condition already exists in the list it
337
404
  * will be removed. If it does not it will be added.
338
405
  *
406
+ * @see https://radashi-org.github.io/reference/array/toggle
407
+ * @example
339
408
  * ```ts
340
409
  * toggle([1, 2, 3], 4) // => [1, 2, 3, 4]
341
410
  * toggle([1, 2, 3], 2) // => [1, 3]
@@ -352,7 +421,7 @@ declare function sum<T extends object>(array: readonly T[], fn: (item: T) => num
352
421
  * // => [{ id: 3 }, { id: 1 }, { id: 2 }]
353
422
  * ```
354
423
  */
355
- declare function toggle<T>(list: readonly T[], item: T,
424
+ declare function toggle<T>(array: readonly T[], item: T,
356
425
  /**
357
426
  * Converts an item of type T item into a value that can be checked
358
427
  * for equality
@@ -364,8 +433,10 @@ toKey?: null | ((item: T, idx: number) => number | string | symbol), options?: {
364
433
  /**
365
434
  * Given a list of items returns a new list with only unique items.
366
435
  * Accepts an optional identity function to convert each item in the
367
- * list to a comparable identity value
436
+ * list to a comparable identity value.
368
437
  *
438
+ * @see https://radashi-org.github.io/reference/array/unique
439
+ * @example
369
440
  * ```ts
370
441
  * unique([1, 1, 2, 2]) // => [1, 2]
371
442
  * unique([1, 2, 3], (n) => n % 2) // => [1, 2]
@@ -373,25 +444,44 @@ toKey?: null | ((item: T, idx: number) => number | string | symbol), options?: {
373
444
  */
374
445
  declare function unique<T, K = T>(array: readonly T[], toKey?: (item: T) => K): T[];
375
446
 
447
+ /**
448
+ * Creates an array of ungrouped elements, where each resulting array
449
+ * contains all elements at a specific index from the input arrays.
450
+ * The first array contains all first elements, the second array
451
+ * contains all second elements, and so on.
452
+ *
453
+ * @see https://radashi-org.github.io/reference/array/unzip
454
+ * @example
455
+ * ```ts
456
+ * unzip([['a', 1, true], ['b', 2, false]])
457
+ * // [['a', 'b'], [1, 2], [true, false]]
458
+ * ```
459
+ */
460
+ declare function unzip<T>(arrays: readonly (readonly T[])[]): T[][];
461
+
376
462
  /**
377
463
  * Creates an array of grouped elements, the first of which contains
378
464
  * the first elements of the given arrays, the second of which
379
465
  * contains the second elements of the given arrays, and so on.
380
466
  *
467
+ * @see https://radashi-org.github.io/reference/array/zip
468
+ * @example
381
469
  * ```ts
382
470
  * zip(['a', 'b'], [1, 2], [true, false])
383
471
  * // [['a', 1, true], ['b', 2, false]]
384
472
  * ```
385
473
  */
386
- declare function zip<T1, T2, T3, T4, T5>(array1: T1[], array2: T2[], array3: T3[], array4: T4[], array5: T5[]): [T1, T2, T3, T4, T5][];
387
- declare function zip<T1, T2, T3, T4>(array1: T1[], array2: T2[], array3: T3[], array4: T4[]): [T1, T2, T3, T4][];
388
- declare function zip<T1, T2, T3>(array1: T1[], array2: T2[], array3: T3[]): [T1, T2, T3][];
389
- declare function zip<T1, T2>(array1: T1[], array2: T2[]): [T1, T2][];
474
+ declare function zip<T1, T2, T3, T4, T5>(array1: readonly T1[], array2: readonly T2[], array3: readonly T3[], array4: readonly T4[], array5: readonly T5[]): [T1, T2, T3, T4, T5][];
475
+ declare function zip<T1, T2, T3, T4>(array1: readonly T1[], array2: readonly T2[], array3: readonly T3[], array4: readonly T4[]): [T1, T2, T3, T4][];
476
+ declare function zip<T1, T2, T3>(array1: readonly T1[], array2: readonly T2[], array3: readonly T3[]): [T1, T2, T3][];
477
+ declare function zip<T1, T2>(array1: readonly T1[], array2: readonly T2[]): [T1, T2][];
390
478
 
391
479
  /**
392
480
  * Creates an object mapping the specified keys to their corresponding
393
- * values
481
+ * values.
394
482
  *
483
+ * @see https://radashi-org.github.io/reference/array/zipToObject
484
+ * @example
395
485
  * ```ts
396
486
  * zipToObject(['a', 'b'], [1, 2])
397
487
  * // { a: 1, b: 2 }
@@ -423,6 +513,8 @@ type PromiseValues<T extends Promise<any>[]> = {
423
513
  * any errors are thrown, all errors are gathered and thrown in an
424
514
  * `AggregateError`.
425
515
  *
516
+ * @see https://radashi-org.github.io/reference/async/all
517
+ * @example
426
518
  * ```ts
427
519
  * const [user] = await all([
428
520
  * api.users.create(...),
@@ -438,6 +530,8 @@ declare function all<T extends Promise<any>[]>(promises: T): Promise<PromiseValu
438
530
  * any errors are thrown, all errors are gathered and thrown in an
439
531
  * `AggregateError`.
440
532
  *
533
+ * @see https://radashi-org.github.io/reference/async/all
534
+ * @example
441
535
  * ```ts
442
536
  * const { user } = await all({
443
537
  * user: api.users.create(...),
@@ -454,8 +548,20 @@ declare function all<T extends Record<string, Promise<any>>>(promises: T): Promi
454
548
  * Useful when for script like things where cleanup should be done on
455
549
  * fail or sucess no matter.
456
550
  *
457
- * You can call defer many times to register many defered functions
551
+ * You can call defer many times to register many deferred functions
458
552
  * that will all be called when the function exits in any state.
553
+ *
554
+ * @see https://radashi-org.github.io/reference/async/defer
555
+ * @example
556
+ * ```ts
557
+ * const result = await defer(async (defer) => {
558
+ * const fileHandle = await openFile('path/to/file')
559
+ * defer(() => fileHandle.close())
560
+ *
561
+ * // Perform operations on the file
562
+ * return processFile(fileHandle)
563
+ * })
564
+ * ```
459
565
  */
460
566
  declare function defer<TResponse>(func: (register: (fn: (error?: any) => any, options?: {
461
567
  rethrow?: boolean;
@@ -465,6 +571,8 @@ declare function defer<TResponse>(func: (register: (fn: (error?: any) => any, op
465
571
  * A helper to try an async function that returns undefined if it
466
572
  * fails.
467
573
  *
574
+ * @see https://radashi-org.github.io/reference/async/guard
575
+ * @example
468
576
  * ```ts
469
577
  * const result = await guard(fetchUsers)() ?? [];
470
578
  * ```
@@ -473,7 +581,17 @@ declare function guard<TFunction extends () => any>(func: TFunction, shouldGuard
473
581
 
474
582
  /**
475
583
  * An async map function. Works like the built-in Array.map function
476
- * but handles an async mapper function
584
+ * but handles an async mapper function.
585
+ *
586
+ * @see https://radashi-org.github.io/reference/async/map
587
+ * @example
588
+ * ```ts
589
+ * const urls = ['/data1', '/data2', '/data3']
590
+ * const responses = await map(urls, async (url) => {
591
+ * const response = await fetch('https://api.example.com' + url)
592
+ * return response.json()
593
+ * })
594
+ * ```
477
595
  */
478
596
  declare function map<T, K>(array: readonly T[], asyncMapFunc: (item: T, index: number) => Promise<K>): Promise<K[]>;
479
597
 
@@ -481,13 +599,30 @@ declare function map<T, K>(array: readonly T[], asyncMapFunc: (item: T, index: n
481
599
  * Executes many async functions in parallel. Returns the results from
482
600
  * all functions as an array. After all functions have resolved, if
483
601
  * any errors were thrown, they are rethrown in an instance of
484
- * AggregateError
602
+ * AggregateError.
603
+ *
604
+ * @see https://radashi-org.github.io/reference/async/parallel
605
+ * @example
606
+ * ```ts
607
+ * // Process images concurrently, resizing each image to a standard size.
608
+ * const images = await parallel(2, imageFiles, async (file) => {
609
+ * return await resizeImage(file)
610
+ * })
611
+ * ```
485
612
  */
486
613
  declare function parallel<T, K>(limit: number, array: readonly T[], func: (item: T) => Promise<K>): Promise<K[]>;
487
614
 
488
615
  /**
489
616
  * An async reduce function. Works like the built-in Array.reduce
490
- * function but handles an async reducer function
617
+ * function but handles an async reducer function.
618
+ *
619
+ * @see https://radashi-org.github.io/reference/async/reduce
620
+ * @example
621
+ * ```ts
622
+ * const result = await reduce([1, 2, 3], async (acc, item, index) => {
623
+ * return acc + (await computeOnGPU(item))
624
+ * }, 0)
625
+ * ```
491
626
  */
492
627
  declare function reduce<T, K>(array: readonly T[], asyncReducer: (acc: K, item: T, index: number) => Promise<K>, initValue?: K): Promise<K>;
493
628
 
@@ -498,25 +633,60 @@ type RetryOptions = {
498
633
  };
499
634
  /**
500
635
  * Retries the given function the specified number of times.
636
+ *
637
+ * @see https://radashi-org.github.io/reference/async/retry
638
+ * @example
639
+ * ```ts
640
+ * const result = await retry({ times: 3, delay: 1000 }, async () => {
641
+ * return await fetch('https://example.com')
642
+ * })
643
+ * ```
501
644
  */
502
645
  declare function retry<TResponse>(options: RetryOptions, func: (exit: (err: any) => void) => Promise<TResponse>): Promise<TResponse>;
503
646
 
504
647
  /**
505
- * Async wait
648
+ * Create a promise that resolves after a given amount of time.
649
+ *
650
+ * @see https://radashi-org.github.io/reference/async/sleep
651
+ * @example
652
+ * ```ts
653
+ * await sleep(1000)
654
+ * ```
506
655
  */
507
656
  declare function sleep(milliseconds: number): Promise<void>;
508
657
 
658
+ /**
659
+ * The result of a `tryit` function.
660
+ *
661
+ * If the function returns a promise, the result is a promise that
662
+ * resolves to an error-first callback-_like_ array response as
663
+ * `[Error, result]`.
664
+ *
665
+ * If the function returns a non-promise, the result is an error-first
666
+ * callback-_like_ array response as `[Error, result]`.
667
+ *
668
+ * @see https://radashi-org.github.io/reference/async/tryit
669
+ * @example
670
+ * ```ts
671
+ * const [err, result] = await tryit(async () => {
672
+ * return await fetch('https://example.com')
673
+ * })
674
+ * ```
675
+ */
676
+ type TryitResult<Return> = Return extends Promise<any> ? Promise<[Error, undefined] | [undefined, Awaited<Return>]> : [Error, undefined] | [undefined, Return];
509
677
  /**
510
678
  * A helper to try an async function without forking the control flow.
511
679
  * Returns an error-first callback-_like_ array response as `[Error,
512
680
  * result]`
513
681
  */
514
- declare function tryit<Args extends any[], Return>(func: (...args: Args) => Return): (...args: Args) => Return extends Promise<any> ? Promise<[Error, undefined] | [undefined, Awaited<Return>]> : [Error, undefined] | [undefined, Return];
682
+ declare function tryit<Args extends any[], Return>(func: (...args: Args) => Return): (...args: Args) => TryitResult<Return>;
515
683
 
516
684
  /**
517
685
  * Make an object callable. Given an object and a function the
518
686
  * returned object will be a function with all the objects properties.
519
687
  *
688
+ * @see https://radashi-org.github.io/reference/curry/callable
689
+ * @example
520
690
  * ```ts
521
691
  * const car = callable({
522
692
  * wheels: 2
@@ -530,6 +700,23 @@ declare function tryit<Args extends any[], Return>(func: (...args: Args) => Retu
530
700
  */
531
701
  declare function callable<TValue, TObj extends Record<string | number | symbol, TValue>, TFunc extends (...args: any) => any>(obj: TObj, fn: (self: TObj) => TFunc): TObj & TFunc;
532
702
 
703
+ /**
704
+ * Create a function that chains multiple functions together. The
705
+ * functions are called in order. Each function takes the result of
706
+ * the previous function as its first argument.
707
+ *
708
+ * @see https://radashi-org.github.io/reference/curry/chain
709
+ * @example
710
+ * ```ts
711
+ * const myChainedFunc = chain(
712
+ * (x) => x + 5,
713
+ * (x) => x * 2,
714
+ * )
715
+ *
716
+ * myChainedFunc(0)
717
+ * // => 10
718
+ * ```
719
+ */
533
720
  declare function chain<T1 extends any[], T2, T3>(f1: (...arg: T1) => T2, f2: (arg: T2) => T3): (...arg: T1) => T3;
534
721
  declare function chain<T1 extends any[], T2, T3, T4>(f1: (...arg: T1) => T2, f2: (arg: T2) => T3, f3: (arg: T3) => T4): (...arg: T1) => T4;
535
722
  declare function chain<T1 extends any[], T2, T3, T4, T5>(f1: (...arg: T1) => T2, f2: (arg: T2) => T3, f3: (arg: T3) => T4, f4: (arg: T3) => T5): (...arg: T1) => T5;
@@ -540,6 +727,23 @@ declare function chain<T1 extends any[], T2, T3, T4, T5, T6, T7, T8, T9>(f1: (..
540
727
  declare function chain<T1 extends any[], T2, T3, T4, T5, T6, T7, T8, T9, T10>(f1: (...arg: T1) => T2, f2: (arg: T2) => T3, f3: (arg: T3) => T4, f4: (arg: T3) => T5, f5: (arg: T3) => T6, f6: (arg: T3) => T7, f7: (arg: T3) => T8, f8: (arg: T3) => T9, f9: (arg: T3) => T10): (...arg: T1) => T10;
541
728
  declare function chain<T1 extends any[], T2, T3, T4, T5, T6, T7, T8, T9, T10, T11>(f1: (...arg: T1) => T2, f2: (arg: T2) => T3, f3: (arg: T3) => T4, f4: (arg: T3) => T5, f5: (arg: T3) => T6, f6: (arg: T3) => T7, f7: (arg: T3) => T8, f8: (arg: T3) => T9, f9: (arg: T3) => T10, f10: (arg: T3) => T11): (...arg: T1) => T11;
542
729
 
730
+ /**
731
+ * Create a function that composes multiple functions together. In a
732
+ * composition of functions, each function is given the next function
733
+ * as an argument and must call it to continue executing.
734
+ *
735
+ * @see https://radashi-org.github.io/reference/curry/compose
736
+ * @example
737
+ * ```ts
738
+ * const myComposedFunc = compose(
739
+ * (x) => x + 5,
740
+ * (x) => x * 2,
741
+ * )
742
+ *
743
+ * myComposedFunc(0)
744
+ * // => 5
745
+ * ```
746
+ */
543
747
  declare function compose<F1Result, F1Args extends any[], F1NextArgs extends any[], LastResult>(f1: (next: (...args: F1NextArgs) => LastResult) => (...args: F1Args) => F1Result, last: (...args: F1NextArgs) => LastResult): (...args: F1Args) => F1Result;
544
748
  declare function compose<F1Result, F1Args extends any[], F1NextArgs extends any[], F2Result, F2NextArgs extends any[], LastResult>(f1: (next: (...args: F1NextArgs) => F2Result) => (...args: F1Args) => F1Result, f2: (next: (...args: F2NextArgs) => LastResult) => (...args: F1NextArgs) => F2Result, last: (...args: F2NextArgs) => LastResult): (...args: F1Args) => F1Result;
545
749
  declare function compose<F1Result, F1Args extends any[], F1NextArgs extends any[], F2NextArgs extends any[], F2Result, F3NextArgs extends any[], F3Result, LastResult>(f1: (next: (...args: F1NextArgs) => F2Result) => (...args: F1Args) => F1Result, f2: (next: (...args: F2NextArgs) => F3Result) => (...args: F1NextArgs) => F2Result, f3: (next: (...args: F3NextArgs) => LastResult) => (...args: F2NextArgs) => F3Result, last: (...args: F3NextArgs) => LastResult): (...args: F1Args) => F1Result;
@@ -572,22 +776,110 @@ type DebounceFunction<TArgs extends any[]> = {
572
776
  *
573
777
  * The debounce function comes with a `cancel` method to cancel
574
778
  * delayed `func` invocations and a `flush` method to invoke them
575
- * immediately
779
+ * immediately.
780
+ *
781
+ * @see https://radashi-org.github.io/reference/curry/debounce
782
+ * @example
783
+ * ```ts
784
+ * const myDebouncedFunc = debounce({ delay: 1000 }, (x) => console.log(x))
785
+ *
786
+ * myDebouncedFunc(0)
787
+ * myDebouncedFunc(1)
788
+ * // Logs 1, but not 0
789
+ * ```
576
790
  */
577
791
  declare function debounce<TArgs extends any[]>({ delay }: {
578
792
  delay: number;
579
793
  }, func: (...args: TArgs) => any): DebounceFunction<TArgs>;
580
794
 
795
+ /**
796
+ * Flip the first two arguments of a function.
797
+ *
798
+ * @see https://radashi-org.github.io/reference/curry/flip
799
+ * @example
800
+ * ```ts
801
+ * const subtract = (x: number, y: number) => x - y
802
+ *
803
+ * // Equivalent to “y - x”
804
+ * const flippedSubtract = flip(subtract)
805
+ *
806
+ * flippedSubtract(3, 4)
807
+ * // => 1
808
+ * ```
809
+ */
810
+ declare function flip<Args extends any[], Result>(fn: (...args: Args) => Result): (...args: Flip<Args>) => Result;
811
+ type Flip<T extends any[]> = T extends [infer A, infer B, ...infer R] ? [B, A, ...R] : never;
812
+
813
+ interface MemoOptions<TArgs extends any[]> {
814
+ key?: (...args: TArgs) => string;
815
+ ttl?: number;
816
+ }
581
817
  /**
582
818
  * Creates a memoized function. The returned function will only
583
819
  * execute the source function when no value has previously been
584
820
  * computed. If a ttl (milliseconds) is given previously computed
585
821
  * values will be checked for expiration before being returned.
822
+ *
823
+ * @see https://radashi-org.github.io/reference/curry/memo
824
+ * @example
825
+ * ```ts
826
+ * const calls: number[] = []
827
+ * const fib = memo((x: number) => {
828
+ * calls.push(x)
829
+ * return x < 2 ? x : fib(x - 1) + fib(x - 2)
830
+ * })
831
+ *
832
+ * fib(10) // 55
833
+ * fib(10) // 55
834
+ * // calls === [10]
835
+ *
836
+ * fib(11) // 89
837
+ * // calls === [10, 11]
838
+ * ```
586
839
  */
587
- declare function memo<TArgs extends any[], TResult>(func: (...args: TArgs) => TResult, options?: {
588
- key?: (...args: TArgs) => string;
589
- ttl?: number;
590
- }): (...args: TArgs) => TResult;
840
+ declare function memo<TArgs extends any[], TResult>(func: (...args: TArgs) => TResult, options?: MemoOptions<TArgs>): (...args: TArgs) => TResult;
841
+
842
+ declare const onceSymbol: unique symbol;
843
+ /**
844
+ * The type of a function wrapped with `once`.
845
+ */
846
+ interface OnceFunction<Args extends unknown[] = unknown[], Return = unknown, This = unknown> {
847
+ (this: This, ...args: Args): Return;
848
+ [onceSymbol]?: Return | typeof onceSymbol;
849
+ }
850
+ /**
851
+ * Create a function that runs at most once, no matter how many times
852
+ * it's called. If it was already called before, returns the result
853
+ * from the first call. This is a lighter version of `memo()`.
854
+ *
855
+ * To allow your `once`-wrapped function to be called again, see the
856
+ * `once.reset` function.
857
+ *
858
+ * @see https://radashi-org.github.io/reference/curry/once
859
+ * @example
860
+ * ```ts
861
+ * const fn = once(() => Math.random())
862
+ * fn() // 0.5
863
+ * fn() // 0.5
864
+ * ```
865
+ */
866
+ declare const once: {
867
+ <Args extends unknown[], Return, This = unknown>(fn: (this: This, ...args: Args) => Return): (this: This, ...args: Args) => Return;
868
+ /**
869
+ * Reset the result of a function that was created with `once`,
870
+ * allowing it to be called again.
871
+ *
872
+ * ```ts
873
+ * const fn = once(() => Math.random())
874
+ * fn() // 0.5
875
+ * fn() // 0.5
876
+ * once.reset(fn)
877
+ * fn() // 0.3
878
+ * fn() // 0.3
879
+ * ```
880
+ */
881
+ reset(fn: OnceFunction): void;
882
+ };
591
883
 
592
884
  /**
593
885
  * This type produces the type array of `TItems` with all the type items
@@ -606,6 +898,8 @@ type RemoveItemsInFront<TItems extends any[], TItemsToRemove extends any[]> = TI
606
898
  * Create a partial function by providing some (or all) of the
607
899
  * arguments the given function needs.
608
900
  *
901
+ * @see https://radashi-org.github.io/reference/curry/partial
902
+ * @example
609
903
  * ```ts
610
904
  * const add = (a: number, b: number) => a + b
611
905
  *
@@ -619,12 +913,35 @@ declare function partial<T extends any[], TA extends Partial<T>, R>(fn: (...args
619
913
  /**
620
914
  * Like partial but for unary functions that accept a single object
621
915
  * argument
916
+ *
917
+ * @see https://radashi-org.github.io/reference/curry/partob
918
+ * @example
919
+ * ```ts
920
+ * const add = (
921
+ * {a = 0, b = 0, c = 0}: {
922
+ * a?: number,
923
+ * b?: number,
924
+ * c?: number
925
+ * }
926
+ * ) => a + b + c
927
+ *
928
+ * const addPartial = partob(add, { a: 1 })
929
+ * addPartial({ b: 2 }) // 3
930
+ * addPartial({ b: 1, c: 5 }) // 7
931
+ * ```
622
932
  */
623
933
  declare function partob<T, K, PartialArgs extends Partial<T>>(fn: (args: T) => K, argobj: PartialArgs): (restobj: Omit<T, keyof PartialArgs>) => K;
624
934
 
625
935
  /**
626
936
  * Creates a Proxy object that will dynamically call the handler
627
- * argument when attributes are accessed
937
+ * argument when attributes are accessed.
938
+ *
939
+ * @see https://radashi-org.github.io/reference/curry/proxied
940
+ * @example
941
+ * ```ts
942
+ * const proxy = proxied(propertyName => propertyName.toUpperCase())
943
+ * proxy.foo // => "FOO"
944
+ * ```
628
945
  */
629
946
  declare function proxied<T, K>(handler: (propertyName: T) => K): Record<string, K>;
630
947
 
@@ -638,119 +955,536 @@ type ThrottledFunction<TArgs extends any[]> = {
638
955
  /**
639
956
  * Given an interval and a function returns a new function that will
640
957
  * only call the source function if interval milliseconds have passed
641
- * since the last invocation
958
+ * since the last invocation.
959
+ *
960
+ * @see https://radashi-org.github.io/reference/curry/throttle
961
+ * @example
962
+ * ```ts
963
+ * const sup = throttle({ interval: 1000 }, () => {
964
+ * console.log("sup")
965
+ * })
966
+ * sup() // => logs "sup"
967
+ * sup() // => no logs
968
+ * setTimeout(() => sup(), 500) // => no logs
969
+ * setTimeout(() => sup(), 1000) // => logs "sup"
970
+ * ```
642
971
  */
643
972
  declare function throttle<TArgs extends any[]>({ interval }: {
644
973
  interval: number;
645
974
  }, func: (...args: TArgs) => any): ThrottledFunction<TArgs>;
646
975
 
647
976
  /**
648
- * Checks if the given number is between zero (0) and the ending
649
- * number. 0 is inclusive.
650
- *
651
- * * Numbers can be negative or positive.
652
- * * Ending number is exclusive.
977
+ * Create a function that always returns the same value.
653
978
  *
654
- * @param {number} number The number to check.
655
- * @param {number} end The end of the range. Exclusive. @returns
656
- * {boolean} Returns `true` if `number` is in the range, else `false`.
979
+ * @example
980
+ * ```ts
981
+ * const alwaysTrue = always(true)
982
+ * alwaysTrue() // true
983
+ * alwaysTrue() // true
984
+ * alwaysTrue() // true
985
+ * ```
657
986
  */
658
- declare function inRange(number: number, end: number): boolean;
987
+ declare function always<T>(value: T): () => T;
988
+
659
989
  /**
660
- * Checks if the given number is between two numbers.
990
+ * Cast a value into a comparator function.
661
991
  *
662
- * * Numbers can be negative or positive.
663
- * * Starting number is inclusive.
664
- * * Ending number is exclusive.
665
- * * The start and the end of the range can be ascending OR descending
666
- * order.
992
+ * - **Function**: If `mapping` is a function, it maps the input
993
+ * values to a comparable value.
994
+ * - **Property Name**: If `mapping` is a property name, it maps the
995
+ * input values to a property of the input values with a comparable
996
+ * value.
667
997
  *
668
- * @param {number} number The number to check.
669
- * @param {number} start The start of the range. Inclusive. @param
670
- * {number} end The end of the range. Exclusive. @returns {boolean}
671
- * Returns `true` if `number` is in the range, else `false`.
672
- */
673
- declare function inRange(number: number, start: number, end: number): boolean;
674
-
675
- declare function toFloat<T extends number | null = number>(value: any, defaultValue?: T): number | T;
676
-
677
- declare function toInt<T extends number | null = number>(value: any, defaultValue?: T): number | T;
678
-
679
- /**
680
- * Merges two objects together recursivly into a new object applying
681
- * values from right to left. Recursion only applies to child object
682
- * properties.
998
+ * Optionally, you can pass a custom `compare` function that receives
999
+ * the mapped values and returns a number. If not provided, values are
1000
+ * compared with the `<` and `>` built-in operators. A positive number
1001
+ * means the “right value” is greater than the “left value”, a
1002
+ * negative number means the “left value” is greater than the “right
1003
+ * value”, and 0 means both values are equal.
1004
+ *
1005
+ * @see https://radashi-org.github.io/reference/function/castComparator
1006
+ * @example
1007
+ * ```ts
1008
+ * const compareUserNames = castComparator(
1009
+ * (user) => user.name,
1010
+ * (a, b) => b.localeCompare(a),
1011
+ * )
1012
+ *
1013
+ * const users = [
1014
+ * { name: 'John', age: 20 },
1015
+ * { name: 'Jane', age: 25 },
1016
+ * { name: 'Doe', age: 22 },
1017
+ * ]
1018
+ *
1019
+ * users.sort(compareUserNames)
1020
+ * // => [Doe, Jane, John]
1021
+ * ```
683
1022
  */
684
- declare function assign<X extends Record<string | symbol | number, any>>(initial: X, override: X): X;
685
-
1023
+ declare function castComparator<TMapping extends keyof any>(mapping: TMapping, compare?: null | undefined, reverse?: boolean): Comparator<MappedInput<TMapping, Comparable>>;
1024
+ declare function castComparator<T, TMapping extends Mapping<any, T>>(mapping: TMapping, compare: Comparator<T>, reverse?: boolean): Comparator<MappedInput<TMapping, T>>;
1025
+ declare function castComparator<TInput, TOutput = Comparable>(mapping: (data: TInput) => TOutput, compare?: Comparator<TOutput> | null, reverse?: boolean): Comparator<TInput>;
1026
+ declare function castComparator<TInput>(mapping: ComparatorMapping<TInput>, compare?: null | undefined, reverse?: boolean): Comparator<TInput>;
1027
+ declare function castComparator<TMapping extends ComparatorMapping>(mapping: TMapping, compare?: Comparator<MappedOutput<TMapping>> | null, reverse?: boolean): Comparator<MappedInput<TMapping>>;
686
1028
  /**
687
- * Creates a shallow copy of the given obejct/value.
688
- * @param {*} obj value to clone @returns {*} shallow clone of the
689
- * given value
1029
+ * A value that describes how a comparator maps the input values to a
1030
+ * comparable value.
1031
+ *
1032
+ * @see https://radashi-org.github.io/reference/function/castComparator
690
1033
  */
691
- declare function clone<T>(obj: T): T;
1034
+ type ComparatorMapping<T = any, Compared extends Comparable = Comparable> = Mapping<T, Compared>;
692
1035
 
693
1036
  /**
694
- * The opposite of crush, given an object that was crushed into key
695
- * paths and values will return the original object reconstructed.
1037
+ * Cast the `mapping` value into a mapping function.
1038
+ *
1039
+ * - If `mapping` is a function, it's returned as is.
1040
+ * - If `mapping` is a property name, the mapping uses it to retrieve
1041
+ * the property value from a given object.
1042
+ * - If `mapping` is nullish, the mapping is `(input: T) => input`.
696
1043
  *
1044
+ * @see https://radashi-org.github.io/reference/function/castMapping
1045
+ * @example
697
1046
  * ```ts
698
- * construct({ name: 'ra', 'children.0.name': 'hathor' })
699
- * // { name: 'ra', children: [{ name: 'hathor' }] }
1047
+ * const getName = castMapping('name')
1048
+ * const getFullName = castMapping(person => {
1049
+ * return `${person.firstName} ${person.lastName}`
1050
+ * })
1051
+ *
1052
+ * getName({ name: 'John' }) // => 'John'
1053
+ * getFullName({ firstName: 'John', lastName: 'Doe' }) // => 'John Doe'
700
1054
  * ```
701
1055
  */
702
- declare function construct<TObject extends object>(obj: TObject): object;
703
-
1056
+ declare function castMapping<TMapping extends Mapping | null | undefined>(mapping: TMapping): MappingFunction<TMapping>;
704
1057
  /**
705
- * Flattens a deep object to a single dimension, converting the keys
706
- * to dot notation.
1058
+ * A value that can be casted with `castMapping`.
707
1059
  *
708
- * ```ts
709
- * crush({ name: 'ra', children: [{ name: 'hathor' }] })
710
- * // { name: 'ra', 'children.0.name': 'hathor' }
711
- * ```
1060
+ * @see https://radashi-org.github.io/reference/function/castMapping
712
1061
  */
713
- declare function crush<TValue extends object>(value: TValue): object;
714
-
715
- type KeyOf<T extends object> = object extends T ? keyof any : keyof T;
716
- type ValueOf<T extends object> = object extends T ? unknown : T[keyof T];
717
- type KeyFilterFunction<T extends object = object> = (value: ValueOf<T>, key: KeyOf<T>, obj: T) => boolean;
1062
+ type Mapping<T = any, U = any> = ((arg: T) => U) | CompatibleProperty<T, U>;
718
1063
  /**
719
- * Functions can use this type to accept either an array of keys or a
720
- * filter function.
1064
+ * A value that can be casted with `castMapping`.
1065
+ *
1066
+ * @see https://radashi-org.github.io/reference/function/castMapping
721
1067
  */
722
- type KeyFilter<T extends object = object, Key extends keyof any = keyof any> = KeyFilterFunction<T> | readonly Key[];
1068
+ type OptionalMapping<T = any, U = any> = Mapping<T, U> | null | undefined;
723
1069
  /**
724
- * Returns true if the key is in the “keys array” or if the “filter
725
- * function” returns true.
1070
+ * The input type of a mapping function created with `castMapping`.
1071
+ *
1072
+ * @see https://radashi-org.github.io/reference/function/castMapping
726
1073
  */
727
- declare function filterKey(obj: object, key: keyof any, filter: KeyFilter | null | undefined): boolean;
1074
+ type MappedInput<TMapping, TPropertyValue = any> = TMapping extends (arg: infer Arg) => any ? [Arg] extends [Any] ? unknown : Arg : TMapping extends keyof any ? {
1075
+ [P in TMapping]: TPropertyValue;
1076
+ } | (TMapping extends number ? readonly TPropertyValue[] : never) : unknown;
1077
+ /**
1078
+ * The return type of a mapping function created with `castMapping`.
1079
+ *
1080
+ * @see https://radashi-org.github.io/reference/function/castMapping
1081
+ */
1082
+ type MappedOutput<TMapping, TInput = any> = TMapping extends (data: TInput) => infer Result ? [Result] extends [Any] ? unknown : Result : [TInput] extends [Any] ? unknown : TMapping extends null | undefined ? TInput : TMapping extends keyof TInput ? TInput[TMapping] : never;
1083
+ /**
1084
+ * A mapping function created with `castMapping`.
1085
+ *
1086
+ * @see https://radashi-org.github.io/reference/function/castMapping
1087
+ */
1088
+ type MappingFunction<TMapping extends Mapping | null | undefined> = <TInput extends MappedInput<TMapping>>(input: TInput) => MappedOutput<TMapping, TInput>;
728
1089
 
729
1090
  /**
730
- * Dynamically get a nested value from an array or object with a
731
- * string.
1091
+ * A callback that does nothing and returns undefined.
732
1092
  *
1093
+ * @example
733
1094
  * ```ts
734
- * const person = {
735
- * name: 'John',
736
- * friends: [{ name: 'Jane' }]
737
- * }
738
- *
739
- * get(person, 'friends[0].name')
740
- * // => 'Jane'
1095
+ * noop() // => undefined
1096
+ * noop(1) // => undefined
1097
+ * noop(1, 2, 3) // => undefined
741
1098
  * ```
742
1099
  */
743
- declare function get<TDefault = unknown>(value: any, path: string, defaultValue?: TDefault): TDefault;
1100
+ declare function noop(): undefined;
1101
+
1102
+ /**
1103
+ * The `clamp` function restricts a number to be within a specified
1104
+ * range.
1105
+ *
1106
+ * - It takes three arguments: the number to clamp, the minimum value,
1107
+ * and the maximum value.
1108
+ * - If the number is less than the minimum, it returns the minimum.
1109
+ * - If the number is greater than the maximum, it returns the
1110
+ * maximum.
1111
+ * - Otherwise, it returns the number itself.
1112
+ *
1113
+ * @see https://radashi-org.github.io/reference/number/clamp
1114
+ * @example
1115
+ * ```ts
1116
+ * clamp(5, 1, 10) // returns 5
1117
+ * clamp(0, 1, 10) // returns 1
1118
+ * clamp(15, 1, 10) // returns 10
1119
+ * ```
1120
+ */
1121
+ declare function clamp(n: number, min: number | null | undefined, max: number | null | undefined): number;
1122
+
1123
+ /**
1124
+ * Checks if the given number is between zero (0) and the ending
1125
+ * number. 0 is inclusive.
1126
+ *
1127
+ * * Numbers can be negative or positive.
1128
+ * * Ending number is exclusive.
1129
+ *
1130
+ * @see https://radashi-org.github.io/reference/number/inRange
1131
+ * @example
1132
+ * ```ts
1133
+ * inRange(5, 10) // => true
1134
+ * inRange(-1, 10) // => false
1135
+ * inRange(10, 10) // => false
1136
+ * ```
1137
+ */
1138
+ declare function inRange(number: number, end: number): boolean;
1139
+ /**
1140
+ * Checks if the given number is between two numbers.
1141
+ *
1142
+ * * Numbers can be negative or positive.
1143
+ * * Starting number is inclusive.
1144
+ * * Ending number is exclusive.
1145
+ * * The start and the end of the range can be ascending OR descending
1146
+ * order.
1147
+ *
1148
+ * @see https://radashi-org.github.io/reference/number/inRange
1149
+ * @example
1150
+ * ```ts
1151
+ * inRange(5, 0, 10) // => true
1152
+ * inRange(-1, 0, 10) // => false
1153
+ * inRange(10, 0, 10) // => false
1154
+ * ```
1155
+ */
1156
+ declare function inRange(number: number, start: number, end: number): boolean;
1157
+
1158
+ /**
1159
+ * Linearly interpolates between two numbers.
1160
+ *
1161
+ * @see https://radashi-org.github.io/reference/number/lerp
1162
+ * @example
1163
+ * ```
1164
+ * lerp(0, 10, 0.5) // => 5
1165
+ * lerp(5, 15, 0.2) // => 7
1166
+ * lerp(-10, 10, 0.75) // => 5
1167
+ * ```
1168
+ */
1169
+ declare function lerp(from: number, to: number, amount: number): number;
1170
+
1171
+ /**
1172
+ * Max gets the greatest value from a list.
1173
+ *
1174
+ * @see https://radashi-org.github.io/reference/array/max
1175
+ * @example
1176
+ * ```ts
1177
+ * max([2, 3, 5]) // => 5
1178
+ * max([{ num: 1 }, { num: 2 }], x => x.num) // => { num: 2 }
1179
+ * ```
1180
+ */
1181
+ declare function max(array: readonly [number, ...number[]]): number;
1182
+ declare function max(array: readonly number[]): number | null;
1183
+ declare function max<T>(array: readonly T[], getter: (item: T) => number): T | null;
1184
+
1185
+ /**
1186
+ * Min gets the smallest value from a list.
1187
+ *
1188
+ * @see https://radashi-org.github.io/reference/array/min
1189
+ * @example
1190
+ * ```ts
1191
+ * min([1, 2, 3, 4]) // => 1
1192
+ * min([{ num: 1 }, { num: 2 }], x => x.num) // => { num: 1 }
1193
+ * ```
1194
+ */
1195
+ declare function min(array: readonly [number, ...number[]]): number;
1196
+ declare function min(array: readonly number[]): number | null;
1197
+ declare function min<T>(array: readonly T[], getter: (item: T) => number): T | null;
1198
+
1199
+ /**
1200
+ * Creates a generator that will produce an iteration through the
1201
+ * range of number as requested.
1202
+ *
1203
+ * @see https://radashi-org.github.io/reference/array/range
1204
+ * @example
1205
+ * ```ts
1206
+ * range(3) // yields 0, 1, 2, 3
1207
+ * range(0, 3) // yields 0, 1, 2, 3
1208
+ * range(0, 3, 'y') // yields y, y, y, y
1209
+ * range(0, 3, () => 'y') // yields y, y, y, y
1210
+ * range(0, 3, i => i) // yields 0, 1, 2, 3
1211
+ * range(0, 3, i => `y${i}`) // yields y0, y1, y2, y3
1212
+ * range(0, 3, obj) // yields obj, obj, obj, obj
1213
+ * range(0, 6, i => i, 2) // yields 0, 2, 4, 6
1214
+ * ```
1215
+ */
1216
+ declare function range<T = number>(startOrLength: number, end?: number, valueOrMapper?: T | ((i: number) => T), step?: number): Generator<T>;
1217
+
1218
+ /**
1219
+ * Rounds a number to the given precision. The default `precision` is
1220
+ * zero. An optional rounding function (e.g. `Math.floor` or
1221
+ * `Math.ceil`) can be provided.
1222
+ *
1223
+ * The `precision` argument is limited to be within the range of -323
1224
+ * to +292. Without this limit, precision values outside this range
1225
+ * can result in NaN.
1226
+ *
1227
+ * @see https://radashi-org.github.io/reference/number/round
1228
+ * @example
1229
+ * ```ts
1230
+ * round(123.456)
1231
+ * // => 123.5
1232
+ *
1233
+ * round(1234.56, -2)
1234
+ * // => 1200
1235
+ *
1236
+ * round(1234.56, 1, Math.floor)
1237
+ * // => 1234.5
1238
+ *
1239
+ * round(1234.54, 1, Math.ceil)
1240
+ * // => 1234.6
1241
+ * ```
1242
+ */
1243
+ declare function round(value: number, precision?: number, toInteger?: (value: number) => number): number;
1244
+
1245
+ /**
1246
+ * Sum all numbers in an array. Optionally provide a function to
1247
+ * convert objects in the array to number values.
1248
+ *
1249
+ * @see https://radashi-org.github.io/reference/array/sum
1250
+ * @example
1251
+ * ```ts
1252
+ * sum([1, 2, 3])
1253
+ * // => 6
1254
+ *
1255
+ * sum([
1256
+ * {value: 1},
1257
+ * {value: 2},
1258
+ * {value: 3}
1259
+ * ], (item) => item.value)
1260
+ * // => 6
1261
+ * ```
1262
+ */
1263
+ declare function sum<T extends number>(array: readonly T[]): number;
1264
+ declare function sum<T extends object>(array: readonly T[], fn: (item: T) => number): number;
1265
+
1266
+ /**
1267
+ * Combines `Number.parseFloat` with NaN handling. By default, a zero
1268
+ * (0) is returned in place of NaN.
1269
+ *
1270
+ * @see https://radashi-org.github.io/reference/number/toFloat
1271
+ * @example
1272
+ * ```ts
1273
+ * toFloat("1.23") // => 1.23
1274
+ * toFloat("foo") // => 0
1275
+ * toFloat("1.23px", 1) // => 1.23
1276
+ * toFloat("foo", 1) // => 1
1277
+ * ```
1278
+ */
1279
+ declare function toFloat(value: unknown): number;
1280
+ declare function toFloat<T>(value: unknown, defaultValue: T | undefined): number | T;
1281
+
1282
+ /**
1283
+ * Combines `Number.parseInt` with NaN handling. By default, a zero
1284
+ * (0) is returned in place of NaN.
1285
+ *
1286
+ * @see https://radashi-org.github.io/reference/number/toInt
1287
+ * @example
1288
+ * ```ts
1289
+ * toInt("1.23") // => 1
1290
+ * toInt("foo") // => 0
1291
+ * toInt("1.23px", 1) // => 1
1292
+ * toInt("foo", -1) // => -1
1293
+ * ```
1294
+ */
1295
+ declare function toInt(value: unknown): number;
1296
+ declare function toInt<T>(value: unknown, defaultValue: T | undefined): number | T;
1297
+
1298
+ /**
1299
+ * Create a copy of the first object, and then merge the second object
1300
+ * into it recursively. Only plain objects are recursively merged.
1301
+ *
1302
+ * @see https://radashi-org.github.io/reference/object/assign
1303
+ * @example
1304
+ * ```ts
1305
+ * const a = { a: 0, b: 2, p: { a: 4 } }
1306
+ * const b = { a: 1, c: 3, p: { b: 5 } }
1307
+ *
1308
+ * assign(a, b)
1309
+ * // => { a: 1, b: 2, c: 3, p: { a: 4, b: 5 } }
1310
+ * ```
1311
+ */
1312
+ declare function assign<X extends Record<string | symbol | number, any>>(initial: X, override: X): X;
1313
+
1314
+ /**
1315
+ * Creates a shallow copy of the given object/value.
1316
+ *
1317
+ * @see https://radashi-org.github.io/reference/object/clone
1318
+ * @example
1319
+ * ```ts
1320
+ * const original = { a: 1, b: { c: 3 } }
1321
+ * const cloned = clone(original)
1322
+ * // => { a: 1, b: { c: 3 } }
1323
+ * original !== cloned
1324
+ * // => true
1325
+ * original.b === cloned.b
1326
+ * // => true
1327
+ * ```
1328
+ */
1329
+ declare function clone<T>(obj: T): T;
1330
+
1331
+ /**
1332
+ * A strategy for cloning objects with `cloneDeep`.
1333
+ *
1334
+ * Methods **must** call the `track` function with the new parent
1335
+ * object **before** looping over the input object's
1336
+ * properties/elements for cloning purposes. This protects against
1337
+ * circular references.
1338
+ *
1339
+ * Methods may return the input object to indicate that cloning should
1340
+ * be skipped.
1341
+ *
1342
+ * Methods may return null to indicate that the default cloning logic
1343
+ * should be used.
1344
+ */
1345
+ interface CloningStrategy {
1346
+ cloneMap: <K, V>(parent: Map<K, V>, track: (newParent: Map<K, V>) => Map<K, V>, clone: <T>(value: T) => T) => Map<K, V> | null;
1347
+ cloneSet: <T>(parent: Set<T>, track: (newParent: Set<T>) => Set<T>, clone: <T>(value: T) => T) => Set<T> | null;
1348
+ cloneArray: <T>(parent: readonly T[], track: (newParent: T[]) => T[], clone: <T>(value: T) => T) => T[] | null;
1349
+ cloneObject: <T extends object>(parent: T, track: (newParent: T) => T, clone: <T>(value: T) => T) => T | null;
1350
+ cloneOther: <T>(parent: T, track: (newParent: T) => T, clone: <T>(value: T) => T) => T | null;
1351
+ }
1352
+ declare const DefaultCloningStrategy: {
1353
+ cloneMap<K, V>(input: Map<K, V>, track: (newParent: Map<K, V>) => Map<K, V>, clone: <T>(value: T) => T): Map<K, V>;
1354
+ cloneSet<T>(input: Set<T>, track: (newParent: Set<T>) => Set<T>, clone: <T_1>(value: T_1) => T_1): Set<T>;
1355
+ cloneArray<T>(input: readonly T[], track: (newParent: T[]) => T[], clone: <T_1>(value: T_1) => T_1): T[];
1356
+ cloneObject<T extends object>(input: T, track: (newParent: T) => T, clone: <T_1>(value: T_1) => T_1): T;
1357
+ cloneOther<T>(input: T, track: (newParent: T) => T): T;
1358
+ };
1359
+ /**
1360
+ * If you don't need support for non-enumerable properties or computed
1361
+ * properties, and you're not using custom classes, you can use this
1362
+ * strategy for better performance.
1363
+ */
1364
+ declare const FastCloningStrategy: {
1365
+ cloneObject: <T extends object>(input: T, track: (newParent: T) => T, clone: <T_1>(value: T_1) => T_1) => T;
1366
+ };
1367
+ /**
1368
+ * Clone the given object and possibly other objects nested inside.
1369
+ *
1370
+ * By default, the only objects that get cloned are plain objects,
1371
+ * class instances, arrays, `Set` instances, and `Map` instances. If
1372
+ * an object is not cloned, any objects nested inside are also not
1373
+ * cloned.
1374
+ *
1375
+ * You may define a custom cloning strategy by passing a partial
1376
+ * implementation of the `CloningStrategy` interface to the
1377
+ * `cloneDeep` function. Any undefined methods will fall back to the
1378
+ * default cloning logic. Your own methods may return null to indicate
1379
+ * that the default cloning logic should be used. They may also return
1380
+ * the input object to indicate that cloning should be skipped.
1381
+ *
1382
+ * ```ts
1383
+ * const obj = { a: 1, b: { c: 2 } }
1384
+ * const clone = cloneDeep(obj)
1385
+ *
1386
+ * assert(clone !== obj)
1387
+ * assert(clone.b !== obj.b)
1388
+ * assert(JSON.stringify(clone) === JSON.stringify(obj))
1389
+ * ```
1390
+ */
1391
+ declare function cloneDeep<T extends object>(root: T, customStrategy?: Partial<CloningStrategy>): T;
1392
+
1393
+ /**
1394
+ * The opposite of crush, given an object that was crushed into key
1395
+ * paths and values will return the original object reconstructed.
1396
+ *
1397
+ * @see https://radashi-org.github.io/reference/object/construct
1398
+ * @example
1399
+ * ```ts
1400
+ * construct({ name: 'ra', 'children.0.name': 'hathor' })
1401
+ * // { name: 'ra', children: [{ name: 'hathor' }] }
1402
+ * ```
1403
+ */
1404
+ declare function construct<TObject extends object>(obj: TObject): object;
1405
+
1406
+ /**
1407
+ * Flattens a deep object to a single dimension, converting the keys
1408
+ * to dot notation.
1409
+ *
1410
+ * @see https://radashi-org.github.io/reference/object/crush
1411
+ * @example
1412
+ * ```ts
1413
+ * crush({ name: 'ra', children: [{ name: 'hathor' }] })
1414
+ * // { name: 'ra', 'children.0.name': 'hathor' }
1415
+ * ```
1416
+ */
1417
+ declare function crush<TValue extends object>(value: TValue): object;
1418
+
1419
+ type KeyOf<T extends object> = object extends T ? keyof any : keyof T;
1420
+ type ValueOf<T extends object> = object extends T ? unknown : T[keyof T];
1421
+ type KeyFilterFunction<T extends object = object> = (value: ValueOf<T>, key: KeyOf<T>, obj: T) => boolean;
1422
+ /**
1423
+ * Functions can use this type to accept either an array of keys or a
1424
+ * filter function.
1425
+ */
1426
+ type KeyFilter<T extends object = object, Key extends keyof any = keyof any> = KeyFilterFunction<T> | readonly Key[];
1427
+ /**
1428
+ * Extract the keys of an object that pass a filter.
1429
+ */
1430
+ type FilteredKeys<T extends object, F extends KeyFilter<T> | null | undefined> = Extract<keyof T, F extends readonly any[] ? F[number] : any>;
1431
+ /**
1432
+ * Returns true if the key is in the “keys array” or if the “filter
1433
+ * function” returns true. This function is useful when creating other
1434
+ * functions that need to enumerate an object or array and filter keys
1435
+ * in a flexible manner. Using it directly in everyday code is not
1436
+ * recommended.
1437
+ *
1438
+ * @see https://radashi-org.github.io/reference/object/filterKey
1439
+ * @example
1440
+ * ```ts
1441
+ * const a = { a: 1, b: 2, c: 3 }
1442
+ * filterKey(a, 'a', ['a', 'b'])
1443
+ * // => true
1444
+ * filterKey(a, 'a', ['a', 'b'])
1445
+ * // => true
1446
+ * ```
1447
+ */
1448
+ declare function filterKey<T extends object>(obj: T, key: keyof T, filter: KeyFilter<T, keyof T> | null | undefined): boolean;
1449
+ declare function filterKey(obj: object, key: keyof any, filter: KeyFilter | null | undefined): boolean;
1450
+
1451
+ /**
1452
+ * Dynamically get a nested value from an array or object with a
1453
+ * string.
1454
+ *
1455
+ * @see https://radashi-org.github.io/reference/object/get
1456
+ * @example
1457
+ * ```ts
1458
+ * const person = {
1459
+ * name: 'John',
1460
+ * friends: [{ name: 'Jane' }]
1461
+ * }
1462
+ *
1463
+ * get(person, 'friends[0].name')
1464
+ * // => 'Jane'
1465
+ * ```
1466
+ */
1467
+ declare function get<TDefault = unknown>(value: any, path: string, defaultValue?: TDefault): TDefault;
744
1468
 
745
1469
  /**
746
1470
  * Returns a new object whose keys are the values of the given object
747
1471
  * and its values are the keys of the given object.
1472
+ *
1473
+ * @see https://radashi-org.github.io/reference/object/invert
1474
+ * @example
1475
+ * ```ts
1476
+ * const a = { a: 1, b: 2, c: 3 }
1477
+ * invert(a)
1478
+ * // => { 1: 'a', 2: 'b', 3: 'c' }
1479
+ * ```
748
1480
  */
749
1481
  declare function invert<TKey extends string | number | symbol, TValue extends string | number | symbol>(obj: Record<TKey, TValue>): Record<TValue, TKey>;
750
1482
 
751
1483
  /**
752
1484
  * Get a string list of all key names that exist in an object (deep).
753
1485
  *
1486
+ * @see https://radashi-org.github.io/reference/object/keys
1487
+ * @example
754
1488
  * ```ts
755
1489
  * keys({ name: 'ra' }) // ['name']
756
1490
  *
@@ -761,30 +1495,74 @@ declare function invert<TKey extends string | number | symbol, TValue extends st
761
1495
  declare function keys(value: object): string[];
762
1496
 
763
1497
  /**
764
- * Convert an object to a list, mapping each entry into a list item
1498
+ * Convert an object to a list, mapping each entry into a list item.
1499
+ *
1500
+ * @see https://radashi-org.github.io/reference/object/listify
1501
+ * @example
1502
+ * ```ts
1503
+ * const a = { a: 1, b: 2, c: 3 }
1504
+ * listify(a, (key, value) => ({ key, value }))
1505
+ * // => [
1506
+ * // { key: 'a', value: 1 },
1507
+ * // { key: 'b', value: 2 },
1508
+ * // { key: 'c', value: 3 }
1509
+ * // ]
1510
+ * ```
765
1511
  */
766
1512
  declare function listify<Value, Key extends string | number | symbol, Item>(obj: Record<Key, Value>, toItem: (key: Key, value: Value) => Item): Item[];
767
1513
 
768
- type LowercasedKeys<T extends Record<string, any>> = {
1514
+ type LowercaseKeys<T extends Record<string, any>> = {
769
1515
  [P in keyof T & string as Lowercase<P>]: T[P];
770
1516
  };
771
1517
  /**
772
- * Convert all keys in an object to lower case
1518
+ * Convert all keys in an object to lower case.
1519
+ *
1520
+ * @see https://radashi-org.github.io/reference/object/lowerize
1521
+ * @example
1522
+ * ```ts
1523
+ * const a = { A: 1, B: 2, C: 3 }
1524
+ * lowerize(a)
1525
+ * // => { a: 1, b: 2, c: 3 }
1526
+ * ```
773
1527
  */
774
- declare function lowerize<T extends Record<string, any>>(obj: T): LowercasedKeys<T>;
1528
+ declare function lowerize<T extends Record<string, any>>(obj: T): LowercaseKeys<T>;
775
1529
 
776
1530
  /**
777
- * Map over all the keys to create a new object
1531
+ * Map over all the keys to create a new object.
1532
+ *
1533
+ * @see https://radashi-org.github.io/reference/object/mapEntries
1534
+ * @example
1535
+ * ```ts
1536
+ * const a = { a: 1, b: 2, c: 3 }
1537
+ * mapEntries(a, (key, value) => [value, key])
1538
+ * // => { 1: 'a', 2: 'b', 3: 'c' }
1539
+ * ```
778
1540
  */
779
1541
  declare function mapEntries<TKey extends string | number | symbol, TValue, TNewKey extends string | number | symbol, TNewValue>(obj: Record<TKey, TValue>, toEntry: (key: TKey, value: TValue) => [TNewKey, TNewValue]): Record<TNewKey, TNewValue>;
780
1542
 
781
1543
  /**
782
- * Map over all the keys of an object to return a new object
1544
+ * Map over all the keys of an object to return a new object.
1545
+ *
1546
+ * @see https://radashi-org.github.io/reference/object/mapKeys
1547
+ * @example
1548
+ * ```ts
1549
+ * const a = { a: 1, b: 2, c: 3 }
1550
+ * mapKeys(a, (key, value) => key + value)
1551
+ * // => { a1: 1, b2: 2, c3: 3 }
1552
+ * ```
783
1553
  */
784
1554
  declare function mapKeys<TValue, TKey extends string | number | symbol, TNewKey extends string | number | symbol>(obj: Record<TKey, TValue>, mapFunc: (key: TKey, value: TValue) => TNewKey): Record<TNewKey, TValue>;
785
1555
 
786
1556
  /**
787
- * Map over all the keys to create a new object
1557
+ * Map over all the keys to create a new object.
1558
+ *
1559
+ * @see https://radashi-org.github.io/reference/object/mapValues
1560
+ * @example
1561
+ * ```ts
1562
+ * const a = { a: 1, b: 2, c: 3 }
1563
+ * mapValues(a, (value, key) => value * 2)
1564
+ * // => { a: 2, b: 4, c: 6 }
1565
+ * ```
788
1566
  */
789
1567
  declare function mapValues<TValue, TKey extends string | number | symbol, TNewValue>(obj: {
790
1568
  [K in TKey]: TValue;
@@ -799,19 +1577,47 @@ declare function mapValues<TValue, TKey extends string | number | symbol, TNewVa
799
1577
 
800
1578
  /**
801
1579
  * Omit a list of properties from an object returning a new object
802
- * with the properties that remain
1580
+ * with the properties that remain.
1581
+ *
1582
+ * @see https://radashi-org.github.io/reference/object/omit
1583
+ * @example
1584
+ * ```ts
1585
+ * const a = { a: 1, b: 2, c: 3 }
1586
+ * omit(a, ['b'])
1587
+ * // => { a: 1, c: 3 }
1588
+ * ```
803
1589
  */
804
1590
  declare function omit<T, TKeys extends keyof T>(obj: T, keys: TKeys[]): Omit<T, TKeys>;
805
1591
 
806
1592
  /**
807
- * Pick a list of properties from an object into a new object
1593
+ * Pick a list of properties from an object into a new object.
1594
+ *
1595
+ * ⚠️ When used with a predicate function, `pick` is potentially
1596
+ * unsafe, because of partial type matching performed by TypeScript.
1597
+ * If you pass an object with more properties than its TypeScript type
1598
+ * has listed, the `value` and `key` parameter types of your callback
1599
+ * will be inaccurate.
1600
+ *
1601
+ * @see https://radashi-org.github.io/reference/object/pick
1602
+ * @example
1603
+ * ```ts
1604
+ * const a = { a: 1, b: 2, c: 3 }
1605
+ *
1606
+ * pick(a, ['a', 'c'])
1607
+ * // => { a: 1, c: 3 }
1608
+ *
1609
+ * pick(a, (value, key) => value > 1)
1610
+ * // => { b: 2, c: 3 }
1611
+ * ```
808
1612
  */
809
- declare function pick<T extends object, TKeys extends keyof T>(obj: T, keys: TKeys[]): Pick<T, TKeys>;
1613
+ declare function pick<T extends object, F extends KeyFilter<T, keyof T>>(obj: T, filter: F): Pick<T, FilteredKeys<T, F>>;
810
1614
 
811
1615
  /**
812
1616
  * Opposite of get, dynamically set a nested value into an object
813
1617
  * using a key path. Does not modify the given initial object.
814
1618
  *
1619
+ * @see https://radashi-org.github.io/reference/object/set
1620
+ * @example
815
1621
  * ```ts
816
1622
  * set({}, 'name', 'ra') // => { name: 'ra' }
817
1623
  * set({}, 'cards[0].value', 2) // => { cards: [{ value: 2 }] }
@@ -822,29 +1628,181 @@ declare function set<T extends object, K>(initial: T, path: string, value: K): T
822
1628
  /**
823
1629
  * Removes (shakes out) undefined entries from an object. Optional
824
1630
  * second argument shakes out values by custom evaluation.
1631
+ *
1632
+ * @see https://radashi-org.github.io/reference/object/shake
1633
+ * @example
1634
+ * ```ts
1635
+ * const a = { a: 1, b: undefined, c: 3 }
1636
+ * shake(a)
1637
+ * // => { a: 1, c: 3 }
1638
+ * ```
825
1639
  */
826
1640
  declare function shake<T extends object>(obj: T, filter?: (value: T[keyof T]) => boolean): T;
827
1641
 
828
- type UppercasedKeys<T extends Record<string, any>> = {
1642
+ interface TraverseOptions<Key = string | number | symbol> {
1643
+ /**
1644
+ * A function that returns the keys of the object to be traversed.
1645
+ *
1646
+ * @default Object.keys
1647
+ */
1648
+ ownKeys?: ((parent: object) => Iterable<Key>) | null;
1649
+ /**
1650
+ * When true, the visitor callback will be invoked for the root object.
1651
+ *
1652
+ * @default false
1653
+ */
1654
+ rootNeedsVisit?: boolean | null;
1655
+ }
1656
+ /**
1657
+ * Recursively visit each property of an object (or each element of an
1658
+ * array) and its nested objects or arrays. By default, the only
1659
+ * nested objects to be traversed are plain objects and arrays.
1660
+ *
1661
+ * @see https://radashi-org.github.io/reference/object/traverse
1662
+ * @example
1663
+ * ```ts
1664
+ * import { traverse } from 'radashi'
1665
+ *
1666
+ * const root = { a: 1, b: { c: { d: [2] }, e: 3 } }
1667
+ *
1668
+ * traverse(root, (value, key, parent, context) => {
1669
+ * console.log(key, '=>', value)
1670
+ * })
1671
+ * // Logs the following:
1672
+ * // a => 1
1673
+ * // b => { … }
1674
+ * // c => { … }
1675
+ * // d => [ 2 ]
1676
+ * // 0 => 2
1677
+ * // e => 3
1678
+ * ```
1679
+ */
1680
+ declare function traverse(root: object, visitor: TraverseVisitor, options?: (TraverseOptions & {
1681
+ rootNeedsVisit?: null;
1682
+ }) | null, outerContext?: TraverseContext): boolean;
1683
+ declare function traverse(root: object, visitor: TraverseVisitor<keyof any | null>, options?: TraverseOptions<keyof any | null> | null, outerContext?: TraverseContext<keyof any | null>): boolean;
1684
+ /**
1685
+ * The visitor callback for the `traverse` function.
1686
+ */
1687
+ type TraverseVisitor<Key = keyof any> = (value: unknown, key: Key, parent: object, context: TraverseContext<Key>, options: TraverseOptions<Key> & {
1688
+ rootNeedsVisit?: null;
1689
+ }) => (() => boolean | void) | boolean | void;
1690
+ /**
1691
+ * The context object for the `traverse` function.
1692
+ */
1693
+ interface TraverseContext<Key = keyof any> {
1694
+ /**
1695
+ * The current value being traversed.
1696
+ */
1697
+ readonly value: unknown;
1698
+ /**
1699
+ * The property key or index with which the current value was found.
1700
+ */
1701
+ readonly key: Key;
1702
+ /**
1703
+ * The parent object of the current value.
1704
+ */
1705
+ readonly parent: object;
1706
+ /**
1707
+ * The stack of parent objects. The last object is the current
1708
+ * parent.
1709
+ *
1710
+ * ⚠️ This array must not be mutated directly or referenced outside
1711
+ * the `visitor` callback. If that's necessary, you'll want to clone
1712
+ * it first.
1713
+ */
1714
+ readonly parents: readonly object[];
1715
+ /**
1716
+ * The path to the `parent` object. The last key is the current key.
1717
+ *
1718
+ * ⚠️ This array must not be mutated directly or referenced outside
1719
+ * the `visitor` callback. If that's necessary, you'll want to clone
1720
+ * it first.
1721
+ */
1722
+ readonly path: readonly (keyof any)[];
1723
+ /**
1724
+ * When the current value is a traversable object/iterable, this
1725
+ * function can be used to skip traversing it altogether.
1726
+ *
1727
+ * If the `obj` argument is provided, it marks the given object as
1728
+ * skipped (instead of the current value), preventing it from being
1729
+ * traversed.
1730
+ */
1731
+ readonly skip: (obj?: object) => void;
1732
+ readonly skipped: ReadonlySet<unknown>;
1733
+ }
1734
+
1735
+ type UppercaseKeys<T extends Record<string, any>> = {
829
1736
  [P in keyof T & string as Uppercase<P>]: T[P];
830
1737
  };
831
1738
  /**
832
- * Convert all keys in an object to upper case
1739
+ * Convert all keys in an object to upper case.
1740
+ *
1741
+ * @see https://radashi-org.github.io/reference/object/upperize
1742
+ * @example
1743
+ * ```ts
1744
+ * const a = { a: 1, b: 2, c: 3 }
1745
+ * upperize(a)
1746
+ * // => { A: 1, B: 2, C: 3 }
1747
+ * ```
833
1748
  */
834
- declare function upperize<T extends Record<string, any>>(obj: T): UppercasedKeys<T>;
1749
+ declare function upperize<T extends Record<string, any>>(obj: T): UppercaseKeys<T>;
835
1750
 
836
1751
  /**
837
- * Draw a random item from a list. Returns null if the list is empty
1752
+ * “Draw” a random item from an array. The item is not removed from
1753
+ * the array. Returns `null` if the array is empty.
1754
+ *
1755
+ * @see https://radashi-org.github.io/reference/random/draw
1756
+ * @example
1757
+ * ```ts
1758
+ * const numbers = [1, 2, 3]
1759
+ *
1760
+ * draw(numbers)
1761
+ * // => 2
1762
+ * numbers
1763
+ * // => [1, 2, 3]
1764
+ * ```
838
1765
  */
839
1766
  declare function draw<T>(array: readonly T[]): T | null;
840
1767
 
841
1768
  /**
842
- * Generates a random number between min and max
1769
+ * Generates a random integer between min and max. Both min and max
1770
+ * are inclusive.
1771
+ *
1772
+ * @see https://radashi-org.github.io/reference/random/random
1773
+ * @example
1774
+ * ```ts
1775
+ * random(1, 10)
1776
+ * // => 5
1777
+ * ```
843
1778
  */
844
1779
  declare function random(min: number, max: number): number;
845
1780
 
846
- declare function shuffle<T>(array: readonly T[]): T[];
1781
+ /**
1782
+ * Clone an array and shuffle its items randomly.
1783
+ *
1784
+ * @see https://radashi-org.github.io/reference/random/shuffle
1785
+ * @example
1786
+ * ```ts
1787
+ * const numbers = [1, 2, 3, 4, 5]
1788
+ * const shuffled = shuffle(numbers)
1789
+ * // => [2, 1, 4, 5, 3]
1790
+ * shuffled !== numbers
1791
+ * // => true
1792
+ * ```
1793
+ */
1794
+ declare function shuffle<T>(array: readonly T[], random?: (min: number, max: number) => number): T[];
847
1795
 
1796
+ /**
1797
+ * Generate a random string of a given length.
1798
+ *
1799
+ * @see https://radashi-org.github.io/reference/random/uid
1800
+ * @example
1801
+ * ```ts
1802
+ * uid(8)
1803
+ * // => "a3fSDf32"
1804
+ * ```
1805
+ */
848
1806
  declare function uid(length: number, specials?: string): string;
849
1807
 
850
1808
  interface Series<T> {
@@ -859,46 +1817,82 @@ interface Series<T> {
859
1817
  /**
860
1818
  * Creates a series object around a list of values that should be
861
1819
  * treated with order.
1820
+ *
1821
+ * @see https://radashi-org.github.io/reference/series/series
1822
+ * @example
1823
+ * ```ts
1824
+ * const numbers = series([1, 2, 3])
1825
+ *
1826
+ * numbers.first() // => 1
1827
+ * numbers.last() // => 3
1828
+ * numbers.next(2) // => 3
1829
+ * numbers.previous(2) // => 1
1830
+ * numbers.spin(2, 1) // => 3
1831
+ * numbers.spin(2, -1) // => 1
1832
+ * ```
862
1833
  */
863
1834
  declare const series: <T>(items: readonly T[], toKey?: (item: T) => string | symbol) => Series<T>;
864
1835
 
865
1836
  /**
866
- * Formats the given string in camel case fashion
1837
+ * Formats the given string in camel case fashion.
867
1838
  *
868
- * camel('hello world') -> 'helloWorld' camel('va va-VOOM') ->
869
- * 'vaVaVoom' camel('helloWorld') -> 'helloWorld'
1839
+ * @see https://radashi-org.github.io/reference/string/camel
1840
+ * @example
1841
+ * ```ts
1842
+ * camel('hello world') // => 'helloWorld'
1843
+ * camel('va va-VOOM') // => 'vaVaVoom'
1844
+ * camel('helloworld') // => 'helloWorld'
1845
+ * ```
870
1846
  */
871
1847
  declare function camel(str: string): string;
872
1848
 
873
1849
  /**
874
- * Capitalize the first word of the string
1850
+ * Capitalize the first word of the string.
875
1851
  *
876
- * capitalize('hello') -> 'Hello' capitalize('va va voom') -> 'Va va
877
- * voom'
1852
+ * @see https://radashi-org.github.io/reference/string/capitalize
1853
+ * @example
1854
+ * ```ts
1855
+ * capitalize('hello') // => 'Hello'
1856
+ * capitalize('va va voom') // => 'Va va voom'
1857
+ * ```
878
1858
  */
879
1859
  declare function capitalize(str: string): string;
880
1860
 
881
1861
  /**
882
- * Formats the given string in dash case fashion
1862
+ * Formats the given string in dash case fashion.
883
1863
  *
884
- * dash('hello world') -> 'hello-world' dash('va va_VOOM') ->
885
- * 'va-va-voom' dash('helloWord') -> 'hello-word'
1864
+ * @see https://radashi-org.github.io/reference/string/dash
1865
+ * @example
1866
+ * ```ts
1867
+ * dash('hello world') // => 'hello-world'
1868
+ * dash('va va_VOOM') // => 'va-va-voom'
1869
+ * dash('helloWord') // => 'hello-word'
1870
+ * ```
886
1871
  */
887
1872
  declare function dash(str: string): string;
888
1873
 
889
1874
  /**
890
- * Formats the given string in pascal case fashion
1875
+ * Formats the given string in pascal case fashion.
891
1876
  *
892
- * pascal('hello world') -> 'HelloWorld' pascal('va va boom') ->
893
- * 'VaVaBoom'
1877
+ * @see https://radashi-org.github.io/reference/string/pascal
1878
+ * @example
1879
+ * ```ts
1880
+ * pascal('hello world') // => 'HelloWorld'
1881
+ * pascal('va va boom') // => 'VaVaBoom'
1882
+ * ```
894
1883
  */
895
1884
  declare function pascal(str: string): string;
896
1885
 
897
1886
  /**
898
- * Formats the given string in snake case fashion
1887
+ * Formats the given string in snake case fashion.
899
1888
  *
900
- * snake('hello world') -> 'hello_world' snake('va va-VOOM') ->
901
- * 'va_va_voom' snake('helloWord') -> 'hello_world'
1889
+ * @see https://radashi-org.github.io/reference/string/snake
1890
+ * @example
1891
+ * ```ts
1892
+ * snake('hello world') // => 'hello_world'
1893
+ * snake('va va-VOOM') // => 'va_va_voom'
1894
+ * snake('helloWorld') // => 'hello_world'
1895
+ * ```
902
1896
  */
903
1897
  declare function snake(str: string, options?: {
904
1898
  splitOnNumber?: boolean;
@@ -908,6 +1902,8 @@ declare function snake(str: string, options?: {
908
1902
  * Replace data by name in template strings. The default expression
909
1903
  * looks for `{{name}}` to identify names.
910
1904
  *
1905
+ * @see https://radashi-org.github.io/reference/string/template
1906
+ * @example
911
1907
  * ```ts
912
1908
  * template('Hello, {{name}}', { name: 'Radashi' })
913
1909
  * // "Hello, Radashi"
@@ -919,11 +1915,16 @@ declare function snake(str: string, options?: {
919
1915
  declare function template(str: string, data: Record<string, any>, regex?: RegExp): string;
920
1916
 
921
1917
  /**
922
- * Formats the given string in title case fashion
1918
+ * Formats the given string in title case fashion.
923
1919
  *
924
- * title('hello world') -> 'Hello World' title('va_va_boom') -> 'Va Va
925
- * Boom' title('root-hook') -> 'Root Hook' title('queryItems') ->
926
- * 'Query Items'
1920
+ * @see https://radashi-org.github.io/reference/string/title
1921
+ * @example
1922
+ * ```ts
1923
+ * title('hello world') // => 'Hello World'
1924
+ * title('va_va_boom') // => 'Va Va Boom'
1925
+ * title('root-hook') // => 'Root Hook'
1926
+ * title('queryItems') // => 'Query Items'
1927
+ * ```
927
1928
  */
928
1929
  declare function title(str: string | null | undefined): string;
929
1930
 
@@ -932,7 +1933,9 @@ declare function title(str: string | null | undefined): string;
932
1933
  * the builtin trim function but accepts other characters you would
933
1934
  * like to trim and trims multiple characters.
934
1935
  *
935
- * ```typescript
1936
+ * @see https://radashi-org.github.io/reference/string/trim
1937
+ * @example
1938
+ * ```ts
936
1939
  * trim(' hello ') // => 'hello'
937
1940
  * trim('__hello__', '_') // => 'hello'
938
1941
  * trim('/repos/:owner/:repo/', '/') // => 'repos/:owner/:repo'
@@ -941,48 +1944,436 @@ declare function title(str: string | null | undefined): string;
941
1944
  */
942
1945
  declare function trim(str: string | null | undefined, charsToTrim?: string): string;
943
1946
 
944
- declare const isArray: (value: unknown) => value is readonly any[];
1947
+ /**
1948
+ * Literally just `Array.isArray` but with better type inference.
1949
+ *
1950
+ * @see https://radashi-org.github.io/reference/typed/isArray
1951
+ * @example
1952
+ * ```ts
1953
+ * isArray([]) // => true
1954
+ * isArray('hello') // => false
1955
+ * ```
1956
+ */
1957
+ declare const isArray: <Input>(value: Input) => value is ExtractArray<Input>;
1958
+ /**
1959
+ * An absurdly complicated but accurate type for extracting Array types.
1960
+ *
1961
+ * It's like `Extract<T, any[]>` but better with edge cases.
1962
+ */
1963
+ type ExtractArray<T> = T extends any ? [StrictExtract<T, readonly any[]>] extends [readonly any[]] ? Extract<T, readonly any[]> : [StrictExtract<T, any[]>] extends [any[]] ? Extract<T, any[]> : unknown[] extends T ? unknown[] : never : never;
1964
+
1965
+ declare function isBoolean(value: unknown): value is boolean;
945
1966
 
946
- declare function isDate(value: any): value is Date;
1967
+ /**
1968
+ * Return true if the given value is a Date object.
1969
+ *
1970
+ * Instances from [other realms][1] are also supported.
1971
+ *
1972
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof#instanceof_and_multiple_realms
1973
+ *
1974
+ * @see https://radashi-org.github.io/reference/typed/isDate
1975
+ * @example
1976
+ * ```ts
1977
+ * isDate(new Date()) // => true
1978
+ * isDate('hello') // => false
1979
+ * ```
1980
+ */
1981
+ declare function isDate(value: unknown): value is Date;
947
1982
 
1983
+ /**
1984
+ * Return true if the given value is empty.
1985
+ *
1986
+ * Empty values include:
1987
+ * - `null`
1988
+ * - `undefined`
1989
+ * - `0`
1990
+ * - `NaN`
1991
+ * - `''`
1992
+ * - `[]`
1993
+ * - `{}`
1994
+ * - invalid `Date` time
1995
+ * - object with `length` property of `0`
1996
+ * - object with `size` property of `0`
1997
+ * - object with no enumerable keys
1998
+ *
1999
+ * @see https://radashi-org.github.io/reference/typed/isEmpty
2000
+ * @example
2001
+ * ```ts
2002
+ * isEmpty(0) // => true
2003
+ * isEmpty(null) // => true
2004
+ * isEmpty(undefined) // => true
2005
+ * isEmpty([]) // => true
2006
+ * isEmpty({}) // => true
2007
+ * ```
2008
+ */
948
2009
  declare function isEmpty(value: any): boolean;
949
2010
 
2011
+ /**
2012
+ * Return true if the given values are equal.
2013
+ *
2014
+ * To determine equality, `Object.is()` is used first. If it returns
2015
+ * false, we do the following special checks:
2016
+ * - `Date` and `Date` with the same time
2017
+ * - `RegExp` and `RegExp` with the same pattern/flags
2018
+ * - object with the same keys and values (recursive)
2019
+ *
2020
+ * @see https://radashi-org.github.io/reference/typed/isEqual
2021
+ * @example
2022
+ * ```ts
2023
+ * isEqual(0, 0) // => true
2024
+ * isEqual(0, 1) // => false
2025
+ * ```
2026
+ */
950
2027
  declare function isEqual<TType>(x: TType, y: TType): boolean;
951
2028
 
2029
+ /**
2030
+ * Return true if the given value is a number that is not an integer.
2031
+ *
2032
+ * @see https://radashi-org.github.io/reference/typed/isFloat
2033
+ * @example
2034
+ * ```ts
2035
+ * isFloat(0) // => false
2036
+ * isFloat(0.1) // => true
2037
+ * ```
2038
+ */
952
2039
  declare function isFloat(value: any): value is number;
953
2040
 
2041
+ /**
2042
+ * Return true if the given value is a function.
2043
+ *
2044
+ * @see https://radashi-org.github.io/reference/typed/isFunction
2045
+ * @example
2046
+ * ```ts
2047
+ * isFunction(0) // => false
2048
+ * isFunction(() => {}) // => true
2049
+ * isFunction(function() {}) // => true
2050
+ * isFunction(async function() {}) // => true
2051
+ * isFunction(class {}) // => false
2052
+ * ```
2053
+ */
954
2054
  declare function isFunction(value: any): value is Function;
955
2055
 
956
- declare function isInt(value: any): value is number;
2056
+ /**
2057
+ * Literally just `Number.isInteger` with a better type.
2058
+ *
2059
+ * @see https://radashi-org.github.io/reference/typed/isInt
2060
+ * @example
2061
+ * ```ts
2062
+ * isInt(0) // => true
2063
+ * isInt(0.1) // => false
2064
+ * ```
2065
+ */
2066
+ declare const isInt: (value: unknown) => value is number;
957
2067
 
2068
+ /**
2069
+ * Return true if the given value is a string that can be parsed as an
2070
+ * integer.
2071
+ *
2072
+ * @see https://radashi-org.github.io/reference/typed/isIntString
2073
+ * @example
2074
+ * ```ts
2075
+ * isIntString('0') // => true
2076
+ * isIntString('0.1') // => false
2077
+ * isIntString('+1') // => false
2078
+ * ```
2079
+ */
958
2080
  declare function isIntString(value: any): value is string;
959
2081
 
960
- declare function isNumber(value: any): value is number;
2082
+ declare function isIterable(value: unknown): value is Iterable<unknown>;
961
2083
 
962
- declare function isObject(value: any): value is object;
2084
+ /**
2085
+ * Return true if the given value is a Map.
2086
+ *
2087
+ * Instances from [other realms][1] are also supported.
2088
+ *
2089
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof#instanceof_and_multiple_realms
2090
+ *
2091
+ * @see https://radashi-org.github.io/reference/typed/isMap
2092
+ * @example
2093
+ * ```ts
2094
+ * isMap(new Map()) // => true
2095
+ * isMap(new Set()) // => false
2096
+ * ```
2097
+ */
2098
+ declare function isMap<Input>(value: Input): value is ExtractMap<Input>;
2099
+ /**
2100
+ * An absurdly complicated but accurate type for extracting Map types.
2101
+ *
2102
+ * It's like `Extract<T, Map<any, any>>` but better with edge cases.
2103
+ */
2104
+ type ExtractMap<T> = T extends any ? [StrictExtract<T, ReadonlyMap<unknown, unknown>>] extends [
2105
+ ReadonlyMap<unknown, unknown>
2106
+ ] ? Extract<T, ReadonlyMap<unknown, unknown>> : [StrictExtract<T, Map<unknown, unknown>>] extends [Map<unknown, unknown>] ? Extract<T, Map<unknown, unknown>> : Map<unknown, unknown> extends T ? Map<unknown, unknown> : never : never;
2107
+
2108
+ /**
2109
+ * Return true if the given value is a number.
2110
+ *
2111
+ * @see https://radashi-org.github.io/reference/typed/isNumber
2112
+ * @example
2113
+ * ```ts
2114
+ * isNumber(0) // => true
2115
+ * isNumber('0') // => false
2116
+ * isNumber(NaN) // => false
2117
+ * ```
2118
+ */
2119
+ declare function isNumber(value: unknown): value is number;
2120
+
2121
+ /**
2122
+ * Returns true if `value` is a plain object, a class instance
2123
+ * (excluding built-in classes like Date/RegExp), or an
2124
+ * `Object.create(null)` result. Objects from [other realms][1] are
2125
+ * also supported.
2126
+ *
2127
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof#instanceof_and_multiple_realms
2128
+ *
2129
+ * @see https://radashi-org.github.io/reference/typed/isObject
2130
+ * @example
2131
+ * ```ts
2132
+ * isObject({}) // true
2133
+ * isObject(new Object()) // true
2134
+ * isObject(Object.create(null)) // true
2135
+ * isObject(new class {}) // true
2136
+ *
2137
+ * isObject([]) // false
2138
+ * isObject(/.+/g) // false
2139
+ * isObject(new Date()) // false
2140
+ * isObject(new Map()) // false
2141
+ * isObject(new Set()) // false
2142
+ * ```
2143
+ */
2144
+ declare function isObject(value: unknown): value is object;
963
2145
 
2146
+ /**
2147
+ * Return true if the given value is a plain object.
2148
+ *
2149
+ * @see https://radashi-org.github.io/reference/typed/isPlainObject
2150
+ * @example
2151
+ * ```ts
2152
+ * isPlainObject({}) // => true
2153
+ * isPlainObject(new Map()) // => false
2154
+ * ```
2155
+ */
964
2156
  declare function isPlainObject(value: any): value is object;
965
2157
 
966
2158
  /**
967
2159
  * Checks if the given value is primitive.
968
2160
  *
969
- * Primitive Types: number , string , boolean , symbol, bigint,
970
- * undefined, null
971
- *
972
- * @param {*} value value to check
973
- * @returns {boolean} result
2161
+ * Primitive types include:
2162
+ * - number
2163
+ * - string
2164
+ * - boolean
2165
+ * - symbol
2166
+ * - bigint
2167
+ * - undefined
2168
+ * - null
2169
+ *
2170
+ * @see https://radashi-org.github.io/reference/typed/isPrimitive
2171
+ * @example
2172
+ * ```ts
2173
+ * isPrimitive(0) // => true
2174
+ * isPrimitive(null) // => true
2175
+ * isPrimitive(undefined) // => true
2176
+ * isPrimitive('0') // => false
2177
+ * ```
974
2178
  */
975
2179
  declare function isPrimitive(value: any): boolean;
976
2180
 
977
2181
  /**
978
- * This is really a _best guess_ promise checking. You should probably
979
- * use Promise.resolve(value) to be 100% sure you're handling it
980
- * correctly.
2182
+ * Returns true if the value is a Promise or has a `then` method.
2183
+ *
2184
+ * @see https://radashi-org.github.io/reference/typed/isPromise
2185
+ * @example
2186
+ * ```ts
2187
+ * isPromise(Promise.resolve(1)) // => true
2188
+ * isPromise({ then() {} }) // => true
2189
+ * isPromise(1) // => false
2190
+ * ```
981
2191
  */
982
2192
  declare function isPromise(value: any): value is Promise<any>;
983
2193
 
984
- declare function isString(value: any): value is string;
2194
+ /**
2195
+ * Checks if the given value is a RegExp.
2196
+ *
2197
+ * Instances from [other realms][1] are also supported.
2198
+ *
2199
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof#instanceof_and_multiple_realms
2200
+ *
2201
+ * @see https://radashi-org.github.io/reference/typed/isRegExp
2202
+ * @example
2203
+ * ```ts
2204
+ * isRegExp(/abc/) // => true
2205
+ * isRegExp('abc') // => false
2206
+ * ```
2207
+ */
2208
+ declare function isRegExp(value: unknown): value is RegExp;
985
2209
 
986
- declare function isSymbol(value: any): value is symbol;
2210
+ /**
2211
+ * Checks if the given value is a Set.
2212
+ *
2213
+ * Instances from [other realms][1] are also supported.
2214
+ *
2215
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof#instanceof_and_multiple_realms
2216
+ *
2217
+ * @see https://radashi-org.github.io/reference/typed/isSet
2218
+ * @example
2219
+ * ```ts
2220
+ * isSet(new Set([1, 2, 3])) // => true
2221
+ * isSet(new Map([1, 2, 3])) // => false
2222
+ * ```
2223
+ */
2224
+ declare function isSet<Input>(value: Input): value is ExtractSet<Input>;
2225
+ /**
2226
+ * An absurdly complicated but accurate type for extracting Set types.
2227
+ *
2228
+ * It's like `Extract<T, Set<any>>` but better with edge cases.
2229
+ */
2230
+ type ExtractSet<T> = T extends any ? [StrictExtract<T, ReadonlySet<unknown>>] extends [ReadonlySet<unknown>] ? Extract<T, ReadonlySet<unknown>> : [StrictExtract<T, Set<unknown>>] extends [Set<unknown>] ? Extract<T, Set<unknown>> : Set<unknown> extends T ? Set<unknown> : never : never;
2231
+
2232
+ /**
2233
+ * Checks if the given value is a string.
2234
+ *
2235
+ * @see https://radashi-org.github.io/reference/typed/isString
2236
+ * @example
2237
+ * ```ts
2238
+ * isString('abc') // => true
2239
+ * isString(123) // => false
2240
+ * ```
2241
+ */
2242
+ declare function isString(value: unknown): value is string;
2243
+
2244
+ /**
2245
+ * Checks if the given value is a symbol.
2246
+ *
2247
+ * @see https://radashi-org.github.io/reference/typed/isSymbol
2248
+ * @example
2249
+ * ```ts
2250
+ * isSymbol(Symbol('abc')) // => true
2251
+ * isSymbol('abc') // => false
2252
+ * ```
2253
+ */
2254
+ declare function isSymbol(value: unknown): value is symbol;
2255
+
2256
+ /**
2257
+ * Compare the given tag to the result of `Object.prototype.toString`.
2258
+ *
2259
+ * ⚠️ You probably won't use this except when implementing another type guard.
2260
+ *
2261
+ * @internal
2262
+ * @example
2263
+ * ```ts
2264
+ * isTagged('foo', '[object String]') // true
2265
+ * ```
2266
+ */
2267
+ declare function isTagged(value: unknown, tag: string): boolean;
2268
+
2269
+ /**
2270
+ * Checks if the given value is a WeakMap.
2271
+ *
2272
+ * Instances from [other realms][1] are also supported.
2273
+ *
2274
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof#instanceof_and_multiple_realms
2275
+ *
2276
+ * @see https://radashi-org.github.io/reference/typed/isWeakMap
2277
+ * @example
2278
+ * ```ts
2279
+ * isWeakMap(new WeakMap()) // => true
2280
+ * isWeakMap(new Map()) // => false
2281
+ * ```
2282
+ */
2283
+ declare function isWeakMap<K extends WeakKey = WeakKey, V = unknown>(value: unknown): value is WeakMap<K, V>;
2284
+
2285
+ /**
2286
+ * Checks if the given value is a WeakSet.
2287
+ *
2288
+ * Instances from [other realms][1] are also supported.
2289
+ *
2290
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof#instanceof_and_multiple_realms
2291
+ *
2292
+ * @see https://radashi-org.github.io/reference/typed/isWeakSet
2293
+ * @example
2294
+ *
2295
+ * ```ts
2296
+ * isWeakSet(new WeakSet()) // => true
2297
+ * isWeakSet(new Set()) // => false
2298
+ * ```
2299
+ */
2300
+ declare function isWeakSet<T extends WeakKey = WeakKey>(value: unknown): value is WeakSet<T>;
2301
+
2302
+ /**
2303
+ * The `Any` class does not exist at runtime. It's used in type
2304
+ * definitions to detect an `any` type.
2305
+ *
2306
+ * ```ts
2307
+ * type IsAny<T> = [T] extends [Any] ? 'is any' : 'is not any'
2308
+ * ```
2309
+ */
2310
+ declare class Any {
2311
+ private any;
2312
+ }
2313
+ /**
2314
+ * Extracts `T` if `T` is not `any`, otherwise `never`.
2315
+ *
2316
+ * ```ts
2317
+ * type A = ExtractNotAny<any, string>
2318
+ * // ^? never
2319
+ * type B = ExtractNotAny<string | number, string>
2320
+ * // ^? string
2321
+ * ```
2322
+ */
2323
+ type ExtractNotAny<T, U> = Extract<[T] extends [Any] ? never : T, U>;
2324
+ type SwitchAny<T, U> = [T] extends [Any] ? U : T;
2325
+ type SwitchNever<T, U> = [T] extends [never] ? U : T;
2326
+ /**
2327
+ * Extract types in `T` that are assignable to `U`. Coerce `any` and
2328
+ * `never` types to unknown.
2329
+ */
2330
+ type StrictExtract<T, U> = SwitchNever<Extract<SwitchAny<T, unknown>, U>, unknown>;
2331
+ /**
2332
+ * Resolve a type union of property name literals within type `T`
2333
+ * whose property values are assignable to type `CompatibleValue`.
2334
+ *
2335
+ * Use case: “I want to know which properties of `T` are compatible
2336
+ * with `CompatibleValue`.”
2337
+ */
2338
+ type CompatibleProperty<T, CompatibleValue> = [T] extends [Any] ? keyof any : T extends null | undefined ? never : {
2339
+ [P in keyof BoxedPrimitive<T>]: BoxedPrimitive<T>[P] extends CompatibleValue ? P : never;
2340
+ }[keyof BoxedPrimitive<T>];
2341
+ /**
2342
+ * Coerce a primitive type to its boxed equivalent.
2343
+ *
2344
+ * @example
2345
+ * ```ts
2346
+ * type A = BoxedPrimitive<string>
2347
+ * // ^? String
2348
+ * type B = BoxedPrimitive<number>
2349
+ * // ^? Number
2350
+ * ```
2351
+ */
2352
+ type BoxedPrimitive<T> = T extends string ? String : T extends number ? Number : T extends boolean ? Boolean : T extends bigint ? BigInt : T extends symbol ? Symbol : T;
2353
+ /**
2354
+ * A value that can be reliably compared with JavaScript comparison
2355
+ * operators (e.g. `>`, `>=`, etc).
2356
+ */
2357
+ type Comparable = number | string | bigint | {
2358
+ valueOf: () => number | string | bigint;
2359
+ } | {
2360
+ [Symbol.toPrimitive](hint: 'number'): number;
2361
+ } | {
2362
+ [Symbol.toPrimitive](hint: 'string'): string;
2363
+ };
2364
+ /**
2365
+ * Extract a string union of property names from type `T` whose value
2366
+ * can be compared with `>`, `>=`, etc.
2367
+ */
2368
+ type ComparableProperty<T> = CompatibleProperty<T, Comparable>;
2369
+ /**
2370
+ * A comparator function. It can be passed to the `sort` method of
2371
+ * arrays to sort the elements.
2372
+ *
2373
+ * Return a negative number to sort the “left” value before the “right”
2374
+ * value, a positive number to sort the “right” value before the “left”
2375
+ * value, and 0 to keep the order of the values.
2376
+ */
2377
+ type Comparator<T> = (left: T, right: T) => number;
987
2378
 
988
- export { AggregateError, type DebounceFunction, type KeyFilter, type KeyFilterFunction, type RetryOptions, type Series, type ThrottledFunction, all, alphabetical, assign, boil, callable, camel, capitalize, chain, clone, cluster, compose, construct, counting, crush, dash, debounce, defer, diff, draw, filterKey, first, flat, fork, get, group, guard, inRange, intersects, invert, isArray, isDate, isEmpty, isEqual, isFloat, isFunction, isInt, isIntString, isNumber, isObject, isPlainObject, isPrimitive, isPromise, isString, isSymbol, iterate, keys, last, list, listify, lowerize, map, mapEntries, mapKeys, mapValues, max, memo, merge, min, objectify, omit, parallel, partial, partob, pascal, pick, proxied, random, range, reduce, replace, replaceOrAppend, retry, select, series, set, shake, shift, shuffle, sift, sleep, snake, sort, sum, template, throttle, title, toFloat, toInt, toggle, trim, tryit as try, tryit, uid, unique, upperize, zip, zipToObject };
2379
+ export { AggregateError, Any, type BoxedPrimitive, type CastArray, type CastArrayIfExists, type CloningStrategy, type Comparable, type ComparableProperty, type Comparator, type ComparatorMapping, type CompatibleProperty, type DebounceFunction, DefaultCloningStrategy, type ExtractArray, type ExtractMap, type ExtractNotAny, type ExtractSet, FastCloningStrategy, type FilteredKeys, type Flip, type KeyFilter, type KeyFilterFunction, type LowercaseKeys, type MappedInput, type MappedOutput, type Mapping, type MappingFunction, type MemoOptions, type OnceFunction, type OptionalMapping, type RetryOptions, type Series, type StrictExtract, type SwitchAny, type SwitchNever, type ThrottledFunction, type TraverseContext, type TraverseOptions, type TraverseVisitor, type TryitResult, type UppercaseKeys, all, alphabetical, always, assign, boil, callable, camel, capitalize, castArray, castArrayIfExists, castComparator, castMapping, chain, clamp, clone, cloneDeep, cluster, compose, construct, counting, crush, dash, debounce, defer, diff, draw, filterKey, first, flat, flip, fork, get, group, guard, inRange, intersects, invert, isArray, isBoolean, isDate, isEmpty, isEqual, isFloat, isFunction, isInt, isIntString, isIterable, isMap, isNumber, isObject, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isString, isSymbol, isTagged, isWeakMap, isWeakSet, iterate, keys, last, lerp, list, listify, lowerize, map, mapEntries, mapKeys, mapValues, mapify, max, memo, merge, min, noop, objectify, omit, once, parallel, partial, partob, pascal, pick, proxied, random, range, reduce, replace, replaceOrAppend, retry, round, select, selectFirst, series, set, shake, shift, shuffle, sift, sleep, snake, sort, sum, template, throttle, title, toFloat, toInt, toggle, traverse, trim, tryit as try, tryit, uid, unique, unzip, upperize, zip, zipToObject };