@valkyriestudios/utils 10.0.0 → 11.1.0

package/README.md

@@ -5,7 +5,7 @@
 [![npm](https://img.shields.io/npm/v/@valkyriestudios/utils.svg)](https://www.npmjs.com/package/@valkyriestudios/utils)
 [![npm](https://img.shields.io/npm/dm/@valkyriestudios/utils.svg)](https://www.npmjs.com/package/@valkyriestudios/utils)
 
-A collection of single-function utilities for common tasks
+Zero-dependency collection of single-function utilities for common tasks
 
 `npm install @valkyriestudios/utils`
 

package/dist/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/dist/array/dedupe.js

@@ -0,0 +1,19 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const fnv1A_1 = require("../hash/fnv1A");
+function dedupe(val) {
+    if (!Array.isArray(val) || val.length === 0)
+        return [];
+    const map = new Map();
+    const acc = [];
+    let hash;
+    for (const item of val) {
+        hash = (0, fnv1A_1.default)(item);
+        if (map.has(hash))
+            continue;
+        map.set(hash, true);
+        acc.push(item);
+    }
+    return acc;
+}
+exports.default = dedupe;

package/dist/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/dist/array/is.js

@@ -0,0 +1,6 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+function isArray(val) {
+    return Array.isArray(val);
+}
+exports.default = isArray;

package/dist/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/dist/array/isNotEmpty.js

@@ -0,0 +1,6 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+function isNotEmptyArray(val) {
+    return Array.isArray(val) && val.length !== 0;
+}
+exports.default = isNotEmptyArray;

package/dist/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/dist/array/join.js

@@ -0,0 +1,24 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const round_1 = require("../number/round");
+function join(val, opts = {}) {
+    if (!Array.isArray(val) || val.length === 0)
+        return '';
+    const OPTS = Object.assign({
+        delim: ' ',
+        trim: true,
+        valtrim: true,
+        valround: false,
+    }, Object.prototype.toString.call(opts) === '[object Object]' ? opts : {});
+    const filtered = [];
+    for (const el of val) {
+        if (typeof el === 'string' && el.trim().length > 0) {
+            filtered.push(OPTS.valtrim === true ? el.trim() : el);
+        }
+        else if (Number.isFinite(el)) {
+            filtered.push(Number.isFinite(OPTS.valround) ? (0, round_1.default)(el, OPTS.valround) : el);
+        }
+    }
+    return OPTS.trim === true ? filtered.join(OPTS.delim).trim() : filtered.join(OPTS.delim);
+}
+exports.default = join;

package/dist/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/{src/array/mapFn.mjs → dist/array/mapFn.js}

@@ -1,30 +1,28 @@
 'use strict';
-
-export default function mapFn (arr, fn, opts) {
-    if (
-        (!Array.isArray(arr) || arr.length === 0) ||
-        typeof fn !== 'function'
-    ) return {};
-
+Object.defineProperty(exports, "__esModule", { value: true });
+function mapFn(arr, fn, opts = {}) {
+    if ((!Array.isArray(arr) || arr.length === 0) ||
+        typeof fn !== 'function')
+        return {};
     const OPTS = Object.assign({
         merge: false,
     }, Object.prototype.toString.call(opts) === '[object Object]' ? opts : {});
-
     const map = {};
     let hash = false;
     for (const el of arr) {
-        if (Object.prototype.toString.call(el) !== '[object Object]') continue;
-
-        //  Get hash
+        if (Object.prototype.toString.call(el) !== '[object Object]')
+            continue;
         hash = fn(el);
-        if (!Number.isFinite(hash) && !(typeof hash === 'string' && hash.trim().length > 0)) continue;
-
+        if (!Number.isFinite(hash) && !(typeof hash === 'string' && hash.trim().length > 0))
+            continue;
+        hash = `${hash}`;
         if (OPTS.merge === true && map.hasOwnProperty(hash)) {
             map[hash] = Object.assign(map[hash], el);
-        } else {
+        }
+        else {
             map[hash] = el;
         }
     }
-
     return map;
 }
+exports.default = mapFn;

package/dist/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/dist/array/mapKey.js

@@ -0,0 +1,27 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+function mapKey(arr, key, opts = {}) {
+    if ((!Array.isArray(arr) || arr.length === 0) ||
+        typeof key !== 'string')
+        return {};
+    const key_s = key.trim();
+    if (key_s.length === 0)
+        return {};
+    const OPTS = Object.assign({
+        merge: false,
+    }, Object.prototype.toString.call(opts) === '[object Object]' ? opts : {});
+    const map = {};
+    for (const el of arr) {
+        if (Object.prototype.toString.call(el) !== '[object Object]' ||
+            !Object.prototype.hasOwnProperty.call(el, key_s))
+            continue;
+        if (OPTS.merge === true && map.hasOwnProperty(el[key_s])) {
+            map[el[key_s]] = Object.assign(map[el[key_s]], el);
+        }
+        else {
+            map[el[key_s]] = el;
+        }
+    }
+    return map;
+}
+exports.default = mapKey;

package/dist/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/dist/array/mapPrimitive.js

@@ -0,0 +1,27 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const round_1 = require("../number/round");
+function mapPrimitive(arr, opts = {}) {
+    if (!Array.isArray(arr) || arr.length === 0)
+        return {};
+    const OPTS = Object.assign({
+        valtrim: false,
+        valround: false,
+        keyround: false,
+    }, Object.prototype.toString.call(opts) === '[object Object]' ? opts : {});
+    const map = {};
+    for (const el of arr) {
+        if (typeof el === 'string' && el.trim().length > 0) {
+            map[el.trim()] = OPTS.valtrim ? el.trim() : el;
+        }
+        else if (Number.isFinite(el)) {
+            map[OPTS.keyround === true ? Math.round(el) : el] = OPTS.valround === false
+                ? el
+                : OPTS.valround === true
+                    ? Math.round(el)
+                    : (0, round_1.default)(el, OPTS.valround);
+        }
+    }
+    return map;
+}
+exports.default = mapPrimitive;

package/dist/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/dist/array/shuffle.js

@@ -0,0 +1,11 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+function shuffle(arr) {
+    if (!Array.isArray(arr) || arr.length === 0)
+        return;
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+}
+exports.default = shuffle;

package/dist/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/dist/array/sort.js

@@ -0,0 +1,92 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const is_1 = require("../boolean/is");
+const isNotEmpty_1 = require("../object/isNotEmpty");
+function partition(arr, start_ix, end_ix) {
+    const pivot_val = arr[Math.floor((start_ix + end_ix) / 2)].t;
+    while (start_ix <= end_ix) {
+        while (arr[start_ix].t < pivot_val) {
+            start_ix++;
+        }
+        while (arr[end_ix].t > pivot_val) {
+            end_ix--;
+        }
+        if (start_ix <= end_ix) {
+            const temp = arr[start_ix];
+            arr[start_ix] = arr[end_ix];
+            arr[end_ix] = temp;
+            start_ix++;
+            end_ix--;
+        }
+    }
+    return start_ix;
+}
+function quickSort(arr, start_ix = 0, end_ix = arr.length - 1) {
+    if (start_ix < end_ix) {
+        const ix = partition(arr, start_ix, end_ix);
+        quickSort(arr, start_ix, ix - 1);
+        quickSort(arr, ix, end_ix);
+    }
+    return arr;
+}
+function sort(arr, by, dir = 'asc', opts = {}) {
+    if (!Array.isArray(arr) || arr.length === 0)
+        return [];
+    if (dir !== 'asc' && dir !== 'desc')
+        throw new Error('Direction should be either asc or desc');
+    const has_opts = Object.prototype.toString.call(opts) === '[object Object]';
+    const OPTS = {
+        filter_fn: has_opts && typeof opts.filter_fn === 'function'
+            ? el => (0, isNotEmpty_1.default)(el) && opts.filter_fn(el)
+            : isNotEmpty_1.default,
+        nokey_hide: has_opts && (0, is_1.default)(opts.nokey_hide) ? opts.nokey_hide : false,
+        nokey_atend: has_opts && (0, is_1.default)(opts.nokey_atend) ? opts.nokey_atend : true,
+    };
+    const prepared_arr = [];
+    const nokey_arr = [];
+    if (typeof by === 'string') {
+        const by_s = by.trim();
+        if (by_s.length === 0)
+            throw new Error('Sort by as string should contain content');
+        for (const el of arr) {
+            if (!OPTS.filter_fn(el))
+                continue;
+            if (!Object.prototype.hasOwnProperty.call(el, by_s) || el[by_s] === undefined) {
+                nokey_arr.push(el);
+            }
+            else {
+                prepared_arr.push({ t: el[by_s], el });
+            }
+        }
+    }
+    else if (typeof by === 'function') {
+        let key;
+        for (const el of arr) {
+            if (!OPTS.filter_fn(el))
+                continue;
+            key = by(el);
+            if (key === undefined) {
+                nokey_arr.push(el);
+            }
+            else {
+                prepared_arr.push({ t: by(el), el });
+            }
+        }
+    }
+    else {
+        throw new Error('Sort by should either be a string with content or a function');
+    }
+    quickSort(prepared_arr);
+    if (dir === 'desc')
+        prepared_arr.reverse();
+    if (OPTS.nokey_hide) {
+        return prepared_arr.map(obj => obj.el);
+    }
+    else if (OPTS.nokey_atend) {
+        return [...prepared_arr.map(obj => obj.el), ...nokey_arr];
+    }
+    else {
+        return [...nokey_arr, ...prepared_arr.map(obj => obj.el)];
+    }
+}
+exports.default = sort;

package/dist/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/dist/boolean/is.js

@@ -0,0 +1,6 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+function isBoolean(val) {
+    return val === true || val === false;
+}
+exports.default = isBoolean;

package/dist/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/dist/caching/memoize.js

@@ -0,0 +1,15 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+function memoize(fn, resolver) {
+    const memoized = function () {
+        const key = typeof resolver === 'function' ? resolver.apply(this, arguments) : arguments[0];
+        if (memoized.cache.has(key))
+            return memoized.cache.get(key);
+        const result = fn.apply(this, arguments);
+        memoized.cache.set(key, result);
+        return result;
+    };
+    memoized.cache = new Map();
+    return memoized;
+}
+exports.default = memoize;

package/dist/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/{src/date/addUTC.mjs → dist/date/addUTC.js}

@@ -1,30 +1,14 @@
 'use strict';
-
-import isDate from './is.mjs';
-
-export default function addUTC (val, amount, key) {
-    if (
-        !isDate(val)
-    ) throw new TypeError('addUTC requires a date object');
-
-    if (
-        !Number.isInteger(amount)
-    ) throw new TypeError('Amount needs to be an integer');
-
-    if (
-        typeof key !== 'string'
-    ) throw new TypeError('Key needs to be a string with content');
-
-    const copy = new Date(Date.UTC(
-        val.getUTCFullYear(),
-        val.getUTCMonth(),
-        val.getUTCDate(),
-        val.getUTCHours(),
-        val.getUTCMinutes(),
-        val.getUTCSeconds(),
-        val.getUTCMilliseconds()
-    ));
-
+Object.defineProperty(exports, "__esModule", { value: true });
+const is_1 = require("./is");
+function addUTC(val, amount = 0, key = 'millisecond') {
+    if (!(0, is_1.default)(val))
+        throw new TypeError('addUTC requires a date object');
+    if (!Number.isInteger(amount))
+        throw new TypeError('Amount needs to be an integer');
+    if (typeof key !== 'string')
+        throw new TypeError('Key needs to be a string with content');
+    const copy = new Date(Date.UTC(val.getUTCFullYear(), val.getUTCMonth(), val.getUTCDate(), val.getUTCHours(), val.getUTCMinutes(), val.getUTCSeconds(), val.getUTCMilliseconds()));
     switch (key) {
         case 'years':
         case 'year': {
@@ -65,3 +49,4 @@ export default function addUTC (val, amount, key) {
             return copy;
     }
 }
+exports.default = addUTC;

package/dist/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;