@ezez/utils 1.1.0 → 1.4.0

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/stripPrefix.spec.ts

@@ -0,0 +1,13 @@
+import { stripPrefix } from "./stripPrefix.js";
+
+describe("strip prefix", function() {
+    it("should strip prefix if string has it", function() {
+        stripPrefix("abc", "a").must.equal("bc");
+        stripPrefix("hello world", "hello").must.equal(" world");
+    });
+
+    it("should keep the string as it is when string don't have specified prefix", function() {
+        stripPrefix("abc", "b").must.equal("abc");
+        stripPrefix("hello world", "world").must.equal("hello world");
+    });
+});

package/src/stripPrefix.ts

@@ -0,0 +1,15 @@
+/**
+ * Strip a prefix from a string.
+ * @param {string} from - string to strip prefix from
+ * @param {string} prefix - prefix to strip
+ */
+const stripPrefix = (from: string, prefix: string): string => {
+    if (from.startsWith(prefix)) {
+        return from.slice(prefix.length);
+    }
+    return from;
+};
+
+export {
+    stripPrefix,
+};

package/src/stripSuffix.spec.ts

@@ -0,0 +1,13 @@
+import { stripSuffix } from "./stripSuffix.js";
+
+describe("strip suffix", function() {
+    it("should strip suffix if string has it", function() {
+        stripSuffix("abc", "c").must.equal("ab");
+        stripSuffix("hello world", "world").must.equal("hello ");
+    });
+
+    it("should keep the string as it is when string don't have specified suffix", function() {
+        stripSuffix("abc", "b").must.equal("abc");
+        stripSuffix("hello world", "hello").must.equal("hello world");
+    });
+});

package/src/stripSuffix.ts

@@ -0,0 +1,16 @@
+/**
+ * Strip a suffix from a string.
+ *
+ * @param {string} from - string to strip suffix from
+ * @param {string} suffix - suffix to strip
+ */
+const stripSuffix = (from: string, suffix: string): string => {
+    if (from.endsWith(suffix)) {
+        return from.slice(0, -suffix.length);
+    }
+    return from;
+};
+
+export {
+    stripSuffix,
+};

package/typedoc.cjs

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