@ezez/utils 3.0.0 → 4.1.0

package/src/compareProps.ts

@@ -1,13 +1,20 @@
 import { unique } from "./unique.js";
 
+/**
+ * Options for `compareProps` function.
+ */
 interface ComparePropsOptions {
+    /**
+     * If `true`, missing properties in the first object will be considered as equal to explicit `undefined` properties
+     * in the second.
+     */
     missingEqualsUndefined?: boolean;
 }
 
 /**
  * Compare two objects and return an array of the properties that are different.
- * By default, if first object doesn't have a property at all and second object has it defined as `undefined` it will be
- * considered as a difference. To change this behavior set `missingEqualsUndefined` option to `true`.
+ * By default, if the first object doesn't have a property at all and the second object has it defined as `undefined`
+ * this will be considered as a difference. To change this behavior, set `missingEqualsUndefined` option to `true`.
  * @param a - first object
  * @param b - second object
  * @param options - options

package/src/deserialize.spec.ts

@@ -5,6 +5,7 @@ import { deserialize } from "./deserialize";
 class Person {
     public name: string;
 
+    // eslint-disable-next-line @typescript-eslint/no-shadow
     public constructor(name: string) {
         this.name = name;
     }
@@ -66,4 +67,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/escapeRegExp.spec.ts

@@ -3,7 +3,7 @@ import { escapeRegExp } from "./escapeRegExp.js";
 describe("escapeRegExp", () => {
     it("it should escape dot", () => {
         const userName = ".";
-        const regex = new RegExp(`^(maciek|${escapeRegExp(userName)})$`);
+        const regex = new RegExp(`^(maciek|${escapeRegExp(userName)})$`, "u");
         const result = regex.test("maciek");
         result.must.be.true();
 
@@ -22,10 +22,12 @@ describe("escapeRegExp", () => {
 
     it("should escape complex string", () => {
         const userName = "([{^|";
-        const fn = () => new RegExp(`^(maciek|${escapeRegExp(userName)})$`);
+        const fn = () => new RegExp(`^(maciek|${escapeRegExp(userName)})$`, "u");
         fn.must.not.throw();
 
-        const fnNoEscape = () => new RegExp(`^(maciek|${userName})$`);
+        const fnNoEscape = () => new RegExp(`^(maciek|${userName})$`, "u");
         fnNoEscape.must.throw();
     });
+
+    // @TODO add tests for missing u flag, test if this flag changed anything in fn behavior
 });

package/src/escapeRegExp.ts

@@ -2,14 +2,15 @@
  * Escapes a string to be used in a regular expression.
  * From: https://stackoverflow.com/a/3561711
  * @param string - string to escape
- * @example ```typescript
+ * @example
+ * ```typescript
  * const badName = "([{^|";
  * const regex = new RegExp(`^(maciek|${escapeRegExp(badName)})$`); // won't crash
  * regex.test(badName); // true
  * ```
  */
 const escapeRegExp = (string: string) => {
-    return string.replace(/[/\-\\^$*+?.()|[\]{}]/g, "\\$&");
+    return string.replace(/[/\-\\^$*+?.()|[\]{}]/gu, "\\$&");
 };
 
 export {

package/src/formatDate.ts

@@ -9,9 +9,9 @@ import { ensureDate } from "./ensureDate.js";
  * Important: this is work in progress. All locale-based values are not supported yet. Formats that heavily depend on
  * locale won't ever be supported.
  */
-const formatDate = (date: Date | number, format: string, locale = "en-US"): string => { // eslint-disable-line max-lines-per-function, max-len
+const formatDate = (date: Date | number, format: string, locale = "en-US"): string => { // eslint-disable-line max-lines-per-function
     const d = ensureDate(date);
-    return format.replace(/%([%a-zA-Z])/g, (_, c) => {
+    return format.replace(/%([%a-zA-Z])/gu, (_, c) => {
         switch (c) {
             case "%": return "%";
             // Day

package/src/get.spec.ts

@@ -55,6 +55,7 @@ describe("get", () => {
 
     it("doesn't parse string as js code, behaves NOT like lodash", () => {
         // Lodash intention-guessing example, inconsistency detected
+        // eslint-disable-next-line @typescript-eslint/no-shadow
         const name = get(testObject, "product[name]");
         (name === undefined).must.be.true();
 

package/src/getMultiple.ts

@@ -29,6 +29,7 @@ const DEFAULT = {};
  * @returns {*} - found value or default value
  */
 const getMultiple = (source: Source, defaultValue: unknown, ...paths: (string | string[])[]): unknown => {
+    // eslint-disable-next-line @typescript-eslint/no-shadow
     const length = paths.length;
     for (let i = 0; i < length; i++) {
         const properties = paths[i]!;

package/src/index.ts

@@ -24,6 +24,7 @@ export * from "./later.js";
 export * from "./mapAsync.js";
 export * from "./mapValues.js";
 export * from "./match.js";
+export * from "./memoize.js";
 export * from "./merge.js";
 export * from "./mostFrequent.js";
 export * from "./noop.js";
@@ -52,6 +53,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/isNumericString.ts

@@ -14,10 +14,10 @@ const NOT_FOUND = -1;
  * @param {object} [options] - Options object
  * @param {boolean} [options.allowFloats=false] - Allow floats
  * @param {boolean} [options.allowExponents=false] - Allow exponents
- * @param {boolean} [options.allowInfinity=false] - Allow Initity and -Infinity (casing matters)
+ * @param {boolean} [options.allowInfinity=false] - Allow Infinity and -Infinity (casing matters)
  * @param {boolean} [options.allowNaN=false] - Allow NaN (casing matters)
  */
-const isNumericString = (string: string, options: Options = {}) => { // eslint-disable-line max-statements, max-lines-per-function, max-len
+const isNumericString = (string: string, options: Options = {}) => { // eslint-disable-line max-statements, max-lines-per-function
     if (typeof string !== "string") {
         throw new TypeError("Expected a string");
     }
@@ -82,7 +82,7 @@ const isNumericString = (string: string, options: Options = {}) => { // eslint-d
         }
     }
 
-    return Boolean(/^[\de.+-]+$/.exec(normalized));
+    return Boolean(/^[\de.+-]+$/u.exec(normalized));
 };
 
 export {

package/src/memoize.spec.ts

@@ -0,0 +1,90 @@
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import must from "must";
+
+import createSpy from "../test/createSpy";
+
+import { memoize } from "./memoize";
+
+describe("memoize", () => {
+    it("should memoize the result if called with the same arguments", async () => {
+        const sum = createSpy((a: number, b: number) => a + b);
+        const memoizedSum = memoize(sum);
+
+        must(memoizedSum(1, 2)).equal(3);
+        must(sum.__spy.calls.length).equal(1);
+        must(memoizedSum(1, 2)).equal(3);
+        must(memoizedSum(1, 2)).equal(3);
+        must(memoizedSum(1, 2)).equal(3);
+        must(sum.__spy.calls.length).equal(1);
+    });
+
+    it("should trigger the function again if arguments are changed", async () => {
+        const sum = createSpy((a: number, b: number) => a + b);
+        const memoizedSum = memoize(sum);
+
+        must(memoizedSum(1, 2)).equal(3);
+        must(sum.__spy.calls.length).equal(1);
+        must(memoizedSum(1, 2)).equal(3);
+        must(sum.__spy.calls.length).equal(1);
+        must(memoizedSum(1, 3)).equal(4);
+        must(sum.__spy.calls.length).equal(2);
+    });
+
+    it("should remember only one value", () => {
+        const sum = createSpy((a: number, b: number) => a + b);
+        const memoizedSum = memoize(sum);
+
+        must(memoizedSum(1, 2)).equal(3);
+        must(sum.__spy.calls.length).equal(1);
+        must(memoizedSum(1, 2)).equal(3);
+        must(sum.__spy.calls.length).equal(1);
+        must(memoizedSum(1, 3)).equal(4);
+        must(sum.__spy.calls.length).equal(2);
+        must(memoizedSum(1, 2)).equal(3);
+        must(sum.__spy.calls.length).equal(3);
+    });
+
+    it("should recalc if arguments amount changes", async () => {
+        const sum = createSpy((a: number, b: number) => a + b);
+        const memoizedSum = memoize(sum);
+
+        must(memoizedSum(1, 2)).equal(3);
+        must(sum.__spy.calls.length).equal(1);
+        must(memoizedSum(1, 2, 0)).equal(3);
+        must(sum.__spy.calls.length).equal(2);
+        must(memoizedSum(1, 2)).equal(3);
+        must(sum.__spy.calls.length).equal(3);
+    });
+
+    it("works with common pitfall values", async () => {
+        const sum = createSpy((a: number, b: number) => a + b);
+        const memoizedSum = memoize(sum);
+
+        memoizedSum(1, NaN);
+        must(sum.__spy.calls.length).equal(1);
+        memoizedSum(1, NaN);
+        must(sum.__spy.calls.length).equal(1);
+
+        memoizedSum(1, 0);
+        must(sum.__spy.calls.length).equal(2);
+        memoizedSum(1, -0);
+        must(sum.__spy.calls.length).equal(3);
+    });
+
+    it("compares by reference", async () => {
+        const fn = createSpy((a: unknown) => null);
+        const memoizedFn = memoize(fn);
+
+        const arr: never[] = [];
+
+        memoizedFn([]);
+        must(fn.__spy.calls.length).equal(1);
+        memoizedFn([]);
+        must(fn.__spy.calls.length).equal(2);
+
+        memoizedFn(arr);
+        must(fn.__spy.calls.length).equal(3);
+        memoizedFn(arr);
+        must(fn.__spy.calls.length).equal(3);
+    });
+});

package/src/memoize.ts

@@ -0,0 +1,35 @@
+/**
+ * Memoizes a function, caching the result of the last call.
+ * If the function is called with the same arguments (and the same context!) again, it will return the cached result.
+ *
+ * It caches only the last call, so it's not suitable for functions that are called with different arguments in a short
+ * time.
+ *
+ * Warning: Your function must be 100% pure, and it can't access anything dynamic outside its scope.
+ *
+ * @param fn - function to memoize
+ * @returns memoized function
+ */
+const memoize = <Args extends unknown[], Ret>(fn: (...args: Args) => Ret) => {
+    let lastArgs: Args | undefined, lastResult: Ret, lastThis: unknown;
+
+    return function memoized(this: unknown, ...args: Args): Ret {
+        if (
+            lastThis === this
+            && lastArgs?.length === args.length
+            && args.every((arg, i) => Object.is(arg, lastArgs![i]))
+        ) {
+            return lastResult;
+        }
+
+        lastThis = this;
+        lastArgs = args;
+        lastResult = fn.apply(this, args);
+
+        return lastResult;
+    };
+};
+
+export {
+    memoize,
+};

package/src/merge.ts

@@ -1,19 +1,37 @@
 /**
  * Special value that can be set as a value in an object.
- * If this value is merged with previous value - the property in a final object will be removed;
+ * If this value is merged with the previous value, the property in a final object will be removed;
  * @see {@link merge}
  */
 const UNSET = typeof Symbol !== "undefined" ? Symbol("UNSET") : {};
 
+/**
+ * Merges two objects into one. If the same property is present in both objects, the value from the second object is
+ * used.
+ */
+type MergeTwo<T, U> = {
+    [K in keyof T | keyof U]: K extends keyof U
+        ? U[K]
+        : K extends keyof T
+            ? T[K]
+            : never;
+};
+
 interface Merge {
     <A>(a: A): A;
-    <A, B>(a: A, b: B): A & B;
-    <A, B, C>(a: A, b: B, c: C): A & B & C;
-    <A, B, C, D>(a: A, b: B, c: C, d: D): A & B & C & D;
-    <A, B, C, D, E>(a: A, b: B, c: C, d: D, e: E): A & B & C & D & E;
-    <A, B, C, D, E, F>(a: A, b: B, c: C, d: D, e: E, f: F): A & B & C & D & E & F;
-    <A, B, C, D, E, F, G>(a: A, b: B, c: C, d: D, e: E, f: F, g: G): A & B & C & D & E & F & G;
-    <A, B, C, D, E, F, G, H>(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H): A & B & C & D & E & F & G & H;
+    <A, B>(a: A, b: B): MergeTwo<A, B>;
+    <A, B, C>(a: A, b: B, c: C): MergeTwo<MergeTwo<A, B>, C>;
+    <A, B, C, D>(a: A, b: B, c: C, d: D): MergeTwo<MergeTwo<MergeTwo<A, B>, C>, D>;
+    <A, B, C, D, E>(a: A, b: B, c: C, d: D, e: E): MergeTwo<MergeTwo<MergeTwo<MergeTwo<A, B>, C>, D>, E>;
+    <A, B, C, D, E, F>(a: A, b: B, c: C, d: D, e: E, f: F): MergeTwo<
+        MergeTwo<MergeTwo<MergeTwo<MergeTwo<A, B>, C>, D>, E>, F
+    >;
+    <A, B, C, D, E, F, G>(a: A, b: B, c: C, d: D, e: E, f: F, g: G): MergeTwo<
+        MergeTwo<MergeTwo<MergeTwo<MergeTwo<MergeTwo<A, B>, C>, D>, E>, F>, G
+    >;
+    <A, B, C, D, E, F, G, H>(a: A, b: B, c: C, d: D, e: E, f: F, g: G, h: H): MergeTwo<
+        MergeTwo<MergeTwo<MergeTwo<MergeTwo<MergeTwo<MergeTwo<A, B>, C>, D>, E>, F>, G>, H
+    >;
     <A, B extends object>(a: A, ...args: B[]): unknown;
 }
 
@@ -56,3 +74,7 @@ export {
     merge,
     UNSET as mergeUNSET,
 };
+
+export type {
+    MergeTwo,
+};

package/src/mostFrequent.ts

@@ -3,6 +3,7 @@
  * @param {Array} array
  */
 const mostFrequent = <T>(array: T[]): T => {
+    // eslint-disable-next-line @typescript-eslint/no-shadow
     let top = 0,
         topValue = array[0];
 

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

@@ -18,7 +18,7 @@ const remove = <T>(array: T[], fn: (elem: T, num: number, list: T[]) => boolean)
         }
     }
 
-    idsToRemove.forEach(id => array.splice(id, 1));
+    idsToRemove.forEach(id => { array.splice(id, 1); });
 
     return removedValues;
 };

package/src/removeCommonProperties.ts

@@ -28,8 +28,10 @@ const removeCommonProperties = (source: Obj, target1: Obj, ...targetN: Obj[]) =>
     for (const key of keys) {
         const allTheSame = targets.every((target) => JSON.stringify(target[key]) === JSON.stringify(source[key]));
         if (allTheSame) {
-            // eslint-disable-next-line no-param-reassign,@typescript-eslint/no-dynamic-delete
-            targets.forEach((target) => delete target[key]);
+            targets.forEach((target) => {
+                // eslint-disable-next-line no-param-reassign,@typescript-eslint/no-dynamic-delete
+                delete target[key];
+            });
         }
     }
 };

package/src/replace.ts

@@ -12,7 +12,7 @@ const replace = (source: string, replaceMap: Record<string, string>) => {
     if (keys.length === 0) {
         return source;
     }
-    const regex = new RegExp(keys.map(escapeRegExp).join("|"), "g");
+    const regex = new RegExp(keys.map(escapeRegExp).join("|"), "gu");
     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 {