@ezez/utils 1.0.0

package/src/setImmutable.spec.ts

@@ -0,0 +1,241 @@
+import { setImmutable } from "./setImmutable.js";
+
+describe("setImmutable", () => {
+    it("updates existing value", () => {
+        const obj = {
+            title: "Hello",
+        };
+        const result = setImmutable(obj, "title", "World");
+        obj.must.not.equal(result);
+        obj.title.must.equal("Hello");
+        result.title.must.equal("World");
+    });
+
+    it("adds new value", () => {
+        const obj = {
+            title: "Hello",
+        };
+        const result = setImmutable(obj, "name", "World");
+        obj.must.not.equal(result);
+        obj.must.eql({
+            title: "Hello",
+        });
+        result.must.eql({
+            title: "Hello",
+            name: "World",
+        });
+    });
+
+    it("matches the value when path is type number", () => {
+        setImmutable({ a: 1 }, 1, "World").must.eql({
+            a: 1,
+            1: "World",
+        });
+        setImmutable([1], 1, "World").must.eql([
+            1, "World",
+        ]);
+    });
+
+    it("disallows other types than string, number or array of strings and numbers", () => {
+        (() => setImmutable({}, null, "test")).must.throw();
+        (() => setImmutable({}, undefined, "test")).must.throw();
+        (() => setImmutable({}, () => {}, "test")).must.throw();
+        (() => setImmutable({}, {}, "test")).must.throw();
+        (() => setImmutable({}, Symbol("abc"), "test")).must.throw();
+
+        (() => setImmutable({}, [1, "s"], "test")).must.not.throw();
+
+        (() => setImmutable({}, [1, "s", []], "test")).must.throw();
+        (() => setImmutable({}, [() => {}], "test")).must.throw();
+    });
+
+    it("disallows empty path paths", () => {
+        (() => setImmutable({}, "", "test")).must.throw();
+        (() => setImmutable({}, ["a", "", "b"], "test")).must.throw();
+        (() => setImmutable({}, ["a", "b", ""], "test")).must.throw();
+        (() => setImmutable({}, [], "test")).must.throw();
+        (() => setImmutable({}, "a.b..c", "test")).must.throw();
+    });
+
+    it("deeply sets value", () => {
+        const object = {
+            data: {
+                title: "666",
+            },
+            other: {
+                a: 5,
+            },
+        };
+        const newObject = setImmutable(object, "data.name", "santa");
+
+        object.must.not.equal(newObject);
+        object.data.must.not.equal(newObject.data);
+
+        object.other.must.equal(newObject.other);
+
+        newObject.must.eql({
+            data: {
+                title: "666",
+                name: "santa",
+            },
+            other: {
+                a: 5,
+            },
+        });
+        object.must.eql({
+            data: {
+                title: "666",
+            },
+            other: {
+                a: 5,
+            },
+        });
+    });
+
+    it("keeps arrays in place", () => {
+        const object = {
+            items: [0, 1],
+        };
+        const newObject = setImmutable(object, "items.2", 2);
+
+        newObject.must.eql({
+            items: [0, 1, 2],
+        });
+    });
+
+    it("replaces functions with objects", () => {
+        const fn = () => {};
+        fn.publicValue = 5;
+
+        const object = {
+            fn,
+        };
+
+        const result = setImmutable(object, "fn.value", 666);
+
+        result.fn.must.be.an.object();
+        result.fn.must.not.be.a.function();
+        result.fn.must.not.equal(fn);
+        result.must.eql({
+            fn: {
+                publicValue: 5,
+                value: 666,
+            },
+        });
+    });
+
+    it("adds objects if not existing on the way", () => {
+        const object = {
+            data: {},
+        };
+
+        const result = setImmutable(object, "data.gallery.items", [1, 2, 3]);
+
+        object.must.not.equal(result);
+        object.data.must.not.equal(result.data);
+        object.must.eql({
+            data: {},
+        });
+        result.must.eql({
+            data: {
+                gallery: {
+                    items: [1, 2, 3],
+                },
+            },
+        });
+    });
+
+    it("replaces primitives on the way", () => {
+        {
+            const object = {
+                data: "string",
+            };
+
+            const result = setImmutable(object, "data.gallery.items", [1, 2, 3]);
+
+            result.must.eql({
+                data: {
+                    gallery: {
+                        items: [1, 2, 3],
+                    },
+                },
+            });
+        }
+
+        {
+            const object = {
+                data: 45678,
+            };
+
+            const result = setImmutable(object, "data.gallery.items", [1, 2, 3]);
+
+            result.must.eql({
+                data: {
+                    gallery: {
+                        items: [1, 2, 3],
+                    },
+                },
+            });
+        }
+    });
+
+    it("works with primitives as source", () => {
+        setImmutable(undefined, "hi", "mom").must.eql({
+            hi: "mom",
+        });
+
+        setImmutable(null, "hi", "mom").must.eql({
+            hi: "mom",
+        });
+
+        setImmutable(69, "hi", "mom").must.eql({
+            hi: "mom",
+        });
+    });
+
+    it("creates an object when using numeric key and source object has missing data there", () => {
+        const result = setImmutable(null, ["data", 5], 100);
+        result.data.must.not.be.an.array();
+        result.must.eql({
+            data: {
+                5: 100,
+            },
+        });
+    });
+
+    it("doesn't parse path string as js code", () => {
+        const result = setImmutable(null, "data[title]", "Horror movie");
+        result.must.not.have.property("data");
+        result.must.have.property("data[title]");
+        result.must.eql({
+            "data[title]": "Horror movie",
+        });
+    });
+
+    it("allows dot separated path", () => {
+        setImmutable(null, "data.title", "Horror movie").must.eql({
+            data: {
+                title: "Horror movie",
+            },
+        });
+    });
+
+    it("allows array as path", () => {
+        setImmutable(null, ["data", "title"], "Horror movie").must.eql({
+            data: {
+                title: "Horror movie",
+            },
+        });
+    });
+
+    it("doesn't parse mixed array/dot-strings paths", () => {
+        const result = setImmutable(null, ["data", "title.name"], "Horror movie");
+        result.data.must.not.have.property("title");
+        result.data.must.have.property("title.name");
+        result.must.eql({
+            data: {
+                "title.name": "Horror movie",
+            },
+        });
+    });
+});

package/src/setImmutable.ts

@@ -0,0 +1,104 @@
+/**
+ * Source object.
+ *
+ * @see {@link setImmutable}.
+ */
+interface Source { [key: string]: unknown }
+
+const isObject = (value: unknown) => (typeof value === "object" || typeof value === "function") && value !== null;
+
+const clone = (value: unknown[] | Source) => {
+    if (Array.isArray(value)) {
+        return [...value as never as unknown[]]; // typecasts to satisfy eslint
+    }
+    return { ...value };
+};
+
+const hasOnlyValidPathParts = (array: unknown[]) => {
+    if (!array.length) {
+        return false;
+    }
+    return array.every(item => {
+        const type = typeof item;
+        return (type === "string" && item !== "") || type === "number";
+    });
+};
+
+/**
+ * Argument of {@link setImmutable}.
+ *
+ * Path to store value in. Can be a dot-separated string or an array of strings.
+ * Numbers are allowed for convenience.
+ */
+type Path = number | string | (number | string)[];
+
+const getPathParts = (path: Path) => {
+    if (typeof path === "number") {
+        return [String(path)];
+    }
+    if (typeof path === "string") {
+        return path.split(".");
+    }
+    if (Array.isArray(path)) {
+        return path;
+    }
+    throw new TypeError("Path must be a string, a number or an array of strings and numbers");
+};
+
+/**
+ * Updates the value at given path of given object. It does not mutate the object but returns a new one. If path is not
+ * found then objects are created "on the way". If non-objects are found, they are replaced with new plain objects. If
+ * primitives are used as source they are ignored and returned value is empty object with updated value at given path.
+ *
+ * This is still too dynamic in nature to get full TypeScript support. Properties are not typed, return type is unknown.
+ * It is recommended to use `immutable-assign` package instead.
+ *
+ * @param {Object} source - source object to mutate
+ * @param {Path} path - path where value should be stored, written as dot-separated
+ * property names or array with property names. Use Array when your keys includes dots.
+ * @param {*} value - value to be set
+ * @example set(object, "deep.property", value)
+ * @example set(object, ["deep", "property"], value)
+ * @example set({}, "deep[0].property", value)
+ * // will create this structure:
+ * { "deep[0]": { "property": value }}
+ * @example set({}, "items.0", value)
+ * // will create an object, not an array
+ * { "items": { "0": value }}
+ * @returns {Object} - given object or new object if source was primitive
+ */
+const setImmutable = (source: Source, path: Path, value: unknown): Source | unknown => { // eslint-disable-line max-statements, max-len, @typescript-eslint/no-redundant-type-constituents
+    const pathParts = getPathParts(path);
+    const isValidPath = hasOnlyValidPathParts(pathParts);
+    if (!isValidPath) {
+        throw new TypeError("Path must not be empty or contain empty parts");
+    }
+    const len = pathParts.length;
+
+    const result = isObject(source) ? clone(source) : {};
+    // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
+    let current: Source | unknown = result;
+    for (let i = 0; i < len; i++) {
+        const isLast = i === len - 1;
+        const key = pathParts[i];
+        if (isLast) {
+            (current as Source)[key] = value;
+            return result;
+        }
+        if (!isObject((current as Source)[key])) { // @todo probably can be removed
+            (current as Source)[key] = {};
+        }
+        else {
+            (current as Source)[key] = clone((current as Source)[key] as Source | unknown[]);
+        }
+        current = (current as Source)[key];
+    }
+    return result;
+};
+
+export { setImmutable };
+
+export type {
+    Path as SetImmutablePath,
+    Source as SetImmutableSource,
+};

package/src/sortBy.spec.ts

@@ -0,0 +1,56 @@
+import { sortBy } from "./sortBy.js";
+
+describe("sortBy", () => {
+    const items = [
+        {
+            name: "Astra",
+        },
+        {
+            name: "Zorro",
+        },
+        {
+            name: "Ewelina",
+        },
+    ];
+
+    it("must sort asc", () => {
+        items.sort(sortBy("name")).must.eql([
+            {
+                name: "Astra",
+            },
+            {
+                name: "Ewelina",
+            },
+            {
+                name: "Zorro",
+            },
+        ]);
+    });
+
+    it("must sort desc", () => {
+        items.sort(sortBy("name", false)).must.eql([
+            {
+                name: "Zorro",
+            },
+            {
+                name: "Ewelina",
+            },
+            {
+                name: "Astra",
+            },
+        ]);
+    });
+
+    it("must sort given property", () => {
+        const sizes = [
+            { size: 30 },
+            { size: 90 },
+            { size: 50 },
+        ];
+        sizes.sort(sortBy("size")).must.eql([
+            { size: 30 },
+            { size: 50 },
+            { size: 90 },
+        ]);
+    });
+});

package/src/sortBy.ts

@@ -0,0 +1,24 @@
+/**
+ * Returns a function that can be used as a callback to `.sort()` method. Returned function will sort array by given
+ * property.
+ * @param {string} propertyName - name of the property to sort by
+ * @param {boolean} [asc=true] - should sort be ascending?
+ * @param {*} defaultValue - value to use when property is not defined in one of the objects
+ */
+const sortBy = <T>(propertyName: keyof T, asc = true, defaultValue: unknown = null) => (a: T, b: T) => {
+    if (a[propertyName] === b[propertyName]) {
+        return 0;
+    }
+    // @ts-expect-error We don't care about types here, it's for runtime pure JS too
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if ((a[propertyName] ?? defaultValue) > (b[propertyName] ?? defaultValue)) {
+        // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+        return asc ? 1 : -1;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+    return asc ? -1 : 1;
+};
+
+export {
+    sortBy,
+};

package/src/throttle.spec.ts

@@ -0,0 +1,136 @@
+import { throttle } from "./throttle.js";
+import { wait } from "./wait.js";
+
+// @TODO much more tests required
+// @TODO for some reason these tests are useless, at 2cfbbc81 they should fail, but they weren't
+
+describe("throttle", function() {
+    it("should work with single value timeout", async function() {
+        const runTimes: number[] = [];
+        const fn = () => {
+            runTimes.push(Date.now());
+        };
+
+        const throttled = throttle(fn, 100);
+        const start = Date.now();
+        while (Date.now() - start < 2000) { // for 2 seconds
+            throttled();
+            await wait(1);
+        }
+
+        runTimes.length.must.be.gte(10); // just to be sure something run
+        runTimes.length.must.be.lt(21);
+
+        runTimes.forEach((time, key) => {
+            if (!key) {
+                return;
+            }
+            const lastTime = runTimes[key - 1];
+            const diff = time - lastTime;
+            diff.must.be.gte(100);
+        });
+    });
+
+    it("should works with multi value timeout", async function() {
+        const runTimes: number[] = [];
+        const fn = () => {
+            runTimes.push(Date.now());
+        };
+
+        const throttled = throttle(fn, [100, 200, 300]);
+        const start = Date.now();
+        while (Date.now() - start < 2000) { // for 2 seconds
+            throttled();
+            await wait(1);
+        }
+
+        const diff1 = runTimes[1] - runTimes[0];
+        diff1.must.be.gte(100);
+        diff1.must.be.lte(150); // cpu hogs can bump this value, fingers crossed it won't be higher to crash the tests
+
+        const diff2 = runTimes[2] - runTimes[1];
+        diff2.must.be.gte(200);
+        diff2.must.be.lte(250);
+
+        const diff3 = runTimes[3] - runTimes[2];
+        diff3.must.be.gte(300);
+        diff3.must.be.lte(350);
+
+        const diff4 = runTimes[4] - runTimes[3];
+        diff4.must.be.gte(300);
+        diff4.must.be.lte(350);
+    });
+
+    it("allows to reset multi value timeout", async function() {
+        const runTimes: number[] = [];
+        const fn = () => {
+            runTimes.push(Date.now());
+        };
+
+        const throttled = throttle(fn, [100, 200, 300]);
+        let start = Date.now();
+        while (Date.now() - start < 2000) { // for 2 seconds
+            throttled();
+            await wait(1);
+        }
+
+        throttled.cancel();
+        runTimes.length = 0;
+
+        start = Date.now();
+        while (Date.now() - start < 2000) { // for 2 seconds
+            throttled();
+            await wait(1);
+        }
+
+        const diff1 = runTimes[1] - runTimes[0];
+        diff1.must.be.gte(100);
+        diff1.must.be.lte(150); // cpu hogs can bump this value, fingers crossed it won't be higher to crash the tests
+
+        const diff2 = runTimes[2] - runTimes[1];
+        diff2.must.be.gte(200);
+        diff2.must.be.lte(250);
+
+        const diff3 = runTimes[3] - runTimes[2];
+        diff3.must.be.gte(300);
+        diff3.must.be.lte(350);
+
+        const diff4 = runTimes[4] - runTimes[3];
+        diff4.must.be.gte(300);
+        diff4.must.be.lte(350);
+    });
+
+    it("works with multiple values with trailing calls", async function() {
+        const runTimes: number[] = [];
+        const fn = () => {
+            runTimes.push(Date.now());
+        };
+
+        const throttled = throttle(fn, [100, 200, 300]);
+        throttled();
+        throttled();
+        await wait(201);
+        throttled();
+        await wait(201);
+        throttled();
+        await wait(201);
+        throttled();
+        await wait(201);
+        throttled();
+
+        const diffs = runTimes.map((time, key) => {
+            if (!key) {
+                return null;
+            }
+            return time - runTimes[key - 1];
+        }).filter(v => v !== null);
+        diffs[0].must.be.gte(100);
+        diffs[0].must.be.lt(150);
+
+        diffs[1].must.be.gte(200);
+        diffs[1].must.be.lt(250);
+
+        diffs[2].must.be.gte(300);
+        diffs[2].must.be.lt(350);
+    });
+});