radashi 12.2.0-beta.0dc9c8a → 12.2.0-beta.1ee40e2

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