@ezez/utils 1.0.0

package/src/ensureError.ts

@@ -0,0 +1,15 @@
+/**
+ * Ensures given value is an instance of Error.
+ * @param {*} e - value to check
+ * @returns Error - original error or new Error instance
+ */
+const ensureError = (e: unknown) => {
+    if (e instanceof Error) {
+        return e;
+    }
+    return new Error("Expected error instance, got something else: " + String(e));
+};
+
+export {
+    ensureError,
+};

package/src/get.spec.ts

@@ -0,0 +1,183 @@
+import { get as _get } from "lodash";
+
+import { get } from "./get.js";
+
+const otherObject = { a: 5 };
+const testObject = {
+    "product": {
+        name: "abc",
+        price: 123,
+        value: undefined,
+        empty: null,
+        notANumber: NaN,
+        object: otherObject,
+    },
+    "product[price]": 400,
+    "name": "string",
+};
+
+const Test = function() {};
+Test.prototype.nonOwn = 1;
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const testInstance = new Test();
+testInstance.own = 1;
+Object.defineProperty(testInstance, "nonEnum", {
+    enumerable: false,
+    value: 15,
+});
+
+describe("get", () => {
+    it("returns shallow property of an object, behaves like lodash", () => {
+        const value = get(testObject, "name");
+        value.must.equal("string");
+
+        const _value = _get(testObject, "name");
+        value.must.equal(_value);
+    });
+
+    it("returns deep property of an object using array, behaves like lodash", () => {
+        const value = get(testObject, ["product", "name"]);
+        value.must.equal("abc");
+
+        const _value = _get(testObject, ["product", "name"]);
+        value.must.equal(_value);
+    });
+
+    it("returns deep property of an object using dot-string, behaves like lodash", () => {
+        const value = get(testObject, "product.name");
+        value.must.equal("abc");
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(testObject, "product.name");
+        value.must.equal(_value);
+    });
+
+    it("doesn't parse string as js code, behaves NOT like lodash", () => {
+        // Lodash intention-guessing example, inconsistency detected
+        const name = get(testObject, "product[name]");
+        (name === undefined).must.be.true();
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _name = _get(testObject, "product[name]"); // deep value
+        _name.must.equal("abc");
+
+        const price = get(testObject, "product[price]");
+        price.must.be.equal(400);
+
+        const _price = _get(testObject, "product[price]"); // shallow value
+        _price.must.equal(400);
+    });
+
+    it("returns undefined when value is not found and default isn't provided, behaves like lodash", () => {
+        const value = get(testObject, "product.something");
+        (value === undefined).must.be.true();
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(testObject, "product.something");
+        (_value === undefined).must.be.true();
+    });
+
+    it("returns default value when property is missing, behaves like lodash", () => {
+        const value = get(testObject, "product.something", 3);
+        value.must.equal(3);
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(testObject, "product.something", 3);
+        _value.must.equal(3);
+    });
+
+    it("returns undefined when found value is explicitly undefined, behaves NOT like lodash", () => {
+        const value = get(testObject, "product.value", 3);
+        (value === undefined).must.be.true();
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(testObject, "product.value", 3);
+        _value.must.equal(3);
+    });
+
+    it("returns null when found value is explicitly null, behaves like lodash", () => {
+        const value = get(testObject, "product.empty", 3);
+        (value === null).must.be.true();
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(testObject, "product.empty", 3);
+        (_value === null).must.be.true();
+    });
+
+    it("returns NaN when found value is NaN, behaves like lodash", () => {
+        const value = get(testObject, "product.notANumber", 3);
+        value.must.be.nan();
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(testObject, "product.notANumber", 3);
+        _value.must.be.nan();
+    });
+
+    it("returns objects, behaves like lodash", () => {
+        const value = get(testObject, "product.object");
+        value.must.equal(otherObject);
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(testObject, "product.object");
+        _value.must.equal(otherObject);
+    });
+
+    it("works on nulls, behaves like lodash", () => {
+        const value = get(null, "product.object", 3);
+        value.must.equal(3);
+
+        const _value = _get(null, "product.object", 3);
+        _value.must.equal(3);
+    });
+
+    it("works on undefined, behaves like lodash", () => {
+        const value = get(undefined, "product.object", 3);
+        value.must.equal(3);
+
+        const _value = _get(undefined, "product.object", 3);
+        _value.must.equal(3);
+    });
+
+    it("works on NaN, behaves like lodash", () => {
+        const value = get(NaN, "product.object", 3);
+        value.must.equal(3);
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(NaN, "product.object", 3);
+        _value.must.equal(3);
+    });
+
+    it("returns inherited properties value, behaves like lodash", () => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        const value = get(testInstance, "nonOwn", 3);
+        value.must.equal(1);
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(testInstance, "nonOwn", 3);
+        _value.must.equal(1);
+    });
+
+    it("returns non-enumerable properties value, behaves like lodash", () => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        const value = get(testInstance, "nonEnum", 3);
+        value.must.equal(15);
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(testInstance, "nonEnum", 3);
+        _value.must.equal(15);
+    });
+
+    it("doesn't parse mixed array/dot-strings property selectors, behaves like lodash", () => {
+        const value = get(testObject, ["product", "object.a"], "def");
+        const value2 = get(testObject, "product.object.a", "def");
+        value.must.equal("def");
+        value2.must.equal(5);
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const _value = _get(testObject, ["product", "object.a"], "def");
+        _value.must.equal("def");
+    });
+
+    // @todo test Maps, Sets etc
+});

package/src/get.ts

@@ -0,0 +1,53 @@
+/**
+ * Source object to search in.
+ *
+ * @see {@link get}.
+ */
+interface Source { [key: string]: unknown }
+
+/**
+ * Returns the value at given path of given object. If path is not found then default value is returned. No exceptions
+ * are thrown when undefined/null value gets in the way.
+ *
+ * This is still too dynamic in nature to get full TypeScript support. Properties are not typed, return type is unknown.
+ * If your data access is statically known there is no need to use this function, just use `object.property` syntax with
+ * optional chaining.
+ *
+ * @param {Object} source - source object to search in
+ * @param {string|Array<string>} property - path to the expected value written as dot-separated property names or array
+ * with property names. Use Array when your keys includes dots. Keys are treated literally, no parsing is done on keys.
+ * @param {*} [defaultValue] - value to return if path is not found. If path is found, but the value is undefined -
+ * default value will NOT be used, use `get(...) || default` instead
+ * @example get(object, "deep.property") // equals to safe `object.deep.property`
+ * @example get(object, ["deep", "property"]) // same as above
+ * @example get(object, "deep[0].property")
+ * // equals to:
+ * object["deep[0]"].property
+ * // not:
+ * object.deep[0].property
+ * @example get(object, "very.deep.property", 5)
+ * // if object.very.deep has also `property` property then it value will be returned, even if undefined
+ * // else `5` will be returned
+ * @returns {*} - found value or default value
+ */
+const get = (source: Source, property: string | string[], defaultValue: unknown = undefined): unknown => {
+    const properties = typeof property === "string" ? property.split(".") : [...property];
+
+    let result: unknown = source;
+    while (properties.length) {
+        const current = properties.shift()!;
+        if (result && typeof result === "object" && current in result) {
+            result = (result as Source)[current];
+        }
+        else {
+            return defaultValue;
+        }
+    }
+    return result;
+};
+
+export { get };
+
+export type {
+    Source as GetSource,
+};

package/src/getMultiple.spec.ts

@@ -0,0 +1,25 @@
+import { getMultiple } from "./getMultiple.js";
+
+const testObject = {
+    product: {
+        title: "abc",
+        nothing: undefined,
+    },
+};
+
+describe("getMultiple", () => {
+    it("returns first property that exist, with mixed selectors", () => {
+        const value = getMultiple(testObject, 123, ["product", "xxx"], "product.title");
+        value.must.equal("abc");
+    });
+
+    it("returns first property that exist even if value is undefined", () => {
+        const value = getMultiple(testObject, 123, ["product", "nothing"], "product.title");
+        (value === undefined).must.be.true();
+    });
+
+    it("returns default value when nothing exists", () => {
+        const value = getMultiple(testObject, 123, ["product", "name"], "product.price");
+        value.must.equal(123);
+    });
+});

package/src/getMultiple.ts

@@ -0,0 +1,47 @@
+import { get } from "./get.js";
+
+/**
+ * Source object to search in.
+ *
+ * @see {@link getMultiple}.
+ */
+interface Source { [key: string]: unknown }
+
+const DEFAULT = {};
+
+/**
+ * Returns first found value at given list of paths of given object. Will return and stop at undefined if found! If
+ * nothing is found then default value (required to pass) will be returned.
+ *
+ * This is still too dynamic in nature to get full TypeScript support. Properties are not typed, return type is unknown.
+ * If your data access is statically known there is no need to use this function, just use `object.property` syntax with
+ * optional chaining.
+ *
+ * @param {Object} source - source object to search in
+ * @param {*} defaultValue - default value to return if nothing is found
+ * @param {...string|Array.<string>} paths - paths defined as dot-separated properties names or array of properties name
+ * @see {@link get} - for base usage example with single path only
+ * @example getMultiple(obj, 5, "details.error.message", ["error", "message"], "errorMessage")
+ * // will look for obj.details.error.message - if path does not exist
+ * // will look for obj.error.message - if not defined
+ * // will look for obj.errorMessage - if not defined
+ * // will return 5
+ * @returns {*} - found value or default value
+ */
+const getMultiple = (source: Source, defaultValue: unknown, ...paths: (string | string[])[]): unknown => {
+    const length = paths.length;
+    for (let i = 0; i < length; i++) {
+        const properties = paths[i];
+        const result = get(source, properties, DEFAULT);
+        if (result !== DEFAULT) {
+            return result;
+        }
+    }
+    return defaultValue;
+};
+
+export { getMultiple };
+
+export type {
+    Source as GetMultipleSource,
+};

package/src/index.ts

@@ -0,0 +1,33 @@
+/* eslint-disable import/max-dependencies */
+export * from "./cap.js";
+export * from "./capitalize.js";
+export * from "./coalesce.js";
+export * from "./ensureArray.js";
+export * from "./ensureError.js";
+export * from "./get.js";
+export * from "./getMultiple.js";
+export * from "./insertSeparator.js";
+export * from "./isEmpty.js";
+export * from "./isPlainObject.js";
+export * from "./last.js";
+export * from "./mapAsync.js";
+export * from "./mapValues.js";
+export * from "./match.js";
+export * from "./merge.js";
+export * from "./mostFrequent.js";
+export * from "./noop.js";
+export * from "./omit.js";
+export * from "./pick.js";
+export * from "./pull.js";
+export * from "./remove.js";
+export * from "./rethrow.js";
+export * from "./scale.js";
+export * from "./seq.js";
+export * from "./set.js";
+export * from "./setImmutable.js";
+export * from "./sortBy.js";
+export * from "./throttle.js";
+export * from "./truthy.js";
+export * from "./wait.js";
+export * from "./waitFor.js";
+export * from "./waitSync.js";

package/src/insertSeparator.spec.ts

@@ -0,0 +1,29 @@
+import { insertSeparator } from "./insertSeparator.js";
+
+describe("insertSeparator", () => {
+    it("inserts value on array with data", () => {
+        const source = [5, 6, 7];
+        insertSeparator(source, "a").must.eql([5, "a", 6, "a", 7]);
+        insertSeparator(source, "a").must.not.equal(source);
+    });
+
+    it("do nothing on array without data (returns source array)", () => {
+        const source = [];
+        insertSeparator(source, "a").must.equal(source);
+        source.length.must.equal(0);
+    });
+
+    it("do nothing on array with single item (returns source array)", () => {
+        const source = [1];
+        insertSeparator(source, "a").must.equal(source);
+        source.length.must.equal(1);
+    });
+
+    it("crashes on non-array", () => {
+        (() => insertSeparator(null, "a")).must.throw();
+        (() => insertSeparator(undefined, "a")).must.throw();
+        (() => insertSeparator({}, "a")).must.throw();
+        (() => insertSeparator(4, "a")).must.throw();
+        (() => insertSeparator("4", "a")).must.throw();
+    });
+});

package/src/insertSeparator.ts

@@ -0,0 +1,22 @@
+/**
+ * Inserts given separator between all array elements
+ *
+ * @param {Array} source - source array to put new elements between
+ * @param {*} separator - separator to inset
+ * @returns {Array} - new array with separator items added or same array if there isn't enough items to put separator
+ */
+const insertSeparator = <T, S>(source: T[], separator: S): (T | S)[] => {
+    if (!Array.isArray(source)) {
+        throw new TypeError("Source must be an array");
+    }
+    if (source.length <= 1) {
+        return source;
+    }
+    const result: (T | S)[] = [...source];
+    for (let i = result.length - 1; i > 0; i--) {
+        result.splice(i, 0, separator);
+    }
+    return result;
+};
+
+export { insertSeparator };

package/src/isEmpty.spec.ts

@@ -0,0 +1,130 @@
+import { isEmpty as _isEmpty } from "lodash";
+
+import { isEmpty } from "./isEmpty.js";
+
+const emptyMap = new Map();
+const filledMap = new Map();
+filledMap.set("x", "x");
+
+const emptySet = new Set();
+const filledSet = new Set();
+filledSet.add("x");
+
+const emptyString = "";
+const filledString = "abc";
+
+const emptyArray = [];
+const holeyArray = [,]; // eslint-disable-line no-sparse-arrays
+const filledArray = [1];
+
+let emptyArgs;
+(function() { emptyArgs = arguments; })(); // eslint-disable-line prefer-rest-params
+let filledArgs;
+(function() { filledArgs = arguments; })(1, 2, 3); // eslint-disable-line prefer-rest-params
+
+const emptyBuffer = Buffer.from("");
+const filledBuffer = Buffer.from("abc");
+
+const emptyObject = {};
+const filledObject = { a: 5 };
+const nonEnumObject = {};
+Object.defineProperty(nonEnumObject, "prop", { enumerable: false, value: 666 });
+
+const SomeElement = function() {};
+SomeElement.prototype.prop = 5;
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const inheritedObject = new SomeElement();
+
+const emptyTypedArray = new Uint8Array();
+const filledTypedArray = new Uint8Array(1);
+filledTypedArray[0] = 69;
+
+describe("isEmpty", () => {
+    it("works with Maps, behaves like lodash", () => {
+        isEmpty(emptyMap).must.be.true();
+        _isEmpty(emptyMap).must.be.true();
+
+        isEmpty(filledMap).must.be.false();
+        _isEmpty(filledMap).must.be.false();
+    });
+
+    it("works with Sets, behaves like lodash", () => {
+        isEmpty(emptySet).must.be.true();
+        _isEmpty(emptySet).must.be.true();
+
+        isEmpty(filledSet).must.be.false();
+        _isEmpty(filledSet).must.be.false();
+    });
+
+    it("works with strings, behaves like lodash", () => {
+        isEmpty(emptyString).must.be.true();
+        _isEmpty(emptyString).must.be.true();
+
+        isEmpty(filledString).must.be.false();
+        _isEmpty(filledString).must.be.false();
+    });
+
+    it("works with arrays, behaves like lodash except for holey arrays", () => {
+        isEmpty(emptyArray).must.be.true();
+        _isEmpty(emptyArray).must.be.true();
+
+        isEmpty(filledArray).must.be.false();
+        _isEmpty(filledArray).must.be.false();
+
+        isEmpty(holeyArray).must.be.true();
+        _isEmpty(holeyArray).must.be.false();
+    });
+
+    it("works with arguments, behaves like lodash", () => {
+        isEmpty(emptyArgs).must.be.true();
+        _isEmpty(emptyArgs).must.be.true();
+
+        isEmpty(filledArgs).must.be.false();
+        _isEmpty(filledArgs).must.be.false();
+    });
+
+    it("works with Buffers, behaves like lodash", () => {
+        isEmpty(emptyBuffer).must.be.true();
+        _isEmpty(emptyBuffer).must.be.true();
+
+        isEmpty(filledBuffer).must.be.false();
+        _isEmpty(filledBuffer).must.be.false();
+    });
+
+    it("works with objects, behaves like lodash", () => {
+        isEmpty(emptyObject).must.be.true();
+        _isEmpty(emptyObject).must.be.true();
+
+        isEmpty(filledObject).must.be.false();
+        _isEmpty({ a: 555, b: 666 }).must.be.false();
+
+        isEmpty(nonEnumObject).must.be.true();
+        _isEmpty(nonEnumObject).must.be.true();
+
+        isEmpty(inheritedObject).must.be.true();
+        _isEmpty(inheritedObject).must.be.true();
+    });
+
+    it("works with typed arrays, behaves like lodash", () => {
+        isEmpty(emptyTypedArray).must.be.true();
+        _isEmpty(emptyTypedArray).must.be.true();
+
+        isEmpty(filledTypedArray).must.be.false();
+        _isEmpty(filledTypedArray).must.be.false();
+    });
+
+    it("returns true for nil values", function() {
+        isEmpty(null).must.be.true();
+        isEmpty(undefined).must.be.true();
+    });
+
+    it("throws on primitives", () => {
+        (() => isEmpty(0)).must.throw();
+        (() => isEmpty(100)).must.throw();
+        (() => isEmpty(true)).must.throw();
+        (() => isEmpty(false)).must.throw();
+        (() => isEmpty(Infinity)).must.throw();
+        (() => isEmpty(NaN)).must.throw();
+        (() => isEmpty(() => {})).must.throw();
+    });
+});

package/src/isEmpty.ts

@@ -0,0 +1,50 @@
+interface ObjectWithLength {
+    length: number;
+}
+
+interface ObjectWithSize {
+    size: number;
+}
+
+/**
+ * Returns true if passed argument seems to be empty.
+ * Nil values are empty.
+ * Strings are considered empty when length is 0.
+ * Other primitives will throw an error.
+ * Objects are considered empty when doesn't have any enumerable & own property.
+ * Arrays and array-like objects are considered empty when length value is 0.
+ * Map, Set and -like objects are considered empty when size value is 0.
+ *
+ * @param {*} obj - source value
+ * @example isEmpty({}) // true
+ * @example isEmpty(100) // throws
+ * @example isEmpty([]) // true
+ * @example isEmpty([1]) // false
+ * @example isEmpty({ length: 5 }) // false
+ * @example isEmpty({ length: 0 }) // true
+ * @example isEmpty({ size: 0 }) // true
+ * @returns {boolean} - is value considered empty
+ */
+const isEmpty = (obj: unknown) => {
+    if (typeof obj === "string") {
+        return !obj.length;
+    }
+    if (obj == null) {
+        return true;
+    }
+    if (typeof obj !== "object") {
+        throw new Error("isEmpty cannot be used on primitives");
+    }
+    if (Array.isArray(obj)) {
+        return !Object.keys(obj).length;
+    }
+    if ("length" in obj) {
+        return !(obj as ObjectWithLength).length;
+    }
+    if ("size" in obj) {
+        return !(obj as ObjectWithSize).size;
+    }
+    return !Object.keys(obj).length;
+};
+
+export { isEmpty };

package/src/isPlainObject.spec.ts

@@ -0,0 +1,42 @@
+import { isPlainObject } from "./isPlainObject.js";
+
+describe("isPlainObject", function() {
+    it("rejects anything non object-like", function() {
+        isPlainObject(null).must.be.false();
+        isPlainObject(5).must.be.false();
+        isPlainObject(() => ({})).must.be.false();
+        isPlainObject(false).must.be.false();
+        isPlainObject(new URL("https://ezez.dev")).must.be.false();
+        isPlainObject([]).must.be.false();
+
+        // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+        class X {}
+        isPlainObject(X).must.be.false();
+    });
+
+    it("accepts plain objects", function() {
+        isPlainObject({}).must.be.true();
+        isPlainObject({ some: "data" }).must.be.true();
+        isPlainObject({ some: function fn() {} }).must.be.true();
+        isPlainObject(Object.create(null)).must.be.true();
+        isPlainObject({ constructor: () => null }).must.be.true();
+    });
+
+    it("accepts plain objects", function() {
+        isPlainObject({}).must.be.true();
+        isPlainObject({ some: "data" }).must.be.true();
+        isPlainObject({ some: function fn() {} }).must.be.true();
+        isPlainObject(Object.create(null)).must.be.true();
+    });
+
+    it("shouldn't accept any instances", function() {
+        // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+        class X {}
+        isPlainObject(new X()).must.be.false();
+
+        // eslint-disable-next-line func-style
+        function MyObject() {}
+        // @ts-expect-error we don't care
+        isPlainObject(new MyObject()).must.be.false();
+    });
+});

package/src/isPlainObject.ts

@@ -0,0 +1,18 @@
+/**
+ * Checks if given value is a plain object. Plain object should be an object that's not an instance of anything.
+ * @param value - value to test
+ */
+const isPlainObject = (value: unknown) => Boolean(
+    value
+    && typeof value === "object"
+    && (
+        value.constructor === Object // default constructor
+        || !("constructor" in value) // no constructor
+        || Object.getOwnPropertyNames(value).includes("constructor") // constructor is set by user
+    ),
+);
+
+export {
+    isPlainObject,
+};
+