@ezez/utils 4.5.0 → 4.7.0

package/src/assertProps.spec.ts

@@ -0,0 +1,128 @@
+import must from "must"; // eslint-disable-line @typescript-eslint/no-shadow
+
+import { assertProps } from "./assertProps";
+
+describe("assertProps", () => {
+    it("should not throw for object with valid string properties", () => {
+        const obj = { id: "123", name: "John" };
+        must(() => { assertProps(obj, { id: "string", name: "string" }); }).not.throw();
+    });
+
+    it("should not throw for object with valid number properties", () => {
+        const obj = { age: 25, count: 100 };
+        must(() => { assertProps(obj, { age: "number", count: "number" }); }).not.throw();
+    });
+
+    it("should not throw for object with valid boolean properties", () => {
+        const obj = { isActive: true, isDeleted: false };
+        must(() => {
+            assertProps(obj, { isActive: "boolean", isDeleted: "boolean" });
+        }).not.throw();
+    });
+
+    it("should not throw for object with mixed property types", () => {
+        const obj = { id: "123", age: 30, isActive: true };
+        must(() => {
+            assertProps(obj, { id: "string", age: "number", isActive: "boolean" });
+        }).not.throw();
+    });
+
+    it("should throw for object with wrong property type", () => {
+        const obj = { id: 123, name: "John" };
+        must(() => {
+            assertProps(obj, { id: "string", name: "string" });
+        }).throw("Object does not match the required schema");
+    });
+
+    it("should throw for object missing required property", () => {
+        const obj = { id: "123" };
+        must(() => {
+            assertProps(obj, { id: "string", name: "string" });
+        }).throw("Object does not match the required schema");
+    });
+
+    it("should throw for null", () => {
+        must(() => {
+            assertProps(null, { id: "string" });
+        }).throw("Object does not match the required schema");
+    });
+
+    it("should throw for undefined", () => {
+        must(() => {
+            assertProps(undefined, { id: "string" });
+        }).throw("Object does not match the required schema");
+    });
+
+    it("should throw for array", () => {
+        const arr = [{ id: "123" }];
+        must(() => {
+            assertProps(arr, { id: "string" });
+        }).throw("Object does not match the required schema");
+    });
+
+    it("should throw for primitive string", () => {
+        must(() => {
+            assertProps("test", { id: "string" });
+        }).throw("Object does not match the required schema");
+    });
+
+    it("should throw for primitive number", () => {
+        must(() => {
+            assertProps(123, { id: "string" });
+        }).throw("Object does not match the required schema");
+    });
+
+    it("should throw for primitive boolean", () => {
+        must(() => {
+            assertProps(true, { id: "string" });
+        }).throw("Object does not match the required schema");
+    });
+
+    it("should not throw for empty schema", () => {
+        const obj = { id: "123", name: "John" };
+        must(() => { assertProps(obj, {}); }).not.throw();
+    });
+
+    it("should allow extra properties on the object", () => {
+        const obj = { id: "123", name: "John", extra: "value" };
+        must(() => { assertProps(obj, { id: "string", name: "string" }); }).not.throw();
+    });
+
+    it("should throw for objects with null property values", () => {
+        const obj = { id: null, name: "John" };
+        must(() => {
+            assertProps(obj, { id: "string", name: "string" });
+        }).throw("Object does not match the required schema");
+    });
+
+    it("should throw for objects with undefined property values", () => {
+        const obj = { id: undefined, name: "John" };
+        must(() => {
+            assertProps(obj, { id: "string", name: "string" });
+        }).throw("Object does not match the required schema");
+    });
+
+    it("should correctly validate boolean false value", () => {
+        const obj = { isActive: false };
+        must(() => { assertProps(obj, { isActive: "boolean" }); }).not.throw();
+    });
+
+    it("should correctly validate number zero value", () => {
+        const obj = { count: 0 };
+        must(() => { assertProps(obj, { count: "number" }); }).not.throw();
+    });
+
+    it("should correctly validate empty string value", () => {
+        const obj = { name: "" };
+        must(() => { assertProps(obj, { name: "string" }); }).not.throw();
+    });
+
+    it("should work with objects source only", async () => {
+        const source = () => null;
+        must(source).have.property("name", "source");
+
+        must(() => {
+            assertProps(source, { name: "string" });
+        }).throw("Object does not match the required schema");
+    });
+});

package/src/assertProps.ts

@@ -0,0 +1,37 @@
+import { hasProps } from "./hasProps";
+
+type AssertPropsFn = <T extends Record<string, "string" | "number" | "boolean">>(
+    obj: unknown,
+    schema: T,
+) => asserts obj is {
+    [K in keyof T]:
+    T[K] extends "string" ? string
+        : T[K] extends "number" ? number
+            : T[K] extends "boolean" ? boolean
+                : never
+};
+
+/**
+ * Asserts that an object has the specified properties with the specified types. Ideal for quick runtime type checking
+ * of API responses if you don't need a full schema validation.
+ *
+ * @example
+ * ```typescript
+ * const validated = assertProps(obj, { id: "string", age: "number" });
+ * // obj is runtime validated and type is now narrowed down to { id: string; age: number }
+ * // if the assertion fails, an error is thrown
+ * console.log(obj.id, obj.age);
+ * ```
+ */
+const assertProps: AssertPropsFn = <T extends Record<string, "string" | "number" | "boolean">>(
+    obj: unknown,
+    schema: T,
+) => {
+    if (!hasProps(obj, schema)) {
+        throw new Error("Object does not match the required schema");
+    }
+};
+
+export {
+    assertProps,
+};

package/src/cap.ts

@@ -4,7 +4,7 @@
  * @param {number} upperLimit - upper limit, inclusive
  * @param {number} [lowerLimit] - lower limit, inclusive
  */
-const cap = (value: number, upperLimit: number, lowerLimit?: number) => {
+const cap = (value: number, upperLimit: number, lowerLimit?: number): number => {
     if (lowerLimit == null) {
         return Math.min(value, upperLimit);
     }

package/src/capitalize.ts

@@ -1,12 +1,12 @@
 /**
  * Capitalize the first letter of a string.
- * @param {string} text - source string
- * @param {boolean} [restLowercase=false] - should the rest of the string be forced to lowercase?
+ * @param text - source string
+ * @param restLowercase - should the rest of the string be forced to lowercase?
  * @example capitalize("hello") // "Hello"
  * @example capitalize("hello my Friend", true) // "Hello my friend"
  * @example capitalize("hello my Friend", false) // "Hello my Friend"
  */
-const capitalize = (text: string, restLowercase = false) => {
+const capitalize = (text: string, restLowercase = false): string => {
     const rest = restLowercase ? text.slice(1).toLowerCase() : text.slice(1);
     return text.charAt(0).toUpperCase() + rest;
 };

package/src/compareArrays.ts

@@ -9,12 +9,11 @@ import { unique } from "./unique.js";
  * 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 compareArrays = <T>(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 };
+    return { onlyA, onlyB, both };
 };
 
 export {

package/src/deserialize.spec.ts

@@ -1,3 +1,5 @@
+import must from "must"; // eslint-disable-line @typescript-eslint/no-shadow
+
 import type { CustomDeserializers } from "./deserialize";
 
 import { deserialize } from "./deserialize";
@@ -5,7 +7,6 @@ import { deserialize } from "./deserialize";
 class Person {
     public name: string;
 
-    // eslint-disable-next-line @typescript-eslint/no-shadow
     public constructor(name: string) {
         this.name = name;
     }

package/src/ensureError.ts

@@ -10,11 +10,15 @@
  * @param {*} e - value to check
  * @returns Error - original error or new Error instance
  */
-const ensureError = (e: unknown) => {
+const ensureError = (e: unknown): Error => {
     if (e instanceof Error) {
         return e;
     }
-    return new Error("Expected error instance, got something else: " + String(e));
+
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    return new Error("Expected error instance, got something else: " + String(e), {
+        cause: e,
+    });
 };
 
 export {

package/src/ensurePrefix.ts

@@ -6,7 +6,7 @@
  * @param {string} string - string to add prefix to
  * @param {string} prefix - prefix to add
  */
-const ensurePrefix = (string: string, prefix: string) => {
+const ensurePrefix = (string: string, prefix: string): string => {
     if (string.startsWith(prefix)) {
         return string;
     }

package/src/ensureSuffix.ts

@@ -6,7 +6,7 @@
  * @param {string} string - string to add suffix to
  * @param {string} suffix - suffix to add
  */
-const ensureSuffix = (string: string, suffix: string) => {
+const ensureSuffix = (string: string, suffix: string): string => {
     if (string.endsWith(suffix)) {
         return string;
     }

package/src/escapeRegExp.ts

@@ -9,7 +9,7 @@
  * regex.test(badName); // true
  * ```
  */
-const escapeRegExp = (string: string) => {
+const escapeRegExp = (string: string): string => {
     return string.replace(/[/\-\\^$*+?.()|[\]{}]/gu, "\\$&");
 };
 

package/src/formatDate.ts

@@ -8,10 +8,15 @@ import { ensureDate } from "./ensureDate.js";
  *
  * Important: this is work in progress. All locale-based values are not supported yet. Formats that heavily depend on
  * locale won't ever be supported.
+ *
+ * @example
+ * ```typescript
+ * formatDate(Date.now(), "%Y-%m-%d %H:%M:%S"); // ie: "2024-06-26 14:23:45"
+ * ```
  */
 const formatDate = (date: Date | number, format: string, locale = "en-US"): string => { // eslint-disable-line max-lines-per-function
     const d = ensureDate(date);
-    return format.replace(/%([%a-zA-Z])/gu, (_, c) => {
+    return format.replace(/%([%a-zA-Z])/gu, (_, c: string) => {
         switch (c) {
             case "%": return "%";
             // Day
@@ -64,7 +69,7 @@ const formatDate = (date: Date | number, format: string, locale = "en-US"): stri
             case "n": return "\n";
             case "t": return "\t";
         }
-        return c as string;
+        return c;
     });
 };
 

package/src/get.spec.ts

@@ -54,7 +54,6 @@ describe("get", () => {
 
     it("doesn't parse string as js code, behaves NOT like lodash", () => {
         // Lodash intention-guessing example, inconsistency detected
-        // eslint-disable-next-line @typescript-eslint/no-shadow
         const name = get(testObject, "product[name]");
         (name === undefined).must.be.true();
 

package/src/getMultiple.ts

@@ -29,7 +29,6 @@ const DEFAULT = {};
  * @returns {*} - found value or default value
  */
 const getMultiple = (source: Source, defaultValue: unknown, ...paths: (string | string[])[]): unknown => {
-    // eslint-disable-next-line @typescript-eslint/no-shadow
     const length = paths.length;
     for (let i = 0; i < length; i++) {
         const properties = paths[i]!;

package/src/hasProps.spec.ts

@@ -0,0 +1,122 @@
+import must from "must"; // eslint-disable-line @typescript-eslint/no-shadow
+
+import { hasProps } from "./hasProps";
+
+describe("hasProps", () => {
+    it("should return true for object with valid string properties", () => {
+        const obj = { id: "123", name: "John" };
+        const result = hasProps(obj, { id: "string", name: "string" });
+        must(result).be.true();
+    });
+
+    it("should return true for object with valid number properties", () => {
+        const obj = { age: 25, count: 100 };
+        const result = hasProps(obj, { age: "number", count: "number" });
+        must(result).be.true();
+    });
+
+    it("should return true for object with valid boolean properties", () => {
+        const obj = { isActive: true, isDeleted: false };
+        const result = hasProps(obj, { isActive: "boolean", isDeleted: "boolean" });
+        must(result).be.true();
+    });
+
+    it("should return true for object with mixed property types", () => {
+        const obj = { id: "123", age: 30, isActive: true };
+        const result = hasProps(obj, { id: "string", age: "number", isActive: "boolean" });
+        must(result).be.true();
+    });
+
+    it("should return false for object with wrong property type", () => {
+        const obj = { id: 123, name: "John" };
+        const result = hasProps(obj, { id: "string", name: "string" });
+        must(result).be.false();
+    });
+
+    it("should return false for object missing required property", () => {
+        const obj = { id: "123" };
+        const result = hasProps(obj, { id: "string", name: "string" });
+        must(result).be.false();
+    });
+
+    it("should return false for null", () => {
+        const result = hasProps(null, { id: "string" });
+        must(result).be.false();
+    });
+
+    it("should return false for undefined", () => {
+        const result = hasProps(undefined, { id: "string" });
+        must(result).be.false();
+    });
+
+    it("should return false for array", () => {
+        const arr = [{ id: "123" }];
+        const result = hasProps(arr, { id: "string" });
+        must(result).be.false();
+    });
+
+    it("should return false for primitive string", () => {
+        const result = hasProps("test", { id: "string" });
+        must(result).be.false();
+    });
+
+    it("should return false for primitive number", () => {
+        const result = hasProps(123, { id: "string" });
+        must(result).be.false();
+    });
+
+    it("should return false for primitive boolean", () => {
+        const result = hasProps(true, { id: "string" });
+        must(result).be.false();
+    });
+
+    it("should return true for empty schema", () => {
+        const obj = { id: "123", name: "John" };
+        const result = hasProps(obj, {});
+        must(result).be.true();
+    });
+
+    it("should allow extra properties on the object", () => {
+        const obj = { id: "123", name: "John", extra: "value" };
+        const result = hasProps(obj, { id: "string", name: "string" });
+        must(result).be.true();
+    });
+
+    it("should handle objects with null property values", () => {
+        const obj = { id: null, name: "John" };
+        const result = hasProps(obj, { id: "string", name: "string" });
+        must(result).be.false();
+    });
+
+    it("should handle objects with undefined property values", () => {
+        const obj = { id: undefined, name: "John" };
+        const result = hasProps(obj, { id: "string", name: "string" });
+        must(result).be.false();
+    });
+
+    it("should correctly validate boolean false value", () => {
+        const obj = { isActive: false };
+        const result = hasProps(obj, { isActive: "boolean" });
+        must(result).be.true();
+    });
+
+    it("should correctly validate number zero value", () => {
+        const obj = { count: 0 };
+        const result = hasProps(obj, { count: "number" });
+        must(result).be.true();
+    });
+
+    it("should correctly validate empty string value", () => {
+        const obj = { name: "" };
+        const result = hasProps(obj, { name: "string" });
+        must(result).be.true();
+    });
+
+    it("should work with objects source only", async () => {
+        const source = () => null;
+        must(source).have.property("name", "source");
+
+        const result = hasProps(source, { name: "string" });
+        must(result).be.false();
+    });
+});

package/src/hasProps.ts

@@ -0,0 +1,36 @@
+/**
+ * Check if an object has the specified properties with the specified types. Ideal for quick runtime type checking of
+ * API responses if you don't need a full schema validation.
+ *
+ * @example
+ * ```typescript
+ * const validated = hasProps(obj, { id: "string", age: "number" });
+ * if (validated) {
+ *     // obj is runtime validated and type is now narrowed down to { id: string; age: number }
+ *     console.log(obj.id, obj.age);
+ * }
+ * ```
+ */
+const hasProps = <
+    T extends Record<string, "string" | "number" | "boolean">,
+>(
+    obj: unknown,
+    schema: T,
+): obj is {
+    [K in keyof T]:
+    T[K] extends "string" ? string
+        : T[K] extends "number" ? number
+            : T[K] extends "boolean" ? boolean
+                : never
+} => {
+    if (typeof obj !== "object" || obj === null || Array.isArray(obj)) { return false; }
+    for (const [key, type] of Object.entries(schema)) {
+        // eslint-disable-next-line valid-typeof
+        if (typeof (obj as { [key]: unknown })[key] !== type) { return false; }
+    }
+    return true;
+};
+
+export {
+    hasProps,
+};

package/src/ignore.spec.ts

@@ -0,0 +1,80 @@
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import must from "must";
+
+// @ts-ignore
+import createSpy from "../test/createSpy";
+import { ignore } from "./ignore";
+import { wait } from "./wait";
+
+const syncCrashingFunction = createSpy(() => {
+    throw new Error("Sync function crashed");
+});
+
+const promiseTypedSyncCrashingFunction = createSpy((): Promise<void> => {
+    throw new Error("Promise typed sync function crashed");
+});
+
+const asyncCrashingFunction = createSpy(async () => {
+    throw new Error("Async function crashed");
+});
+
+const asyncCrashingFunctionSlow = createSpy(async () => {
+    await wait(500);
+    throw new Error("Async function crashed");
+});
+
+const get5 = createSpy(() => 5);
+
+describe("ignore", () => {
+    beforeEach(() => {
+        syncCrashingFunction.__spy.reset();
+        promiseTypedSyncCrashingFunction.__spy.reset();
+        asyncCrashingFunction.__spy.reset();
+        asyncCrashingFunctionSlow.__spy.reset();
+        get5.__spy.reset();
+    });
+
+    it("it should not crash on sync function crash", async () => {
+        ignore(syncCrashingFunction);
+        ignore(promiseTypedSyncCrashingFunction);
+        // ^ technically this is also a sync crash
+    });
+
+    it("it should not crash on async function crash", async () => {
+        ignore(asyncCrashingFunction);
+    });
+
+    it("it should not wait for async function", async () => {
+        const now = Date.now();
+        ignore(asyncCrashingFunctionSlow);
+        const after = Date.now();
+        if (after - now > 100) {
+            throw new Error("Took too long, it waited for the async function");
+        }
+    });
+
+    it("should not return a value", async () => {
+        // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+        const res = ignore(get5);
+        must(res).be.undefined();
+    });
+
+    it("actually calls the function", async () => {
+        must(syncCrashingFunction.__spy.calls.length).be.equal(0);
+        must(promiseTypedSyncCrashingFunction.__spy.calls.length).be.equal(0);
+        must(asyncCrashingFunction.__spy.calls.length).be.equal(0);
+        must(get5.__spy.calls.length).be.equal(0);
+
+        ignore(syncCrashingFunction);
+        must(syncCrashingFunction.__spy.calls.length).be.equal(1);
+
+        ignore(promiseTypedSyncCrashingFunction);
+        must(promiseTypedSyncCrashingFunction.__spy.calls.length).be.equal(1);
+
+        ignore(asyncCrashingFunction);
+        must(asyncCrashingFunction.__spy.calls.length).be.equal(1);
+
+        ignore(get5);
+        must(get5.__spy.calls.length).be.equal(1);
+    });
+});

package/src/ignore.ts

@@ -0,0 +1,38 @@
+/**
+ * A function that executes a callback and ignores it completely, if it throws an error, returns any value, rejects
+ * a promise - it will be all ignored. It will attach a catch handler to any returned promise to avoid unhandled
+ * rejections.
+ *
+ * Use it whenever you want to call a function, but you are not interested in its result or failure.
+ *
+ * @example
+ * ```javascript
+ * import { trackPageVisit } from "analytics-service";
+ *
+ * function onButtonClick() {
+ *     ignore(() => trackPageVisit("button-click"));
+ *     // ^ prevent uncaught errors or unhandled promise rejections from trackPageVisit
+ * }
+ * Promise.resolve(5).then(ignore(trackPageVisit)).then((value) => {
+ *   console.log(value); // 5, won't ever crash due to errors in trackPageVisit
+ * });
+ * ```
+ * @param callback
+ */
+const ignore = (callback: () => unknown): undefined => {
+    try {
+        // eslint-disable-next-line callback-return
+        const p = callback();
+        if (p && typeof p === "object"
+            && "then" in p && typeof p.then === "function"
+            && "catch" in p && typeof p.catch === "function") {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+            p.catch(() => null);
+        }
+    }
+    catch {}
+};
+
+export {
+    ignore,
+};

package/src/index.ts

@@ -17,6 +17,7 @@ export * from "./escapeRegExp.js";
 export * from "./formatDate.js";
 export * from "./get.js";
 export * from "./getMultiple.js";
+export * from "./ignore.js";
 export * from "./insertSeparator.js";
 export * from "./isEmpty.js";
 export * from "./isNumericString.js";

package/src/isEmpty.ts

@@ -1,11 +1,3 @@
-interface ObjectWithLength {
-    length: number;
-}
-
-interface ObjectWithSize {
-    size: number;
-}
-
 /**
  * Returns true if passed argument seems to be empty.
  * Nil values are empty.
@@ -15,7 +7,7 @@ interface ObjectWithSize {
  * 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
+ * @param obj - source value
  * @example isEmpty({}) // true
  * @example isEmpty(100) // throws
  * @example isEmpty([]) // true
@@ -23,9 +15,11 @@ interface ObjectWithSize {
  * @example isEmpty({ length: 5 }) // false
  * @example isEmpty({ length: 0 }) // true
  * @example isEmpty({ size: 0 }) // true
- * @returns {boolean} - is value considered empty
+ * @returns is value considered empty
+ *
+ * @deprecated This function is not needed in a modern, type-safe code and is encouraging bad practices in general.
  */
-const isEmpty = (obj: unknown) => {
+const isEmpty = (obj: unknown): boolean => {
     if (typeof obj === "string") {
         return !obj.length;
     }
@@ -38,11 +32,11 @@ const isEmpty = (obj: unknown) => {
     if (Array.isArray(obj)) {
         return !Object.keys(obj).length;
     }
-    if ("length" in obj) {
-        return !(obj as ObjectWithLength).length;
+    if ("length" in obj && typeof obj.length === "number") {
+        return !(obj).length;
     }
-    if ("size" in obj) {
-        return !(obj as ObjectWithSize).size;
+    if ("size" in obj && typeof obj.size === "number") {
+        return !(obj).size;
     }
     return !Object.keys(obj).length;
 };

package/src/isNumericString.ts

@@ -17,7 +17,7 @@ const NOT_FOUND = -1;
  * @param {boolean} [options.allowInfinity=false] - Allow Infinity and -Infinity (casing matters)
  * @param {boolean} [options.allowNaN=false] - Allow NaN (casing matters)
  */
-const isNumericString = (string: string, options: Options = {}) => { // eslint-disable-line max-statements, max-lines-per-function
+const isNumericString = (string: string, options: Options = {}): boolean => { // eslint-disable-line max-statements, max-lines-per-function
     if (typeof string !== "string") {
         throw new TypeError("Expected a string");
     }