@ezez/utils 3.0.0 → 4.0.0

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