@ezez/utils 3.0.0 → 4.0.0

package/esm/serialize.js

@@ -1,5 +1,29 @@
 import { sortProps } from "./sortProps.js";
+import { replaceDeepByFn } from "./replaceDeepByFn.js";
+import { isPlainObject } from "./isPlainObject.js";
+import { DataWrapper } from "./utils/utils.js";
 const serialize = (data, customSerializers, options) => {
+    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, value) => {
         if (typeof value === "string") {
             return `s:${value}`;
@@ -19,40 +43,54 @@ const serialize = (data, customSerializers, options) => {
         if (value === null) {
             return "l:";
         }
+        if (Array.isArray(value)) {
+            return value;
+        }
+        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}`;
             }
+            if (serialized !== null) {
+                throw new Error(`Custom serializer for key ${key} returned a non-string value: ${String(serialized)}`);
+            }
         }
         if (typeof value === "object") {
             return value;
         }
         throw new Error(`Unsupported data type: ${typeof value}`);
     };
-    if (data == null
-        || typeof data === "string"
-        || typeof data === "number"
-        || typeof data === "bigint"
-        || typeof data === "undefined"
-        || typeof data === "boolean"
-        || Array.isArray(data)) {
-        return JSON.stringify(data, replacer);
+    if (sourceData == null
+        || typeof sourceData === "string"
+        || typeof sourceData === "number"
+        || typeof sourceData === "bigint"
+        || typeof sourceData === "undefined"
+        || typeof sourceData === "boolean"
+        || Array.isArray(sourceData)) {
+        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}"`;
+            }
+            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), replacer);
+            ? sourceData
+            : sortProps(sourceData), replacer);
     }
-    throw new Error(`Unsupported data type: ${typeof data}`);
+    throw new Error(`Unsupported data type: ${typeof sourceData}`);
 };
 export { serialize };
 //# sourceMappingURL=serialize.js.map

package/esm/serialize.js.map

@@ -1 +1 @@
-{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAkC3C,MAAM,SAAS,GAAG,CAAC,IAAa,EAAE,iBAAqC,EAAE,OAAiB,EAAE,EAAE;IAC1F,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,KAAc,EAAE,EAAE;QAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;YAC3B,OAAO,KAAK,KAAK,EAAE,CAAC;SACvB;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;YAC3B,OAAO,KAAK,KAAK,EAAE,CAAC;SACvB;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;YAC3B,OAAO,KAAK,KAAK,EAAE,CAAC;SACvB;QACD,IAAI,OAAO,KAAK,KAAK,WAAW,EAAE;YAC9B,OAAO,IAAI,CAAC;SACf;QACD,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE;YAC5B,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SACpC;QACD,IAAI,KAAK,KAAK,IAAI,EAAE;YAChB,OAAO,IAAI,CAAC;SACf;QACD,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;QAC5D,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE;YAC9B,MAAM,UAAU,GAAG,iBAAkB,CAAC,GAAG,CAAE,CAAC,KAAK,CAAC,CAAC;YACnD,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE;gBAChC,OAAO,GAAG,GAAG,IAAI,UAAU,EAAE,CAAC;aACjC;SACJ;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE;YAC3B,OAAO,KAAK,CAAC;SAChB;QAED,MAAM,IAAI,KAAK,CAAC,0BAA0B,OAAO,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC,CAAC;IAEF,IACI,IAAI,IAAI,IAAI;WACT,OAAO,IAAI,KAAK,QAAQ;WACxB,OAAO,IAAI,KAAK,QAAQ;WACxB,OAAO,IAAI,KAAK,QAAQ;WACxB,OAAO,IAAI,KAAK,WAAW;WAC3B,OAAO,IAAI,KAAK,SAAS;WACzB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EACxB;QACE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;KACzC;IAED,MAAM,oBAAoB,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;IAClE,KAAK,MAAM,GAAG,IAAI,oBAAoB,EAAE;QACpC,MAAM,UAAU,GAAG,iBAAkB,CAAC,GAAG,CAAE,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE;YAChC,OAAO,IAAI,GAAG,IAAI,UAAU,GAAG,CAAC;SACnC;KACJ;IAED,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE;QAC1B,OAAO,IAAI,CAAC,SAAS,CACjB,OAAO,EAAE,SAAS,KAAK,KAAK;YACxB,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,SAAS,CAAC,IAA+B,CAAC,EAChD,QAAQ,CACX,CAAC;KACL;IAED,MAAM,IAAI,KAAK,CAAC,0BAA0B,OAAO,IAAI,EAAE,CAAC,CAAC;AAC7D,CAAC,CAAC;AAGF,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"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"}

package/esm/trim.d.ts

@@ -0,0 +1,3 @@
+declare const trim: (source: string, characters: string) => string;
+export { trim, };
+//# sourceMappingURL=trim.d.ts.map

package/esm/trim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trim.d.ts","sourceRoot":"","sources":["../src/trim.ts"],"names":[],"mappings":"AAgBA,QAAA,MAAM,IAAI,WAAY,MAAM,cAAc,MAAM,WAE/C,CAAC;AAEF,OAAO,EACH,IAAI,GACP,CAAC"}

package/esm/trim.js

@@ -0,0 +1,7 @@
+import { trimStart } from "./trimStart.js";
+import { trimEnd } from "./trimEnd.js";
+const trim = (source, characters) => {
+    return trimStart(trimEnd(source, characters), characters);
+};
+export { trim, };
+//# sourceMappingURL=trim.js.map

package/esm/trim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trim.js","sourceRoot":"","sources":["../src/trim.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAevC,MAAM,IAAI,GAAG,CAAC,MAAc,EAAE,UAAkB,EAAE,EAAE;IAChD,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,CAAC,CAAC;AAC9D,CAAC,CAAC;AAEF,OAAO,EACH,IAAI,GACP,CAAC"}

package/esm/trimEnd.d.ts

@@ -0,0 +1,3 @@
+declare const trimEnd: (source: string, characters: string) => string;
+export { trimEnd, };
+//# sourceMappingURL=trimEnd.d.ts.map

package/esm/trimEnd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trimEnd.d.ts","sourceRoot":"","sources":["../src/trimEnd.ts"],"names":[],"mappings":"AAWA,QAAA,MAAM,OAAO,WAAY,MAAM,cAAc,MAAM,WAMlD,CAAC;AAEF,OAAO,EACH,OAAO,GACV,CAAC"}

package/esm/trimEnd.js

@@ -0,0 +1,9 @@
+const trimEnd = (source, characters) => {
+    let s = source;
+    while (s.endsWith(characters)) {
+        s = s.slice(0, -characters.length);
+    }
+    return s;
+};
+export { trimEnd, };
+//# sourceMappingURL=trimEnd.js.map

package/esm/trimEnd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trimEnd.js","sourceRoot":"","sources":["../src/trimEnd.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,GAAG,CAAC,MAAc,EAAE,UAAkB,EAAE,EAAE;IACnD,IAAI,CAAC,GAAG,MAAM,CAAC;IACf,OAAO,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE;QAC3B,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;KACtC;IACD,OAAO,CAAC,CAAC;AACb,CAAC,CAAC;AAEF,OAAO,EACH,OAAO,GACV,CAAC"}

package/esm/trimStart.d.ts

@@ -0,0 +1,3 @@
+declare const trimStart: (source: string, characters: string) => string;
+export { trimStart, };
+//# sourceMappingURL=trimStart.d.ts.map

package/esm/trimStart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trimStart.d.ts","sourceRoot":"","sources":["../src/trimStart.ts"],"names":[],"mappings":"AAWA,QAAA,MAAM,SAAS,WAAY,MAAM,cAAc,MAAM,WAMpD,CAAC;AAEF,OAAO,EACH,SAAS,GACZ,CAAC"}

package/esm/trimStart.js

@@ -0,0 +1,9 @@
+const trimStart = (source, characters) => {
+    let s = source;
+    while (s.startsWith(characters)) {
+        s = s.slice(characters.length);
+    }
+    return s;
+};
+export { trimStart, };
+//# sourceMappingURL=trimStart.js.map

package/esm/trimStart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trimStart.js","sourceRoot":"","sources":["../src/trimStart.ts"],"names":[],"mappings":"AAWA,MAAM,SAAS,GAAG,CAAC,MAAc,EAAE,UAAkB,EAAE,EAAE;IACrD,IAAI,CAAC,GAAG,MAAM,CAAC;IACf,OAAO,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE;QAC7B,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;KAClC;IACD,OAAO,CAAC,CAAC;AACb,CAAC,CAAC;AAEF,OAAO,EACH,SAAS,GACZ,CAAC"}

package/esm/utils/utils.d.ts

@@ -0,0 +1,6 @@
+declare class DataWrapper<T> {
+    data: T;
+    constructor(data: T);
+}
+export { DataWrapper, };
+//# sourceMappingURL=utils.d.ts.map

package/esm/utils/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils/utils.ts"],"names":[],"mappings":"AAAA,cAAM,WAAW,CAAC,CAAC;IACR,IAAI,EAAE,CAAC,CAAC;gBAEI,IAAI,EAAE,CAAC;CAG7B;AAED,OAAO,EACH,WAAW,GACd,CAAC"}

package/esm/utils/utils.js

@@ -0,0 +1,7 @@
+class DataWrapper {
+    constructor(data) {
+        this.data = data;
+    }
+}
+export { DataWrapper, };
+//# sourceMappingURL=utils.js.map

package/esm/utils/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils/utils.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW;IAGb,YAAmB,IAAO;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;CACJ;AAED,OAAO,EACH,WAAW,GACd,CAAC"}

package/package.json

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

package/src/deserialize.spec.ts

@@ -66,4 +66,16 @@ describe("deserialize", () => {
     it("throws on unknown data type", () => {
         must(() => deserialize(`"v:test"`)).throw("Unsupported data type: v");
     });
+
+    it("supports deserializers with things like Date", async () => {
+        const customSerializers: CustomDeserializers = {
+            D: (value) => {
+                return new Date(Number(value));
+            },
+        };
+
+        const result = deserialize(`"D:1714398481437"`, customSerializers);
+        must(result).be.instanceof(Date);
+        must(result.getTime()).equal(1714398481437);
+    });
 });

package/src/index.ts

@@ -52,6 +52,9 @@ export * from "./stripPrefix.js";
 export * from "./stripSuffix.js";
 export * from "./throttle.js";
 export * from "./toggle.js";
+export * from "./trim.js";
+export * from "./trimEnd.js";
+export * from "./trimStart.js";
 export * from "./truthy.js";
 export * from "./unique.js";
 export * from "./wait.js";

package/src/omit.ts

@@ -1,7 +1,13 @@
 // TODO verify & maybe fix typings when object is an Array
 
 /**
- * Returns new object with copied all properties without these specified.
+ * Returns a cloned source object but without specified properties.
+ *
+ * TypeScript tip: if you want to omit properties that TS think does not exist in the object, call the function like
+ * that:
+ * ```typescript
+ * omit<Record<string, unknown>>(source, ["property"]);
+ * ```
  *
  * @param {Object} object - source object
  * @param {Array.<string>} props - properties to skip
@@ -13,7 +19,7 @@
  * // { 1: "world" }
  * @returns {Object} - new object without given properties
  */
-const omit = <T extends object, K extends keyof T>(
+const omit = <T extends object, K extends keyof T = keyof T>(
     object: T | null, props: K[],
 ): T extends null ? { [key: string]: never } : Omit<T, K> => {
     if (!object || (typeof object !== "object" && typeof object !== "function")) {

package/src/pick.ts

@@ -1,7 +1,7 @@
 // TODO verify & maybe fix typings when object is an Array
 
 /**
- * Returns new object with copied given properties from source object.
+ * Returns a new object with given properties copied from a source object.
  *
  * @param {Object} object - source object
  * @param {Array.<string>} props - properties to copy

package/src/replaceDeep.spec.ts

@@ -1,5 +1,13 @@
 import { replaceDeep } from "./replaceDeep";
 
+class MyClass {
+    public value: number;
+
+    public constructor(value: number) {
+        this.value = value;
+    }
+}
+
 describe("replaceDeep", () => {
     it("should replace given value in a deep object", () => {
         const source = [
@@ -68,4 +76,87 @@ describe("replaceDeep", () => {
             b: 123,
         });
     });
+
+    it("should allow to replace nils", async () => {
+        must(replaceDeep(null, null, 300)).equal(300);
+        // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+        must(replaceDeep(undefined, undefined, 300)).equal(300);
+    });
+
+    it("does not mutate original object", () => {
+        const source = {
+            a: 1,
+            b: {
+                c: 2,
+            },
+        };
+        const result = replaceDeep(source, 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 = replaceDeep(source, 2, 4);
+        must(result).not.equal(source);
+        must(result[3]).not.equal(source[3]);
+        must(result).eql([1, 4, 3, [4, 3]]);
+    });
+
+    it("mutates original object when enabled", () => {
+        const source = {
+            a: 1,
+            b: {
+                c: 2,
+            },
+        };
+        const result = replaceDeep(source, 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 = replaceDeep(source, 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 = replaceDeep(source, 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 = replaceDeep(source, 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(() => replaceDeep(source, 100, 200, {
+            replaceInstancesProps: true,
+            mutate: false,
+        })).throw("`replaceInstancesProps` option requires `mutate` to be enabled");
+    });
 });

package/src/replaceDeep.ts

@@ -1,8 +1,26 @@
+import { replaceDeepByFn } from "./replaceDeepByFn.js";
+
+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. Comparison is done with `Object.is`.
  * If `source` is exactly the `search` a `value` will be returned. It does not do a substring replacements.
  *
- * It mutates the `source` object/array!
+ * 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.
@@ -10,33 +28,10 @@
  * @param source - source object/array/value
  * @param search - value to search for
  * @param value - value to replace with
+ * @param options - optional options
  */
-const replaceDeep = <T>(source: T, search: unknown, value: unknown): T => {
-    if (Object.is(source, search)) {
-        return value as T;
-    }
-
-    if (source == null) {
-        return source;
-    }
-
-    if (typeof source === "object") {
-        if (Array.isArray(source)) {
-            for (let i = 0; i < source.length; i++) {
-                // eslint-disable-next-line no-param-reassign,@typescript-eslint/no-unsafe-assignment
-                source[i] = replaceDeep(source[i], search, value);
-            }
-            return source;
-        }
-
-        return Object.keys(source).reduce<Record<string, unknown>>((acc, key) => {
-            // eslint-disable-next-line no-param-reassign
-            acc[key] = replaceDeep((source as Record<string, unknown>)[key], search, value);
-            return acc;
-        }, {}) as T;
-    }
-
-    return source;
+const replaceDeep = <T>(source: T, search: unknown, value: unknown, options?: Options): T => {
+    return replaceDeepByFn(source, (v) => Object.is(v, search), () => value, options);
 };
 
 export {

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");
+    });
+});