@andrew_l/toolkit 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -115,7 +115,7 @@ declare function chunk<T>(list: readonly T[], size?: number): T[][];
  *
  * @group Array
  */
-declare function chunkSeries(list: number[], step?: number): number[][];
+declare function chunkSeries(list: readonly number[], step?: number): number[][];
 
 /**
  * Computes the difference between arrays.
@@ -136,11 +136,7 @@ declare function chunkSeries(list: number[], step?: number): number[][];
  *
  * @group Array
  */
-declare function difference<T>(...arrays: readonly T[][]): T[];
-
-type MaybePropertyKey<T> = T extends object
-  ? keyof T | PropertyKey
-  : PropertyKey;
+declare function difference<T>(...arrays: (readonly T[])[]): T[];
 
 type PropertyKeyLiteralToType<T> = T extends string
   ? string
@@ -156,10 +152,14 @@ type IsPropertyKey<T, V, L> = T extends object
     : L
   : PropertyKeyLiteralToType<L>;
 
-declare function groupBy<T, K extends MaybePropertyKey<T>>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, K>, T[]>;
+type ToPropertyKey<T> = T extends PropertyKey ? T : string;
+
+declare function groupBy<T, K extends keyof T>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, unknown>, T[]>;
+declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, unknown>, T[]>;
 declare function groupBy<T, K>(array: readonly T[], keyBy: (item: T) => K, objectMode?: false): Map<K, T[]>;
-declare function groupBy<T, K extends MaybePropertyKey<T>>(array: readonly T[], keyBy: K, objectMode: true): Record<K, T[]>;
-declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: (item: T) => K, objectMode: true): Record<K, T[]>;
+declare function groupBy<T, K extends keyof T>(array: readonly T[], keyBy: K, objectMode: true): Record<ToPropertyKey<T[K]>, T[]>;
+declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: K, objectMode?: true): Record<ToPropertyKey<IsPropertyKey<T, K, unknown>>, T[]>;
+declare function groupBy<T, K>(array: readonly T[], keyBy: (item: T) => K, objectMode: true): Record<ToPropertyKey<K>, T[]>;
 
 /**
  * Returns the intersection of arrays.
@@ -178,31 +178,18 @@ declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: (
  *
  * @group Array
  */
-declare function intersection<T>(...arrays: readonly T[][]): T[];
+declare function intersection<T>(...arrays: (readonly T[])[]): T[];
 
-/**
- * Maps each element of an array based on a provided key.
- *
- * @example
- * const data = [
- *     { id: 1, name: 'group 1' },
- *     { id: 2, name: 'group 2' },
- *     { id: 1, name: 'group 2' }
- * ];
- *
- * const result = keyBy(data, 'id');
- * console.log(Object.entries(result));
- * // [
- * //    [1, [{ id: 1, name: 'group 1' }, { id: 1, name: 'group 2' }],
- * //    [2, { id: 2, name: 'group 2' }],
- * // ]
- *
- * @group Array
- */
-declare function keyBy<T, K extends MaybePropertyKey<T>>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, K>, T>;
+declare function intersectionBy<T>(keyBy: keyof T, ...arrays: (readonly T[])[]): T[];
+declare function intersectionBy<T>(keyBy: PropertyKey, ...arrays: (readonly T[])[]): T[];
+declare function intersectionBy<T>(keyBy: (item: T) => unknown, ...arrays: (readonly T[])[]): T[];
+
+declare function keyBy<T, K extends keyof T>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, unknown>, T>;
+declare function keyBy<T, K extends PropertyKey>(array: readonly T[], keyBy: K, objectMode?: false): Map<IsPropertyKey<T, K, unknown>, T[]>;
 declare function keyBy<T, K>(array: readonly T[], keyBy: (item: T) => K, objectMode?: false): Map<K, T>;
-declare function keyBy<T, K extends MaybePropertyKey<T>>(array: readonly T[], keyBy: K, objectMode: true): Record<K, T>;
-declare function keyBy<T, K extends PropertyKey>(array: readonly T[], keyBy: (item: T) => K, objectMode: true): Record<K, T>;
+declare function keyBy<T, K extends keyof T>(array: readonly T[], keyBy: K, objectMode: true): Record<ToPropertyKey<T[K]>, T>;
+declare function keyBy<T, K extends PropertyKey>(array: readonly T[], keyBy: K, objectMode?: true): Record<ToPropertyKey<IsPropertyKey<T, K, unknown>>, T>;
+declare function keyBy<T, K>(array: readonly T[], keyBy: (item: T) => K, objectMode: true): Record<ToPropertyKey<K>, T>;
 
 /**
  * Sort array by multiple fields
@@ -350,7 +337,7 @@ declare const sum: (values: readonly number[]) => number;
  *
  * @group Array
  */
-declare function union<T>(...arrays: readonly T[][]): T[];
+declare function union<T>(...arrays: (readonly T[])[]): T[];
 
 /**
  * Returns a new array with duplicates removed.
@@ -369,7 +356,7 @@ declare function union<T>(...arrays: readonly T[][]): T[];
  *
  * @group Array
  */
-declare function uniq<T extends any[]>(value: T): T;
+declare function uniq<T>(value: readonly T[]): T[];
 
 /**
  * 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;
  *
  * @group Array
  */
-declare function uniqBy<T>(array: T[], comparator: ((value: T) => any) | PropertyKey): T[];
+declare function uniqBy<T>(array: readonly T[], comparator: ((value: T) => any) | PropertyKey): T[];
 
 type WrrItem<T> = {
     item: T;
@@ -2545,7 +2532,7 @@ declare class EJSON {
      * @param {string} value - The JSON string to parse.
      * @returns {any} - The decoded JavaScript object.
      */
-    parse(value: string): any;
+    parse<T = any>(value: string): T;
     /** @internal */
     protected _replacer(value: any, key: string): any;
     /** @internal */
@@ -3373,6 +3360,21 @@ declare function isPromise<T = void>(value: unknown): value is Promise<T>;
  * @group Predicates
  */
 declare const isPrimitive: (value: unknown) => value is Primitive;
+/**
+ * Checks if the current environment is Node.js.
+ *
+ * This function checks for the existence of the `process.versions.node` property,
+ * which only exists in Node.js environments.
+ *
+ * @returns {boolean} `true` if the current environment is Node.js, otherwise `false`.
+ *
+ * @example
+ * if (isNode()) {
+ *   console.log('This is running in Node.js');
+ *   const fs = import('node:fs');
+ * }
+ */
+declare function isNode(): boolean;
 
 type LogLevel = Exclude<keyof Logger, 'extend'>;
 /**
@@ -4452,7 +4454,9 @@ declare const unset: (object: any, path: lodash.PropertyPath) => boolean;
  *
  * @group Promise
  */
-declare function asyncFilter<T>(array: T[], predicate: (value: T, index: number, array: Array<T>) => Promise<boolean> | boolean): Promise<T[]>;
+declare function asyncFilter<T>(array: T[], predicate: (value: T, index: number, array: Array<T>) => Promise<boolean> | boolean, { concurrency }?: {
+    concurrency?: number | undefined;
+}): Promise<T[]>;
 
 /**
  * Asynchronously finds the first element in an array that satisfies the provided async predicate.
@@ -5125,6 +5129,82 @@ declare class ResourcePool<T = unknown> extends SimpleEventEmitter<ResourcePoolE
  */
 declare function timeout<T = any>(ms: number, promiseOrCallback: Promise<T> | ((abortSignal: AbortSignal) => Awaitable<T>), timeoutError?: any): Promise<T>;
 
+type ResolverFn<R extends Promise<any>, T = any, A extends any[] = any[]> = (this: T, ...args: A) => R;
+type WithResolve<R extends Promise<any>, T = any, A extends any[] = any[]> = (this: T, ...args: A) => R;
+/**
+ * A function that generates cache key based on the arguments.
+ *
+ * @param args - The original function arguments
+ * @param computeKey - A helper function to stringify arguments into a cache key
+ * @returns A cache key string if a variant should be used, or undefined to skip this variant
+ */
+type GetCacheKey = (args: any[], computeKey: (...args: any[]) => string) => string | null | undefined;
+/**
+ * Wraps an async function to guarantee single execution for identical arguments.
+ * Acts as a request deduplication mechanism - when multiple calls are made with the same
+ * arguments before the first call completes, all calls wait for and receive the result
+ * of the first execution.
+ *
+ * This is useful for preventing redundant async operations like duplicate API calls or
+ * database queries that are triggered simultaneously.
+ *
+ * @template R - The Promise return type of the wrapped function
+ * @template T - The `this` context type for the function
+ * @template A - The argument types tuple for the function
+ *
+ * @param fn - The async function to wrap
+ * @param getCacheKey - Optional array of functions to generate alternative cache keys.
+ *   Useful when different argument combinations should be treated as equivalent.
+ *
+ * @returns A wrapped version of the function with deduplication behavior
+ *
+ * @example Basic usage - deduplicating database queries
+ * ```ts
+ * const fetchUserById = withResolve((userId: number) =>
+ *   db.users.findById(userId)
+ * );
+ *
+ * // Only produces 1 database query, both calls receive the same result
+ * const [user1, user2] = await Promise.all([
+ *   fetchUserById(100),
+ *   fetchUserById(100)
+ * ]);
+ * ```
+ *
+ * @example With cache key variants
+ * ```ts
+ * const fetchUser = withResolve(
+ *   (id: number, options?: { fresh?: boolean }) => api.getUser(id, options),
+ *   [
+ *     // Treat calls with/without options as equivalent if fresh is false/undefined
+ *     (args, computeKey) => {
+ *       const [id, options] = args;
+ *       if (options?.fresh) {
+ *         return null;
+ *       }
+ *
+ *       return computeKey(id, {});
+ *     }
+ *   ]
+ * );
+ *
+ * // Both calls deduplicated to single request
+ * await Promise.all([
+ *   fetchUser(1),
+ *   fetchUser(1, { fresh: false })
+ * ]);
+ * ```
+ *
+ * @remarks
+ * - The cache is held only during the execution of the first call
+ * - Once the promise resolves or rejects, the cache entry is cleared
+ * - All waiting calls receive the same result (success or error)
+ * - Works with both resolved and rejected promises
+ *
+ * @group Promise
+ */
+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>;
+
 /**
  * Converts a string to camel case.
  *
@@ -5662,4 +5742,4 @@ declare function wrapText(value: string, maxLength?: number): string;
  */
 declare function toError<T>(value: T, unknownMessage?: string): T extends Error ? T : Error;
 
-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 };
+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, 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 };