@ezez/utils 1.0.0

package/src/last.spec.ts

@@ -0,0 +1,88 @@
+import { last as _last } from "lodash";
+
+import { last } from "./last.js";
+
+const array = [1, 2];
+const holeyArray = [,]; // eslint-disable-line no-sparse-arrays
+const holeyArray2 = Array(2);
+holeyArray2[0] = 1;
+const holeyArray3 = Array(2);
+holeyArray3[1] = 1;
+
+const arrayLike = { 0: 0, 1: 1, length: 2 };
+const string = "elo";
+const object = {};
+
+const emptyMap = new Map();
+const filledMap = new Map();
+filledMap.set("x", "x");
+
+const emptySet = new Set();
+const filledSet = new Set();
+filledSet.add("x");
+
+describe("last", () => {
+    it("returns last element of typical array, behaves like lodash", () => {
+        last(array).must.equal(2);
+        _last(array).must.equal(2);
+    });
+
+    it("returns last element of holey array, behaves like lodash", () => {
+        // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+        (last(holeyArray) === undefined).must.be.true();
+        // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+        (_last(holeyArray) === undefined).must.be.true();
+
+        (last(holeyArray2) === undefined).must.be.true();
+        (_last(holeyArray2) === undefined).must.be.true();
+
+        last(holeyArray3).must.equal(1);
+        _last(holeyArray3).must.equal(1);
+    });
+
+    it("returns last element of array-like object, behaves like lodash", () => {
+        last(arrayLike).must.equal(1);
+        _last(arrayLike).must.equal(1);
+    });
+
+    it("returns undefined for standard object, behaves like lodash", () => {
+        (last(object) === undefined).must.be.true();
+        (_last(object) === undefined).must.be.true();
+    });
+
+    it("returns last char of a string, behaves like lodash", () => {
+        last(string).must.equal("o");
+        _last(string).must.equal("o");
+    });
+
+    it("crashes on nil values, behaves NOT like lodash", () => {
+        (() => last(null)).must.throw();
+        (_last(null) === undefined).must.be.true();
+
+        (() => last()).must.throw();
+        (_last() === undefined).must.be.true();
+    });
+
+    it("returns undefined for other values, behaves like lodash", () => {
+        (last(NaN) === undefined).must.be.true();
+        (_last(NaN) === undefined).must.be.true();
+        (last(1) === undefined).must.be.true();
+        (_last(1) === undefined).must.be.true();
+        (last(0) === undefined).must.be.true();
+        (_last(0) === undefined).must.be.true();
+        (last(true) === undefined).must.be.true();
+        (_last(true) === undefined).must.be.true();
+        (last(false) === undefined).must.be.true();
+        (_last(false) === undefined).must.be.true();
+        (last(Infinity) === undefined).must.be.true();
+        (_last(Infinity) === undefined).must.be.true();
+        (last(emptyMap) === undefined).must.be.true();
+        (_last(emptyMap) === undefined).must.be.true();
+        (last(filledMap) === undefined).must.be.true();
+        (_last(filledMap) === undefined).must.be.true();
+        (last(emptySet) === undefined).must.be.true();
+        (_last(emptySet) === undefined).must.be.true();
+        (last(filledSet) === undefined).must.be.true();
+        (_last(filledSet) === undefined).must.be.true();
+    });
+});

package/src/last.ts

@@ -0,0 +1,12 @@
+/**
+ * Gets last element of an array.
+ *
+ * @param {Array} array - source array
+ * @example last([1, 2]) // 2
+ * @example last([1]) // 1
+ * @example last([]) // undefined
+ * @returns {*} - last element of an array or undefined
+ */
+const last = <T>(array: T[]): T | undefined => array[array.length - 1];
+
+export { last };

package/src/mapAsync.spec.ts

@@ -0,0 +1,39 @@
+import { mapAsync } from "./mapAsync.js";
+import { waitSync } from "./waitSync.js";
+
+const slowCb = (val: number) => {
+    waitSync(5);
+    return val + 1;
+};
+
+describe("mapAsync", () => {
+    it("must return the same output as map", async () => {
+        (await mapAsync([1, 2, 3], i => i + 1)).must.eql([2, 3, 4]);
+        (await mapAsync([1, 2, 3], slowCb, 1, 1)).must.eql([2, 3, 4]);
+    });
+
+    it("must let other tasks to work", async () => {
+        let i = 0,
+            id;
+        const bump = () => {
+            i++;
+            id = setTimeout(bump, 2);
+            // let's make sure we're gonna consume every loop release (timeout lower than wait time) but just once
+            // (timeout higher than wait time) - it's just to estimate values while testing
+        };
+        bump();
+
+        await mapAsync([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], slowCb, 10);
+
+        i.must.be.gte(5);
+
+        // now let's test standard, sync `map`
+        i = 0;
+        [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].map(slowCb);
+        i.must.be.equal(0);
+
+        clearTimeout(id);
+    });
+
+    // @TODO more tests, test callback params
+});

package/src/mapAsync.ts

@@ -0,0 +1,41 @@
+import { wait } from "./wait.js";
+
+const DEFAULT_MAX_BLOCK_TIME = 16; // a frame
+const DEFAULT_WAIT_TIME = 1;
+
+/**
+ * Non-blocking version of `Array.prototype.map`, it will pause the map loop every `pauseEvery`. Keep in mind that
+ * depending on your code workload the pause interval and duration may be exact or longer than specified. It's the same
+ * single thread JavaScript nature setTimeout have to follow.
+ * @param {Array} context - original array
+ * @param {function} callback - map function
+ * @param {number} pauseEvery - pause after this many ms
+ * @param {number} pauseTime - how long to wait on pause
+ */
+const mapAsync = async <T, Y>(
+    context: readonly T[],
+    callback: (item: T, key: number, array: readonly T[]) => Y,
+    pauseEvery = DEFAULT_MAX_BLOCK_TIME,
+    pauseTime = DEFAULT_WAIT_TIME,
+): Promise<Y[]> => {
+    let lastWaitMoment = Date.now();
+    const result = [];
+
+    const l = context.length;
+
+    for (let i = 0; i < l; i++) {
+        const item = context[i];
+        // eslint-disable-next-line callback-return
+        result.push(callback(item, i, context));
+        if (Date.now() - lastWaitMoment >= pauseEvery) {
+            await wait(pauseTime);
+            lastWaitMoment = Date.now();
+        }
+    }
+
+    return result;
+};
+
+export {
+    mapAsync,
+};

package/src/mapValues.spec.ts

@@ -0,0 +1,178 @@
+import { mapValues as _mapValues } from "lodash";
+
+import { mapValues, mapValuesUNSET } from "./mapValues.js";
+
+const REMOVE = mapValuesUNSET;
+
+describe("mapValues", () => {
+    const square = v => v * v;
+
+    const obj = {
+        a: 5,
+        b: 6,
+    };
+    const result = {
+        a: 25,
+        b: 36,
+    };
+
+    it("returns new object, behaves like lodash", () => {
+        mapValues(obj, square).must.not.equal(obj);
+        _mapValues(obj, square).must.not.equal(obj);
+    });
+
+    it("maps values, behaves like lodash", () => {
+        mapValues(obj, square).must.eql(result);
+        _mapValues(obj, square).must.eql(result);
+    });
+
+    it("skips inherited properties, behaves like lodash", () => {
+        const Test = function() {};
+        Test.prototype.nonOwn = 1;
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const testInstance = new Test();
+        testInstance.own = 2;
+        const testInstanceResult = {
+            own: 4,
+        };
+
+        mapValues(testInstance, square).must.eql(testInstanceResult);
+        _mapValues(testInstance, square).must.eql(testInstanceResult);
+    });
+
+    it("skips non-enumerable properties, behaves like lodash", () => {
+        const nonEnum = {
+            enum: 1,
+        };
+        Object.defineProperty(nonEnum, "nonEnum", {
+            enumerable: false,
+            value: 5,
+        });
+        const nonEnumResult = {
+            enum: 1,
+        };
+
+        mapValues(nonEnum, square).must.eql(nonEnumResult);
+        _mapValues(nonEnum, square).must.eql(nonEnumResult);
+    });
+
+    it("keeps array an array, behaves NOT like lodash", () => {
+        const array = [1, 5];
+        array.property = 3;
+        const arrayResult = [1, 25];
+        arrayResult.property = 9;
+        const arrayResultLodash = {
+            0: 1,
+            1: 25,
+            property: 9,
+        };
+
+        mapValues(array, square).must.eql(arrayResult);
+        _mapValues(array, square).must.eql(arrayResultLodash);
+    });
+
+    it("works on holey array, behaves NOT like lodash", () => {
+        const holeyArray = [1,, 3]; // eslint-disable-line no-sparse-arrays
+        const holeyArrayResult = [1,, 9]; // eslint-disable-line no-sparse-arrays
+        const holeyArrayResultLodash = {
+            0: 1,
+            1: NaN,
+            2: 9,
+        };
+
+        mapValues(holeyArray, square).must.eql(holeyArrayResult);
+        _mapValues(holeyArray, square).must.eql(holeyArrayResultLodash);
+    });
+
+    it("allows filtering while mapping values", () => {
+        const source = {
+            title: "abc",
+            price: 16.10,
+            author: "dzek",
+            items: [],
+            data: {},
+            category: null,
+            description: "abcd",
+        };
+
+        mapValues(source, (value, key) => {
+            const keyStartsWithCP = ["c", "p"].includes(key.substring(0, 1));
+            const isString = typeof value === "string";
+            if (!isString && !keyStartsWithCP) {
+                return REMOVE;
+            }
+            if (typeof value === "number") {
+                return value + 1;
+            }
+            if (key === "description") {
+                return (value as string).toUpperCase();
+            }
+            return value;
+        }).must.eql({
+            title: "abc",
+            price: 17.10,
+            author: "dzek",
+            category: null,
+            description: "ABCD",
+        });
+    });
+
+    it("crashes on nil values, behaves NOT like lodash", () => {
+        (() => mapValues(null, square)).must.throw();
+        (() => mapValues(undefined, square)).must.throw();
+
+        (() => _mapValues(null, square)).must.not.throw();
+        (() => _mapValues(undefined, square)).must.not.throw();
+    });
+
+    it("calls given method once per property", () => {
+        {
+            const source = {
+                aaa: false,
+            };
+
+            let calls;
+            calls = 0;
+
+            mapValues(source, (value) => {
+                calls++;
+                return value;
+            });
+
+            calls.must.equal(1);
+        }
+
+        {
+            const source = {
+                aaa: false,
+                title: "albert eats flowers",
+            };
+
+            let calls;
+            calls = 0;
+
+            mapValues(source, (value) => {
+                calls++;
+                return value;
+            });
+
+            calls.must.equal(2);
+        }
+    });
+
+    it("leaves gaps in an array if some elements are removed", () => {
+        const array = [1, "string", 1, "dog", 69];
+
+        const res = mapValues(array, (val) => (typeof val === "string" ? REMOVE : val));
+
+        // eslint-disable-next-line no-sparse-arrays
+        res.must.eql([
+            1, , 1, , 69,
+        ]);
+        ("0" in res).must.be.true();
+        ("1" in res).must.be.false();
+        ("2" in res).must.be.true();
+        ("3" in res).must.be.false();
+        ("4" in res).must.be.true();
+    });
+});

package/src/mapValues.ts

@@ -0,0 +1,57 @@
+/**
+ * @see {@link mapValues}
+ */
+const UNSET = typeof Symbol !== "undefined" ? Symbol("unset") : {};
+
+/**
+ * A callback function to {@link mapValues}. It should return new value, optionally may return exported mapValuesUnset
+ * value to unset a property in the target the object.
+ *
+ * @callback MapValuesFn
+ * @param {*} value - property value
+ * @param {string} key - property name
+ * @example function fn(value, key) { return value * 5; } // all properties will be multiplied
+ * @example function fn(value, key) {
+ *   if (key === "name") {
+ *     return mapValuesUNSET;
+ *   }
+ *   return value.toUpperCase();
+ * } // will upper case all properties and filter out name property
+ * @returns {*} - new value of a property
+ */
+type MapValuesFn<S, R> = (value: S[keyof S], key: keyof S) => R;
+
+/**
+ * Iterates through object properties returning object with same properties but modified values. Optionally some
+ * properties may be filtered out on returned object.
+ *
+ * @param {Object|Array} source - source object
+ * @param {MapValuesFn} fn - map function callback that will return new value of a property
+ * @example mapValues({ a: 1, b: 2 }, x => x * 2) // will return { a: 2, b: 4 }
+ * @example mapValues({ a: 1, b: 2 }, () => mapValuesUNSET) // will return {}
+ * @example mapValues({ a: 1, b: 2 }, (value, key) => key === "b" ? mapValuesUNSET : value * 5) // will return { a: 5 }
+ * @returns {Object|Array}
+ */
+const mapValues = <SourceObject extends Record<string, unknown>, PossibleReturnValues>(
+    source: SourceObject, fn: MapValuesFn<SourceObject, PossibleReturnValues>,
+): { [P in keyof SourceObject]: PossibleReturnValues } => {
+    const keys = Object.keys(source) as (keyof SourceObject)[];
+
+    // @ts-expect-error TypeScript doesn't work well with this type with reduce
+    // @TODO check with ts 5+ or something
+    const def: { [P in keyof SourceObject]: PossibleReturnValues } = Array.isArray(source) ? [] : {};
+
+    return keys.reduce((result, key) => {
+        const value = fn(source[key], key);
+        if (value !== UNSET) {
+            result[key] = value; // eslint-disable-line no-param-reassign
+        }
+        return result;
+    }, def);
+};
+
+export { mapValues, UNSET as mapValuesUNSET };
+
+export type {
+    MapValuesFn,
+};

package/src/match.spec.ts

@@ -0,0 +1,11 @@
+import { match } from "./match.js";
+
+describe("match", () => {
+    it("must match correctly", () => {
+        const items = [1, 500, 3, 15, 200, -100];
+
+        const { matched, unmatched } = match(items, (item) => item > 15);
+        matched.must.eql([500, 200]);
+        unmatched.must.eql([1, 3, 15, -100]);
+    });
+});

package/src/match.ts

@@ -0,0 +1,30 @@
+type MatchCallback<T> = (value: T) => boolean;
+
+/**
+ * A `Array.prototype.filter`-like function that splits the results into two groups - matched and unmatched
+ * @param {Array} list - original array
+ * @param {function} fn - function matching elements
+ */
+const match = <T>(list: T[], fn: MatchCallback<T>) => {
+    const matched: T[] = [];
+    const unmatched: T[] = [];
+    list.forEach(item => {
+        if (fn(item)) {
+            matched.push(item);
+            return;
+        }
+        unmatched.push(item);
+    });
+
+    return {
+        matched,
+        unmatched,
+    };
+};
+
+export {
+    match,
+};
+export type {
+    MatchCallback,
+};

package/src/merge.spec.ts

@@ -0,0 +1,69 @@
+import { merge, mergeUNSET } from "./merge.js";
+
+describe("merge", () => {
+    it("merges two objects", () => {
+        merge({ a: true }, { b: false }).must.eql({
+            a: true,
+            b: false,
+        });
+        merge({ a: true }, { a: false }).must.eql({
+            a: false,
+        });
+        merge({ c: true }, { a: undefined, c: undefined }).must.eql({
+            a: undefined,
+            c: undefined,
+        });
+    });
+
+    it("merges three objects", () => {
+        merge({ a: true }, { b: false }, { c: "maybe" }).must.eql({
+            a: true,
+            b: false,
+            c: "maybe",
+        });
+        merge({ a: true }, { a: false }, { a: true }).must.eql({
+            a: true,
+        });
+        merge({ c: true }, { a: undefined, c: undefined }, { c: null, a: false }).must.eql({
+            a: false,
+            c: null,
+        });
+    });
+
+    it("allows to unset value", () => {
+        const result = merge({ c: true }, { c: mergeUNSET });
+        result.must.not.have.property("c");
+        result.must.eql({});
+    });
+
+    it("allows to overwrite unset value", () => {
+        const result = merge({ c: true }, { c: mergeUNSET }, { c: true });
+        result.must.eql({ c: true });
+    });
+
+    it("rejects arrays", () => {
+        (() => merge({ c: true }, { c: mergeUNSET }, { c: true }, [])).must.throw(TypeError);
+    });
+
+    it("rejects primitive types", () => {
+        (() => merge({ c: true }, { c: mergeUNSET }, { c: true }, "string")).must.throw(TypeError);
+        (() => merge({ c: true }, { c: mergeUNSET }, { c: true }, 555)).must.throw(TypeError);
+        (() => merge({ c: true }, { c: mergeUNSET }, { c: true }, false)).must.throw(TypeError);
+        (() => merge({ c: true }, { c: mergeUNSET }, { c: true }, Symbol("hi"))).must.throw(TypeError);
+    });
+
+    it("rejects functions", () => {
+        (() => merge({ c: true }, { c: mergeUNSET }, { c: true }, () => "hi")).must.throw(TypeError);
+    });
+
+    it("ignores nil", () => {
+        (() => merge({ c: true }, { c: mergeUNSET }, { c: true }, undefined, null)).must.not.throw();
+        merge({ c: true }, { c: mergeUNSET }, { c: true }, undefined, null).must.eql({
+            c: true,
+        });
+    });
+
+    it("unsets value if mergeUNSET is present on first object", function() {
+        merge({ c: mergeUNSET }).must.eql({});
+    });
+});

package/src/merge.ts

@@ -0,0 +1,58 @@
+/**
+ * Special value that can be set as a value in an object.
+ * If this value is merged with previous value - the property in a final object will be removed;
+ * @see {@link merge}
+ */
+const UNSET = typeof Symbol !== "undefined" ? Symbol("UNSET") : {};
+
+interface Merge {
+    <A>(a: A): A;
+    <A, B>(a: A, b: B): A & B;
+    <A, B, C>(a: A, b: B, c: C): A & B & C;
+    <A, B, C, D>(a: A, b: B, c: C, d: D): A & B & C & D;
+    <A, B, C, D, E>(a: A, b: B, c: C, d: D, e: E): A & B & C & D & E;
+    <A, B, C, D, E, F>(a: A, b: B, c: C, d: D, e: E, f: F): A & B & C & D & E & F;
+    <A, B, C, D, E, F, G>(a: A, b: B, c: C, d: D, e: E, f: F, g: G): A & B & C & D & E & F & G;
+    <A, B, C, D, E, F, G, H>(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H): A & B & C & D & E & F & G & H;
+    <A, B extends object>(a: A, ...args: B[]): unknown;
+}
+
+/**
+ * Shallow merges given objects into new object. It does not mutate any object given. Allows removing properties as
+ * well by assigning special `mergeUNSET` value.
+ * @example merge({a: 1}, {b: 2}) // {a: 1, b: 2}
+ * @example merge({a: 1}, {a: 2}) // {a: 2}
+ * @example merge({a: 1}, {a: mergeUNSET}) // {}
+ * @param {...object} args - input objects
+ * @returns {*}
+ */
+const merge: Merge = <MergeCandidate extends object>(...args: MergeCandidate[]) => {
+    const nonObjects = args.some(p => {
+        const t = typeof p;
+        return t === "string" || t === "number" || t === "symbol" || t === "boolean" || t === "function"
+            || Array.isArray(p);
+    });
+
+    if (nonObjects) {
+        throw new TypeError("Only objects are allowed");
+    }
+
+    const r: { [key: string]: unknown } = {};
+    args.forEach((obj) => {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        Object.entries(obj || {}).forEach(([key, value]) => {
+            if (value === UNSET) {
+                // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+                delete r[key];
+                return;
+            }
+            r[key] = value;
+        });
+    });
+    return r;
+};
+
+export {
+    merge,
+    UNSET as mergeUNSET,
+};

package/src/mostFrequent.spec.ts

@@ -0,0 +1,35 @@
+import { mostFrequent } from "./mostFrequent.js";
+
+describe("mostFrequent", () => {
+    it("returns most frequent element", () => {
+        mostFrequent([1, 2, 3, 2, 5, 400]).must.equal(2);
+    });
+
+    it("returns first most frequent element if equal top count", () => {
+        mostFrequent([1, 2, 3, 2, 5, 400, 400]).must.equal(2);
+    });
+
+    it("returns first value if nothing wins", () => {
+        mostFrequent([5, 9, 1000]).must.equal(5);
+    });
+
+    it("returns undefined if array empty", () => {
+        must(mostFrequent([])).equal(undefined);
+    });
+
+    it("compares strictly", () => {
+        mostFrequent([1, "1", 1, "1", 2, 2, 2]).must.equal(2);
+    });
+
+    it("works with NaNs", () => {
+        // lol, must.js doesn't work with NaNs
+        Number.isNaN(mostFrequent([5, NaN, 300, NaN])).must.be.true();
+    });
+
+    it("compares by reference", function() {
+        const a = {};
+        const b = {};
+
+        mostFrequent([a, b, b]).must.equal(b);
+    });
+});

package/src/mostFrequent.ts

@@ -0,0 +1,27 @@
+/**
+ * Finds most frequent value in array
+ * @param {Array} array
+ */
+const mostFrequent = <T>(array: T[]): T => {
+    let top = 0,
+        topValue = array[0];
+
+    const map = new Map<T, number>();
+    array.forEach(value => {
+        if (!map.has(value)) {
+            map.set(value, 0);
+        }
+        const next = map.get(value)! + 1;
+        map.set(value, map.get(value)! + 1);
+        if (next > top) {
+            top = next;
+            topValue = value;
+        }
+    });
+
+    return topValue;
+};
+
+export {
+    mostFrequent,
+};

package/src/noop.ts

@@ -0,0 +1,8 @@
+/**
+ * No-operation function. It does nothing and returns nothing.
+ */
+const noop = () => undefined;
+
+export {
+    noop,
+};