@ezez/utils 4.2.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezez/utils",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "repository": "https://github.com/dzek69/bottom-line.git",
   "author": "Jacek Nowacki @dzek69 <git-public@dzek.eu>",
   "license": "MIT",

package/src/index.ts

@@ -32,6 +32,7 @@ export * from "./occurrences.js";
 export * from "./omit.js";
 export * from "./pick.js";
 export * from "./pull.js";
+export * from "./race.js";
 export * from "./remove.js";
 export * from "./removeCommonProperties.js";
 export * from "./replace.js";
@@ -49,6 +50,7 @@ export * from "./set.js";
 export * from "./setImmutable.js";
 export * from "./shuffle.js";
 export * from "./sortBy.js";
+export * from "./sortByMultiple.js";
 export * from "./sortProps.js";
 export * from "./stripPrefix.js";
 export * from "./stripSuffix.js";

package/src/race.ts

@@ -0,0 +1,30 @@
+/**
+ * This function helps you timeout your promises while keeping the TS types right.
+ *
+ * @example await race(yourPromise, 1000); // resolves (or rejects) with the value of yourPromise or rejects with "Race: Timeout" message in a second
+ * @example
+ * ```
+ * type Data = { a: number };
+ * const myPromise = new Promise<Data>((resolve) => setTimeout(() => resolve({ a: 1 }), 2000));
+ * const { a } = await race(myPromise, 1000); // You're allowed to destructure the result with TS
+ * ```
+ *
+ * @param promise - Your promise
+ * @param timeout - Time in milliseconds to wait for the promise to resolve
+ * @param message - Error message to use when the timeout is reached
+ */
+const race = <T>(promise: Promise<T>, timeout: number, message = "Race: Timeout"): Promise<T> => {
+    return Promise.race([
+        promise, new Promise<T>((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(message));
+            }, timeout);
+        }),
+    ]);
+};
+
+export {
+    race,
+};
+
+// TODO unit tests

package/src/sortBy.spec.ts

@@ -53,4 +53,17 @@ describe("sortBy", () => {
             { size: 90 },
         ]);
     });
+
+    it("supports using default value", () => {
+        const sizes = [
+            { size: 30 },
+            { size: 90 },
+            {},
+        ];
+        sizes.sort(sortBy("size", true, 55)).must.eql([
+            { size: 30 },
+            {}, // size assumed to be 55
+            { size: 90 },
+        ]);
+    });
 });

package/src/sortBy.ts

@@ -1,22 +1,18 @@
+import { sortByMultiple } from "./sortByMultiple.js";
+
 /**
  * Returns a function that can be used as a callback to `.sort()` method. Returned function will sort array by given
  * property.
- * @param {string} propertyName - name of the property to sort by
- * @param {boolean} [asc=true] - should sort be ascending?
- * @param {*} defaultValue - value to use when property is not defined in one of the objects
+ *
+ * @param propertyName - name of the property to sort by
+ * @param asc - should sort be ascending?
+ * @param defaultValue - value to use when property is not defined in one of the objects
  */
-const sortBy = <T>(propertyName: keyof T, asc = true, defaultValue: unknown = null) => (a: T, b: T) => {
-    if (a[propertyName] === b[propertyName]) {
-        return 0;
-    }
-    // @ts-expect-error We don't care about types here, it's for runtime pure JS too
-
-    if ((a[propertyName] ?? defaultValue) > (b[propertyName] ?? defaultValue)) {
-        // eslint-disable-next-line @typescript-eslint/no-magic-numbers
-        return asc ? 1 : -1;
-    }
-    // eslint-disable-next-line @typescript-eslint/no-magic-numbers
-    return asc ? -1 : 1;
+const sortBy = <T extends Record<string | number | symbol, any>>( // eslint-disable-line @typescript-eslint/no-explicit-any
+    propertyName: keyof T, asc = true, defaultValue: unknown = null,
+) => (a: T, b: T) => {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions, @typescript-eslint/no-explicit-any
+    return sortByMultiple([propertyName], asc, { [propertyName]: defaultValue } as Partial<Record<keyof T, any>>)(a, b);
 };
 
 export {

package/src/sortByMultiple.spec.ts

@@ -0,0 +1,87 @@
+import { sortByMultiple } from "./sortByMultiple.js";
+
+describe("sortByMultiple", () => {
+    const items = [
+        { height: 480, bitrate: 300 },
+        { height: 720, bitrate: 100 },
+        { height: 720, bitrate: 200 },
+        { height: 720, bitrate: 50 },
+    ];
+
+    it("must sort asc", () => {
+        items.sort(sortByMultiple(["height", "bitrate"])).must.eql([
+            { height: 480, bitrate: 300 },
+            { height: 720, bitrate: 50 },
+            { height: 720, bitrate: 100 },
+            { height: 720, bitrate: 200 },
+        ]);
+    });
+
+    it("must sort desc", () => {
+        items.sort(sortByMultiple(["height", "bitrate"], false)).must.eql([
+            { height: 720, bitrate: 200 },
+            { height: 720, bitrate: 100 },
+            { height: 720, bitrate: 50 },
+            { height: 480, bitrate: 300 },
+        ]);
+    });
+
+    it("must sort with default value (example 1)", () => {
+        const itemsMissing = [
+            { height: 480, bitrate: 300 },
+            { height: 720, bitrate: 100 },
+            { height: 720 },
+            { height: 720, bitrate: 200 },
+        ];
+
+        itemsMissing.sort(sortByMultiple(["height", "bitrate"], false, { bitrate: 999 })).must.eql([
+            { height: 720 }, // bitrate assumed to be 999
+            { height: 720, bitrate: 200 },
+            { height: 720, bitrate: 100 },
+            { height: 480, bitrate: 300 },
+        ]);
+    });
+
+    it("must sort with default value (example 2)", () => {
+        const itemsMissing = [
+            { height: 480, bitrate: 300 },
+            { height: 720, bitrate: 100 },
+            { height: 720 },
+            { height: 720, bitrate: 200 },
+        ];
+
+        itemsMissing.sort(sortByMultiple(["height", "bitrate"], true, { bitrate: 1 })).must.eql([
+            { height: 480, bitrate: 300 },
+            { height: 720 }, // bitrate assumed to be 1
+            { height: 720, bitrate: 100 },
+            { height: 720, bitrate: 200 },
+        ]);
+    });
+
+    it("must sort each prop order separately", () => {
+        items.sort(sortByMultiple(["height", "bitrate"], { height: true, bitrate: false })).must.eql([
+            { height: 480, bitrate: 300 },
+            { height: 720, bitrate: 200 },
+            { height: 720, bitrate: 100 },
+            { height: 720, bitrate: 50 },
+        ]);
+    });
+
+    it("must sort each prop order separately (with missing)", () => {
+        const itemsMissing = [
+            { height: 480, bitrate: 300 },
+            { height: 720, bitrate: 100 },
+            { height: 720 },
+            { height: 720, bitrate: 200 },
+        ];
+
+        itemsMissing.sort(
+            sortByMultiple(["height", "bitrate"], { height: true, bitrate: false }, { bitrate: 150 }),
+        ).must.eql([
+            { height: 480, bitrate: 300 },
+            { height: 720, bitrate: 200 },
+            { height: 720 }, // bitrate assumed to be 150
+            { height: 720, bitrate: 100 },
+        ]);
+    });
+});

package/src/sortByMultiple.ts

@@ -0,0 +1,57 @@
+/**
+ * Returns a function that can be used as a callback to `.sort()` method. Returned function will sort array by given
+ * properties.
+ *
+ * @param propertyNames - name of the properties to sort by, in order of priority
+ * @param ascending - should sort be ascending? Pass boolean or object with boolean values for each property
+ * @param defaultValues - values to use when properties are not defined in one of the objects
+ *
+ * @example:
+ * ```
+ * const videos = [
+ *   { height: 480, bitrate: 300 },
+ *   { height: 720, bitrate: 100 },
+ *   { height: 720 },
+ *   { height: 720, bitrate: 200 },
+ * ];
+ * // Sort by height ascending, then by bitrate descending, and set default bitrate to 150
+ * itemsMissing.sort(sortByMultiple(["height", "bitrate"], { height: true, bitrate: false }, { bitrate: 150 }));
+ * // Result:
+ * [
+ *   { height: 480, bitrate: 300 },
+ *   { height: 720, bitrate: 200 },
+ *   { height: 720 }, // bitrate assumed to be 150
+ *   { height: 720, bitrate: 100 },
+ * ]
+ * ```
+ */
+const sortByMultiple = <
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    T extends Record<string | number | symbol, any>,
+    K extends (keyof T)[],
+>(
+    propertyNames: K,
+    ascending: boolean | Record<K[number], boolean> = true,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    defaultValues?: Partial<Record<K[number], any>>, // Force defaultValues to use only keys from K
+): ((a: T, b: T) => number) => (a: T, b: T) => {
+    for (const propertyName of propertyNames) {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        const asc = typeof ascending === "boolean" ? ascending : (ascending[propertyName] ?? true);
+        const aBiggerValue = asc ? 1 : -1; // eslint-disable-line @typescript-eslint/no-magic-numbers
+        const bBiggerValue = asc ? -1 : 1; // eslint-disable-line @typescript-eslint/no-magic-numbers
+
+        const aValue = a[propertyName] ?? defaultValues?.[propertyName];
+        const bValue = b[propertyName] ?? defaultValues?.[propertyName];
+
+        if (aValue !== bValue) {
+            // @ts-expect-error Too dynamic for TS
+            return (aValue > bValue ? aBiggerValue : bBiggerValue);
+        }
+    }
+    return 0;
+};
+
+export {
+    sortByMultiple,
+};