@ezez/utils 4.3.0 → 4.5.0

package/src/serializeToBuffer/unserializeFromBuffer.spec.ts

@@ -0,0 +1,63 @@
+import must from "must"; // eslint-disable-line @typescript-eslint/no-shadow
+
+import { unserializeFromBuffer } from "./unserializeFromBuffer";
+
+const unserialize = unserializeFromBuffer.bind(null, Buffer, []);
+
+describe("unserialize", () => {
+    it("unserializes basic string", async () => {
+        must(unserialize(Buffer.from([0x34, 0x66, 0x00, 0x74, 0x65, 0x73, 0x74, 0x00]))).eql(["test"]);
+    });
+
+    it("unserializes multiple strings", async () => {
+        must(unserialize(Buffer.from([
+            0x34, 0x66, 0x00, 0x74, 0x65, 0x73, 0x74, 0x00,
+            0x34, 0x66, 0x00, 0x74, 0x65, 0x73, 0x74, 0x00,
+        ]))).eql(["test", "test"]);
+    });
+
+    it("unserializes buffer", async () => {
+        const result = unserialize(Buffer.from([0x34, 0x74, 0x00, 0x74, 0x65, 0x73, 0x74, 0x00]));
+        must(result.length).equal(1);
+        must(result[0]).instanceof(Buffer);
+        must((result[0] as Buffer).toString()).equal("test");
+    });
+
+    it("unserializes both buffer and string", async () => {
+        const result = unserialize(Buffer.from([
+            0x34, 0x74, 0x00, 0x74, 0x65, 0x73, 0x74, 0x00,
+            0x34, 0x66, 0x00, 0x74, 0x65, 0x73, 0x74, 0x00,
+        ]));
+
+        must(result.length).equal(2);
+
+        must(result[0]).instanceof(Buffer);
+        must((result[0] as Buffer).toString()).equal("test");
+
+        must(result[1]).equal("test");
+    });
+
+    it("unserializes JSON-looking string as string", async () => {
+        must(unserialize(
+            Buffer.from([0x36, 0x66, 0x00, 0x22, 0x74, 0x65, 0x73, 0x74, 0x22, 0x00]),
+        )).eql([`"test"`]);
+    });
+
+    it("unserializes JSON-serialized string as string", async () => {
+        must(unserialize(Buffer.from([
+            0x38, 0x66, 0x00, 0x22, 0x73, 0x3a, 0x74, 0x65, 0x73, 0x74, 0x22, 0x00,
+        ]))).eql([`"s:test"`]);
+    });
+
+    it("unserializes JSON-serialized json as string", async () => {
+        must(unserialize(Buffer.from([
+            0x38, 0x6a, 0x00, 0x22, 0x73, 0x3a, 0x74, 0x65, 0x73, 0x74, 0x22, 0x00,
+        ]))).eql(["test"]);
+    });
+
+    it("unserializes number as number", async () => {
+        must(unserialize(Buffer.from([
+            0x35, 0x6a, 0x00, 0x22, 0x6e, 0x3a, 0x31, 0x22, 0x00,
+        ]))).eql([1]);
+    });
+});

package/src/serializeToBuffer/unserializeFromBuffer.ts

@@ -0,0 +1,75 @@
+import { deserialize } from "../deserialize.js";
+
+import { BINARY_MARK_BIN, BINARY_MARK_MAP, BINARY_MARK_STRING } from "./const.js";
+
+const MAX_DATA_PARTS = 4;
+
+const NOT_FOUND = -1;
+const LAST_CHAR = -1;
+
+type DeserializeArgs = Parameters<typeof deserialize> extends [any, ...infer Rest] ? Rest : never; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+/**
+ * Unserialize data from a Buffer serialized with {@link serializeToBuffer}, useful when working with web sockets or
+ * other binary protocols. Make sure to understand how {@link deserialize} works before using this function.
+ * @param BufferImplementation - Buffer implementation, in browsers use `buffer` npm package
+ * and import it from `buffer/`, in Node.js simply pass `Buffer`.
+ * @param deserializeArgs - [customDeserializers] - optional arguments if you need to unserialize custom data types,
+ * @param rawData - Buffer to unserialize
+ * @returns unserialized data
+ */
+const unserializeFromBuffer = <RT extends any[] = unknown[]>( // eslint-disable-line @typescript-eslint/no-explicit-any,max-statements
+    BufferImplementation: typeof Buffer, deserializeArgs: DeserializeArgs, rawData: Buffer | Uint8Array,
+): RT => {
+    const intData: Uint8Array = rawData instanceof Uint8Array ? rawData : new Uint8Array(rawData);
+
+    if (intData.length === 0) {
+        throw new Error("No data to unserialize");
+    }
+
+    let startPoint = 0;
+    const result = [];
+
+    let i = 0;
+    while (i++ < MAX_DATA_PARTS) {
+        const dataSplitPoint = intData.indexOf(0, startPoint); // find null
+        if (dataSplitPoint === NOT_FOUND) { // no null found = no data
+            break;
+        }
+
+        const lengthBytes = BufferImplementation.from(intData.slice(startPoint, dataSplitPoint)).toString("utf8");
+        const binaryMark = lengthBytes.slice(LAST_CHAR) as keyof typeof BINARY_MARK_MAP;
+        if (!Object.keys(BINARY_MARK_MAP).includes(binaryMark)) {
+            throw new Error(`Invalid binary mark: ${binaryMark}`);
+        }
+
+        const len = Number(lengthBytes.slice(0, lengthBytes.length - 1));
+
+        const dataStringFrom = dataSplitPoint + 1;
+        const dataStringTo = dataStringFrom + len;
+        const dataBytes = intData.slice(dataStringFrom, dataStringTo);
+
+        if (binaryMark === BINARY_MARK_BIN) {
+            result.push(dataBytes);
+        }
+        else if (binaryMark === BINARY_MARK_STRING) {
+            const stringData = BufferImplementation.from(dataBytes).toString("utf8");
+            result.push(stringData);
+        }
+        else {
+            const stringData = BufferImplementation.from(dataBytes).toString("utf8");
+            const jsonData = deserialize(stringData, ...deserializeArgs);
+            result.push(jsonData);
+        }
+
+        startPoint = dataStringTo + 1; // skip separating null
+    }
+
+    if (result.length === 0) {
+        throw new Error("No data found (no split points)");
+    }
+
+    return result as RT;
+};
+
+export { unserializeFromBuffer, unserializeFromBuffer as deserializeFromBuffer };

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,
+};