@ezez/utils 4.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;
     }

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";

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

package/src/serialize.ts

@@ -35,7 +35,7 @@ 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,

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/waitFor.spec.ts

@@ -4,6 +4,7 @@ import must from "must";
 import createSpy from "../test/createSpy";
 
 import { waitFor } from "./waitFor";
+import { wait } from "./wait";
 
 describe("waitFor", () => {
     it("calls function multiple times until it returns truthy value", async () => {
@@ -53,14 +54,18 @@ describe("waitFor", () => {
     });
 
     it("time outs after given time", async () => {
+        const spy = createSpy(() => false);
         // eslint-disable-next-line @typescript-eslint/await-thenable
-        await must(waitFor(() => null, {
+        await must(waitFor(spy, {
             interval: 40,
             timeout: 300,
         })).reject.to.instanceOf(Error);
+        const calls = spy.__spy.calls.length;
+        await wait(100);
+        must(spy.__spy.calls.length).equal(calls);
     });
 
-    it("time outs after given amout of retries", async () => {
+    it("time outs after given count of retries", async () => {
         const spy = createSpy(() => false);
 
         // eslint-disable-next-line @typescript-eslint/await-thenable

package/src/waitFor.ts

@@ -77,7 +77,7 @@ const waitFor = <T>(fn: () => MaybePromise<T>, options: Options = defaultOptions
                         return;
                     }
 
-                    setTimeout(() => {
+                    intervalTimer = setTimeout(() => {
                         tryFn().catch(noop);
                     }, options.interval);
                 }

package/typedoc.cjs

@@ -1,5 +1,3 @@
-const json = require("./pagesconfig.json");
-
 module.exports = {
-    pluginPages: json,
-};
+    projectDocuments: ["./CHANGELOG.md"]
+}

package/docs/assets/pages.css

@@ -1,14 +0,0 @@
-.tsd-navigation li.pages-entry.pages-entry-page > a {
-	color: var(--color-link);
-}
-.tsd-navigation li.pages-entry > a {
-	padding-top: 0.25rem;
-	padding-bottom: 0.25rem;
-}
-.tsd-page-toolbar .table-cell .pages-entry {
-	white-space: normal;
-}
-
-#tsd-search .results .pages-entry-page > a::before {
-	content: '📚 ';
-}