deverything 0.43.0 → 0.45.0

package/README.md

@@ -4,11 +4,11 @@
 
 The promise:
 
-- **✅ 1 package**: say goodbye to lodash, faker, this and that and the other package.
+- **✅ 1 package**: say goodbye to lodash, faker, and the other package you don't recall the name of.
 - **⭕ 0 dependencies**: keep it simple and lightweight.
-- **🏆 Pick the best**: the code is minimal and uses the best current practices and is optimized for max performance.
+- **🏆 Pick the best**: the code is minimal and uses the best practices for max performance.
 - **👪🏼 Typescript**: use it, support it and export it.
-- **🌊 Intuitive**: favour always the most intuitive API and common usage, _never_ throw errors unless asked.
+- **🌊 Intuitive**: favour always the most intuitive API and common usage, _never_ throw error unless asked to.
 - **🙈 Semantic**: use simple function names that are easy to remember, no complicated options.
 
 Contributions always welcome!
@@ -18,12 +18,14 @@ Contributions always welcome!
 - `isArray()`
 - `isBoolean()`
 - `isBrowser()` to detect if you are on the browser
-- `isClient()` to detect if you are ont the browser/client
+- `isBuffer()`
+- `isClient()` same as isBrowser
 - `isEmail()` this is a relaxed check, use your own validation if you need to be strict
 - ⭐ `isEmpty()` to check for empty object, empty array, empty string, null or undefined
   - `isEmptyString()` trims the string and checks if something is left
   - `isEmptyArray()`
   - `isEmptyObject()`
+- `isFile()`
 - `isFunction()`
 - `isJsDate()` if it's a **valid** javascript's Date
   - `isFutureDate()`
@@ -38,7 +40,7 @@ Contributions always welcome!
   - `isOdd()`
   - `isPositiveInt()`
   - `isNegativeInt()`
-- `isNumeric()`
+- `isNumeric()` if string is representing a number
 - ⭐ `isObject()` if it's a js plain Object
 - `isPromise()`
 - `isPWA()`
@@ -52,11 +54,12 @@ Contributions always welcome!
 
 ### Math
 
-- `average()` numbers of an array
-- `max()` numbers of an array
-- `min()` numbers of an array
-- `multiply()` numbers of an array
-- `sum()` numbers an array
+- `average()`
+- `max()`
+- `min()`
+- `multiply()`
+- `percentageChange()`
+- `sum()`
 
 ### Helpers
 
@@ -71,7 +74,6 @@ Contributions always welcome!
 - `first()` get the first element of an array
 - `firstKey()`
 - `firstValue()`
-- `getKeys()` get the keys of an object, includes symbols
 - `getUrlSearchParam()`
 - `getUrlSearchParams()`
 - `incrementalId()` autoincremental SQL-like, process-unique numeric id
@@ -98,9 +100,12 @@ Contributions always welcome!
 
 ### Formatters
 
+- `formatCamelCase()`
 - `formatNumber()` 1000 => "1,000" or "1K" or 0.112 => "11.2%"
-- `stringToUnicode()` "hello" => "\u0068\u0065\u006c\u006c\u006f"
+- `formatPercentage()` 0.11 => "11%"
+- `formatProgress()` => "[2/10]"
 - `stringToCSSUnicode()` "hello" => "\000068\000065\00006c\00006c\00006f" use this for CSS
+- `stringToUnicode()` "hello" => "\u0068\u0065\u006c\u006c\u006f"
 
 ### Random data generators
 
@@ -127,6 +132,7 @@ These functions are optimized for low entropy random data generation useful for
 - `randomEnumValue()` enum FRUIT { APPLE = 1, PEAR = 3 } => 3
 - `randomFile()`
 - `randomFloat()`
+- `randomObject()`
 - `randomHandle()` useful for social identifiers, or slugs
 - `randomHexColor()`
 - `randomHexValue()`
@@ -149,6 +155,7 @@ These functions are optimized for low entropy random data generation useful for
 - `randomPhoneNumber()`
 - `randomString()`
 - `randomUUID()` lightweight uuid generation, passing UUID validation
+- `randomValue()`
 - `randomWord()`
 
 ### Checks
@@ -167,20 +174,21 @@ Checks are functions that throw an error, if the validation fails
   - `MaybePromiseOrValue<>`
   - `MaybePromiseOrValueArray<>`
 - `NonUndefined`
+- `Key`
 - `ObjectKey<>`
 - `ObjectKeys<>`
 - `ObjectValue<>`
 - `ObjectValues<>`
+- `ObjectEntry<>`
 - `ObjectEntries<>`
 - ⭐ `PlainObject` use this instead of `Record<,>` or `extends object`, also makes sure it's not an array
 - `Point`
-- `PrismaSelect<>`
 - `HashMap<>`
-- `HashMapKey`
-- `NumberMap`
-- `StringMap`
-- `BoolMap`
-- `TrueMap`
+  - `BoolMap`
+  - `NumberMap`
+  - `StringMap`
+  - `TrueMap`
+- `VoidFn`
 
 ## Development
 

package/dist/index.d.ts

@@ -38,6 +38,8 @@ type Config = {
  */
 declare const checkEnvVars: (envVarsMap: Record<string, SimpleValidationRule | EnvValidation | WithEnvValidation>, config?: Config) => void;
 
+declare const formatCamelCase: (str: string) => string;
+
 /**
  *
  * @example formatNumber(1000, { compact: true }) // 1K
@@ -51,10 +53,30 @@ declare const formatNumber: (value: number, { compact, maxDigits, percentage, }?
     percentage?: boolean | undefined;
 }) => string;
 
-declare const stringToUnicode: (text: string) => string;
+/**
+ *
+ * @example formatPercentage(1) => 100%
+ * @example formatPercentage(0, { digits: 2 }) => 0.00%
+ */
+declare const formatPercentage: (value: number, { digits, }?: {
+    digits?: number | undefined;
+}) => string;
+
+/**
+ *
+ * @example formatProgress({ index: -1, total: 10 }) => [1/10] capped
+ * @example formatProgress({ index: 1, total: 10 }) => [2/10]
+ * @example formatProgress({ index: 11, total: 10 }) => [10/10] capped
+ */
+declare const formatProgress: ({ index, total, }: {
+    index: number;
+    total: number;
+}) => string;
 
 declare const stringToCSSUnicode: (text: string) => string;
 
+declare const stringToUnicode: (text: string) => string;
+
 declare const array: <U extends (...args: any) => any>(length: number, mapFn?: U) => ReturnType<U>[];
 
 declare const arrayDiff: (arr1: any[], arr2: any[]) => any[];
@@ -63,6 +85,19 @@ declare const arrayIntersection: <T>(arr1: T[], arr2: T[]) => T[];
 
 declare const capitalize: (string: string) => string;
 
+declare const chunkArray: <T>(array: T[], size: number) => T[][];
+
+declare const chunkedAll: <T>(array: T[], chunkSize: number, fn: (chunk: T[]) => Promise<any>) => Promise<any[]>;
+
+/**
+ * @description Run a series of (async) functions in order and return the results
+ * @param array
+ * @param chunkSize
+ * @param fn
+ *
+ */
+declare const chunkedAsync: <T>(array: T[], chunkSize: number, fn: (chunk: T[]) => Promise<any>) => Promise<any[]>;
+
 declare const clamp: ({ number, min, max, }: {
     number: number;
     min: number;
@@ -81,13 +116,15 @@ declare const cyclicalItem: <T>(array: T[], index: number) => T;
  */
 declare const dir: (arg: any, depth?: number) => void;
 
+type Key = string | number | symbol;
 type ObjectKey<T> = keyof T;
 type ObjectKeys<T> = ObjectKey<T>[];
 type ObjectValue<T> = T[keyof T];
 type ObjectValues<T> = ObjectValue<T>[];
-type ObjectEntries<T> = {
+type ObjectEntry<T> = {
     [K in keyof T]: [K, T[K]];
-}[keyof T][];
+}[keyof T];
+type ObjectEntries<T> = ObjectEntry<T>[];
 
 declare const enumKeys: <T extends object>(arg: T) => ObjectKeys<T>;
 
@@ -112,12 +149,11 @@ type Dimensions = {
     height: number;
 };
 
-type HashMapKey = string | number | symbol;
-type HashMap<T> = Record<HashMapKey, T>;
-type NumberMap = Record<HashMapKey, number>;
-type StringMap = Record<HashMapKey, string>;
-type BoolMap = Record<HashMapKey, boolean>;
-type TrueMap = Record<HashMapKey, true>;
+type HashMap<T> = Record<Key, T>;
+type NumberMap = Record<Key, number>;
+type StringMap = Record<Key, string>;
+type BoolMap = Record<Key, boolean>;
+type TrueMap = Record<Key, true>;
 
 type Matrix<T> = T[][];
 
@@ -128,7 +164,11 @@ type MaybePromiseOrValueArray<T> = MaybePromiseOrValue<T>[];
 
 type NonUndefined<T> = T extends undefined ? never : T;
 
-type PlainObject = Record<string | symbol, any> & {
+/**
+ * A plain object is an object that is not an array, does not have a length property, and is not a function.
+ * Would have been nice to call it just Object, but that's already taken by the built-in type.
+ */
+type PlainObject<T = any> = Record<Key, T> & {
     length?: never;
 };
 
@@ -139,12 +179,16 @@ type Point = {
 
 type PrismaSelect<T> = Record<keyof T, true>;
 
-declare const firstKey: <T extends PlainObject>(arg: T) => keyof T;
+declare const firstKey: <T extends PlainObject<any>>(arg: T) => keyof T;
 
-declare const firstValue: <T extends PlainObject>(arg: T) => ObjectValue<T>;
+declare const firstValue: <T extends PlainObject<any>>(arg: T) => ObjectValue<T>;
 
-declare const getKeys: <T extends PlainObject>(obj: T) => ObjectKeys<T>;
-declare const getEnumerableOwnPropertySymbols: (obj: object) => any[];
+/**
+ * TODO: rename to allKeys
+ * @deprecated use Object.keys instead unless you need to include symbols, but the function will be renamed to allKeys
+ */
+declare const getKeys: <T extends PlainObject<any>>(obj: T) => (string | symbol)[];
+declare const getEnumerableOwnPropertySymbols: (obj: object) => symbol[];
 
 declare const getUrlSearchParam: (urlString: Maybe<string>, param: string) => string | undefined;
 
@@ -152,7 +196,7 @@ declare const getUrlSearchParams: (urlString: Maybe<string>) => Record<string, s
 
 declare const incrementalId: () => number;
 
-declare const keysLength: <T extends PlainObject>(obj: T) => number;
+declare const keysLength: <T extends PlainObject<any>>(obj: T) => number;
 
 declare const last: <T>(arr: T[]) => T;
 
@@ -162,7 +206,7 @@ declare const lastIndex: (array: any[]) => number;
  * @description Simple merge function that merges two objects, arrays get overwritten, no options
  *
  */
-declare const merge: (target: PlainObject, source: PlainObject) => PlainObject;
+declare const merge: (target: PlainObject, source: PlainObject) => PlainObject<any>;
 
 /**
  * @description Merge two arrays, unique values, no options
@@ -180,15 +224,15 @@ declare const normalizeNumber: ({ value, max, min, }: {
     min: number;
 }) => number;
 
-declare const objectDiff: (leftObject: PlainObject, rightObject: PlainObject) => PlainObject;
+declare const objectDiff: (leftObject: PlainObject, rightObject: PlainObject) => PlainObject<any>;
 
-declare const omit: <T extends PlainObject>(obj: T, keys: (keyof T)[]) => Partial<T>;
+declare const omit: <T extends PlainObject<any>>(obj: T, keys: (keyof T)[]) => Partial<T>;
 
 declare const parseDate: (arg?: Maybe<DateLike>) => Date | undefined;
 
-declare const pickObjectKeys: <T extends PlainObject>(obj: T, keys: ObjectKeys<T>) => Partial<T>;
+declare const pickObjectKeys: <T extends PlainObject<any>>(obj: T, keys: ObjectKeys<T>) => Partial<T>;
 
-declare const pickObjectValues: <T extends PlainObject>(obj: T, values: ObjectValues<T>) => Partial<T>;
+declare const pickObjectValues: <T extends PlainObject<any>>(obj: T, values: ObjectValues<T>) => Partial<T>;
 
 declare const pretty: (arg?: any) => string;
 
@@ -197,13 +241,13 @@ declare const promiseWithTimeout: <T>(promise: () => Promise<T>, timeoutMs: numb
 declare const scrambleText: (str: string) => string;
 
 /**
- * Serialize plain object to a deterministic string,
+ * Serialize shallow object to a deterministic string,
  * for nested objects use [json-stable-stringify](https://www.npmjs.com/package/json-stable-stringify)
  *
  * @example
  * serialize({ b: 1, a: 2 }) // '{"a":1,"b":2}'
  */
-declare const serialize: <T extends PlainObject>(obj: T) => string;
+declare const serialize: <T extends PlainObject<any>>(obj: T) => string;
 
 /**
  *
@@ -213,8 +257,7 @@ declare const serialize: <T extends PlainObject>(obj: T) => string;
  *  () => Promise.resolve(1),
  *  () => sleep(100).then(() => 2),
  *  () => Promise.resolve(3),
- * ]);
- * @returns [1, 2, 3]
+ * ]); => [1, 2, 3]
  */
 declare const seriesAll: <T>(series: Function[]) => Promise<T[]>;
 
@@ -463,6 +506,8 @@ declare const isBoolean: (arg: any) => arg is boolean;
 
 declare const isBrowser: () => boolean;
 
+declare const isBuffer: (val?: any) => boolean;
+
 declare const isClient: () => boolean;
 
 declare const isEmail: (arg: string) => boolean;
@@ -472,13 +517,15 @@ declare const isEmptyString: (arg: string) => boolean;
 declare const isEmptyArray: (arg: any[]) => boolean;
 declare const isEmptyObject: (arg: PlainObject) => boolean;
 
+declare const isFile: (arg?: any) => arg is File;
+
 declare const isFunction: (arg: any) => arg is Function;
 
 declare const isFutureDate: (arg: DateLike) => boolean;
 
 declare const isJsDate: (arg: Date) => arg is Date;
 
-declare const isKey: <T extends object>(key: string | number | symbol, obj: T) => key is keyof T;
+declare const isKey: <T extends object>(key: Key, obj: T) => key is keyof T;
 
 declare const isLastIndex: (index: number, array: any[]) => boolean;
 
@@ -499,11 +546,18 @@ declare const isNegative: (arg: any) => boolean;
 declare const isNegativeInt: (arg: any) => boolean;
 declare const isNumber: (arg: any) => arg is number;
 
+/**
+ *
+ * @example isNumeric(1) => true
+ * @example isNumeric('1') => true
+ * @example isNumeric('1.1') => true
+ * @example isNumeric('1.1.1') => false
+ */
 declare const isNumeric: (arg: number | string) => boolean;
 
 declare const isNumericId: (id: string) => boolean;
 
-declare const isObject: <T>(arg?: any) => arg is Record<string, T>;
+declare const isObject: <T>(arg?: any) => arg is PlainObject<T>;
 
 declare const isPastDate: (arg: DateLike) => boolean;
 
@@ -531,4 +585,4 @@ declare const isUUID: (arg: string) => boolean;
 
 declare const isValue: (arg?: Maybe<any>) => boolean;
 
-export { BoolMap, Coords, DateLike, DateRange, Datey, Dimensions, HashMap, HashMapKey, JS_MAX_DIGITS, Matrix, Maybe, MaybePromise, MaybePromiseOrValue, MaybePromiseOrValueArray, NonUndefined, NumberMap, ObjectEntries, ObjectKey, ObjectKeys, ObjectValue, ObjectValues, PlainObject, Point, PrismaSelect, StringMap, TrueMap, array, arrayDiff, arrayIntersection, average, capitalize, checkEnvVars, clamp, cleanSpaces, cyclicalItem, dir, enumKeys, enumValues, first, firstKey, firstValue, formatNumber, formatTrpcInputQueryString, getEnumerableOwnPropertySymbols, getKeys, getUrlSearchParam, getUrlSearchParams, incrementalId, isArray, isArrayIncluded, isBoolean, isBrowser, isClient, isEmail, isEmpty, isEmptyArray, isEmptyObject, isEmptyString, isEven, isFunction, isFutureDate, isInt, isJsDate, isKey, isLastIndex, isNegative, isNegativeInt, isNotEmptyString, isNumber, isNumeric, isNumericId, isObject, isOdd, isPWA, isPastDate, isPositive, isPositiveInt, isPromise, isReactElement, isRegExp, isSame, isServer, isSpacedString, isString, isStringDate, isURL, isUUID, isValue, keysLength, last, lastIndex, max, merge, mergeArrays, min, moveToFirst, moveToLast, multiply, normalizeNumber, objectDiff, omit, parseDate, percentageChange, pickObjectKeys, pickObjectValues, pretty, prismaDateRange, promiseWithTimeout, randomAddress, randomAlphaNumericCode, randomArrayItem, randomBankAccount, randomBool, randomChar, randomCompany, randomCoords, randomDate, randomDateRange, randomEmail, randomEmoji, 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, randomNumericId, randomParagraph, randomPassword, randomPastDate, randomPath, randomPercentage, randomPhoneNumber, randomPositiveInt, randomPositivePercentage, randomString, randomUUID, randomVerb, randomWord, scrambleText, serialize, seriesAll, setUrlSearchParams, shuffle, sleep, stringToCSSUnicode, stringToUnicode, sum, toggleArray, toggleArrayValue, truncate, uniqueValues };
+export { BoolMap, Coords, DateLike, DateRange, Datey, Dimensions, HashMap, JS_MAX_DIGITS, Key, Matrix, Maybe, MaybePromise, MaybePromiseOrValue, MaybePromiseOrValueArray, NonUndefined, NumberMap, ObjectEntries, ObjectEntry, ObjectKey, ObjectKeys, ObjectValue, ObjectValues, PlainObject, Point, PrismaSelect, StringMap, TrueMap, array, arrayDiff, arrayIntersection, average, capitalize, checkEnvVars, chunkArray, chunkedAll, chunkedAsync, clamp, cleanSpaces, cyclicalItem, dir, enumKeys, enumValues, first, firstKey, firstValue, formatCamelCase, formatNumber, formatPercentage, formatProgress, formatTrpcInputQueryString, getEnumerableOwnPropertySymbols, getKeys, getUrlSearchParam, getUrlSearchParams, incrementalId, isArray, isArrayIncluded, 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, isPWA, isPastDate, isPositive, isPositiveInt, isPromise, isReactElement, isRegExp, isSame, isServer, isSpacedString, isString, isStringDate, isURL, isUUID, isValue, keysLength, last, lastIndex, max, merge, mergeArrays, min, moveToFirst, moveToLast, multiply, normalizeNumber, objectDiff, omit, parseDate, percentageChange, pickObjectKeys, pickObjectValues, pretty, prismaDateRange, promiseWithTimeout, randomAddress, randomAlphaNumericCode, randomArrayItem, randomBankAccount, randomBool, randomChar, randomCompany, randomCoords, randomDate, randomDateRange, randomEmail, randomEmoji, 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, randomNumericId, randomParagraph, randomPassword, randomPastDate, randomPath, randomPercentage, randomPhoneNumber, randomPositiveInt, randomPositivePercentage, randomString, randomUUID, randomVerb, randomWord, scrambleText, serialize, seriesAll, setUrlSearchParams, shuffle, sleep, stringToCSSUnicode, stringToUnicode, sum, toggleArray, toggleArrayValue, truncate, uniqueValues };