@ezez/utils 1.0.0

package/src/seq.spec.ts

@@ -0,0 +1,157 @@
+import { seq, seqEarlyBreak } from "./seq.js";
+
+describe("seq", () => {
+    // @TODO more tests
+
+    it("calls methods one by one", async () => {
+        let firstCalled = false,
+            secondCalled = false;
+        const list = [
+            () => {
+                firstCalled = true;
+                return Promise.resolve(1);
+            },
+            () => {
+                secondCalled = true;
+                return Promise.resolve(2);
+            },
+        ];
+
+        const res = await seq(list);
+        res.must.equal(1);
+        firstCalled.must.equal(true);
+        secondCalled.must.equal(false);
+    });
+
+    it("returns first resolved value", async () => {
+        let firstCalled = false,
+            secondCalled = false;
+        const list = [
+            () => {
+                firstCalled = true;
+                return Promise.reject(new Error("Nope"));
+            },
+            () => {
+                secondCalled = true;
+                return Promise.resolve(2);
+            },
+        ];
+
+        const res = await seq(list);
+        res.must.equal(2);
+        firstCalled.must.equal(true);
+        secondCalled.must.equal(true);
+    });
+
+    it("works with non-async functions", async () => {
+        let firstCalled = false,
+            secondCalled = false;
+        const list = [
+            () => {
+                firstCalled = true;
+                throw new Error("Nope");
+            },
+            () => {
+                secondCalled = true;
+                return 2;
+            },
+        ];
+
+        const res = await seq(list);
+        res.must.equal(2);
+        firstCalled.must.equal(true);
+        secondCalled.must.equal(true);
+    });
+
+    it("rejects if everything rejects", async () => {
+        const list = [
+            () => {
+                throw new Error("Nope");
+            },
+            () => {
+                throw new Error("Also nope");
+            },
+        ];
+
+        let caught = false;
+        try {
+            await seq(list);
+        }
+        catch (e: unknown) {
+            caught = true;
+            e.must.be.instanceof(Error);
+            if (e instanceof Error) {
+                e.message.must.equal("Every function had thrown.");
+                const errors = e.details?.errors as Error[];
+                errors.must.be.an.array();
+                errors.must.have.length(2);
+                errors[0].must.be.instanceof(Error);
+                errors[0].message.must.equal("Nope");
+                errors[1].must.be.instanceof(Error);
+                errors[1].message.must.equal("Also nope");
+            }
+        }
+
+        caught.must.be.true();
+    });
+
+    it("rejects if no functions given", async () => {
+        let caught = false;
+        try {
+            await seq();
+        }
+        catch (e: unknown) {
+            caught = true;
+            e.must.be.instanceof(TypeError);
+            if (e instanceof TypeError) {
+                e.message.must.equal("At least one function must be provided.");
+            }
+        }
+
+        caught.must.be.true();
+    });
+
+    it("allows to break early on rejection", async () => {
+        let firstCalled = false,
+            secondCalled = false,
+            thirdCalled = false;
+
+        const list = [
+            () => {
+                firstCalled = true;
+                // eslint-disable-next-line prefer-promise-reject-errors
+                return Promise.reject(1);
+            },
+            () => {
+                secondCalled = true;
+                // eslint-disable-next-line prefer-promise-reject-errors
+                return Promise.reject(2);
+            },
+            () => {
+                thirdCalled = true;
+                // eslint-disable-next-line prefer-promise-reject-errors
+                return Promise.reject(3);
+            },
+        ];
+
+        let caught = false;
+        try {
+            await seqEarlyBreak((e: unknown) => {
+                if (e === 2) {
+                    return true;
+                }
+                return false;
+            }, list);
+        }
+        catch (e: unknown) {
+            caught = true;
+            e.must.be.equal(2);
+
+            firstCalled.must.be.true();
+            secondCalled.must.be.true();
+            thirdCalled.must.be.false();
+        }
+
+        caught.must.be.true();
+    });
+});

package/src/seq.ts

@@ -0,0 +1,104 @@
+const fail = function() {
+    return Promise.reject(new TypeError("At least one function must be provided."));
+};
+
+/**
+ * Function to be called.
+ *
+ * @see {@link seq}
+ */
+type Fn<T> = () => T;
+
+/**
+ * Functions to call sequentially.
+ * Either an array of functions or a list of functions.
+ *
+ * @see {@link seq}
+ */
+type Functions<T> = Fn<T>[] | [Fn<T>[]];
+
+/**
+ * A function that decides if the sequential run should be early stopped.
+ *
+ * @param {*} e - Value thrown by the function (usually Error).
+ * @see {@link seq}
+ */
+type EarlyBreaker = (e: unknown) => boolean;
+
+const run = <T>(list: Fn<T>[], earlyBreaker?: EarlyBreaker): Promise<T> => {
+    if (!list.length) {
+        return fail();
+    }
+
+    const promises = [...list];
+
+    return new Promise((resolve, reject) => {
+        let promise: Promise<T | undefined> = Promise.resolve(undefined);
+
+        const errors: Error[] = [];
+
+        const doTry = function(error?: Error) {
+            if (error !== undefined && earlyBreaker && earlyBreaker(error)) {
+                reject(error);
+                return;
+            }
+
+            if (error) {
+                errors.push(error);
+            }
+            const fn = promises.shift();
+            if (typeof fn !== "function") {
+                const finalError = new Error("Every function had thrown.");
+                // @ts-expect-error More details on error object are wanted
+                finalError.details = { errors };
+                reject(finalError);
+            }
+            promise = (promise.then(fn).then(resolve, doTry)) as unknown as Promise<T>;
+        };
+
+        doTry();
+    });
+};
+
+/**
+ * The same as {@link seq} but accepts a function that gets run after each error and using that erro decides if continue
+ * to try next functions.
+ *
+ * @example seqEarlyBreak(
+ *   (e) => e.message === "important error",
+ *   () => { throw new Error("important error") }, () => 2, () => 3
+ * ) // throws given important error, does not run next functions
+ * @param {EarlyBreaker} earlyBreaker - function that decides about early breaking the sequential run
+ * @param {...Functions<*>[]} args - functions to run, you can either pass them as many arguments or just single
+ * arguments with array
+ * @returns {*} - whatever gets returned from given functions
+ */
+const seqEarlyBreak = <T>(earlyBreaker: EarlyBreaker | undefined, ...args: Functions<T>) => {
+    if (args.length === 1) {
+        return run(Array.isArray(args[0]) ? args[0] : [args[0]], earlyBreaker);
+    }
+    return run(args as Fn<T>[], earlyBreaker);
+};
+
+/**
+ * Runs given functions sequentially one by one, until any returns value. Supports async functions. Throws with new
+ * Error when every function throws.
+ *
+ * @example seq(() => 1, () => 2, () => 3) // returns 1
+ * @example seq(() => { throw new Error("1") }, () => 2, () => 3) // returns 2
+ * @example seq(() => { throw new Error("1") }, () => { throw new Error("2") } }) // throws
+ * @param {...Functions<*>[]} fns - functions to run, you can either pass them as many arguments or just single
+ * arguments with array
+ * @returns {*} - whatever gets returned from given functions
+ */
+const seq = <T>(...fns: Functions<T>) => {
+    return seqEarlyBreak(undefined, ...fns);
+};
+
+export { seq, seqEarlyBreak };
+
+export type {
+    EarlyBreaker as SeqEarlyBreaker,
+    Functions as SeqFunctions,
+    Fn as SeqFn,
+};

package/src/set.spec.ts

@@ -0,0 +1,348 @@
+import { set as _set } from "lodash";
+
+import { set } from "./set.js";
+
+describe("set", () => {
+    it("replaces existing value, behaves like lodash", () => {
+        lodash: {
+            const obj = {
+                title: "Hello",
+            };
+            _set(obj, "title", "World");
+            obj.title.must.equal("World");
+        }
+
+        bottom: {
+            const obj = {
+                title: "Hello",
+            };
+            set(obj, "title", "World");
+            obj.title.must.equal("World");
+        }
+    });
+
+    it("adds new value, behaves like lodash", () => {
+        lodash: {
+            const obj = {
+                title: "Hello",
+            };
+            _set(obj, "name", "World");
+            obj.title.must.equal("Hello");
+            obj.name.must.equal("World");
+        }
+
+        bottom: {
+            const obj = {
+                title: "Hello",
+            };
+            set(obj, "name", "World");
+            obj.title.must.equal("Hello");
+            obj.name.must.equal("World");
+        }
+    });
+
+    it("allows deep set, behaves like lodash", () => {
+        lodash: {
+            const obj = {
+                data: {
+                    title: "Bye",
+                },
+            };
+
+            const dataBefore = obj.data;
+
+            _set(obj, "data.title", "Hi");
+
+            obj.data.title.must.equal("Hi");
+            obj.data.must.equal(dataBefore);
+        }
+
+        bottom: {
+            const obj = {
+                data: {
+                    title: "Bye",
+                },
+            };
+
+            const dataBefore = obj.data;
+
+            set(obj, "data.title", "Hi");
+
+            obj.data.title.must.equal("Hi");
+            obj.data.must.equal(dataBefore);
+        }
+    });
+
+    it("adds objects if not existing on the way, behaves like lodash", () => {
+        lodash1: {
+            const obj = {
+                data: null,
+            };
+            _set(obj, "data.title", "Hi");
+            obj.data.must.be.an.object();
+            obj.data.title.must.equal("Hi");
+        }
+
+        lodash2: {
+            const obj = {};
+            _set(obj, "data.title.short", "Hi");
+            obj.data.must.be.an.object();
+            obj.data.title.must.be.an.object();
+            obj.data.title.short.must.equal("Hi");
+        }
+
+        bottom1: {
+            const obj = {
+                data: null,
+            };
+            set(obj, "data.title", "Hi");
+            obj.data.must.be.an.object();
+            obj.data.title.must.equal("Hi");
+        }
+
+        bottom2: {
+            const obj = {};
+            set(obj, "data.title.short", "Hi");
+            obj.data.must.be.an.object();
+            obj.data.title.must.be.an.object();
+            obj.data.title.short.must.equal("Hi");
+        }
+    });
+
+    it("replaces primitives with objects on the way, behaves like lodash", () => {
+        lodash1: {
+            const obj = {
+                data: true,
+            };
+            _set(obj, "data.title.short", "Hi");
+            obj.data.must.be.an.object();
+            obj.data.title.must.be.an.object();
+            obj.data.title.short.must.equal("Hi");
+        }
+
+        lodash2: {
+            const obj = {
+                data: "empty",
+            };
+            _set(obj, "data.title.short", "Hi");
+            obj.data.must.be.an.object();
+            obj.data.title.must.be.an.object();
+            obj.data.title.short.must.equal("Hi");
+        }
+
+        bottom1: {
+            const obj = {
+                data: true,
+            };
+            set(obj, "data.title.short", "Hi");
+            obj.data.must.be.an.object();
+            obj.data.title.must.be.an.object();
+            obj.data.title.short.must.equal("Hi");
+        }
+
+        bottom2: {
+            const obj = {
+                data: "empty",
+            };
+            set(obj, "data.title.short", "Hi");
+            obj.data.must.be.an.object();
+            obj.data.title.must.be.an.object();
+            obj.data.title.short.must.equal("Hi");
+        }
+    });
+
+    it("doesn't crash on nulls as source, but returns new object, behaves NOT like lodash", () => {
+        lodash: {
+            const obj = null;
+            (() => {
+                _set(obj, "data.title.short", "Hi");
+            }).must.not.throw();
+
+            const newObj = _set(obj, "data.title.short", "Hi");
+            (newObj === null).must.be.true();
+        }
+
+        bottom: {
+            const obj = null;
+            (() => {
+                set(obj, "data.title.short", "Hi");
+            }).must.not.throw();
+
+            const newObj = set(obj, "data.title.short", "Hi");
+            newObj.must.be.an.object();
+            newObj.data.title.short.must.equal("Hi");
+        }
+    });
+
+    it("doesn't crash on primitives as source", () => {
+        lodash1: {
+            const obj = "hello";
+            (() => {
+                _set(obj, "data.title.short", "Hi");
+            }).must.not.throw();
+
+            const newObj = _set(obj, "data.title.short", "Hi");
+            newObj.must.equal("hello");
+        }
+
+        lodash2: {
+            const obj = 88;
+            (() => {
+                _set(obj, "data.title.short", "Hi");
+            }).must.not.throw();
+
+            const newObj = _set(obj, "data.title.short", "Hi");
+            newObj.must.equal(88);
+        }
+
+        bottom1: {
+            const obj = "hello";
+            (() => {
+                set(obj, "data.title.short", "Hi");
+            }).must.not.throw();
+
+            const newObj = set(obj, "data.title.short", "Hi");
+            newObj.must.be.an.object();
+            newObj.data.title.short.must.equal("Hi");
+        }
+
+        bottom2: {
+            const obj = 88;
+            (() => {
+                set(obj, "data.title.short", "Hi");
+            }).must.not.throw();
+
+            const newObj = set(obj, "data.title.short", "Hi");
+            newObj.must.be.an.object();
+            newObj.data.title.short.must.equal("Hi");
+        }
+    });
+
+    it("works on functions as source, behaves like lodash", () => {
+        lodash: {
+            const obj = () => {};
+            (() => {
+                _set(obj, "lo.da", "sh");
+            }).must.not.throw();
+
+            obj.lo.da.must.equal("sh");
+        }
+
+        bottom: {
+            const obj = () => {};
+            (() => {
+                set(obj, "lo.da", "sh");
+            }).must.not.throw();
+
+            obj.lo.da.must.equal("sh");
+        }
+    });
+
+    it("creates an object when numeric index is used and target isn't set, behaves NOT like lodash", () => {
+        lodash1: {
+            const obj = {};
+            _set(obj, ["items", 5, "title"], "Jan Padeusz");
+            obj.items.must.be.an.array();
+            obj.items.must.eql([,,,,, // eslint-disable-line no-sparse-arrays
+                {
+                    title: "Jan Padeusz",
+                }]);
+        }
+
+        lodash2: {
+            const obj = {};
+            _set(obj, "items.5.title", "Jan Padeusz");
+            obj.items.must.be.an.array();
+            obj.items.must.eql([,,,,, // eslint-disable-line no-sparse-arrays
+                {
+                    title: "Jan Padeusz",
+                }]);
+        }
+
+        bottom1: {
+            const obj = {};
+            set(obj, ["items", 5, "title"], "Jan Padeusz");
+            obj.items.must.not.be.an.array();
+            obj.items.must.eql({
+                5: {
+                    title: "Jan Padeusz",
+                },
+            });
+        }
+
+        bottom2: {
+            const obj = {};
+            set(obj, "items.5.title", "Jan Padeusz");
+            obj.items.must.not.be.an.array();
+            obj.items.must.eql({
+                5: {
+                    title: "Jan Padeusz",
+                },
+            });
+        }
+    });
+
+    it("doesn't parse path string as js code, behaves NOT like lodash", () => {
+        lodash: {
+            const obj = {};
+            _set(obj, "hello[world]", "is it me you're looking for?");
+            obj.hello.world.must.equal("is it me you're looking for?");
+        }
+
+        bottom: {
+            const obj = {};
+            set(obj, "hello[world]", "is it me you're looking for?");
+            obj.must.not.have.property("hello");
+            obj.must.have.property("hello[world]");
+            obj["hello[world]"].must.equal("is it me you're looking for?");
+        }
+    });
+
+    it("allow dot separated path, behaves like lodash", () => {
+        lodash: {
+            const obj = {};
+            _set(obj, "hello.world", "is it me you're looking for?");
+            obj.hello.world.must.equal("is it me you're looking for?");
+        }
+
+        bottom: {
+            const obj = {};
+            set(obj, "hello.world", "is it me you're looking for?");
+            obj.hello.world.must.equal("is it me you're looking for?");
+        }
+    });
+
+    it("allow arrays as path, behaves like lodash", () => {
+        lodash: {
+            const obj = {};
+            _set(obj, ["hello", "world"], "is it me you're looking for?");
+            obj.hello.world.must.equal("is it me you're looking for?");
+        }
+
+        bottom: {
+            const obj = {};
+            set(obj, ["hello", "world"], "is it me you're looking for?");
+            obj.hello.world.must.equal("is it me you're looking for?");
+        }
+    });
+
+    it("doesn't parse mixed array/dot-strings paths, behaves like lodash", () => {
+        lodash: {
+            const obj = {};
+            _set(obj, ["hello", "world.5"], "is it me you're looking for?");
+            obj.hello.must.not.have.property("world");
+            obj.hello.must.have.property("world.5");
+            obj.hello["world.5"].must.equal("is it me you're looking for?");
+        }
+
+        bottom: {
+            const obj = {};
+            set(obj, ["hello", "world.5"], "is it me you're looking for?");
+            obj.hello.must.not.have.property("world");
+            obj.hello.must.have.property("world.5");
+            obj.hello["world.5"].must.equal("is it me you're looking for?");
+        }
+    });
+
+    // @todo test Maps, Sets, etc.
+});

package/src/set.ts

@@ -0,0 +1,59 @@
+/**
+ * Source object to mutate.
+ *
+ * @see {@link set}.
+ */
+interface Source { [key: string]: unknown }
+
+const isObject = (value: unknown) => (typeof value === "object" || typeof value === "function") && value !== null;
+
+/**
+ * Updates the value at given path of given object. It mutates the object. 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.
+ * If you are okay with NOT mutating the object but get new one instead it is recommended to use `immutable-assign`
+ * package instead.
+ *
+ * @param {Object} source - source object to mutate
+ * @param {string|Array<string>} 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 object, not array
+ * { "items": { "0": value }}
+ * @returns {Object} - given object or new object if source was primitive
+ */
+const set = (source: Source, path: string | string[], value: unknown): Source | unknown => { // eslint-disable-line @typescript-eslint/no-redundant-type-constituents,max-len
+    const pathParts = typeof path === "string" ? path.split(".") : path;
+    const len = pathParts.length;
+
+    const result = isObject(source) ? 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])) {
+            (current as Source)[key] = {};
+        }
+        current = (current as Source)[key];
+    }
+    return result;
+};
+
+export { set };
+
+export type {
+    Source as SetSource,
+};