deverything 3.3.0 → 4.0.0

package/dist/index.d.ts

@@ -141,17 +141,20 @@ type Serialized<T> = T extends Date ? string : T extends Array<infer R> ? Array<
 } : T;
 
 /**
- *
- * @description Generate a series of dates between the start and end dates
- * NOTE: it does NOT include the end date
+ * Buckets dates into groups based on a date series
+ * @param dateSeries Array of dates that define the buckets, must be sorted in ascending order
+ * @param dates Array of dates to be bucketed, must be sorted in ascending order
+ * @param unit The time unit to use for bucketing ('day', 'hour', 'minute', 'second')
+ * @returns Record mapping each bucket date to an array of dates that fall within that bucket
  */
-declare const getDateRangeSeries: (dateRange: DateRange, unit: "day" | "hour" | "minute" | "second" | "calendarMonth") => ISODate[];
+declare const bucketSortedDates: (dateSeries: ISODate[], dates: ISODate[], unit: "day" | "hour" | "minute" | "second") => Record<ISODate, ISODate[]>;
 
 /**
  *
- * @deprecated use getDateRangeSeries instead
+ * @description Generate a series of dates between the start and end dates
+ * NOTE: it does NOT include the end date
  */
-declare const getDateSeries: (startDate: Date, endDate: Date, unit: "days" | "hours" | "minutes" | "seconds") => ISODate[];
+declare const getDateRangeSeries: (dateRange: DateRange, unit: "day" | "hour" | "minute" | "second" | "calendarMonth") => ISODate[];
 
 /**
  * @description Returns the smallest and biggest dates from an array of dates in DateRange format
@@ -159,7 +162,7 @@ declare const getDateSeries: (startDate: Date, endDate: Date, unit: "days" | "ho
  * @returns DateRange object with startDate (smallest) and endDate (biggest)
  * @throws Error if the array is empty or contains invalid dates
  */
-declare const getDateSeriesRange: (dateSeries: DateSeries<DateLike>) => DateRange;
+declare const getDateSeriesRange: (dateSeries: DateSeries) => DateRange;
 
 declare const isOver18: (birthDate: DateLike) => boolean;
 
@@ -203,8 +206,8 @@ declare const formatCookies: (object: PlainObject) => string;
 /**
  *
  * @example formatIndexProgress(-1, 10) => [1/10] capped
- * @example formatProgress(1, 10) => [2/10]
- * @example formatProgress(11, 10) => [10/10] capped
+ * @example formatIndexProgress(1, 10) => [2/10]
+ * @example formatIndexProgress(11, 10) => [10/10] capped
  */
 declare const formatIndexProgress: (index: number, total: number) => string;
 
@@ -216,9 +219,9 @@ declare const formatIndexProgress: (index: number, total: number) => string;
  * @example formatNumber(0.12345, { percentage: true, maxDigits: 2 }) // '12.35%' (rounding)
  */
 declare const formatNumber: (value: number, { compact, maxDigits, percentage, }?: {
-    compact?: boolean | undefined;
-    maxDigits?: number | undefined;
-    percentage?: boolean | undefined;
+    compact?: boolean;
+    maxDigits?: number;
+    percentage?: boolean;
 }) => string;
 
 /**
@@ -227,15 +230,7 @@ declare const formatNumber: (value: number, { compact, maxDigits, percentage, }?
  * @example formatPercentage(0, { digits: 2 }) => 0.00%
  */
 declare const formatPercentage: (value: number, { digits, }?: {
-    digits?: number | undefined;
-}) => string;
-
-/**
- * @deprecated Use `formatIndexProgress` instead.
- */
-declare const formatProgress: ({ index, total, }: {
-    index: number;
-    total: number;
+    digits?: number;
 }) => string;
 
 declare const stringToCSSUnicode: (text: string) => string;
@@ -272,7 +267,7 @@ declare const chunkedAll: <T>(array: T[], chunkSize: number, fn: (chunk: T[]) =>
  * @param options.minChunkTimeMs - Minimum time to process each chunk
  */
 declare const chunkedAsync: <T>(array: T[], chunkSize: number, fn: (chunk: T[], chunkIndex: number, chunks: T[][]) => Promise<any>, { minChunkTimeMs, }?: {
-    minChunkTimeMs?: number | undefined;
+    minChunkTimeMs?: number;
 }) => Promise<any[]>;
 
 /**
@@ -287,11 +282,11 @@ declare const chunkedAsync: <T>(array: T[], chunkSize: number, fn: (chunk: T[],
  * @param options.sleepTimeMs - Time to sleep between each chunk
  */
 declare const chunkedDynamic: <T>(array: T[], initialChunkSize: number, fn: (chunk: T[], currentChunkIndex: number) => Promise<any>, { idealChunkDuration, maxChunkSize, minChunkDuration, minChunkSize, sleepTimeMs, }?: {
-    idealChunkDuration?: number | undefined;
-    maxChunkSize?: number | undefined;
-    minChunkDuration?: number | undefined;
-    minChunkSize?: number | undefined;
-    sleepTimeMs?: number | undefined;
+    idealChunkDuration?: number;
+    maxChunkSize?: number;
+    minChunkDuration?: number;
+    minChunkSize?: number;
+    sleepTimeMs?: number;
 }) => Promise<any[]>;
 
 declare const clamp: ({ number, min, max, }: {
@@ -311,7 +306,7 @@ declare const cyclicalItem: <T>(array: T[], index: number) => T;
  * Print or log helper that does not break on circular references, and expands nested objects.
  */
 declare const dir: (arg: any, { maxDepth }?: {
-    maxDepth?: number | undefined;
+    maxDepth?: number;
 }) => void;
 
 declare const enumKeys: <T extends object>(arg: T) => ObjectKeys<T>;
@@ -326,9 +321,9 @@ declare const filterAlphanumeric: (string: string) => string;
 
 declare const first: <T>(arr: T[]) => T;
 
-declare const firstKey: <T extends PlainObject<any>>(arg: T) => keyof T;
+declare const firstKey: <T extends PlainObject>(arg: T) => ObjectKey<T>;
 
-declare const firstValue: <T extends PlainObject<any>>(arg: T) => ObjectValue<T>;
+declare const firstValue: <T extends PlainObject>(arg: T) => ObjectValue<T>;
 
 /**
  * Get a client cookie by name, works only in the browser
@@ -375,7 +370,7 @@ declare const groupByKey: <T, K extends keyof T>(items: T[], key: K) => Record<k
 
 declare const incrementalId: () => number;
 
-declare const keysLength: <T extends PlainObject<any>>(obj: T) => number;
+declare const keysLength: <T extends PlainObject>(obj: T) => number;
 
 declare const last: <T>(arr: T[]) => T;
 
@@ -392,13 +387,14 @@ declare const lastIndex: (array: any[]) => number;
  * itemsById[1]; // { id: 1, name: "Alice" }
  * itemsById[2]; // { id: 2, name: "Bob" }
  */
-declare const mapByKey: <T extends PlainObject<any>>(items: T[], key: keyof T) => Record<Exclude<T[keyof T], null | undefined>, T>;
+declare const mapByKey: <T extends PlainObject>(items: T[], key: keyof T) => Record<Exclude<T[keyof T], null | undefined>, // any value of T, excluding null and undefined
+T>;
 
 /**
  * @description Simple merge function that merges two objects, arrays get overwritten, no options
  *
  */
-declare const merge: (target: PlainObject, source: PlainObject) => PlainObject<any>;
+declare const merge: (target: PlainObject, source: PlainObject) => PlainObject;
 
 /**
  * @description Merge two arrays, unique values, no options
@@ -416,9 +412,9 @@ declare const normalizeNumber: ({ value, max, min, }: {
     min: number;
 }) => number;
 
-declare const objectDiff: (leftObject: PlainObject, rightObject: PlainObject) => PlainObject<any>;
+declare const objectDiff: (leftObject: PlainObject, rightObject: PlainObject) => PlainObject;
 
-declare const omit: <T extends PlainObject<any>>(obj: T, keys: (keyof T)[]) => Partial<T>;
+declare const omit: <T extends PlainObject>(obj: T, keys: (keyof T)[]) => Partial<T>;
 
 /**
  *
@@ -437,7 +433,7 @@ declare const parseDate: (arg?: Maybe<DateLike>, options?: {
  * const obj = { a: 1, b: 2, c: 3 };
  * pickObjectKeys(obj, ["a", "c"]); // { a: 1, c: 3 }
  */
-declare const pickObjectKeys: <T extends PlainObject<any>>(obj: T, keys: ObjectKeys<T>) => Partial<T>;
+declare const pickObjectKeys: <T extends PlainObject>(obj: T, keys: ObjectKeys<T>) => Partial<T>;
 
 /**
  *
@@ -446,9 +442,9 @@ declare const pickObjectKeys: <T extends PlainObject<any>>(obj: T, keys: ObjectK
  * const obj = { a: 1, b: 2, c: 3 };
  * pickObjectValues(obj, [1, 3]); // { a: 1, c: 3 }
  */
-declare const pickObjectValues: <T extends PlainObject<any>>(obj: T, values: ObjectValues<T>) => Partial<T>;
+declare const pickObjectValues: <T extends PlainObject>(obj: T, values: ObjectValues<T>) => Partial<T>;
 
-declare const pluck: <T extends PlainObject<any>>(items: T[], key: keyof T) => Exclude<T[keyof T], null | undefined>[];
+declare const pluck: <T extends PlainObject>(items: T[], key: keyof T) => Exclude<T[keyof T], null | undefined>[];
 
 declare const promiseWithTimeout: <T>(promise: () => Promise<T>, timeoutMs: number, error?: Error) => Promise<T>;
 
@@ -465,7 +461,7 @@ declare const scrambleText: (str: string) => string;
  * @example
  * serialize({ b: 1, a: 2 }) // '{"a":1,"b":2}'
  */
-declare const serialize: <T extends PlainObject<any>>(obj: T) => string;
+declare const serialize: <T extends PlainObject>(obj: T) => string;
 
 type AsyncFunction<T = any> = () => Promise<T>;
 type SeriesResult<T extends readonly AsyncFunction[]> = {
@@ -482,7 +478,7 @@ type SeriesResult<T extends readonly AsyncFunction[]> = {
  *  async () => 4,
  * ]); => [1, 2, 3, 4]
  */
-declare const seriesAsync: <T extends readonly AsyncFunction<any>[]>(series: readonly [...T]) => Promise<SeriesResult<T>>;
+declare const seriesAsync: <T extends readonly AsyncFunction[]>(series: readonly [...T]) => Promise<SeriesResult<T>>;
 
 /**
  * Sets a value in an object using a dot-separated path.
@@ -502,17 +498,10 @@ declare const sleep: (timeMs: number) => Promise<void>;
 declare const stringify: (arg?: any) => string;
 
 declare const toggleArrayValue: <T>(array: T[], value: T) => T[];
-/**
- * @deprecated Use toggleArrayValue instead
- * @param {T[]} array
- * @param {T} value
- * @returns {T[]}
- */
-declare const toggleArray: <T>(array: T[], value: T) => T[];
 
 declare const truncate: (arg: string, limit: number, { ellipsis, position, }?: {
-    ellipsis?: string | undefined;
-    position?: "start" | "middle" | "end" | undefined;
+    ellipsis?: string;
+    position?: "start" | "middle" | "end";
 }) => string;
 
 declare const uniqueValues: <T>(arr: T[]) => T[];
@@ -531,6 +520,11 @@ declare const isOutside: (value: number, min: number, max: number) => boolean;
 
 declare const isStrictlyBetween: (value: number, min: number, max: number) => boolean;
 
+/**
+ * Returns the maximum value in an array of numbers.
+ * @param values - The array of numbers to find the maximum value of.
+ * @returns The maximum value in the array. If the array is empty, returns 0.
+ */
 declare const max: (values: number[]) => number;
 
 declare const min: (values: number[]) => number;
@@ -586,13 +580,13 @@ declare const randomAddress: () => RandomAddress;
  * randomAlphaNumericCode(); => "A2G4G6"
  */
 declare const randomAlphaNumericCode: ({ length, }?: {
-    length?: number | undefined;
+    length?: number;
 }) => string;
 
 declare const randomArray: () => (string | number | boolean | symbol | Date | BigInt)[];
 
 declare const randomArrayItem: <T>(array: T[], { weights }?: {
-    weights?: number[] | undefined;
+    weights?: number[];
 }) => T;
 
 type BankAccount = {
@@ -640,21 +634,21 @@ declare const randomDateRange: () => {
 };
 
 declare const randomEmail: ({ handle, handleSuffix, }?: {
-    handle?: string | undefined;
-    handleSuffix?: string | undefined;
+    handle?: string;
+    handleSuffix?: string;
 }) => string;
 
 declare const randomEmoji: () => string;
 
 declare const randomEmptyValue: () => number | null | undefined;
 
-declare const randomEnumKey: <T extends object>(arg: T) => keyof T;
+declare const randomEnumKey: <T extends object>(arg: T) => ObjectKey<T>;
 
 declare const randomEnumValue: <T extends object>(arg: T) => ObjectValue<T>;
 
 declare const randomFile: ({ name, extension, }?: {
-    name?: string | undefined;
-    extension?: string | undefined;
+    name?: string;
+    extension?: string;
 }) => File | undefined;
 
 declare const JS_MAX_DIGITS = 16;
@@ -666,7 +660,7 @@ declare const randomFloat: (min?: number, max?: number, decimals?: number) => nu
  * @example "john.doe15"
  */
 declare const randomHandle: ({ suffix }?: {
-    suffix?: string | undefined;
+    suffix?: string;
 }) => string;
 
 declare const randomHexColor: () => string;
@@ -678,17 +672,17 @@ declare const randomHtmlColorName: () => string;
 declare const randomIBAN: () => string;
 
 declare const randomInt: ({ min, max, }?: {
-    min?: number | undefined;
-    max?: number | undefined;
+    min?: number;
+    max?: number;
 }) => number;
 declare const randomBigInt: () => BigInt;
 declare const randomPositiveInt: ({ min, max, }?: {
-    min?: number | undefined;
-    max?: number | undefined;
+    min?: number;
+    max?: number;
 }) => number;
 declare const randomNegativeInt: ({ min, max, }?: {
-    min?: number | undefined;
-    max?: number | undefined;
+    min?: number;
+    max?: number;
 }) => number;
 declare const randomMaxSafeInt: () => number;
 declare const randomMaxInt: () => number;
@@ -712,13 +706,13 @@ declare const randomFullName: () => string;
  * randomNumericCode({ length: 4 }); => "1234"
  */
 declare const randomNumericCode: ({ length }?: {
-    length?: number | undefined;
+    length?: number;
 }) => string;
 
 declare const randomObject: ({ maxDepth, circular, }?: {
-    maxDepth?: number | undefined;
-    circular?: boolean | undefined;
-}) => PlainObject<any>;
+    maxDepth?: number;
+    circular?: boolean;
+}) => PlainObject;
 
 /**
  * Generates a random paragraph of text.
@@ -727,24 +721,24 @@ declare const randomObject: ({ maxDepth, circular, }?: {
  * @returns A random paragraph of text.
  */
 declare const randomParagraph: ({ maxCharacters, minWords, maxWords, }?: {
-    maxCharacters?: number | undefined;
-    minWords?: number | undefined;
-    maxWords?: number | undefined;
+    maxCharacters?: number;
+    minWords?: number;
+    maxWords?: number;
 }) => string;
 
 declare const randomPassword: ({ minChars, maxChars, }?: {
-    minChars?: number | undefined;
-    maxChars?: number | undefined;
+    minChars?: number;
+    maxChars?: number;
 }) => string;
 
 declare const randomPath: ({ depth, }?: {
-    depth?: number | undefined;
+    depth?: number;
 }) => string;
 
 declare const randomPhoneNumber: () => string;
 
 declare const randomString: ({ length, }?: {
-    length?: number | undefined;
+    length?: number;
 }) => string;
 
 declare const randomSymbol: () => symbol;
@@ -796,7 +790,8 @@ declare const isFutureDate: (arg: DateLike) => boolean;
 
 declare const isJsDate: (arg: Date) => arg is Date;
 
-declare const isKey: <T extends PlainObject<any>>(key: Key, obj: T) => key is keyof T;
+declare const isKey: <T extends PlainObject>(key: Key, // cannot use PlainKey here because it does not include symbol (keyof T does)
+obj: T) => key is keyof T;
 
 declare const isLastIndex: (index: number, array: any[]) => boolean;
 
@@ -805,15 +800,7 @@ declare const isNotEmptyString: (arg: any) => boolean;
 declare const isInt: (arg: any) => boolean;
 declare const isEven: (arg: any) => boolean;
 declare const isOdd: (arg: any) => boolean;
-/**
- * @deprecated use isPositiveInt instead
- */
-declare const isPositive: (arg: any) => boolean;
 declare const isPositiveInt: (arg: any) => boolean;
-/**
- * @deprecated use isNegativeInt instead
- */
-declare const isNegative: (arg: any) => boolean;
 declare const isNegativeInt: (arg: any) => boolean;
 declare const isNumber: (arg: any) => arg is number;
 declare const isBigInt: (arg: any) => arg is BigInt;
@@ -837,7 +824,7 @@ declare const isObject: <T>(arg?: any) => arg is PlainObject<T>;
 
 declare const isPastDate: (arg: DateLike) => boolean;
 
-declare const isPromise: (arg: any) => boolean;
+declare const isPromise: (arg: any) => arg is Promise<any>;
 
 declare const isPWA: () => boolean;
 
@@ -871,4 +858,4 @@ declare const isUUID: (arg: string) => boolean;
 
 declare const isValue: <T>(arg?: Maybe<T>) => arg is T;
 
-export { BoolMap, Coords, DateLike, DateRange, DateSeries, Datey, Defined, Dimensions, HashMap, ISODate, ISODay, ISOMonth, ISOYear, JS_MAX_DIGITS, Key, Matrix, Maybe, MaybePromise, MaybePromiseOrValue, MaybePromiseOrValueArray, NonUndefined, NumberMap, ObjectEntries, ObjectEntry, ObjectKey, ObjectKeys, ObjectValue, ObjectValues, PickDefined, PickRequired, PlainKey, PlainObject, Point, PrismaSelect, Serialized, StringMap, Timezone, TrueMap, VoidFn, array, arrayDiff, arrayIntersection, average, capitalize, chunkArray, chunkedAll, chunkedAsync, chunkedDynamic, clamp, cleanSpaces, cyclicalItem, dir, enumKeys, enumValues, filterAlphanumeric, first, firstKey, firstValue, formatCamelCase, formatCookies, formatIndexProgress, formatNumber, formatPercentage, formatProgress, formatTrpcInputQueryString, getCookieByName, getDateRangeSeries, getDateSeries, getDateSeriesRange, getKeys, getUrlSearchParam, getUrlSearchParams, groupByKey, incrementalId, isArray, isArrayIncluded, isBetween, isBigInt, isBigIntString, isBoolean, isBrowser, isBuffer, isClient, isEmail, isEmpty, isEmptyArray, isEmptyObject, isEmptyString, isEven, isFile, isFunction, isFutureDate, isInt, isJsDate, isKey, isLastIndex, isNegative, isNegativeInt, isNotEmptyString, isNumber, isNumeric, isNumericId, isObject, isOdd, isOutside, isOutsideInt4, isOver18, isPWA, isPastDate, isPositive, isPositiveInt, isPromise, isReactElement, isRegExp, isSame, isSequence, isServer, isSpacedString, isStrictlyBetween, isString, isStringDate, isURL, isUUID, isValue, keysLength, last, lastIndex, mapByKey, max, merge, mergeArrays, min, moveToFirst, moveToLast, multiply, noop, normaliseArray, normaliseNumber, normalizeNumber, objectDiff, omit, parseDate, percentageChange, pickObjectKeys, pickObjectValues, pluck, prismaDateRange, promiseWithTimeout, randomAddress, randomAlphaNumericCode, randomArray, randomArrayItem, randomBankAccount, randomBigInt, randomBool, randomChar, randomCompany, randomCoords, randomDate, randomDateRange, randomEmail, randomEmoji, randomEmptyValue, randomEnumKey, randomEnumValue, randomFile, randomFirstName, randomFloat, randomFormattedPercentage, randomFullName, randomFutureDate, randomHandle, randomHexColor, randomHexValue, randomHtmlColorName, randomIBAN, randomIP, randomInt, randomLastName, randomLat, randomLng, randomMaxDate, randomMaxInt, randomMaxSafeInt, randomName, randomNegativeInt, randomNoun, randomNumericCode, randomObject, randomParagraph, randomPassword, randomPastDate, randomPath, randomPhoneNumber, randomPositiveInt, randomString, randomSymbol, randomUUID, randomValue, randomVerb, randomWord, removeUndefinedValues, scrambleText, serialize, seriesAsync, setObjectPath, setUrlSearchParams, shuffle, sleep, startOfDay, startOfNextMonth, startOfNextWeek, startOfThisWeek, startOfToday, startOfTomorrow, startOfUTCDay, startOfUTCTomorrow, stringToCSSUnicode, stringToUnicode, stringify, sum, toggleArray, toggleArrayValue, truncate, uniqueValues };
+export { type BoolMap, type Coords, type DateLike, type DateRange, type DateSeries, type Datey, type Defined, type Dimensions, type HashMap, type ISODate, type ISODay, type ISOMonth, type ISOYear, JS_MAX_DIGITS, type Key, type Matrix, type Maybe, type MaybePromise, type MaybePromiseOrValue, type MaybePromiseOrValueArray, type NonUndefined, type NumberMap, type ObjectEntries, type ObjectEntry, type ObjectKey, type ObjectKeys, type ObjectValue, type ObjectValues, type PickDefined, type PickRequired, type PlainKey, type PlainObject, type Point, type PrismaSelect, type Serialized, type StringMap, type Timezone, type TrueMap, type VoidFn, array, arrayDiff, arrayIntersection, average, bucketSortedDates, capitalize, chunkArray, chunkedAll, chunkedAsync, chunkedDynamic, clamp, cleanSpaces, cyclicalItem, dir, enumKeys, enumValues, filterAlphanumeric, first, firstKey, firstValue, formatCamelCase, formatCookies, formatIndexProgress, formatNumber, formatPercentage, formatTrpcInputQueryString, getCookieByName, getDateRangeSeries, getDateSeriesRange, getKeys, getUrlSearchParam, getUrlSearchParams, groupByKey, incrementalId, isArray, isArrayIncluded, isBetween, isBigInt, isBigIntString, isBoolean, isBrowser, isBuffer, isClient, isEmail, isEmpty, isEmptyArray, isEmptyObject, isEmptyString, isEven, isFile, isFunction, isFutureDate, isInt, isJsDate, isKey, isLastIndex, isNegativeInt, isNotEmptyString, isNumber, isNumeric, isNumericId, isObject, isOdd, isOutside, isOutsideInt4, isOver18, isPWA, isPastDate, isPositiveInt, isPromise, isReactElement, isRegExp, isSame, isSequence, isServer, isSpacedString, isStrictlyBetween, isString, isStringDate, isURL, isUUID, isValue, keysLength, last, lastIndex, mapByKey, max, merge, mergeArrays, min, moveToFirst, moveToLast, multiply, noop, normaliseArray, normaliseNumber, normalizeNumber, objectDiff, omit, parseDate, percentageChange, pickObjectKeys, pickObjectValues, pluck, prismaDateRange, promiseWithTimeout, randomAddress, randomAlphaNumericCode, randomArray, randomArrayItem, randomBankAccount, randomBigInt, randomBool, randomChar, randomCompany, randomCoords, randomDate, randomDateRange, randomEmail, randomEmoji, randomEmptyValue, randomEnumKey, randomEnumValue, randomFile, randomFirstName, randomFloat, randomFormattedPercentage, randomFullName, randomFutureDate, randomHandle, randomHexColor, randomHexValue, randomHtmlColorName, randomIBAN, randomIP, randomInt, randomLastName, randomLat, randomLng, randomMaxDate, randomMaxInt, randomMaxSafeInt, randomName, randomNegativeInt, randomNoun, randomNumericCode, randomObject, randomParagraph, randomPassword, randomPastDate, randomPath, randomPhoneNumber, randomPositiveInt, randomString, randomSymbol, randomUUID, randomValue, randomVerb, randomWord, removeUndefinedValues, scrambleText, serialize, seriesAsync, setObjectPath, setUrlSearchParams, shuffle, sleep, startOfDay, startOfNextMonth, startOfNextWeek, startOfThisWeek, startOfToday, startOfTomorrow, startOfUTCDay, startOfUTCTomorrow, stringToCSSUnicode, stringToUnicode, stringify, sum, toggleArrayValue, truncate, uniqueValues };