@ezez/utils 2.1.0 → 4.0.0

package/src/serialize.spec.ts

@@ -80,4 +80,46 @@ describe("serialize", () => {
 
         must(serialize(a)).equal(serialize(b));
     });
+
+    it("allows serializing dates and other objects containing .toJSON", async () => {
+        const date = new Date(1714390008941);
+        must(serialize(date, {
+            D: (value) => {
+                if (value instanceof Date) {
+                    return String(value.getTime());
+                }
+                return null;
+            },
+        })).equal(`"D:1714390008941"`);
+    });
+
+    it("should avoid excessive calls to custom serializers", async () => {
+        const customSerializers: CustomSerializers = {
+            p: (value) => {
+                // console.log("Called with", typeof value, value);
+                if (value instanceof Person) {
+                    return value.name;
+                }
+                return null;
+            },
+        };
+
+        const p1 = new Person("John");
+        const spy = jest.spyOn(customSerializers, "p");
+
+        serialize({
+            a: [p1],
+            b: 1,
+            c: {
+                d: true,
+                e: p1,
+            },
+        }, customSerializers);
+        expect(spy).toHaveBeenCalledTimes(4);
+    });
+
+    it("should not crash on unknown instances but serialize as plain object", async () => {
+        const p1 = new Person("John");
+        must(serialize(p1)).equal(`{"name":"s:John"}`);
+    });
 });

package/src/serialize.ts

@@ -1,4 +1,7 @@
 import { sortProps } from "./sortProps.js";
+import { replaceDeepByFn } from "./replaceDeepByFn.js";
+import { isPlainObject } from "./isPlainObject.js";
+import { DataWrapper } from "./utils/utils.js";
 
 type CustomSerializers = {
     [key: string]: (data: unknown) => (string | null);
@@ -33,6 +36,32 @@ type Options = {
  * @param options - options
  */
 const serialize = (data: unknown, customSerializers?: CustomSerializers, options?: Options) => { // eslint-disable-line max-lines-per-function,max-len
+    const sourceData = Object.keys(customSerializers ?? {}).length
+        ? replaceDeepByFn(
+            data,
+            value => {
+                if (["string", "number", "bigint", "undefined", "boolean"].includes(typeof value)) {
+                    return false;
+                }
+                if (value === null || Array.isArray(value)) {
+                    return false;
+                }
+                if (isPlainObject(value)) {
+                    return false;
+                }
+
+                const serializerKeys = Object.keys(customSerializers ?? {});
+                for (const key of serializerKeys) {
+                    const serialized = customSerializers![key]!(value);
+                    if (typeof serialized === "string") {
+                        return true;
+                    }
+                }
+                return false;
+            },
+            value => new DataWrapper(value),
+        )
+        : data;
     const replacer = (_key: string, value: unknown) => { // eslint-disable-line max-statements
         if (typeof value === "string") {
             return `s:${value}`;
@@ -52,12 +81,22 @@ const serialize = (data: unknown, customSerializers?: CustomSerializers, options
         if (value === null) {
             return "l:";
         }
+        if (Array.isArray(value)) {
+            return value as unknown[];
+        }
+        if (isPlainObject(value)) {
+            return value;
+        }
         const serializerKeys = Object.keys(customSerializers ?? {});
         for (const key of serializerKeys) {
-            const serialized = customSerializers![key]!(value);
+            const serialized = customSerializers![key]!(value instanceof DataWrapper ? value.data : value);
             if (typeof serialized === "string") {
                 return `${key}:${serialized}`;
             }
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (serialized !== null) {
+                throw new Error(`Custom serializer for key ${key} returned a non-string value: ${String(serialized)}`);
+            }
         }
         if (typeof value === "object") {
             return value;
@@ -67,35 +106,43 @@ const serialize = (data: unknown, customSerializers?: CustomSerializers, options
     };
 
     if (
-        data == null
-        || typeof data === "string"
-        || typeof data === "number"
-        || typeof data === "bigint"
-        || typeof data === "undefined"
-        || typeof data === "boolean"
-        || Array.isArray(data)
+        sourceData == null
+        || typeof sourceData === "string"
+        || typeof sourceData === "number"
+        || typeof sourceData === "bigint"
+        || typeof sourceData === "undefined"
+        || typeof sourceData === "boolean"
+        || Array.isArray(sourceData)
     ) {
-        return JSON.stringify(data, replacer);
+        return JSON.stringify(sourceData, replacer);
     }
 
-    const serializerKeysGlobal = Object.keys(customSerializers ?? {});
-    for (const key of serializerKeysGlobal) {
-        const serialized = customSerializers![key]!(data);
-        if (typeof serialized === "string") {
-            return `"${key}:${serialized}"`;
+    if (!isPlainObject(sourceData)) {
+        const serializerKeysGlobal = Object.keys(customSerializers ?? {});
+        for (const key of serializerKeysGlobal) {
+            const serialized = customSerializers![key]!(
+                sourceData instanceof DataWrapper ? sourceData.data : sourceData,
+            );
+            if (typeof serialized === "string") {
+                return `"${key}:${serialized}"`;
+            }
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (serialized !== null) {
+                throw new Error(`Custom serializer for key ${key} returned a non-string value: ${String(serialized)}`);
+            }
         }
     }
 
-    if (typeof data === "object") {
+    if (typeof sourceData === "object") {
         return JSON.stringify(
             options?.sortProps === false
-                ? data
-                : sortProps(data as Record<string, unknown>),
+                ? sourceData
+                : sortProps(sourceData as Record<string, unknown>),
             replacer,
         );
     }
 
-    throw new Error(`Unsupported data type: ${typeof data}`);
+    throw new Error(`Unsupported data type: ${typeof sourceData}`);
 };
 
 export type { CustomSerializers };

package/src/shuffle.spec.ts

@@ -0,0 +1,39 @@
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import must from "must";
+
+import { shuffle } from "./shuffle";
+
+describe("shuffle", () => {
+    it("should shuffle the array", async () => {
+        for (let i = 0; i < 100; i++) {
+            {
+                const elements = [1, 2, 3];
+
+                const result = shuffle(elements);
+                must(result).have.length(3);
+
+                for (const item of result) {
+                    must(elements).include(item);
+                }
+                must([...new Set(result)]).have.length(3);
+            }
+        }
+    });
+
+    it("should shuffle the array with duplicates", async () => {
+        for (let i = 0; i < 100; i++) {
+            {
+                const elements = [1, 2, 2, 3];
+
+                const result = shuffle(elements);
+                must(result).have.length(4);
+
+                for (const item of result) {
+                    must(elements).include(item);
+                }
+                must([...new Set(result)]).have.length(3);
+                must(result.filter(r => r === 2).length).equal(2);
+            }
+        }
+    });
+});

package/src/shuffle.ts

@@ -0,0 +1,13 @@
+import { samples } from "./samples.js";
+
+/**
+ * Shuffles an array, returning a new array.
+ * @param array source array
+ */
+const shuffle = <T>(array: T[]): T[] => {
+    return samples(array, array.length, true);
+};
+
+export {
+    shuffle,
+};

package/src/toggle.spec.ts

@@ -0,0 +1,43 @@
+import { toggle } from "./toggle.js";
+
+describe("toggle", () => {
+    it("adds the value if it doesn't exist", async () => {
+        must(toggle([1], 2)).eql([1, 2]);
+    });
+
+    it("removes the value if it exists", async () => {
+        must(toggle([1, 2], 2)).eql([1]);
+    });
+
+    it("removes only one occurrence", async () => {
+        must(toggle([1, 2, 2], 2)).eql([1, 2]);
+    });
+
+    it("modifies the original array when adding", async () => {
+        const array = [1];
+        toggle(array, 2);
+        must(array).eql([1, 2]);
+    });
+
+    it("modifies the original array when removing", async () => {
+        const array = [1, 2];
+        toggle(array, 2);
+        must(array).eql([1]);
+    });
+
+    it("returns the original array", async () => {
+        const array = [1];
+        // adding
+        must(toggle(array, 2)).equal(array);
+        // removing
+        must(toggle(array, 2)).equal(array);
+    });
+
+    it("adds NaN values correctly", async () => {
+        must(toggle([1], NaN)).eql([1, NaN]);
+    });
+
+    it("removes NaN values correctly", async () => {
+        must(toggle([1, NaN], NaN)).eql([1]);
+    });
+});

package/src/toggle.ts

@@ -0,0 +1,22 @@
+/**
+ * Toggles an item in an array. If it exists, remove it. If it doesn't exist, add it.
+ * If the array contains the given value more than once, this function will remove only one occurrence.
+ *
+ * @param array - source array
+ * @param item - item to toggle
+ */
+const toggle = <T>(array: T[], item: T): T[] => {
+    const index = array.findIndex((i) => Object.is(i, item));
+    // eslint-disable-next-line @typescript-eslint/no-magic-numbers
+    if (index === -1) {
+        array.push(item);
+    }
+    else {
+        array.splice(index, 1);
+    }
+    return array;
+};
+
+export {
+    toggle,
+};

package/src/trim.spec.ts

@@ -0,0 +1,22 @@
+import { trim } from "./trim";
+
+describe("trim", () => {
+    it("should trim single character from both sides of the string", async () => {
+        must(trim("aaacataaa", "a")).equal("cat");
+        must(trim("abacteria", "a")).equal("bacteri");
+        must(trim("abc", "a")).equal("bc");
+        must(trim("abc", "c")).equal("ab");
+        must(trim("aajjja", "a")).equal("jjj");
+    });
+
+    it("should trim multiple characters as a whole", async () => {
+        must(trim("abopopab", "ab")).equal("opop");
+        must(trim("atitleb", "ab")).equal("atitleb");
+        must(trim("abtitleab", "ab")).equal("title");
+    });
+
+    it("can trim into empty string", async () => {
+        must(trim("abc", "abc")).equal("");
+        must(trim("a", "a")).equal("");
+    });
+});

package/src/trim.ts

@@ -0,0 +1,23 @@
+import { trimStart } from "./trimStart.js";
+import { trimEnd } from "./trimEnd.js";
+
+/**
+ * Removes given characters from both sides of the string.
+ * If you want to remove from one side of the string see {@link trimStart} and {@link trimEnd}.
+ *
+ * @param source - Source string.
+ * @param characters - Characters to remove, taken as a whole.
+ *
+ * @example
+ * trim("abcb", "ab"); // "cb"
+ * trim("!aaa!", "!"); // "aaa"
+ * trim("!aaa!!!", "!"); // "aaa"
+ * trim("!aaa!!!", "!!!"); // "!aaa"
+ */
+const trim = (source: string, characters: string) => {
+    return trimStart(trimEnd(source, characters), characters);
+};
+
+export {
+    trim,
+};

package/src/trimEnd.spec.ts

@@ -0,0 +1,20 @@
+import { trimEnd } from "./trimEnd";
+
+describe("trimEnd", () => {
+    it("should trim single character from the end of the string", async () => {
+        must(trimEnd("abc?", "?")).equal("abc");
+        must(trimEnd("a? b?c???", "?")).equal("a? b?c");
+    });
+
+    it("should trim multiple characters as a whole", async () => {
+        must(trimEnd("abc", "bc")).equal("a");
+
+        must(trimEnd("abcc", "bc")).equal("abcc");
+        must(trimEnd("abcb", "bc")).equal("abcb");
+    });
+
+    it("can trim into empty string", async () => {
+        must(trimEnd("abc", "abc")).equal("");
+        must(trimEnd("a", "a")).equal("");
+    });
+});

package/src/trimEnd.ts

@@ -0,0 +1,22 @@
+/**
+ * Removes given characters from the end of the string.
+ * See also: {@link trim} and {@link trimStart}.
+ *
+ * @param source - Source string.
+ * @param characters - Characters to remove, taken as a whole.
+ *
+ * @example
+ * trimEnd("abcxzyz", "yz"); // "abcxz"
+ * trimEnd("!aaa!!", "!"); // "!aaa"
+ */
+const trimEnd = (source: string, characters: string) => {
+    let s = source;
+    while (s.endsWith(characters)) {
+        s = s.slice(0, -characters.length);
+    }
+    return s;
+};
+
+export {
+    trimEnd,
+};

package/src/trimStart.spec.ts

@@ -0,0 +1,20 @@
+import { trimStart } from "./trimStart";
+
+describe("trimStart", () => {
+    it("should trim single character from the start of the string", async () => {
+        must(trimStart("?abc", "?")).equal("abc");
+        must(trimStart("aaabc", "a")).equal("bc");
+    });
+
+    it("should trim multiple characters as a whole", async () => {
+        must(trimStart("abc", "ab")).equal("c");
+
+        must(trimStart("aabcc", "ab")).equal("aabcc");
+        must(trimStart("babcb", "ab")).equal("babcb");
+    });
+
+    it("should trim into empty string if needed", async () => {
+        must(trimStart("abc", "abc")).equal("");
+        must(trimStart("aaa", "a")).equal("");
+    });
+});

package/src/trimStart.ts

@@ -0,0 +1,22 @@
+/**
+ * Removes given characters from the start of the string.
+ * See also: {@link trim} and {@link trimEnd}.
+ *
+ * @param source - Source string.
+ * @param characters - Characters to remove, taken as a whole.
+ *
+ * @example
+ * trimStart("abbcb", "ab"); // "bcb"
+ * trimStart("!!aaa!", "!"); // "aaa!"
+ */
+const trimStart = (source: string, characters: string) => {
+    let s = source;
+    while (s.startsWith(characters)) {
+        s = s.slice(characters.length);
+    }
+    return s;
+};
+
+export {
+    trimStart,
+};

package/src/utils/utils.ts

@@ -0,0 +1,11 @@
+class DataWrapper<T> {
+    public data: T;
+
+    public constructor(data: T) {
+        this.data = data;
+    }
+}
+
+export {
+    DataWrapper,
+};

package/src/waitFor.spec.ts

@@ -0,0 +1,141 @@
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import must from "must";
+
+import createSpy from "../test/createSpy";
+
+import { waitFor } from "./waitFor";
+
+describe("waitFor", () => {
+    it("calls function multiple times until it returns truthy value", async () => {
+        let calls = 0;
+        const spy = createSpy(() => {
+            calls++;
+            return calls === 3;
+        });
+
+        const start = Date.now();
+        await waitFor(spy);
+
+        must(calls).equal(3);
+        // waited for 3 tries, should be 100ms (0 for first try) in total
+        must(Date.now() - start).be.gte(100);
+    });
+
+    it("returns value if check passes", async () => {
+        const x = await waitFor(() => 5);
+        must(x).equal(5);
+    });
+
+    it("returns value if check passes in non-first try", async () => {
+        let calls = 0;
+        const spy = createSpy(() => {
+            calls++;
+            return calls === 3;
+        });
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const res = await waitFor(spy);
+        must(res).equal(true);
+    });
+
+    it("allows to adjust interval", async () => {
+        let calls = 0;
+        const spy = createSpy(() => {
+            calls++;
+            return calls === 3;
+        });
+
+        const start = Date.now();
+        await waitFor(spy, { interval: 150 });
+
+        must(calls).equal(3);
+        must(Date.now() - start).be.gte(300);
+    });
+
+    it("time outs after given time", async () => {
+        // eslint-disable-next-line @typescript-eslint/await-thenable
+        await must(waitFor(() => null, {
+            interval: 40,
+            timeout: 300,
+        })).reject.to.instanceOf(Error);
+    });
+
+    it("time outs after given amout of retries", async () => {
+        const spy = createSpy(() => false);
+
+        // eslint-disable-next-line @typescript-eslint/await-thenable
+        await must(waitFor(spy, {
+            interval: 40,
+            maxTries: 3,
+        })).reject.to.instanceOf(Error);
+
+        must(spy.__spy.calls).have.length(3);
+    });
+
+    it("validates max tries", async () => {
+        // eslint-disable-next-line @typescript-eslint/await-thenable
+        await must(waitFor(() => null, {
+            maxTries: 0,
+        })).reject.to.instanceOf(TypeError);
+
+        // eslint-disable-next-line @typescript-eslint/await-thenable
+        await must(waitFor(() => null, {
+            maxTries: -666,
+        })).reject.to.instanceOf(TypeError);
+    });
+
+    it("crashes if check function crashes", async () => {
+        await waitFor(() => {
+            throw new Error(5);
+        }, 40).then(() => {
+            throw new Error("Should not resolve");
+        }, (e) => {
+            must(e).instanceOf(Error);
+            must(e.message).equal("[waitFor] check function threw an error");
+        });
+    });
+
+    describe("treats most falsy values as succeeded check", () => {
+        it("numeric zero", async () => {
+            const result = await waitFor(() => 0);
+            must(result).equal(0);
+        });
+
+        it("empty string", async () => {
+            const result = await waitFor(() => "");
+            must(result).equal("");
+        });
+    });
+
+    describe("supports promises", () => {
+        it("truthy value", async () => {
+            const result = await waitFor(() => true);
+            must(result).be.true();
+        });
+
+        it("by retrying if Promise returns false", async () => {
+            let calls = 0;
+            const spy = createSpy(() => {
+                calls++;
+                return calls === 3;
+            });
+
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            const result = await waitFor(spy);
+            must(result).be.true();
+            must(calls).equal(3);
+        });
+
+        it("by crashing if check function returns rejected promise", async () => {
+            await waitFor(() => {
+                return Promise.reject(new Error("oops"));
+            }, 40).then(() => {
+                throw new Error("Should not resolve");
+            }, (e) => {
+                must(e).instanceOf(Error);
+                must(e.message).equal("[waitFor] check function threw an error");
+            });
+        });
+    });
+});
+