@andrew_l/toolkit 0.3.2 → 0.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -115,7 +115,7 @@ declare function chunk<T>(list: readonly T[], size?: number): T[][];
115
115
  *
116
116
  * @group Array
117
117
  */
118
- declare function chunkSeries(list: number[], step?: number): number[][];
118
+ declare function chunkSeries(list: readonly number[], step?: number): number[][];
119
119
 
120
120
  /**
121
121
  * Computes the difference between arrays.
@@ -136,11 +136,7 @@ declare function chunkSeries(list: number[], step?: number): number[][];
136
136
  *
137
137
  * @group Array
138
138
  */
139
- declare function difference<T>(...arrays: readonly T[][]): T[];
140
-
141
- type MaybePropertyKey<T> = T extends object
142
- ? keyof T | PropertyKey
143
- : PropertyKey;
139
+ declare function difference<T>(...arrays: (readonly T[])[]): T[];
144
140
 
145
141
  type PropertyKeyLiteralToType<T> = T extends string
146
142
  ? string
@@ -156,10 +152,14 @@ type IsPropertyKey<T, V, L> = T extends object
156
152
  : L
157
153
  : PropertyKeyLiteralToType<L>;
158
154
 
159
- declare function groupBy<T, K extends MaybePropertyKey<T>>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, K>, T[]>;
155
+ type ToPropertyKey<T> = T extends PropertyKey ? T : string;
156
+
157
+ declare function groupBy<T, K extends keyof T>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, unknown>, T[]>;
158
+ declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, unknown>, T[]>;
160
159
  declare function groupBy<T, K>(array: readonly T[], keyBy: (item: T) => K, objectMode?: false): Map<K, T[]>;
161
- declare function groupBy<T, K extends MaybePropertyKey<T>>(array: readonly T[], keyBy: K, objectMode: true): Record<K, T[]>;
162
- declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: (item: T) => K, objectMode: true): Record<K, T[]>;
160
+ declare function groupBy<T, K extends keyof T>(array: readonly T[], keyBy: K, objectMode: true): Record<ToPropertyKey<T[K]>, T[]>;
161
+ declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: K, objectMode?: true): Record<ToPropertyKey<IsPropertyKey<T, K, unknown>>, T[]>;
162
+ declare function groupBy<T, K>(array: readonly T[], keyBy: (item: T) => K, objectMode: true): Record<ToPropertyKey<K>, T[]>;
163
163
 
164
164
  /**
165
165
  * Returns the intersection of arrays.
@@ -178,31 +178,18 @@ declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: (
178
178
  *
179
179
  * @group Array
180
180
  */
181
- declare function intersection<T>(...arrays: readonly T[][]): T[];
181
+ declare function intersection<T>(...arrays: (readonly T[])[]): T[];
182
182
 
183
- /**
184
- * Maps each element of an array based on a provided key.
185
- *
186
- * @example
187
- * const data = [
188
- * { id: 1, name: 'group 1' },
189
- * { id: 2, name: 'group 2' },
190
- * { id: 1, name: 'group 2' }
191
- * ];
192
- *
193
- * const result = keyBy(data, 'id');
194
- * console.log(Object.entries(result));
195
- * // [
196
- * // [1, [{ id: 1, name: 'group 1' }, { id: 1, name: 'group 2' }],
197
- * // [2, { id: 2, name: 'group 2' }],
198
- * // ]
199
- *
200
- * @group Array
201
- */
202
- declare function keyBy<T, K extends MaybePropertyKey<T>>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, K>, T>;
183
+ declare function intersectionBy<T>(keyBy: keyof T, ...arrays: (readonly T[])[]): T[];
184
+ declare function intersectionBy<T>(keyBy: PropertyKey, ...arrays: (readonly T[])[]): T[];
185
+ declare function intersectionBy<T>(keyBy: (item: T) => unknown, ...arrays: (readonly T[])[]): T[];
186
+
187
+ declare function keyBy<T, K extends keyof T>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, unknown>, T>;
188
+ declare function keyBy<T, K extends PropertyKey>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, unknown>, T[]>;
203
189
  declare function keyBy<T, K>(array: readonly T[], keyBy: (item: T) => K, objectMode?: false): Map<K, T>;
204
- declare function keyBy<T, K extends MaybePropertyKey<T>>(array: readonly T[], keyBy: K, objectMode: true): Record<K, T>;
205
- declare function keyBy<T, K extends PropertyKey>(array: readonly T[], keyBy: (item: T) => K, objectMode: true): Record<K, T>;
190
+ declare function keyBy<T, K extends keyof T>(array: readonly T[], keyBy: K, objectMode: true): Record<ToPropertyKey<T[K]>, T>;
191
+ declare function keyBy<T, K extends PropertyKey>(array: readonly T[], keyBy: K, objectMode?: true): Record<ToPropertyKey<IsPropertyKey<T, K, unknown>>, T>;
192
+ declare function keyBy<T, K>(array: readonly T[], keyBy: (item: T) => K, objectMode: true): Record<ToPropertyKey<K>, T>;
206
193
 
207
194
  /**
208
195
  * Sort array by multiple fields
@@ -350,7 +337,7 @@ declare const sum: (values: readonly number[]) => number;
350
337
  *
351
338
  * @group Array
352
339
  */
353
- declare function union<T>(...arrays: readonly T[][]): T[];
340
+ declare function union<T>(...arrays: (readonly T[])[]): T[];
354
341
 
355
342
  /**
356
343
  * Returns a new array with duplicates removed.
@@ -369,7 +356,7 @@ declare function union<T>(...arrays: readonly T[][]): T[];
369
356
  *
370
357
  * @group Array
371
358
  */
372
- declare function uniq<T extends any[]>(value: T): T;
359
+ declare function uniq<T>(value: readonly T[]): T[];
373
360
 
374
361
  /**
375
362
  * Extracts unique elements from an array based on a comparator function or property key.
@@ -415,7 +402,7 @@ declare function uniq<T extends any[]>(value: T): T;
415
402
  *
416
403
  * @group Array
417
404
  */
418
- declare function uniqBy<T>(array: T[], comparator: ((value: T) => any) | PropertyKey): T[];
405
+ declare function uniqBy<T>(array: readonly T[], comparator: ((value: T) => any) | PropertyKey): T[];
419
406
 
420
407
  type WrrItem<T> = {
421
408
  item: T;
@@ -794,6 +781,251 @@ declare function bigIntBytes(value: bigint): Uint8Array;
794
781
  */
795
782
  declare function bigIntFromBytes(bytes: Uint8Array): bigint;
796
783
 
784
+ type Arrayable<T> = T[] | T;
785
+
786
+ type Awaitable<T> = Promise<T> | T;
787
+
788
+ type ArgumentsType<T> = T extends (...args: infer U) => any ? U : never;
789
+
790
+ type FunctionArgs<Args extends any[] = any[], Return = void> = (
791
+ ...args: Args
792
+ ) => Return;
793
+
794
+ type DeepPartial<T> = T extends Date
795
+ ? T
796
+ : T extends object
797
+ ? { [P in keyof T]?: DeepPartial<T[P]> }
798
+ : T;
799
+
800
+ type DeepReadonly<T> = T extends unknown[]
801
+ ? Readonly<T>
802
+ : T extends object
803
+ ? Readonly<{ [P in keyof T]: DeepReadonly<T[P]> }>
804
+ : Readonly<T>;
805
+
806
+ type AnyFunction = (...args: any[]) => any;
807
+
808
+ type Data = Record<string, unknown>;
809
+
810
+ type GenericObject = Record<string, any>;
811
+
812
+ type SelectOptions<T = any> = SelectOptionItem<T>[];
813
+
814
+ type OverwriteWith<T1, T2> =
815
+ IsAny<T2> extends true ? T1 : Omit<T1, keyof T2> & T2;
816
+
817
+ type IsAny<T> = boolean extends (T extends never ? true : false)
818
+ ? true
819
+ : false;
820
+
821
+ type IfAny<T, Y, N> = 0 extends 1 & T ? Y : N;
822
+
823
+ /**
824
+ * @example
825
+ * LiteralUnion<'foo' | 'bar', string>
826
+ *
827
+ * @see {@link https://github.com/microsoft/TypeScript/issues/29729}
828
+ */
829
+ type LiteralUnion<Union, Type> = Union | (Type & Nothing);
830
+
831
+ interface Nothing {}
832
+
833
+ type ValuesOfObject<T> = T[keyof T];
834
+
835
+ type Fn = () => void;
836
+
837
+ type PromisifyFn<T extends AnyFunction> = (
838
+ ...args: ArgumentsType<T>
839
+ ) => Promise<ReturnType<T>>;
840
+
841
+ /**
842
+ * A time value, which can be a string (e.g., "HH:MM"),
843
+ * an object with `h` (hours) and `m` (minutes) properties, or a similar format
844
+ * that `createTimeObject` can parse.
845
+ */
846
+ type TimeValue = TimeString | TimeObject;
847
+
848
+ /**
849
+ * Represent time string in 24h format
850
+ */
851
+ type TimeString = string;
852
+
853
+ /**
854
+ * Represent time object in 24h format ("HH:MM")
855
+ */
856
+ type TimeObject = {
857
+ /**
858
+ * Hour (0 - 23).
859
+ */
860
+ h: number;
861
+
862
+ /**
863
+ * Minutes (0 - 59).
864
+ */
865
+ m: number;
866
+ };
867
+
868
+ /**
869
+ * Represent date object
870
+ */
871
+ type DateObject = {
872
+ /**
873
+ * The year of the date (e.g., 2024).
874
+ */
875
+ year: number;
876
+
877
+ /**
878
+ * The month of the date (1 = January, 12 = December).
879
+ */
880
+ month: number;
881
+
882
+ /**
883
+ * The day of the month (1-31).
884
+ */
885
+ date: number;
886
+ };
887
+
888
+ interface ThemeConfig {
889
+ colors: {
890
+ [x: string]: Record<string, string>;
891
+ };
892
+ variables: {
893
+ [x: string]: Record<string, string | number>;
894
+ };
895
+ }
896
+
897
+ type Prettify<T> = {
898
+ [K in keyof T]: T[K];
899
+ } & {};
900
+
901
+ interface SelectOptionItem<T = any> {
902
+ text: string;
903
+ value: T;
904
+ props?: any;
905
+ }
906
+
907
+ interface SelectOptionItem<T = any> {
908
+ text: string;
909
+ value: T;
910
+ props?: any;
911
+ }
912
+
913
+ type Primitive =
914
+ | null
915
+ | undefined
916
+ | string
917
+ | number
918
+ | bigint
919
+ | boolean
920
+ | symbol;
921
+
922
+ type ExecResult<T extends Data = Data, K extends Data = Data> =
923
+ | ExecSuccess<T>
924
+ | ExecSkip<K>;
925
+
926
+ type ExecSuccess<T extends Data = Data> = {
927
+ success: true;
928
+ code: string;
929
+ reason?: string;
930
+ } & T;
931
+
932
+ type ExecSkip<T extends Data = Data> = {
933
+ skip: true;
934
+ code: string;
935
+ reason?: string;
936
+ } & T;
937
+
938
+ type ExecResultToSuccess<T> =
939
+ T extends ExecSuccess<infer X> ? ExecSuccess<X> : ExecSuccess;
940
+
941
+ type ExecResultToSkip<T> =
942
+ T extends ExecSkip<infer X> ? ExecSkip<X> : ExecSkip;
943
+
944
+ interface Logger {
945
+ info: (...args: unknown[]) => void;
946
+ warn: (...args: unknown[]) => void;
947
+ error: (...args: unknown[]) => void;
948
+ debug: (...args: unknown[]) => void;
949
+ log: (...args: unknown[]) => void;
950
+ extend: (...args: unknown[]) => void;
951
+ }
952
+
953
+ declare namespace BitPack {
954
+ type Field = {
955
+ name: string;
956
+ bits: number;
957
+ take: Take;
958
+ };
959
+ type Options<TFields extends Field[]> = {
960
+ totalBits: number;
961
+ fields: TFields;
962
+ debug?: boolean;
963
+ optimize?: boolean;
964
+ };
965
+ type Take = 'low' | 'high';
966
+ type API<TFields extends string = string> = {
967
+ buffer: Fn.Buffer<TFields>;
968
+ number: Fn.Number<TFields>;
969
+ bigint: Fn.BigInt<TFields>;
970
+ bits: Fn.Bits<TFields>;
971
+ plan?: Plan[];
972
+ };
973
+ namespace Fn {
974
+ type Buffer<TFields extends string = string> = WithDebug<(data: FieldOptions<TFields>) => Uint8Array>;
975
+ type Number<TFields extends string = string> = WithDebug<(data: FieldOptions<TFields>) => number>;
976
+ type BigInt<TFields extends string = string> = WithDebug<(data: FieldOptions<TFields>) => bigint>;
977
+ type Bits<TFields extends string = string> = WithDebug<(data: FieldOptions<TFields>) => string>;
978
+ }
979
+ type WithDebug<T extends AnyFunction> = T & {
980
+ code?: string;
981
+ };
982
+ type ExtractFieldNames<T extends Field[]> = T[number]['name'];
983
+ type FieldOptions<T extends string> = {
984
+ [P in T]: number;
985
+ };
986
+ }
987
+ type Plan = {
988
+ object: 'set' | 'value';
989
+ container?: number;
990
+ bits?: number;
991
+ offset?: number;
992
+ value?: unknown;
993
+ child?: Plan;
994
+ };
995
+ declare function bitPack<const TFields extends BitPack.Field[], TFieldNames extends string = BitPack.ExtractFieldNames<TFields>>(options: BitPack.Options<TFields>): BitPack.API<TFieldNames>;
996
+
997
+ declare namespace BitUnpack {
998
+ type Field = {
999
+ name: string;
1000
+ bits: number;
1001
+ };
1002
+ type Options<TFields extends Field[]> = {
1003
+ totalBits: number;
1004
+ fields: TFields;
1005
+ debug?: boolean;
1006
+ };
1007
+ type API<TFields extends string = string> = {
1008
+ buffer: Fn.Buffer<TFields>;
1009
+ number: Fn.Number<TFields>;
1010
+ bigint: Fn.BigInt<TFields>;
1011
+ bits: Fn.Bits<TFields>;
1012
+ };
1013
+ namespace Fn {
1014
+ type Buffer<TFields extends string = string> = WithDebug<(data: Uint8Array) => FieldResult<TFields>>;
1015
+ type Number<TFields extends string = string> = WithDebug<(data: number) => FieldResult<TFields>>;
1016
+ type BigInt<TFields extends string = string> = WithDebug<(data: bigint) => FieldResult<TFields>>;
1017
+ type Bits<TFields extends string = string> = WithDebug<(data: string) => FieldResult<TFields>>;
1018
+ }
1019
+ type WithDebug<T extends AnyFunction> = T & {
1020
+ code?: string;
1021
+ };
1022
+ type ExtractFieldNames<T extends Field[]> = T[number]['name'];
1023
+ type FieldResult<T extends string> = {
1024
+ [P in T]: number;
1025
+ };
1026
+ }
1027
+ declare function bitUnpack<const TFields extends BitUnpack.Field[], TFieldNames extends string = BitUnpack.ExtractFieldNames<TFields>>(options: BitUnpack.Options<TFields>): BitUnpack.API<TFieldNames>;
1028
+
797
1029
  type BytesToBase64Options = {
798
1030
  /**
799
1031
  * Specifies the encoding type.
@@ -1013,175 +1245,6 @@ declare function uint8ToUint16(value: Uint8Array): Uint16Array;
1013
1245
  */
1014
1246
  declare function uint8ToUint32(value: Uint8Array): Uint32Array;
1015
1247
 
1016
- type Arrayable<T> = T[] | T;
1017
-
1018
- type Awaitable<T> = Promise<T> | T;
1019
-
1020
- type ArgumentsType<T> = T extends (...args: infer U) => any ? U : never;
1021
-
1022
- type FunctionArgs<Args extends any[] = any[], Return = void> = (
1023
- ...args: Args
1024
- ) => Return;
1025
-
1026
- type DeepPartial<T> = T extends Date
1027
- ? T
1028
- : T extends object
1029
- ? { [P in keyof T]?: DeepPartial<T[P]> }
1030
- : T;
1031
-
1032
- type DeepReadonly<T> = T extends unknown[]
1033
- ? Readonly<T>
1034
- : T extends object
1035
- ? Readonly<{ [P in keyof T]: DeepReadonly<T[P]> }>
1036
- : Readonly<T>;
1037
-
1038
- type AnyFunction = (...args: any[]) => any;
1039
-
1040
- type Data = Record<string, unknown>;
1041
-
1042
- type GenericObject = Record<string, any>;
1043
-
1044
- type SelectOptions<T = any> = SelectOptionItem<T>[];
1045
-
1046
- type OverwriteWith<T1, T2> =
1047
- IsAny<T2> extends true ? T1 : Omit<T1, keyof T2> & T2;
1048
-
1049
- type IsAny<T> = boolean extends (T extends never ? true : false)
1050
- ? true
1051
- : false;
1052
-
1053
- type IfAny<T, Y, N> = 0 extends 1 & T ? Y : N;
1054
-
1055
- /**
1056
- * @example
1057
- * LiteralUnion<'foo' | 'bar', string>
1058
- *
1059
- * @see {@link https://github.com/microsoft/TypeScript/issues/29729}
1060
- */
1061
- type LiteralUnion<Union, Type> = Union | (Type & Nothing);
1062
-
1063
- interface Nothing {}
1064
-
1065
- type ValuesOfObject<T> = T[keyof T];
1066
-
1067
- type Fn = () => void;
1068
-
1069
- type PromisifyFn<T extends AnyFunction> = (
1070
- ...args: ArgumentsType<T>
1071
- ) => Promise<ReturnType<T>>;
1072
-
1073
- /**
1074
- * A time value, which can be a string (e.g., "HH:MM"),
1075
- * an object with `h` (hours) and `m` (minutes) properties, or a similar format
1076
- * that `createTimeObject` can parse.
1077
- */
1078
- type TimeValue = TimeString | TimeObject;
1079
-
1080
- /**
1081
- * Represent time string in 24h format
1082
- */
1083
- type TimeString = string;
1084
-
1085
- /**
1086
- * Represent time object in 24h format ("HH:MM")
1087
- */
1088
- type TimeObject = {
1089
- /**
1090
- * Hour (0 - 23).
1091
- */
1092
- h: number;
1093
-
1094
- /**
1095
- * Minutes (0 - 59).
1096
- */
1097
- m: number;
1098
- };
1099
-
1100
- /**
1101
- * Represent date object
1102
- */
1103
- type DateObject = {
1104
- /**
1105
- * The year of the date (e.g., 2024).
1106
- */
1107
- year: number;
1108
-
1109
- /**
1110
- * The month of the date (1 = January, 12 = December).
1111
- */
1112
- month: number;
1113
-
1114
- /**
1115
- * The day of the month (1-31).
1116
- */
1117
- date: number;
1118
- };
1119
-
1120
- interface ThemeConfig {
1121
- colors: {
1122
- [x: string]: Record<string, string>;
1123
- };
1124
- variables: {
1125
- [x: string]: Record<string, string | number>;
1126
- };
1127
- }
1128
-
1129
- type Prettify<T> = {
1130
- [K in keyof T]: T[K];
1131
- } & {};
1132
-
1133
- interface SelectOptionItem<T = any> {
1134
- text: string;
1135
- value: T;
1136
- props?: any;
1137
- }
1138
-
1139
- interface SelectOptionItem<T = any> {
1140
- text: string;
1141
- value: T;
1142
- props?: any;
1143
- }
1144
-
1145
- type Primitive =
1146
- | null
1147
- | undefined
1148
- | string
1149
- | number
1150
- | bigint
1151
- | boolean
1152
- | symbol;
1153
-
1154
- type ExecResult<T extends Data = Data, K extends Data = Data> =
1155
- | ExecSuccess<T>
1156
- | ExecSkip<K>;
1157
-
1158
- type ExecSuccess<T extends Data = Data> = {
1159
- success: true;
1160
- code: string;
1161
- reason?: string;
1162
- } & T;
1163
-
1164
- type ExecSkip<T extends Data = Data> = {
1165
- skip: true;
1166
- code: string;
1167
- reason?: string;
1168
- } & T;
1169
-
1170
- type ExecResultToSuccess<T> =
1171
- T extends ExecSuccess<infer X> ? ExecSuccess<X> : ExecSuccess;
1172
-
1173
- type ExecResultToSkip<T> =
1174
- T extends ExecSkip<infer X> ? ExecSkip<X> : ExecSkip;
1175
-
1176
- interface Logger {
1177
- info: (...args: unknown[]) => void;
1178
- warn: (...args: unknown[]) => void;
1179
- error: (...args: unknown[]) => void;
1180
- debug: (...args: unknown[]) => void;
1181
- log: (...args: unknown[]) => void;
1182
- extend: (...args: unknown[]) => void;
1183
- }
1184
-
1185
1248
  interface ArgToKeyOptions {
1186
1249
  /**
1187
1250
  * Object key generation strategy.
@@ -2545,7 +2608,7 @@ declare class EJSON {
2545
2608
  * @param {string} value - The JSON string to parse.
2546
2609
  * @returns {any} - The decoded JavaScript object.
2547
2610
  */
2548
- parse(value: string): any;
2611
+ parse<T = any>(value: string): T;
2549
2612
  /** @internal */
2550
2613
  protected _replacer(value: any, key: string): any;
2551
2614
  /** @internal */
@@ -2931,6 +2994,11 @@ declare function getMostSpecificPaths(keys: string[]): string[];
2931
2994
  */
2932
2995
  declare function humanFileSize(bytes: number, digits?: number, withSpace?: boolean): string;
2933
2996
 
2997
+ type WithCode<T extends AnyFunction> = T & {
2998
+ code: string;
2999
+ };
3000
+ declare function createFunction<T extends AnyFunction>(fnName: string, code: string, ...args: any[]): WithCode<T>;
3001
+
2934
3002
  interface DebounceOptions {
2935
3003
  /**
2936
3004
  * An optional AbortSignal to cancel the debounced function.
@@ -3373,6 +3441,21 @@ declare function isPromise<T = void>(value: unknown): value is Promise<T>;
3373
3441
  * @group Predicates
3374
3442
  */
3375
3443
  declare const isPrimitive: (value: unknown) => value is Primitive;
3444
+ /**
3445
+ * Checks if the current environment is Node.js.
3446
+ *
3447
+ * This function checks for the existence of the `process.versions.node` property,
3448
+ * which only exists in Node.js environments.
3449
+ *
3450
+ * @returns {boolean} `true` if the current environment is Node.js, otherwise `false`.
3451
+ *
3452
+ * @example
3453
+ * if (isNode()) {
3454
+ * console.log('This is running in Node.js');
3455
+ * const fs = import('node:fs');
3456
+ * }
3457
+ */
3458
+ declare function isNode(): boolean;
3376
3459
 
3377
3460
  type LogLevel = Exclude<keyof Logger, 'extend'>;
3378
3461
  /**
@@ -4452,7 +4535,9 @@ declare const unset: (object: any, path: lodash.PropertyPath) => boolean;
4452
4535
  *
4453
4536
  * @group Promise
4454
4537
  */
4455
- declare function asyncFilter<T>(array: T[], predicate: (value: T, index: number, array: Array<T>) => Promise<boolean> | boolean): Promise<T[]>;
4538
+ declare function asyncFilter<T>(array: T[], predicate: (value: T, index: number, array: Array<T>) => Promise<boolean> | boolean, { concurrency }?: {
4539
+ concurrency?: number | undefined;
4540
+ }): Promise<T[]>;
4456
4541
 
4457
4542
  /**
4458
4543
  * Asynchronously finds the first element in an array that satisfies the provided async predicate.
@@ -5125,6 +5210,82 @@ declare class ResourcePool<T = unknown> extends SimpleEventEmitter<ResourcePoolE
5125
5210
  */
5126
5211
  declare function timeout<T = any>(ms: number, promiseOrCallback: Promise<T> | ((abortSignal: AbortSignal) => Awaitable<T>), timeoutError?: any): Promise<T>;
5127
5212
 
5213
+ type ResolverFn<R extends Promise<any>, T = any, A extends any[] = any[]> = (this: T, ...args: A) => R;
5214
+ type WithResolve<R extends Promise<any>, T = any, A extends any[] = any[]> = (this: T, ...args: A) => R;
5215
+ /**
5216
+ * A function that generates cache key based on the arguments.
5217
+ *
5218
+ * @param args - The original function arguments
5219
+ * @param computeKey - A helper function to stringify arguments into a cache key
5220
+ * @returns A cache key string if a variant should be used, or undefined to skip this variant
5221
+ */
5222
+ type GetCacheKey = (args: any[], computeKey: (...args: any[]) => string) => string | null | undefined;
5223
+ /**
5224
+ * Wraps an async function to guarantee single execution for identical arguments.
5225
+ * Acts as a request deduplication mechanism - when multiple calls are made with the same
5226
+ * arguments before the first call completes, all calls wait for and receive the result
5227
+ * of the first execution.
5228
+ *
5229
+ * This is useful for preventing redundant async operations like duplicate API calls or
5230
+ * database queries that are triggered simultaneously.
5231
+ *
5232
+ * @template R - The Promise return type of the wrapped function
5233
+ * @template T - The `this` context type for the function
5234
+ * @template A - The argument types tuple for the function
5235
+ *
5236
+ * @param fn - The async function to wrap
5237
+ * @param getCacheKey - Optional array of functions to generate alternative cache keys.
5238
+ * Useful when different argument combinations should be treated as equivalent.
5239
+ *
5240
+ * @returns A wrapped version of the function with deduplication behavior
5241
+ *
5242
+ * @example Basic usage - deduplicating database queries
5243
+ * ```ts
5244
+ * const fetchUserById = withResolve((userId: number) =>
5245
+ * db.users.findById(userId)
5246
+ * );
5247
+ *
5248
+ * // Only produces 1 database query, both calls receive the same result
5249
+ * const [user1, user2] = await Promise.all([
5250
+ * fetchUserById(100),
5251
+ * fetchUserById(100)
5252
+ * ]);
5253
+ * ```
5254
+ *
5255
+ * @example With cache key variants
5256
+ * ```ts
5257
+ * const fetchUser = withResolve(
5258
+ * (id: number, options?: { fresh?: boolean }) => api.getUser(id, options),
5259
+ * [
5260
+ * // Treat calls with/without options as equivalent if fresh is false/undefined
5261
+ * (args, computeKey) => {
5262
+ * const [id, options] = args;
5263
+ * if (options?.fresh) {
5264
+ * return null;
5265
+ * }
5266
+ *
5267
+ * return computeKey(id, {});
5268
+ * }
5269
+ * ]
5270
+ * );
5271
+ *
5272
+ * // Both calls deduplicated to single request
5273
+ * await Promise.all([
5274
+ * fetchUser(1),
5275
+ * fetchUser(1, { fresh: false })
5276
+ * ]);
5277
+ * ```
5278
+ *
5279
+ * @remarks
5280
+ * - The cache is held only during the execution of the first call
5281
+ * - Once the promise resolves or rejects, the cache entry is cleared
5282
+ * - All waiting calls receive the same result (success or error)
5283
+ * - Works with both resolved and rejected promises
5284
+ *
5285
+ * @group Promise
5286
+ */
5287
+ declare function withResolve<R extends Promise<any>, T = any, A extends any[] = any[]>(fn: ResolverFn<R, T, A>, getCacheKey?: Arrayable<GetCacheKey>): WithResolve<R, T, A>;
5288
+
5128
5289
  /**
5129
5290
  * Converts a string to camel case.
5130
5291
  *
@@ -5662,4 +5823,4 @@ declare function wrapText(value: string, maxLength?: number): string;
5662
5823
  */
5663
5824
  declare function toError<T>(value: T, unknownMessage?: string): T extends Error ? T : Error;
5664
5825
 
5665
- export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, type BaseX, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DebouncedFunction, type DeepPartial, type DeepReadonly, type Defer, instance as EJSON, EJSON as EJSONInstance, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EJSONType, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, ResourcePool, type ResourcePoolEventMap, type ResourcePoolOptions, type RetryOnErrorConfig, type SecureCustomizerOptions, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, SortedArray, type SortedArrayCompareFn, _default as TWEMOJI_REGEX, type ThemeConfig, type ThrottledFunction, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, type WrrItem, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, avgCircular, base62, base62Fast, base64, base64ToBytes, base64url, basex, bigIntBytes, bigIntFromBytes, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, debounce, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, loggerSetLevel, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, textDecoder, textEncoder, throttle, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, weightedRoundRobin, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };
5826
+ export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, type BaseX, BitPack, BitUnpack, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DebouncedFunction, type DeepPartial, type DeepReadonly, type Defer, instance as EJSON, EJSON as EJSONInstance, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EJSONType, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, ResourcePool, type ResourcePoolEventMap, type ResourcePoolOptions, type RetryOnErrorConfig, type SecureCustomizerOptions, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, SortedArray, type SortedArrayCompareFn, _default as TWEMOJI_REGEX, type ThemeConfig, type ThrottledFunction, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCode, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, type WrrItem, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, avgCircular, base62, base62Fast, base64, base64ToBytes, base64url, basex, bigIntBytes, bigIntFromBytes, bitPack, bitUnpack, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createFunction, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, debounce, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, intersectionBy, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNode, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, loggerSetLevel, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, textDecoder, textEncoder, throttle, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, weightedRoundRobin, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, withResolve, wrapText };