@ezez/utils 1.2.0 → 1.5.0

package/src/compareArrays.spec.ts

@@ -0,0 +1,38 @@
+import { compareArrays } from "./compareArrays.js";
+
+describe("compareArrays", () => {
+    it("should mark items that are only in a or b", async () => {
+        compareArrays([1, 2, 3], [4, 5, 6]).must.eql({
+            onlyA: [1, 2, 3],
+            onlyB: [4, 5, 6],
+            both: [],
+        });
+    });
+
+    it("should mark items that exists in both arrays", async () => {
+        compareArrays([1, 2, 3], [3, 4, 5]).must.eql({
+            onlyA: [1, 2],
+            onlyB: [4, 5],
+            both: [3],
+        });
+    });
+
+    it("should not return duplicates if given", async () => {
+        compareArrays([1, 1, 2, 3, 3], [3, 4, 5]).must.eql({
+            onlyA: [1, 2],
+            onlyB: [4, 5],
+            both: [3],
+        });
+        compareArrays([1, 2, 3, 3], [3, 3, 4, 5]).must.eql({
+            onlyA: [1, 2],
+            onlyB: [4, 5],
+            both: [3],
+        });
+        compareArrays([1, 2, 3, 3], [3, 3, 3, 4, 5]).must.eql({
+            onlyA: [1, 2],
+            onlyB: [4, 5],
+            both: [3],
+        });
+    });
+});
+

package/src/compareArrays.ts

@@ -0,0 +1,22 @@
+import { unique } from "./unique.js";
+
+/**
+ * Compares two arrays and returns the items that are only in arrayA, only in arrayB, and in both arrays.
+ * @param arrayA - first array
+ * @param arrayB - second array
+ * @returns an object with three properties:
+ * onlyA - items that exists only in first array,
+ * onlyB - items that exists only in second array,
+ * both - items that exists in both arrays
+ */
+const compareArrays = <T extends unknown[]>(arrayA: T, arrayB: T): { onlyA: T; onlyB: T; both: T } => {
+    const onlyA = unique(arrayA.filter((item) => !arrayB.includes(item)));
+    const onlyB = unique(arrayB.filter((item) => !arrayA.includes(item)));
+    const both = unique(arrayA.filter((item) => arrayB.includes(item)));
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return { onlyA, onlyB, both } as { onlyA: T; onlyB: T; both: T };
+};
+
+export {
+    compareArrays,
+};

package/src/ensureArray.ts

@@ -1,5 +1,5 @@
 /**
- * Wraps value in an array until the value is already an array
+ * Wraps value in an array unless the value is already an array
  * @param {*} value - value to be wrapped
  * @returns {Array}
  */

package/src/ensureError.ts

@@ -1,5 +1,12 @@
 /**
  * Ensures given value is an instance of Error.
+ *
+ * This is for simple use cases only, for maximum flexibility use `@ezez/errors` package.
+ * @example ensureError(new Error("test")); // returns given Error instance (not modified)
+ * @example ensureError("test");
+ * // ^ returns new Error instance with error message: "Expected error instance, got something else: test"
+ * @example ensureError({});
+ * // ^ returns new Error instance with error message: "Expected error instance, got something else: [object Object]"
  * @param {*} e - value to check
  * @returns Error - original error or new Error instance
  */

package/src/escapeRegExp.spec.ts

@@ -0,0 +1,31 @@
+import { escapeRegExp } from "./escapeRegExp.js";
+
+describe("escapeRegExp", () => {
+    it("it should escape dot", () => {
+        const userName = ".";
+        const regex = new RegExp(`^(maciek|${escapeRegExp(userName)})$`);
+        const result = regex.test("maciek");
+        result.must.be.true();
+
+        const result2 = regex.test("stefan");
+        result2.must.be.false();
+
+        const result3 = regex.test(",");
+        result3.must.be.false();
+
+        const result4 = regex.test(".");
+        result4.must.be.true();
+
+        const result5 = regex.test("...");
+        result5.must.be.false();
+    });
+
+    it("should escape complex string", () => {
+        const userName = "([{^|";
+        const fn = () => new RegExp(`^(maciek|${escapeRegExp(userName)})$`);
+        fn.must.not.throw();
+
+        const fnNoEscape = () => new RegExp(`^(maciek|${userName})$`);
+        fnNoEscape.must.throw();
+    });
+});

package/src/escapeRegExp.ts

@@ -0,0 +1,17 @@
+/**
+ * Escapes a string to be used in a regular expression.
+ * From: https://stackoverflow.com/a/3561711
+ * @param string - string to escape
+ * @example ```typescript
+ * const badName = "([{^|";
+ * const regex = new RegExp(`^(maciek|${escapeRegExp(badName)})$`); // won't crash
+ * regex.test(badName); // true
+ * ```
+ */
+const escapeRegExp = (string: string) => {
+    return string.replace(/[/\-\\^$*+?.()|[\]{}]/g, "\\$&");
+};
+
+export {
+    escapeRegExp,
+};

package/src/index.ts

@@ -4,10 +4,12 @@ export * from "./ensureSuffix.js";
 export * from "./cap.js";
 export * from "./capitalize.js";
 export * from "./coalesce.js";
+export * from "./compareArrays.js";
 export * from "./ensureArray.js";
 export * from "./ensureDate.js";
 export * from "./ensureError.js";
 export * from "./ensureTimestamp.js";
+export * from "./escapeRegExp.js";
 export * from "./get.js";
 export * from "./getMultiple.js";
 export * from "./insertSeparator.js";
@@ -26,16 +28,20 @@ export * from "./omit.js";
 export * from "./pick.js";
 export * from "./pull.js";
 export * from "./remove.js";
+export * from "./replace.js";
 export * from "./rethrow.js";
+export * from "./safe.js";
 export * from "./scale.js";
 export * from "./seq.js";
 export * from "./set.js";
 export * from "./setImmutable.js";
 export * from "./sortBy.js";
+export * from "./sortProps.js";
 export * from "./stripPrefix.js";
 export * from "./stripSuffix.js";
 export * from "./throttle.js";
 export * from "./truthy.js";
+export * from "./unique.js";
 export * from "./wait.js";
 export * from "./waitFor.js";
 export * from "./waitSync.js";

package/src/isPlainObject.spec.ts

@@ -22,13 +22,6 @@ describe("isPlainObject", function() {
         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 {}

package/src/isPlainObject.ts

@@ -1,5 +1,10 @@
 /**
  * Checks if given value is a plain object. Plain object should be an object that's not an instance of anything.
+ * @example isPlainObject({}); // returns true
+ * @example isPlainObject(Object.create(null)); // returns true
+ * @example isPlainObject(new URL("https://ezez.dev")); // returns false
+ * @example isPlainObject([]); // returns false
+ * @example isPlainObject(5); // returns false
  * @param value - value to test
  */
 const isPlainObject = (value: unknown) => Boolean(

package/src/replace.spec.ts

@@ -0,0 +1,22 @@
+import { replace } from "./replace.js";
+
+describe("replace", () => {
+    it("does a basic replace", () => {
+        replace("Hello, %name%!", { "%name%": "John" }).must.equal("Hello, John!");
+    });
+
+    it("replaces multiple occurrences", () => {
+        replace("Hello, %name%! Nice to meet you %name%!", { "%name%": "Jane" })
+            .must.equal("Hello, Jane! Nice to meet you Jane!");
+    });
+
+    it("replaces multiple occurences of multiple variables", () => {
+        replace("Hello, %name%, your age is %age%! Nice to meet you %age% yo %name%!",
+            { "%name%": "Jane", "%age%": "30" },
+        ).must.equal("Hello, Jane, your age is 30! Nice to meet you 30 yo Jane!");
+    });
+
+    it("doesn't break on regexp characters", () => {
+        replace("Hello.", { ".": "!" }).must.equal("Hello!");
+    });
+});

package/src/replace.ts

@@ -0,0 +1,19 @@
+/* eslint-disable max-len */
+import { escapeRegExp } from "./escapeRegExp.js";
+
+/**
+ * Replaces all occurrences of the keys in the replaceMap with the values.
+ * @param source - source string
+ * @param replaceMap - keys from this object will be replaced with values in source string
+ * @example replace("Hello, %name%!", { "%name%: "John" }) // "Hello, John!"
+ * @example replace("Hello, %name%! Nice to meet you %name%!", { "%name%": "Jane" }) // "Hello, Jane! Nice to meet you Jane!"
+ */
+const replace = (source: string, replaceMap: Record<string, string>) => {
+    /* eslint-enable max-len */
+    const regex = new RegExp(Object.keys(replaceMap).map(escapeRegExp).join("|"), "g");
+    return source.replace(regex, (matched) => replaceMap[matched]);
+};
+
+export {
+    replace,
+};

package/src/safe.spec.ts

@@ -0,0 +1,52 @@
+import { safe } from "./safe.js";
+
+describe("safe", () => {
+    it("returns value from a function if it doesn't throw", () => {
+        const result = safe(() => 5);
+        result.must.equal(5);
+    });
+
+    it("returns undefined if function throws and no default value is given", () => {
+        // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+        const result = safe(() => {
+            throw new Error("Boo");
+        });
+        (result === undefined).must.be.true();
+    });
+
+    it("returns given default value if function throws", () => {
+        const result = safe(() => {
+            throw new Error("Boo");
+        }, 15);
+        result.must.equal(15);
+    });
+
+    it("returns undefined if function throws and default value is undefined", () => {
+        // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+        const result = safe(() => {
+            throw new Error("Boo");
+        }, undefined);
+        (result === undefined).must.be.true();
+    });
+
+    it("returns value from function if it doesn't throw and default is given", () => {
+        const result = safe(() => 5, 15);
+        result.must.equal(5);
+    });
+
+    it("doesn't unwrap promises", () => {
+        const result = safe(() => Promise.resolve(5));
+        result.must.be.instanceof(Promise);
+    });
+
+    it("doesn't 'work' with promises", () => {
+        // eslint-disable-next-line @typescript-eslint/require-await
+        const result = safe(async () => {
+            throw new Error("Boo!!!");
+        });
+        result.must.be.instanceof(Promise);
+
+        // prevent unhandled rejection warning
+        result.catch(() => null);
+    });
+});

package/src/safe.ts

@@ -0,0 +1,24 @@
+function safe<T>(fn: () => T): T | undefined;
+function safe<T, Y>(fn: () => T, def: Y): T | Y;
+
+/* eslint-disable max-len */
+/**
+ * Safely execute a function, return its return value or default value if the function throws.
+ * @param fn - function to run
+ * @param def - default value
+ *
+ * @example
+ * safe(() => JSON.parse(unknownString), null); // if unknownString is not a valid JSON, null will be returned
+ * safe(() => trySomethingComplicated(), defaultValue); // if trySomethingComplicated throws, defaultValue will be returned
+ */
+function safe<T, Y>(fn: () => T, def?: Y) { // eslint-disable-line func-style
+    /* eslint-enable max-len */
+    try {
+        return fn();
+    }
+    catch {
+        return def;
+    }
+}
+
+export { safe };

package/src/sortProps.spec.ts

@@ -0,0 +1,20 @@
+import { sortProps } from "./sortProps.js";
+
+describe("sort props", () => {
+    it("can sort props ascending", () => {
+        const sorted = sortProps({ b: 2, a: 1, z: 26 });
+        Object.keys(sorted).must.eql(["a", "b", "z"]);
+    });
+
+    it("can sort props descending", () => {
+        const sorted = sortProps({ b: 2, a: 1, z: 26 }, false);
+        Object.keys(sorted).must.eql(["z", "b", "a"]);
+    });
+
+    it("doesn't modify original object", () => {
+        const source = { b: 2, a: 1, z: 26 };
+        const sorted = sortProps(source);
+        Object.keys(source).must.eql(["b", "a", "z"]);
+        Object.keys(sorted).must.eql(["a", "b", "z"]);
+    });
+});

package/src/sortProps.ts

@@ -0,0 +1,21 @@
+/**
+ * Sorts the properties of an object alphabetically, ascending or descending.
+ * REMEMBER: In theory JS engines do not guarantee the order of object properties. In practice most popular engines do.
+ * @param object - source object
+ * @param asc - sort ascending?
+ * @example sortProps({ b: 2, a: 1, z: 26 }) // { a: 1, b: 2, z: 26 }
+ */
+const sortProps = <T extends Record<string, unknown>>(object: T, asc = true): T => {
+    const sorted: Record<string, unknown> = {};
+    const keys = Object.keys(object);
+    if (asc) { keys.sort(); }
+    else { keys.sort().reverse(); }
+    for (const key of keys) {
+        sorted[key] = object[key];
+    }
+    return sorted as T;
+};
+
+export {
+    sortProps,
+};

package/src/unique.spec.ts

@@ -0,0 +1,10 @@
+import { unique } from "./unique.js";
+
+describe("unique", () => {
+    it("returns unique values in array", async () => {
+        unique([1, 2, 3, 2, 1]).must.eql([1, 2, 3]);
+        unique([{ a: true }, { a: true }]).must.eql([{ a: true }, { a: true }]);
+        const a = { a: true };
+        unique([a, a]).must.eql([a]);
+    });
+});

package/src/unique.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns a new array with unique values of given array.
+ * @param arr - source array
+ * @example unique([1, 2, 3, 2, 1]) // [1, 2, 3]
+ */
+const unique = <T extends unknown[]>(arr: T): T => {
+    return [...new Set(arr)] as T;
+};
+
+export {
+    unique,
+};

package/typedoc.cjs

@@ -0,0 +1,5 @@
+const json = require("./pagesconfig.json");
+
+module.exports = {
+    pluginPages: json,
+};