@ezez/utils 1.2.0 → 1.4.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@ezez/utils",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "repository": "https://github.com/dzek69/bottom-line.git",
   "author": "Jacek Nowacki @dzek69 <git-public@dzek.eu>",
   "license": "MIT",
   "scripts": {
     "test": "NODE_ENV=test jest",
     "test:lodashImports": "node test/lodash-tree.cjs",
-    "docs": "typedoc src/index.ts --skipErrorChecking --out docs --includeVersion --pluginPages ./pagesconfig.json",
+    "docs": "typedoc src/index.ts --skipErrorChecking --out docs --includeVersion",
     "compile": "yarn compile:esm && yarn compile:cjs",
     "compile:esm": "rm -rf esm && tsc --project tsconfig.esm.json && node ./build-scripts/compile.esm.after.mjs",
     "compile:cjs": "rm -rf dist && tsc --project tsconfig.cjs.json && node ./build-scripts/compile.cjs.after.mjs",
@@ -35,31 +35,31 @@
   "module": "./esm/index.js",
   "type": "module",
   "devDependencies": {
-    "@babel/core": "^7.19.3",
-    "@babel/preset-env": "^7.19.3",
-    "@babel/preset-typescript": "^7.18.6",
-    "@dzek69/eslint-config-base": "^2.3.0",
-    "@dzek69/eslint-config-typescript": "^1.0.2",
-    "@types/jest": "^29.0.3",
+    "@babel/core": "^7.21.4",
+    "@babel/preset-env": "^7.21.4",
+    "@babel/preset-typescript": "^7.21.4",
+    "@dzek69/eslint-config-base": "^2.4.0",
+    "@dzek69/eslint-config-import": "^1.2.0",
+    "@dzek69/eslint-config-import-typescript": "^1.0.0",
+    "@dzek69/eslint-config-typescript": "^1.1.0",
+    "@knodes/typedoc-plugin-pages": "^0.23.4",
+    "@types/jest": "^29.5.0",
     "@types/lodash": "^4.14.168",
-    "@typescript-eslint/eslint-plugin": "^5.38.1",
-    "@typescript-eslint/parser": "^5.38.1",
+    "@typescript-eslint/eslint-plugin": "^5.58.0",
+    "@typescript-eslint/parser": "^5.58.0",
     "babel-plugin-module-extension": "^0.1.3",
-    "eslint": "^8.24.0",
-    "fs-extra": "^10.1.0",
-    "husky": "^8.0.1",
-    "jest": "^29.1.1",
+    "eslint": "^8.38.0",
+    "eslint-plugin-import": "^2.27.5",
+    "fs-extra": "^11.1.1",
+    "husky": "^8.0.3",
+    "jest": "^29.5.0",
     "lodash": "^4.17.21",
     "must": "^0.13.4",
-    "nodemon": "^2.0.20",
+    "nodemon": "^2.0.22",
+    "prettier": "^2.8.7",
     "ts-node": "^10.9.1",
-    "typedoc": "^0.23.15",
-    "typescript": "^4.9.5",
-    "eslint-plugin-import": "^2.26.0",
-    "@dzek69/eslint-config-import": "^1.0.0",
-    "@dzek69/eslint-config-import-typescript": "^1.0.0",
-    "@knodes/typedoc-plugin-pages": "^0.23.1",
-    "prettier": "^2.8.3"
+    "typedoc": "^0.23.28",
+    "typescript": "^5.0.4"
   },
   "husky": {
     "hooks": {
@@ -67,7 +67,7 @@
     }
   },
   "libraryTemplate": {
-    "version": "3.8.0",
+    "version": "3.9.1",
     "language": "typescript",
     "fixDefaultForCommonJS": false,
     "jsx": false

package/src/coalesce.ts

@@ -2,8 +2,8 @@
  * Returns first non-nil (not undefined, not null) value from given arguments.
  *
  * @param {...*} args - values
- * @example coalesce(null, undefined, void 0, 5); // returns 5
- * @example coalesce(4, null, 6, undefined); // returns 4
+ * @example coalesce(null, undefined, void 1, 5); // returns 5 (mind the `void`)
+ * @example coalesce(0, null, 6, undefined); // returns 0
  * @example coalesce(undefined); // returns null
  * @example coalesce(); // returns null
  * @returns {*|null} first non-nil value or null

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

@@ -8,6 +8,7 @@ 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,12 +27,15 @@ 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";

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/typedoc.cjs

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