@ezez/utils 3.0.0 → 4.1.0

package/src/replaceDeepByFn.spec.ts

@@ -0,0 +1,162 @@
+import { replaceDeepByFn } from "./replaceDeepByFn";
+
+class MyClass {
+    public value: number;
+
+    public constructor(value: number) {
+        this.value = value;
+    }
+}
+
+describe("replaceDeepByFn", () => {
+    it("should replace given value in a deep object", () => {
+        const source = [
+            99,
+            100,
+            {
+                favouriteBook: {
+                    title: "The Ring of The Lord",
+                    price: 100,
+                },
+                otherBooks: [
+                    {
+                        title: "Parry Hotter",
+                        price: 50,
+                        tag: "100",
+                    },
+                    {
+                        title: "The Hobbyte 100",
+                        price: [100],
+                    },
+                ],
+            },
+        ];
+
+        must(replaceDeepByFn(source, v => v === 100, () => 200)).eql([
+            99,
+            200,
+            {
+                favouriteBook: {
+                    title: "The Ring of The Lord",
+                    price: 200,
+                },
+                otherBooks: [
+                    {
+                        title: "Parry Hotter",
+                        price: 50,
+                        tag: "100",
+                    },
+                    {
+                        title: "The Hobbyte 100",
+                        price: [200],
+                    },
+                ],
+            },
+        ]);
+    });
+
+    it("should leave primitives as-is unless they equal to the search value", () => {
+        must(replaceDeepByFn(100, v => v === 200, () => 300)).equal(100);
+        must(replaceDeepByFn(200, v => v === 200, () => 300)).equal(300);
+        must(replaceDeepByFn("100", v => v === 200, () => 300)).equal("100");
+        // ESLINT BUG: (see replaceDeep.spec.ts)
+        // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+        must(replaceDeepByFn(undefined, v => v === 200, () => 300)).equal(undefined);
+        must(replaceDeepByFn(null, v => v === 200, () => 300)).equal(null);
+        must(replaceDeepByFn(true, v => v === 200, () => 300)).equal(true);
+        must(replaceDeepByFn(666n, v => v === 200, () => 300)).equal(666n);
+    });
+
+    it("should work with nans", async () => {
+        must(replaceDeepByFn({
+            a: NaN,
+            b: 123,
+        }, v => Number.isNaN(v), () => 300)).eql({
+            a: 300,
+            b: 123,
+        });
+    });
+
+    it("should allow to replace nils", async () => {
+        must(replaceDeepByFn(null, v => v === null, () => 300)).equal(300);
+        // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+        must(replaceDeepByFn(undefined, v => v === undefined, () => 300)).equal(300);
+    });
+
+    it("does not mutate the original object", () => {
+        const source = {
+            a: 1,
+            b: {
+                c: 2,
+            },
+        };
+        const result = replaceDeepByFn(source, v => v === 2, () => 3);
+        must(result).not.equal(source);
+        must(result.b).not.equal(source.b);
+        must(result).eql({
+            a: 1,
+            b: {
+                c: 3,
+            },
+        });
+    });
+
+    it("does not mutate original array", async () => {
+        const source = [1, 2, 3, [2, 3]];
+        const result = replaceDeepByFn(source, v => v === 2, () => 4);
+        must(result).not.equal(source);
+        must(result[3]).not.equal(source[3]);
+        must(result).eql([1, 4, 3, [4, 3]]);
+    });
+
+    it("mutates the original object when enabled", () => {
+        const source = {
+            a: 1,
+            b: {
+                c: 2,
+            },
+        };
+        const result = replaceDeepByFn(source, v => v === 2, () => 3, { mutate: true });
+        must(result).equal(source);
+        must(result.b).equal(source.b);
+        must(result).eql({
+            a: 1,
+            b: {
+                c: 3,
+            },
+        });
+    });
+
+    it("mutates original array when enabled", async () => {
+        const source = [1, 2, 3, [2, 3]];
+        const result = replaceDeepByFn(source, v => v === 2, () => 4, { mutate: true });
+        must(result).equal(source);
+        must(result[3]).equal(source[3]);
+        must(result).eql([1, 4, 3, [4, 3]]);
+    });
+
+    it("does not get into instances by default", async () => {
+        const source = new MyClass(100);
+        const result = replaceDeepByFn(source, v => v === 100, () => 200);
+        must(result).equal(source);
+        must(source.value).equal(100);
+    });
+
+    it("gets into instances when allowed", async () => {
+        const source = new MyClass(100);
+        const result = replaceDeepByFn(source, v => v === 100, () => 200, {
+            replaceInstancesProps: true,
+            mutate: true,
+        });
+        must(result).equal(source);
+        must(source.value).equal(200);
+    });
+
+    it("requires `mutate` option if `replaceInstancesProps` is defined", async () => {
+        const source = new MyClass(100);
+        must(() => replaceDeepByFn(source, v => v === 100, () => 200, {
+            replaceInstancesProps: true,
+            mutate: false,
+        })).throw("`replaceInstancesProps` option requires `mutate` to be enabled");
+    });
+});

package/src/replaceDeepByFn.ts

@@ -0,0 +1,93 @@
+import { isPlainObject } from "./isPlainObject";
+
+type Options = {
+    /**
+     * If true, the source objects and arrays will be mutated. Default is false.
+     */
+    mutate?: boolean;
+    /**
+     * If true, the function will go into instances for replacement. Otherwise, it will only replace properties of plain
+     * objects. Default is false.
+     * Warning: This option requires `mutate` to be enabled, because we can't clone instances.
+     */
+    replaceInstancesProps?: boolean;
+};
+
+/**
+ * Replaces all occurrences of `search` with `value` in `source` object/array. You do comparison by yourself by providing a callback function.
+ *
+ * Warnings:
+ * - By default, it does not mutate the `source`/deep objects/arrays, but it can be enabled with `mutate` option.
+ * - By default, it does not go into instances for replacement, only plain objects.
+ * - If your instances are cross-referenced, you may end up in an infinite loop.
+ *
+ * TypeScript users: This is way too dynamic to type properly, therefore, typing assumes the most basic form of
+ * replacement where search and value are of the same type. If that's not the case for you - you'll have to typecast.
+ *
+ * @param source - source object/array/value
+ * @param search - value to search for
+ * @param replaceWith - value to replace with
+ * @param options - optional options
+ */
+const replaceDeepByFn = <T>( // eslint-disable-line max-statements
+    source: T, search: (value: unknown) => boolean, replaceWith: (value: unknown) => unknown, options?: Options,
+): T => {
+    if (options?.replaceInstancesProps && !options.mutate) {
+        throw new Error("`replaceInstancesProps` option requires `mutate` to be enabled");
+    }
+
+    const searchResult = search(source);
+
+    if (typeof searchResult !== "boolean") {
+        throw new Error("search function must return a boolean");
+    }
+
+    if (searchResult) {
+        return replaceWith(source) as T;
+    }
+
+    if (source == null) {
+        return source;
+    }
+
+    if (typeof source === "object") {
+        if (Array.isArray(source)) {
+            if (options?.mutate) {
+                for (let i = 0; i < source.length; i++) {
+                    // eslint-disable-next-line no-param-reassign,@typescript-eslint/no-unsafe-assignment
+                    source[i] = replaceDeepByFn(source[i], search, replaceWith, options);
+                }
+                return source;
+            }
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return source.map((item) => replaceDeepByFn(item, search, replaceWith, options)) as unknown as T;
+        }
+
+        if (options?.mutate) {
+            if (isPlainObject(source) || options.replaceInstancesProps) {
+                for (const key of Object.keys(source)) {
+                    // eslint-disable-next-line no-param-reassign
+                    (source as Record<string, unknown>)[key] = replaceDeepByFn(
+                        (source as Record<string, unknown>)[key], search, replaceWith, options,
+                    );
+                }
+            }
+
+            return source;
+        }
+
+        if (isPlainObject(source)) {
+            return Object.keys(source).reduce<Record<string, unknown>>((acc, key) => {
+                // eslint-disable-next-line no-param-reassign
+                acc[key] = replaceDeepByFn((source as Record<string, unknown>)[key], search, replaceWith, options);
+                return acc;
+            }, {}) as T;
+        }
+    }
+
+    return source;
+};
+
+export {
+    replaceDeepByFn,
+};

package/src/rethrow.ts

@@ -3,7 +3,7 @@
  * @param {*} e
  */
 const rethrow = (e: unknown) => {
-    // eslint-disable-next-line @typescript-eslint/no-throw-literal
+    // eslint-disable-next-line @typescript-eslint/only-throw-error
     throw e;
 };
 

package/src/sample.spec.ts

@@ -25,6 +25,7 @@ describe("sample", () => {
 
     it("should work with 0 items array", async () => {
         const array: never[] = [];
+        // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
         const item = sample(array);
         must(item).equal(undefined);
     });

package/src/sample.ts

@@ -1,9 +1,25 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type IsTuple<T> = T extends readonly [infer A, ...(infer B)] ? true : false;
+type MaybeTupleReturn<T> = IsTuple<T> extends true
+    ? (T extends readonly (infer U)[] ? U : never)
+    : (T extends (infer U)[] ? U | undefined : never);
+
 /**
  * Picks a random element from an array.
  * @param array - source array
+ *
+ * @example
+ * sample([1, 2, 3]); // 2 (type: number | undefined)
+ * sample(["a", "b", "c"]); // "c" (type: string | undefined)
+ * sample([]); // undefined (type: undefined)
+ *
+ * const a = [1, 2, 3] as const;
+ * sample(a); // 2 (type: 1 | 2 | 3)
+ *
+ * sample([1, 1, 1] as [number, number, number]); // 1 (type: number)
  */
-const sample = <T>(array: T[]): T => {
-    return array[Math.floor(Math.random() * array.length)]!;
+const sample = <X, T extends readonly X[]>(array: T): MaybeTupleReturn<T> => {
+    return array[Math.floor(Math.random() * array.length)] as MaybeTupleReturn<T>;
 };
 
 export {

package/src/samples.ts

@@ -8,7 +8,7 @@
  * @param elementsToPick - number of elements to pick
  * @param allowShuffle - if true, it will shuffle the values if elementsToPick is greater or equal to array length instead of returning the original array
  */
-const samples = <T>(array: T[], elementsToPick: number, allowShuffle = false): T[] => { // eslint-disable-line max-statements,max-len
+const samples = <T>(array: T[], elementsToPick: number, allowShuffle = false): T[] => { // eslint-disable-line max-statements
     if (elementsToPick < 0) {
         throw new Error("elementsToPick must be a positive number");
     }

package/src/seq.spec.ts

@@ -119,17 +119,20 @@ describe("seq", () => {
         const list = [
             () => {
                 firstCalled = true;
-                // eslint-disable-next-line prefer-promise-reject-errors
+
+                // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
                 return Promise.reject(1);
             },
             () => {
                 secondCalled = true;
-                // eslint-disable-next-line prefer-promise-reject-errors
+
+                // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
                 return Promise.reject(2);
             },
             () => {
                 thirdCalled = true;
-                // eslint-disable-next-line prefer-promise-reject-errors
+
+                // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
                 return Promise.reject(3);
             },
         ];

package/src/seq.ts

@@ -38,7 +38,7 @@ const run = <T>(list: Fn<T>[], earlyBreaker?: EarlyBreaker): Promise<T> => {
         const errors: Error[] = [];
 
         const doTry = function(error?: Error) {
-            if (error !== undefined && earlyBreaker && earlyBreaker(error)) {
+            if (error !== undefined && earlyBreaker?.(error)) {
                 reject(error);
                 return;
             }

package/src/serialize.spec.ts

@@ -9,6 +9,7 @@ interface Test {
 class Person {
     public name: string;
 
+    // eslint-disable-next-line @typescript-eslint/no-shadow
     public constructor(name: string) {
         this.name = name;
     }
@@ -80,4 +81,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);
@@ -32,7 +35,33 @@ type Options = {
  * @param customSerializers - an object with custom serializers
  * @param options - options
  */
-const serialize = (data: unknown, customSerializers?: CustomSerializers, options?: Options) => { // eslint-disable-line max-lines-per-function,max-len
+const serialize = (data: unknown, customSerializers?: CustomSerializers, options?: Options) => { // eslint-disable-line max-lines-per-function
+    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/set.ts

@@ -30,7 +30,7 @@ const isObject = (value: unknown) => (typeof value === "object" || typeof value
  * { "items": { "0": value }}
  * @returns {Object} - given object or new object if source was primitive
  */
-const set = (source: Source, path: string | string[], value: unknown): Source | unknown => { // eslint-disable-line @typescript-eslint/no-redundant-type-constituents,max-len
+const set = (source: Source, path: string | string[], value: unknown): Source | unknown => { // eslint-disable-line @typescript-eslint/no-redundant-type-constituents
     const pathParts = typeof path === "string" ? path.split(".") : path;
     const len = pathParts.length;
 

package/src/setImmutable.ts

@@ -67,7 +67,7 @@ const getPathParts = (path: Path) => {
  * { "items": { "0": value }}
  * @returns {Object} - given object or new object if source was primitive
  */
-const setImmutable = (source: Source, path: Path, value: unknown): Source | unknown => { // eslint-disable-line max-statements, max-len, @typescript-eslint/no-redundant-type-constituents
+const setImmutable = (source: Source, path: Path, value: unknown): Source | unknown => { // eslint-disable-line max-statements, @typescript-eslint/no-redundant-type-constituents
     const pathParts = getPathParts(path);
     const isValidPath = hasOnlyValidPathParts(pathParts);
     if (!isValidPath) {

package/src/sortBy.ts

@@ -10,7 +10,7 @@ const sortBy = <T>(propertyName: keyof T, asc = true, defaultValue: unknown = nu
         return 0;
     }
     // @ts-expect-error We don't care about types here, it's for runtime pure JS too
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+
     if ((a[propertyName] ?? defaultValue) > (b[propertyName] ?? defaultValue)) {
         // eslint-disable-next-line @typescript-eslint/no-magic-numbers
         return asc ? 1 : -1;

package/src/throttle.ts

@@ -46,7 +46,7 @@ type CanReturnUndefined<F extends (...args: any[]) => any> = (...args: Parameter
  * @param {number | number[]} time - throttle time as number or array of numbers (min 1 element)
  * @param {Opts} options
  */
-const throttle = <RT, F extends (...args: any[]) => RT>( // eslint-disable-line max-lines-per-function, @typescript-eslint/no-explicit-any, max-len
+const throttle = <RT, F extends (...args: any[]) => RT>( // eslint-disable-line max-lines-per-function, @typescript-eslint/no-explicit-any
     fn: F, time: number | [number, ...number[]] = 0, options?: Opts,
 ): CanReturnUndefined<F> & Extras => {
     const opts: Required<Opts> = {

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