@ezez/utils 2.1.0 → 4.0.0

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

@@ -38,16 +38,23 @@ export * from "./replaceDeep.js";
 export * from "./rethrow.js";
 export * from "./round.js";
 export * from "./safe.js";
+export * from "./sample.js";
+export * from "./samples.js";
 export * from "./scale.js";
 export * from "./seq.js";
 export * from "./serialize.js";
 export * from "./set.js";
 export * from "./setImmutable.js";
+export * from "./shuffle.js";
 export * from "./sortBy.js";
 export * from "./sortProps.js";
 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/replace.ts

@@ -12,7 +12,6 @@ const replace = (source: string, replaceMap: Record<string, string>) => {
     if (keys.length === 0) {
         return source;
     }
-    /* eslint-enable max-len */
     const regex = new RegExp(keys.map(escapeRegExp).join("|"), "g");
     return source.replace(regex, (matched) => replaceMap[matched]!);
 };

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

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/safe.ts

@@ -11,7 +11,6 @@ function safe<T, Y>(fn: () => T, def: Y): T | Y;
  * safe(() => trySomethingComplicated(), defaultValue); // if trySomethingComplicated throws, defaultValue will be returned
  */
 function safe<T, Y>(fn: () => T, def?: Y) { // eslint-disable-line func-style
-    /* eslint-enable max-len */
     try {
         return fn();
     }

package/src/sample.spec.ts

@@ -0,0 +1,31 @@
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import must from "must";
+
+import { sample } from "./sample";
+
+describe("sample", () => {
+    it("should return any random item of an array", async () => {
+        const array = [1, 2, 3, 4, 5];
+        const pickSet = new Set<number>();
+        for (let i = 0; i < 1000; i++) {
+            const item = sample(array);
+            must(array).include(item);
+            pickSet.add(item);
+        }
+        must(pickSet.size).equal(5);
+    });
+
+    it("should work with 1 item array", async () => {
+        const array = [1];
+        for (let i = 0; i < 1000; i++) {
+            const item = sample(array);
+            must(item).equal(1);
+        }
+    });
+
+    it("should work with 0 items array", async () => {
+        const array: never[] = [];
+        const item = sample(array);
+        must(item).equal(undefined);
+    });
+});

package/src/sample.ts

@@ -0,0 +1,11 @@
+/**
+ * Picks a random element from an array.
+ * @param array - source array
+ */
+const sample = <T>(array: T[]): T => {
+    return array[Math.floor(Math.random() * array.length)]!;
+};
+
+export {
+    sample,
+};

package/src/samples.spec.ts

@@ -0,0 +1,50 @@
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import must from "must";
+
+import { samples } from "./samples";
+
+describe("samples", () => {
+    it("must pick random elements", async () => {
+        const elements = [1, 2, 3];
+
+        const result = samples(elements, 2);
+        must(result).have.length(2);
+
+        for (const item of result) {
+            must(elements).include(item);
+        }
+        must([...new Set(result)]).have.length(2);
+    });
+
+    it("should be able to pick one element", async () => {
+        const elements = [1, 2, 3];
+        const result = samples(elements, 1);
+        must(result).have.length(1);
+        must(elements).include(result[0]);
+    });
+
+    it("should return empty array if no elements to pick", async () => {
+        const elements = [1, 2, 3];
+        const result = samples(elements, 0);
+        must(result).be.empty();
+    });
+
+    it("should return all elements if elements to pick is greater than array length", async () => {
+        const elements = [1, 2, 3];
+        const result = samples(elements, 5);
+        must(result).have.length(3);
+        must(result).eql(elements);
+    });
+
+    it("should return all elements if elements to pick is equal to array length", async () => {
+        const elements = [1, 2, 3];
+        const result = samples(elements, 3);
+        must(result).have.length(3);
+        must(result).eql(elements);
+    });
+
+    it("should throw if elements to pick is negative", async () => {
+        const elements = [1, 2, 3];
+        must(() => samples(elements, -1)).throw();
+    });
+});

package/src/samples.ts

@@ -0,0 +1,41 @@
+/**
+ * Picks a given number of random elements from the array. It won't pick the same element twice (unless the array has
+ * duplicates).
+ *
+ * If the number of elements to pick is greater than the array length, it will return the original array.
+ *
+ * @param array - source array
+ * @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
+    if (elementsToPick < 0) {
+        throw new Error("elementsToPick must be a positive number");
+    }
+    if (elementsToPick === 0) {
+        return [];
+    }
+
+    if (!allowShuffle && elementsToPick >= array.length) {
+        return array;
+    }
+
+    const keys = Object.keys(array);
+    let picked = 0;
+    const result: T[] = [];
+
+    while (picked < elementsToPick) {
+        const indexOfKey = Math.floor(Math.random() * keys.length);
+        const indexOfArray = Number(keys[indexOfKey]);
+        const element = array[indexOfArray]!;
+        result.push(element);
+        keys.splice(indexOfKey, 1);
+        picked++;
+    }
+
+    return result;
+};
+
+export {
+    samples,
+};