@valkyriestudios/utils 11.0.0 → 11.2.0

package/array/dedupe.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Dedupes the provided array
+ *
+ * @param val - Array to dedupe
+ *
+ * @returns Deduped array
+ */
+export default function dedupe(val: any[]): any[];

package/array/is.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Check whether or not a provided value is an array
+ *
+ * @param val - Value to verify
+ *
+ * @returns Whether or not the value is an array
+ */
+export default function isArray(val: any): boolean;

package/array/isNotEmpty.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Check whether or not a provided value is an array with content
+ *
+ * @param val - Value to verify
+ *
+ * @returns Whether or not the value is an array with content
+ */
+export default function isNotEmptyArray(val: any): boolean;

package/array/join.d.ts

@@ -0,0 +1,36 @@
+interface joinOptions {
+    /**
+     * Delimiter to join with
+     * (default=' ')
+     * eg: join(['hello', 'world', {delim: '_'}]) -> 'hello_world'
+     */
+    delim?: string;
+    /**
+     * Trim after joining or not
+     * (default=true)
+     * eg: join(['  hello', 'world  '], {trim: true}) -> 'hello world'
+     */
+    trim?: boolean;
+    /**
+     * Automatically trim all string values
+     * (default=true)
+     * eg: join([' hello   ', ' world '], {valtrim: true}) -> 'hello world'
+     */
+    valtrim?: boolean;
+    /**
+     * Automatically round all numeric values
+     * (default=false)
+     * eg: join([5.432, 'world', 1.2], {valround: 1}) -> '5.4 world 1.2'
+     */
+    valround?: number;
+}
+/**
+ * Join an array of values while autofiltering any non-string/non-number elements
+ *
+ * @param val - Array of values to join
+ * @param opts - Join options
+ *
+ * @returns Joined array as string
+ */
+export default function join(val: any[], opts?: joinOptions): string;
+export {};

package/array/mapFn.d.ts

@@ -0,0 +1,40 @@
+interface mapOptions {
+    /**
+     * Allow merging existing keys or not, if not keys will be overriden if they exist
+     * (default=false)
+     *
+     * Example:
+     *  mapFn([{uid: 12, a: 'hi'}, {uid: 12, b: 'ho'}], el => el.uid, {merge: true})
+     * Output:
+     *  {12: {uid: 12, a: 'hi', b: 'ho'}}
+     * Output if merge is false
+     *  {12: {uid: 12, b: 'ho'}}
+     */
+    merge?: boolean;
+}
+interface kvMap {
+    [key: string]: {
+        [key: string]: any;
+    };
+}
+/**
+ * Map an object array into a kv-object through a function that generates a key. Returning a non-string,
+ * non-numeric value from the function (eg: false) will filter out the object.
+ *
+ * Example:
+ *  mapFn([{uid: 12, name: 'Peter'}, {uid: 15, name: 'Jonas'}], el => el.uid);
+ * Output:
+ *  {12: {uid: 12, name: 'Peter'}, 15: {uid: 15, name: 'Jonas'}}
+ *
+ * @param val - Array to map
+ * @param fn - Handler function which is run for each of the objects and should return a string or number
+ * @param opts - Options object to override built-in defaults
+ *
+ * @returns KV-Map object
+ */
+export default function mapFn(arr: {
+    [key: string]: any;
+}[], fn: (entry: {
+    [key: string]: any;
+}) => (string | number | boolean), opts?: mapOptions): kvMap;
+export {};

package/array/mapKey.d.ts

@@ -0,0 +1,38 @@
+interface mapOptions {
+    /**
+     * Allow merging existing keys or not, if not keys will be overriden if they exist
+     * (default=false)
+     *
+     * Example:
+     *  mapKey([{uid: 12, a: 'hi'}, {uid: 12, b: 'ho'}], 'uid', {merge: true})
+     * Output:
+     *  {12: {uid: 12, a: 'hi', b: 'ho'}}
+     * Output if merge is false
+     *  {12: {uid: 12, b: 'ho'}}
+     */
+    merge?: boolean;
+}
+interface kvMap {
+    [key: string]: {
+        [key: string]: any;
+    };
+}
+/**
+ * Map an object array into a kv-object by passing a common key that exists on the objects. Objects for
+ * which the key doesn't exist will be filtered out automatically
+ *
+ * Example:
+ *  mapKey([{uid: 12, name: 'Peter'}, {uid: 15, name: 'Jonas'}], 'uid');
+ * Output:
+ *  {12: {uid: 12, name: 'Peter'}, 15: {uid: 15, name: 'Jonas'}}
+ *
+ * @param val - Array to map
+ * @param key - Key to map by
+ * @param opts - Options object to override built-in defaults
+ *
+ * @returns KV-Map object
+ */
+export default function mapKey(arr: {
+    [key: string]: any;
+}[], key: string, opts?: mapOptions): kvMap;
+export {};

package/array/mapPrimitive.d.ts

@@ -0,0 +1,40 @@
+interface mapOptions {
+    /**
+     * Automatically trim all string values
+     * (default=false)
+     * eg: join([' hello   ', ' world '], {valtrim: true}) -> 'hello world'
+     */
+    valtrim?: boolean;
+    /**
+     * Automatically round all numeric values
+     * (default=false)
+     * eg: mapPrimitive([5.432, 5.4, 5.43, 4.2, 4.1], {valround: true}) -> {'5.432': 5, '5.4': 5, '5.43': 5, '4.2': 4, '4.1': 4}
+     * eg: mapPrimitive([5.432, 5.43, 4.21, 4.1], {valround: 1}) -> {'5.432': 5.4, '5.43': 5.4, '4.21': 4.2, '4.1': 4.1}
+     */
+    valround?: boolean | number;
+    /**
+     * Automaticaly round all keys from numeric values
+     * (default=false)
+     * eg: mapPrimitive([5.432, 5.4, 5.43, 4.2, 4.1], {keyround: true}) -> {5: 5.43, 4: 4.1}
+     */
+    keyround?: boolean;
+}
+interface mapReturn {
+    [key: string]: string | number;
+}
+/**
+ * Map an array of primitive values (numbers/strings) into a kv-object
+ * non-numeric and non-string values will be filtered out
+ *
+ * Example:
+ *  mapPrimitive(['hello', 'hello', 'foo', 'bar']);
+ * Output:
+ *  {hello: 'hello', foo: 'foo', bar: 'bar'}
+ *
+ * @param val - Array to map
+ * @param opts - Options object to override built-in defaults
+ *
+ * @returns KV-Map object
+ */
+export default function mapPrimitive(arr: any[], opts?: mapOptions): mapReturn;
+export {};

package/array/shuffle.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shuffle an array using a Fisher-Yates shuffle O(n)
+ * https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
+ *
+ * Take Note: The passed array will be changed and edited in place
+ *
+ * @param val - Array to shuffle
+ */
+export default function shuffle(arr: any[]): void;

package/array/sort.d.ts

@@ -0,0 +1,58 @@
+interface sortOptions {
+    /**
+     * Filter function to apply to the array before sorting
+     * (default=isNotEmptyObject)
+     */
+    filter_fn?: (el: any) => boolean;
+    /**
+     * Remove objects that don't have the key or where the key is falsy
+     * (default=false)
+     */
+    nokey_hide?: boolean;
+    /**
+     * Move invalid values (eg: non-objects or objects that don't match the key/function passed) to the end of the sorted array
+     * (default=true)
+     */
+    nokey_atend?: boolean;
+}
+interface sortObject {
+    [key: string]: any;
+}
+type sortByFunction = (el: sortObject) => string;
+/**
+ * Sort an array of objects, uses an implementation of Tony Hoare's quicksort
+ * (https://cs.stanford.edu/people/eroberts/courses/soco/projects/2008-09/tony-hoare/quicksort.html)
+ *
+ * Example:
+ *  sort([
+ *      {test: 'Peter'},
+ *      {test: 'Jack'},
+ *      {test: 'Pony'},
+ *      {test: 'John'},
+ *      {test: 'Joe'},
+ *      {test: 'Bob'},
+ *      {test: 'Alice'},
+ *  ], 'test', 'desc');
+ * Output:
+ *  [{test: 'Pony'}, {test: 'Peter'}, {test: 'John'}, {test: 'Joe'}, {test: 'Jack'}, {test: 'Bob'}, {test: 'Alice'}]
+ *
+ * Example w/ Function:
+ *  sort([
+ *      {test: 'Peter'},
+ *      {test: 'Pony'},
+ *      {test: 'JOHn'},
+ *      {test: 'Joe'},
+ *  ], el => el.test.toLowerCase(), 'desc');
+ * Output:
+ *  [{test: 'Pony'}, {test: 'Peter'}, {test: 'JOHn'}, {test: 'Joe'}]
+ *
+ * @param val - Array to sort
+ * @param by - Either a string (key) or a function
+ * @param dir - (default='asc') Direction to sort in (asc or desc)
+ * @param opts - Sort options
+ *
+ * @returns Sorted array
+ * @throws {Error}
+ */
+export default function sort(arr: sortObject[], by: string | sortByFunction, dir?: 'asc' | 'desc', opts?: sortOptions): sortObject[];
+export {};

package/boolean/is.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Check whether or not a provided value is a boolean
+ *
+ * @param val - Value to verify
+ *
+ * @returns Whether or not the value is a boolean
+ */
+export default function isBoolean(val: any): boolean;

package/caching/memoize.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Turn a function into a memoized function. An optional resolver function can be passed which allows custom cache key generation.
+ *
+ * Example:
+ *  const memoized_function = memoize((a) => fnv1A(a));
+ *
+ * @param fn - Function to memoize
+ * @param resolver - Optional resolver function to generate cache key. If not passed the first argument is used as map key
+ */
+export default function memoize(fn: Function, resolver?: Function): Function;

package/date/addUTC.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Adds the provided amount of a specific key to the provided date
+ *
+ * @param val - Date to set to end of
+ * @param amount - (default=0) Amount of key to add
+ * @param key - (default='millisecond') Key to set
+ *
+ * @returns New date with provided amount of key added
+ */
+export default function addUTC(val: Date, amount?: number, key?: 'years' | 'year' | 'months' | 'month' | 'days' | 'day' | 'hours' | 'hour' | 'minutes' | 'minute' | 'seconds' | 'second' | 'milliseconds' | 'millisecond'): Date;

package/date/diff.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compute the diff between two dates in the provided key
+ *
+ * @param val_a - Date to diff against
+ * @param val_b - Date to diff with
+ * @param key - (default='millisecond') Key to diff in
+ *
+ * @returns Numerical diff between two dates
+ */
+export default function diff(val_a: Date, val_b: Date, key?: 'week' | 'weeks' | 'day' | 'days' | 'hour' | 'hours' | 'minute' | 'minutes' | 'second' | 'seconds' | 'millisecond' | 'milliseconds'): number;

package/{dist/date → date}/endOfUTC.d.ts

@@ -1 +1,9 @@
+/**
+ * Sets the provided date to end of UTC of provided key
+ *
+ * @param val - Date to set to end of
+ * @param key - (default='millisecond') Key to set
+ *
+ * @returns New date set to end of key
+ */
 export default function endOfUTC(val: Date, key?: 'year' | 'quarter' | 'month' | 'week' | 'week_sun' | 'week_mon' | 'week_tue' | 'week_wed' | 'week_thu' | 'week_fri' | 'week_sat' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond'): Date;

package/date/is.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Check whether or not a provided value is a Date
+ *
+ * @param val - Value to verify
+ *
+ * @returns Whether or not the value is a Date
+ */
+export default function isDate(val: any): boolean;

package/date/nowUnix.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Compute the current unix timestamp in seconds
+ *
+ * @returns Current unix timestamp in seconds
+ */
+export default function nowUnix(): number;

package/date/nowUnixMs.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Compute the current unix timestamp in milliseconds
+ *
+ * @returns Current unix timestamp in milliseconds
+ */
+export default function nowUnixMs(): number;

package/{dist/date → date}/startOfUTC.d.ts

@@ -1 +1,9 @@
+/**
+ * Sets the provided date to start of UTC of provided key
+ *
+ * @param val - Date to set to start of
+ * @param key - (default='millisecond') Key to set
+ *
+ * @returns New date set to start of key
+ */
 export default function startOfUTC(val: Date, key?: 'year' | 'quarter' | 'month' | 'week' | 'week_sun' | 'week_mon' | 'week_tue' | 'week_wed' | 'week_thu' | 'week_fri' | 'week_sat' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond'): Date;

package/date/toUTC.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sets a passed date to UTC
+ *
+ * @param val - Date to set to UTC
+ *
+ * @returns New date object set to the UTC contents of the passed date
+ */
+export default function toUTC(val: Date): Date;

package/date/toUnix.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns the unix time in seconds of the passed date
+ *
+ * @param val - Date to get the unix time for
+ *
+ * @returns Unix time in seconds
+ */
+export default function toUnix(val: Date): number;

package/{dist/deep → deep}/freeze.d.ts

@@ -3,5 +3,12 @@ type deepInput = {
 } | {
     [key: string]: any;
 }[] | any[];
+/**
+ * Recursively freezes all properties of an object
+ *
+ * @param obj - Object to deep freeze
+ *
+ * @returns Deeply frozen object
+ */
 export default function deepFreeze(obj: deepInput): Readonly<deepInput>;
 export {};

package/deep/get.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Get a property's value deep inside the structure of an array/object
+ *
+ * Example:
+ *  const myObj = {
+ *      a: 2,
+ *      b: [
+ *          {price : 2},
+ *          {price : 4},
+ *      ],
+ *  };
+ *  deepGet(myObj, 'b[0].price');
+ * Output:
+ *  2
+ *
+ * @param val - Object/Array to get the value from
+ * @param path - Path string to deeply get the value at
+ * @param get_parent - If passed as true retrieves the parent of where the value lives
+ *
+ * @returns Value stored at property or undefined
+ * @throws {TypeError}
+ */
+export default function deepGet(obj: {
+    [key: string]: any;
+} | {
+    [key: string]: any;
+}[] | any[], path: string, get_parent?: boolean): any | undefined;

package/{dist/deep → deep}/seal.d.ts

@@ -3,5 +3,12 @@ type deepInput = {
 } | {
     [key: string]: any;
 }[] | any[];
+/**
+ * Recursively seals all properties of an object
+ *
+ * @param obj - Object to deep seal
+ *
+ * @returns Deeply sealed object
+ */
 export default function deepSeal(obj: deepInput): deepInput;
 export {};

package/deep/set.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Sets a property and its value deep in the structure of an object
+ *
+ * Example:
+ *  const myObj = {a: 2};
+ *  deepSet(myObj, 'b.c.d.e', 4);
+ * Output:
+ *  {
+ *      a: 2,
+ *      b: {
+ *          c: {
+ *              d: {
+ *                  e: 4
+ *              }
+ *          }
+ *      }
+ *  }
+ *
+ * Example:
+ *  const myObj = {a: 2, b: [{price: 2}]};
+ *  deepSet(myObj, 'b[0].price', 4);
+ * Output:
+ *  {
+ *      a: 2,
+ *      b: [
+ *          {price: 4}
+ *      ]
+ *  }
+ *
+ * @param val - Object to set the value on
+ * @param path - Path string to deeply set the value at
+ * @param value - Value to set (if using defineProperty can be an accessor object)
+ * @param define - Whether or not the property should be directly assigned or set using Object.defineProperty
+ *
+ * @returns True or false depending on whether or not the property was set correctly
+ * @throws {TypeError}
+ */
+export default function deepSet(obj: {
+    [key: string]: any;
+} | {
+    [key: string]: any;
+}[] | any[], path: string, value: any, define?: boolean): boolean;

package/equal.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compute whether or not two provided values are deeply equal
+ *
+ * @param a - Value to compare against
+ * @param b - Value to compare with
+ *
+ * @returns Whether or not they are equal
+ */
+declare function equal(a: any, b: any): boolean;
+export default equal;

package/function/is.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Check whether or not a provided value is a Function
+ *
+ * @param val - Value to verify
+ *
+ * @returns Whether or not the value is a Function
+ */
+export default function isFunction(val: any): boolean;

package/function/noop.d.ts

@@ -0,0 +1,6 @@
+/**
+ * No-Operation (noop) function that does nothing and simply returns.
+ *
+ * @returns Void
+ */
+export default function noop(): void;

package/function/noopresolve.d.ts

@@ -0,0 +1,9 @@
+/**
+ * No-Operation (noop) resolver that simply returns a promise
+ * that resolves with the value that was passed to it
+ *
+ * @param val - Value to be resolved with
+ *
+ * @returns Promise that resolves with passed value
+ */
+export default function noopresolve(val?: any): Promise<any>;

package/function/noopreturn.d.ts

@@ -0,0 +1,8 @@
+/**
+ * No-Operation (noop) function that returns the value passed to it when called.
+ *
+ * @param val - Value to return
+ *
+ * @returns Passed value
+ */
+export default function noopreturn(val?: any): any;

package/function/sleep.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns a promise that resolves after X milliseconds, useful in
+ * async scenarios where we wish to wait for a specific periodic of time
+ *
+ * @param ms - (default=1000) Amount of milliseconds to wait for
+ *
+ * @returns Promise that resolves after X milliseconds
+ */
+export default function sleep(ms?: number): Promise<void>;

package/hash/fnv1A.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Convert a provided value into a Fowler-Noll-Vo 1A hash
+ * For more info: https://tools.ietf.org/html/draft-eastlake-fnv-03
+ *
+ * @param data - Value to be converted
+ * @param offset - (default=2166136261) FNV prime to use
+ *
+ * @returns FNV1A hash of provided value
+ */
+export default function fnv1A(data: any, offset?: number): number;

package/hash/guid.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generate a unique identifier (guid) according to RFC4122
+ *
+ * @returns Generated guid string
+ */
+export default function guid(): string;