@naturalcycles/js-lib 15.9.0 → 15.10.0

package/dist/array/array.util.d.ts

@@ -96,7 +96,7 @@ export interface MutateOptions {
      */
     mutate?: boolean;
 }
-export interface SortByOptions extends MutateOptions {
+export interface SortOptions extends MutateOptions {
     /**
      * Defaults to 'asc'.
      */
@@ -109,7 +109,7 @@ export interface SortByOptions extends MutateOptions {
  * Same:
  * _sortBy([{age: 20}, {age: 10}], o => o.age)
  */
-export declare function _sortBy<T, COMPARE_TYPE extends string | number>(items: T[], mapper: Mapper<T, COMPARE_TYPE>, opt?: SortByOptions): T[];
+export declare function _sortBy<T, COMPARE_TYPE extends string | number>(items: T[], mapper: Mapper<T, COMPARE_TYPE>, opt?: SortOptions): T[];
 /**
  * Similar to `Array.find`, but the `predicate` may return `END` to stop the iteration early.
  *

package/dist/datetime/localDate.d.ts

@@ -1,5 +1,6 @@
+import type { MutateOptions, SortOptions } from '../array/array.util.js';
 import { Iterable2 } from '../iter/iterable2.js';
-import type { Inclusiveness, IsoDate, IsoDateTime, MonthId, SortDirection, UnixTimestamp, UnixTimestampMillis } from '../types.js';
+import type { Inclusiveness, IsoDate, IsoDateTime, MonthId, UnixTimestamp, UnixTimestampMillis } from '../types.js';
 import type { DateObject, ISODayOfWeek, LocalTime } from './localTime.js';
 export type LocalDateUnit = LocalDateUnitStrict | 'week';
 export type LocalDateUnitStrict = 'year' | 'month' | 'day';
@@ -16,7 +17,7 @@ export declare class LocalDate {
     day: number;
     constructor(year: number, month: number, day: number);
     get(unit: LocalDateUnitStrict): number;
-    set(unit: LocalDateUnitStrict, v: number, mutate?: boolean): LocalDate;
+    set(unit: LocalDateUnitStrict, v: number, opt?: MutateOptions): LocalDate;
     setYear(v: number): LocalDate;
     setMonth(v: number): LocalDate;
     setDay(v: number): LocalDate;
@@ -100,8 +101,8 @@ export declare class LocalDate {
     minusWeeks(num: number): LocalDate;
     minusMonths(num: number): LocalDate;
     minusYears(num: number): LocalDate;
-    plus(num: number, unit: LocalDateUnit, mutate?: boolean): LocalDate;
-    minus(num: number, unit: LocalDateUnit, mutate?: boolean): LocalDate;
+    plus(num: number, unit: LocalDateUnit, opt?: MutateOptions): LocalDate;
+    minus(num: number, unit: LocalDateUnit, opt?: MutateOptions): LocalDate;
     startOf(unit: LocalDateUnitStrict): LocalDate;
     endOf(unit: LocalDateUnitStrict): LocalDate;
     /**
@@ -246,7 +247,7 @@ declare class LocalDateFactory {
     /**
      * Sorts an array of LocalDates in `dir` order (ascending by default).
      */
-    sort(items: LocalDate[], dir?: SortDirection, mutate?: boolean): LocalDate[];
+    sort(items: LocalDate[], opt?: SortOptions): LocalDate[];
     /**
      * Returns the earliest (min) LocalDate from the array, or undefined if the array is empty.
      */

package/dist/datetime/localDate.js

@@ -23,8 +23,8 @@ export class LocalDate {
     get(unit) {
         return unit === 'year' ? this.year : unit === 'month' ? this.month : this.day;
     }
-    set(unit, v, mutate = false) {
-        const t = mutate ? this : this.clone();
+    set(unit, v, opt = {}) {
+        const t = opt.mutate ? this : this.clone();
         if (unit === 'year') {
             t.year = v;
         }
@@ -266,7 +266,7 @@ export class LocalDate {
     minusYears(num) {
         return this.plus(-num, 'year');
     }
-    plus(num, unit, mutate = false) {
+    plus(num, unit, opt = {}) {
         num = Math.floor(num); // if a fractional number like 0.5 is passed - it will be floored, as LocalDate only deals with "whole days" as minimal unit
         let { day, month, year } = this;
         if (unit === 'week') {
@@ -323,7 +323,7 @@ export class LocalDate {
                 }
             }
         }
-        if (mutate) {
+        if (opt.mutate) {
             this.year = year;
             this.month = month;
             this.day = day;
@@ -331,8 +331,8 @@ export class LocalDate {
         }
         return new LocalDate(year, month, day);
     }
-    minus(num, unit, mutate = false) {
-        return this.plus(-num, unit, mutate);
+    minus(num, unit, opt = {}) {
+        return this.plus(-num, unit, opt);
     }
     startOf(unit) {
         if (unit === 'day')
@@ -612,9 +612,9 @@ class LocalDateFactory {
     /**
      * Sorts an array of LocalDates in `dir` order (ascending by default).
      */
-    sort(items, dir = 'asc', mutate = false) {
-        const mod = dir === 'desc' ? -1 : 1;
-        return (mutate ? items : [...items]).sort((a, b) => a.compare(b) * mod);
+    sort(items, opt = {}) {
+        const mod = opt.dir === 'desc' ? -1 : 1;
+        return (opt.mutate ? items : [...items]).sort((a, b) => a.compare(b) * mod);
     }
     /**
      * Returns the earliest (min) LocalDate from the array, or undefined if the array is empty.
@@ -687,7 +687,7 @@ class LocalDateFactory {
             // ok
         }
         else {
-            value.plus(1, stepUnit, true);
+            value.plus(1, stepUnit, { mutate: true });
         }
         const rightInclusive = incl[1] === ']';
         return Iterable2.of({

package/dist/datetime/localTime.d.ts

@@ -1,3 +1,4 @@
+import type { MutateOptions } from '../array/array.util.js';
 import type { IANATimezone, Inclusiveness, IsoDate, IsoDateTime, MonthId, NumberOfHours, NumberOfMinutes, SortDirection, UnixTimestamp, UnixTimestampMillis } from '../types.js';
 import type { LocalDate } from './localDate.js';
 import { WallTime } from './wallTime.js';
@@ -86,7 +87,7 @@ export declare class LocalTime {
      */
     getUTCOffsetString(tz: IANATimezone): string;
     get(unit: LocalTimeUnit): number;
-    set(unit: LocalTimeUnit, v: number, mutate?: boolean): LocalTime;
+    set(unit: LocalTimeUnit, v: number, opt?: MutateOptions): LocalTime;
     get year(): number;
     setYear(v: number): LocalTime;
     get month(): number;
@@ -117,7 +118,7 @@ export declare class LocalTime {
      * If this LocalTime is Monday, and desired DoW is also Monday - `this` is returned.
      */
     setNextDayOfWeek(dow: ISODayOfWeek): LocalTime;
-    setComponents(c: Partial<DateTimeObject>, mutate?: boolean): LocalTime;
+    setComponents(c: Partial<DateTimeObject>, opt?: MutateOptions): LocalTime;
     plusSeconds(num: number): LocalTime;
     plusMinutes(num: number): LocalTime;
     plusHours(num: number): LocalTime;
@@ -132,12 +133,12 @@ export declare class LocalTime {
     minusWeeks(num: number): LocalTime;
     minusMonths(num: number): LocalTime;
     minusYears(num: number): LocalTime;
-    plus(num: number, unit: LocalTimeUnit, mutate?: boolean): LocalTime;
-    minus(num: number, unit: LocalTimeUnit, mutate?: boolean): LocalTime;
+    plus(num: number, unit: LocalTimeUnit, opt?: MutateOptions): LocalTime;
+    minus(num: number, unit: LocalTimeUnit, opt?: MutateOptions): LocalTime;
     absDiff(other: LocalTimeInput, unit: LocalTimeUnit): number;
     diff(other: LocalTimeInput, unit: LocalTimeUnit): number;
-    startOf(unit: LocalTimeUnit, mutate?: boolean): LocalTime;
-    endOf(unit: LocalTimeUnit, mutate?: boolean): LocalTime;
+    startOf(unit: LocalTimeUnit, opt?: MutateOptions): LocalTime;
+    endOf(unit: LocalTimeUnit, opt?: MutateOptions): LocalTime;
     /**
      * Returns how many days are in the current month.
      * E.g 31 for January.
@@ -314,7 +315,7 @@ declare class LocalTimeFactory {
      * consider caching the Intl.supportedValuesOf values as Set and reuse that.
      */
     isTimezoneValid(tz: string): boolean;
-    sort(items: LocalTime[], dir?: SortDirection, mutate?: boolean): LocalTime[];
+    sort(items: LocalTime[], dir?: SortDirection, opt?: MutateOptions): LocalTime[];
     minOrUndefined(items: LocalTimeInputNullable[]): LocalTime | undefined;
     min(items: LocalTimeInputNullable[]): LocalTime;
     maxOrUndefined(items: LocalTimeInputNullable[]): LocalTime | undefined;

package/dist/datetime/localTime.js

@@ -146,8 +146,8 @@ export class LocalTime {
         // second
         return this.$date.getSeconds();
     }
-    set(unit, v, mutate = false) {
-        const t = mutate ? this : this.clone();
+    set(unit, v, opt = {}) {
+        const t = opt.mutate ? this : this.clone();
         if (unit === 'year') {
             t.$date.setFullYear(v);
         }
@@ -167,7 +167,7 @@ export class LocalTime {
             t.$date.setSeconds(v);
         }
         else if (unit === 'week') {
-            setWeek(t.$date, v, true);
+            setWeek(t.$date, v, { mutate: true });
         }
         return t;
     }
@@ -241,8 +241,8 @@ export class LocalTime {
             delta += 7;
         return this.plus(delta, 'day');
     }
-    setComponents(c, mutate = false) {
-        const d = mutate ? this.$date : new Date(this.$date);
+    setComponents(c, opt = {}) {
+        const d = opt.mutate ? this.$date : new Date(this.$date);
         // Year, month and day set all-at-once, to avoid 30/31 (and 28/29) mishap
         if (c.day || c.month !== undefined || c.year !== undefined) {
             d.setFullYear(c.year ?? d.getFullYear(), c.month ? c.month - 1 : d.getMonth(), c.day || d.getDate());
@@ -256,7 +256,7 @@ export class LocalTime {
         if (c.second !== undefined) {
             d.setSeconds(c.second);
         }
-        return mutate ? this : new LocalTime(d);
+        return opt.mutate ? this : new LocalTime(d);
     }
     plusSeconds(num) {
         return this.plus(num, 'second');
@@ -300,19 +300,19 @@ export class LocalTime {
     minusYears(num) {
         return this.plus(-num, 'year');
     }
-    plus(num, unit, mutate = false) {
+    plus(num, unit, opt = {}) {
         if (unit === 'week') {
             num *= 7;
             unit = 'day';
         }
         if (unit === 'year' || unit === 'month') {
-            const d = addMonths(this.$date, unit === 'month' ? num : num * 12, mutate);
-            return mutate ? this : localTime.fromInput(d);
+            const d = addMonths(this.$date, unit === 'month' ? num : num * 12, opt);
+            return opt.mutate ? this : localTime.fromInput(d);
         }
-        return this.set(unit, this.get(unit) + num, mutate);
+        return this.set(unit, this.get(unit) + num, opt);
     }
-    minus(num, unit, mutate = false) {
-        return this.plus(num * -1, unit, mutate);
+    minus(num, unit, opt = {}) {
+        return this.plus(num * -1, unit, opt);
     }
     absDiff(other, unit) {
         return Math.abs(this.diff(other, unit));
@@ -348,10 +348,10 @@ export class LocalTime {
         // `|| 0` is to avoid returning -0
         return Math.trunc(r) || 0;
     }
-    startOf(unit, mutate = false) {
+    startOf(unit, opt = {}) {
         if (unit === 'second')
             return this;
-        const d = mutate ? this.$date : new Date(this.$date);
+        const d = opt.mutate ? this.$date : new Date(this.$date);
         d.setSeconds(0, 0);
         if (unit !== 'minute') {
             d.setMinutes(0);
@@ -368,17 +368,17 @@ export class LocalTime {
                     }
                     else {
                         // week
-                        startOfWeek(d, true);
+                        startOfWeek(d, { mutate: true });
                     }
                 }
             }
         }
-        return mutate ? this : new LocalTime(d);
+        return opt.mutate ? this : new LocalTime(d);
     }
-    endOf(unit, mutate = false) {
+    endOf(unit, opt = {}) {
         if (unit === 'second')
             return this;
-        const d = mutate ? this.$date : new Date(this.$date);
+        const d = opt.mutate ? this.$date : new Date(this.$date);
         d.setSeconds(59, 0);
         if (unit !== 'minute') {
             d.setMinutes(59);
@@ -390,7 +390,7 @@ export class LocalTime {
                         d.setMonth(11);
                     }
                     if (unit === 'week') {
-                        endOfWeek(d, true);
+                        endOfWeek(d, { mutate: true });
                     }
                     else {
                         // year or month
@@ -400,7 +400,7 @@ export class LocalTime {
                 }
             }
         }
-        return mutate ? this : new LocalTime(d);
+        return opt.mutate ? this : new LocalTime(d);
     }
     /**
      * Returns how many days are in the current month.
@@ -856,9 +856,9 @@ class LocalTimeFactory {
             return true; // we deliberately consider UTC a valid timezone, while it's mostly used in testing
         return Intl.supportedValuesOf('timeZone').includes(tz);
     }
-    sort(items, dir = 'asc', mutate = false) {
+    sort(items, dir = 'asc', opt = {}) {
         const mod = dir === 'desc' ? -1 : 1;
-        return (mutate ? items : [...items]).sort((a, b) => {
+        return (opt.mutate ? items : [...items]).sort((a, b) => {
             const v1 = a.$date.valueOf();
             const v2 = b.$date.valueOf();
             if (v1 === v2)
@@ -906,8 +906,8 @@ function getWeek(date) {
     const diff = startOfWeek(date).getTime() - startOfWeekYear(date).getTime();
     return Math.round(diff / MILLISECONDS_IN_WEEK) + 1;
 }
-function setWeek(date, week, mutate = false) {
-    const d = mutate ? date : new Date(date);
+function setWeek(date, week, opt = {}) {
+    const d = opt.mutate ? date : new Date(date);
     const diff = getWeek(d) - week;
     d.setDate(d.getDate() - diff * 7);
     return d;
@@ -918,7 +918,7 @@ function startOfWeekYear(date) {
     const fourthOfJanuary = new Date(0);
     fourthOfJanuary.setFullYear(year, 0, 4);
     fourthOfJanuary.setHours(0, 0, 0, 0);
-    return startOfWeek(fourthOfJanuary, true);
+    return startOfWeek(fourthOfJanuary, { mutate: true });
 }
 // based on: https://github.com/date-fns/date-fns/blob/fd6bb1a0bab143f2da068c05a9c562b9bee1357d/src/getISOWeekYear/index.ts
 function getWeekYear(date) {
@@ -926,11 +926,11 @@ function getWeekYear(date) {
     const fourthOfJanuaryOfNextYear = new Date(0);
     fourthOfJanuaryOfNextYear.setFullYear(year + 1, 0, 4);
     fourthOfJanuaryOfNextYear.setHours(0, 0, 0, 0);
-    const startOfNextYear = startOfWeek(fourthOfJanuaryOfNextYear, true);
+    const startOfNextYear = startOfWeek(fourthOfJanuaryOfNextYear, { mutate: true });
     const fourthOfJanuaryOfThisYear = new Date(0);
     fourthOfJanuaryOfThisYear.setFullYear(year, 0, 4);
     fourthOfJanuaryOfThisYear.setHours(0, 0, 0, 0);
-    const startOfThisYear = startOfWeek(fourthOfJanuaryOfThisYear, true);
+    const startOfThisYear = startOfWeek(fourthOfJanuaryOfThisYear, { mutate: true });
     if (date.getTime() >= startOfNextYear.getTime()) {
         return year + 1;
     }
@@ -940,8 +940,8 @@ function getWeekYear(date) {
     return year - 1;
 }
 // based on: https://github.com/date-fns/date-fns/blob/fd6bb1a0bab143f2da068c05a9c562b9bee1357d/src/startOfWeek/index.ts
-function startOfWeek(date, mutate = false) {
-    const d = mutate ? date : new Date(date);
+function startOfWeek(date, opt = {}) {
+    const d = opt.mutate ? date : new Date(date);
     const day = d.getDay();
     const diff = (day < weekStartsOn ? 7 : 0) + day - weekStartsOn;
     d.setDate(d.getDate() - diff);
@@ -949,15 +949,15 @@ function startOfWeek(date, mutate = false) {
     return d;
 }
 // based on: https://github.com/date-fns/date-fns/blob/master/src/endOfWeek/index.ts
-function endOfWeek(date, mutate = false) {
-    const d = mutate ? date : new Date(date);
+function endOfWeek(date, opt = {}) {
+    const d = opt.mutate ? date : new Date(date);
     const day = d.getDay();
     const diff = (day < weekStartsOn ? -7 : 0) + 6 - (day - weekStartsOn);
     d.setDate(d.getDate() + diff);
     return d;
 }
-function addMonths(d, num, mutate = false) {
-    if (!mutate)
+function addMonths(d, num, opt = {}) {
+    if (!opt.mutate)
         d = new Date(d);
     let day = d.getDate();
     let month = d.getMonth() + 1 + num;

package/dist/log/commonLogger.d.ts

@@ -1,3 +1,4 @@
+import type { MutateOptions } from '../array/array.util.js';
 /**
  * These levels follow console.* naming,
  * so you can use console[level] safely.
@@ -38,7 +39,7 @@ export declare const commonLoggerNoop: CommonLogger;
 /**
  * Creates a "child" logger that is "limited" to the specified CommonLogLevel.
  */
-export declare function commonLoggerMinLevel(logger: CommonLogger, minLevel: CommonLogLevel, mutate?: boolean): CommonLogger;
+export declare function commonLoggerMinLevel(logger: CommonLogger, minLevel: CommonLogLevel, opt?: MutateOptions): CommonLogger;
 /**
  * Creates a "proxy" CommonLogger that pipes log messages to all provided sub-loggers.
  */

package/dist/log/commonLogger.js

@@ -1,4 +1,3 @@
-// copy-pasted to avoid weird circular dependency
 const _noop = (..._args) => undefined;
 export const commonLogLevelNumber = {
     log: 10,
@@ -18,9 +17,9 @@ export const commonLoggerNoop = {
 /**
  * Creates a "child" logger that is "limited" to the specified CommonLogLevel.
  */
-export function commonLoggerMinLevel(logger, minLevel, mutate = false) {
+export function commonLoggerMinLevel(logger, minLevel, opt = {}) {
     const level = commonLogLevelNumber[minLevel];
-    if (mutate) {
+    if (opt.mutate) {
         if (level > commonLogLevelNumber['log']) {
             logger.log = _noop;
             if (level > commonLogLevelNumber['warn']) {

package/dist/number/number.util.d.ts

@@ -1,4 +1,5 @@
-import type { Inclusiveness, SortDirection } from '../types.js';
+import type { SortOptions } from '../array/array.util.js';
+import type { Inclusiveness } from '../types.js';
 export declare function _randomInt(minIncl: number, maxIncl: number): number;
 /**
  * Returns random item from an array.
@@ -37,7 +38,7 @@ export declare function _clamp(x: number, minIncl: number, maxIncl: number): num
  * _sortNumbers([1, 3, 2])
  * // [1, 2, 3]
  */
-export declare function _sortNumbers(numbers: number[], mutate?: boolean, dir?: SortDirection): number[];
+export declare function _sortNumbers(numbers: number[], opt?: SortOptions): number[];
 /**
  * Same as .toFixed(), but conveniently casts the output to Number.
  *

package/dist/number/number.util.js

@@ -52,9 +52,9 @@ export function _clamp(x, minIncl, maxIncl) {
  * _sortNumbers([1, 3, 2])
  * // [1, 2, 3]
  */
-export function _sortNumbers(numbers, mutate = false, dir = 'asc') {
-    const mod = dir === 'desc' ? -1 : 1;
-    return (mutate ? numbers : [...numbers]).sort((a, b) => (a - b) * mod);
+export function _sortNumbers(numbers, opt = {}) {
+    const mod = opt.dir === 'desc' ? -1 : 1;
+    return (opt.mutate ? numbers : [...numbers]).sort((a, b) => (a - b) * mod);
 }
 /**
  * Same as .toFixed(), but conveniently casts the output to Number.

package/dist/object/object.util.d.ts

@@ -1,5 +1,5 @@
 import type { MutateOptions } from '../array/array.util.js';
-import type { AnyObject, KeyValueTuple, ObjectMapper, ObjectPredicate, Reviver, ValueOf } from '../types.js';
+import type { AnyObject, KeyValueTuple, ObjectMapper, ObjectPredicate, Reviver, StringMap, ValueOf } from '../types.js';
 import { SKIP } from '../types.js';
 /**
  * Returns clone of `obj` with only `props` preserved.
@@ -93,6 +93,18 @@ export declare function _objectNullValuesToUndefined<T extends AnyObject>(obj: T
  * Deep copy object (by json parse/stringify, since it has unbeatable performance+simplicity combo).
  */
 export declare function _deepCopy<T>(o: T, reviver?: Reviver): T;
+/**
+ * Performance-optimized implementation of merging two objects
+ * without mutating any of them.
+ * (if you are allowed to mutate - there can be a faster implementation).
+ *
+ * Gives ~40% speedup with map sizes between 10 and 100k items,
+ * compared to {...obj1, ...obj2} or Object.assign({}, obj1, obj2).
+ *
+ * Only use it in hot paths that are known to be performance bottlenecks,
+ * otherwise it's not worth it (use normal object spread then).
+ */
+export declare function _mergeObjects<T>(obj1: StringMap<T>, obj2: StringMap<T>): StringMap<T>;
 /**
  * Returns `undefined` if it's empty (according to `_isEmpty()` specification),
  * otherwise returns the original object.

package/dist/object/object.util.js

@@ -192,6 +192,25 @@ export function _objectNullValuesToUndefined(obj, opt = {}) {
 export function _deepCopy(o, reviver) {
     return JSON.parse(JSON.stringify(o), reviver);
 }
+/**
+ * Performance-optimized implementation of merging two objects
+ * without mutating any of them.
+ * (if you are allowed to mutate - there can be a faster implementation).
+ *
+ * Gives ~40% speedup with map sizes between 10 and 100k items,
+ * compared to {...obj1, ...obj2} or Object.assign({}, obj1, obj2).
+ *
+ * Only use it in hot paths that are known to be performance bottlenecks,
+ * otherwise it's not worth it (use normal object spread then).
+ */
+export function _mergeObjects(obj1, obj2) {
+    const map = {};
+    for (const k of Object.keys(obj1))
+        map[k] = obj1[k];
+    for (const k of Object.keys(obj2))
+        map[k] = obj2[k];
+    return map;
+}
 /**
  * Returns `undefined` if it's empty (according to `_isEmpty()` specification),
  * otherwise returns the original object.

package/dist/semver.d.ts

@@ -1,4 +1,4 @@
-import type { SortDirection } from './types.js';
+import type { SortOptions } from './array/array.util.js';
 export type SemverInput = string | Semver;
 export type SemverInputNullable = SemverInput | null | undefined;
 export type SemverTokens = [major: number, minor: number, patch: number];
@@ -62,7 +62,7 @@ declare class SemverFactory {
     /**
      * Sorts an array of Semvers in `dir` order (ascending by default).
      */
-    sort(items: Semver[], dir?: SortDirection, mutate?: boolean): Semver[];
+    sort(items: Semver[], opt?: SortOptions): Semver[];
 }
 interface SemverFn extends SemverFactory {
     (input: SemverInput): Semver;

package/dist/semver.js

@@ -118,9 +118,9 @@ class SemverFactory {
     /**
      * Sorts an array of Semvers in `dir` order (ascending by default).
      */
-    sort(items, dir = 'asc', mutate = false) {
-        const mod = dir === 'desc' ? -1 : 1;
-        return (mutate ? items : [...items]).sort((a, b) => a.compare(b) * mod);
+    sort(items, opt = {}) {
+        const mod = opt.dir === 'desc' ? -1 : 1;
+        return (opt.mutate ? items : [...items]).sort((a, b) => a.compare(b) * mod);
     }
 }
 const semverFactory = new SemverFactory();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.9.0",
+  "version": "15.10.0",
   "dependencies": {
     "tslib": "^2",
     "zod": "^3"

package/src/array/array.util.ts

@@ -181,7 +181,7 @@ export interface MutateOptions {
   mutate?: boolean
 }
 
-export interface SortByOptions extends MutateOptions {
+export interface SortOptions extends MutateOptions {
   /**
    * Defaults to 'asc'.
    */
@@ -198,7 +198,7 @@ export interface SortByOptions extends MutateOptions {
 export function _sortBy<T, COMPARE_TYPE extends string | number>(
   items: T[],
   mapper: Mapper<T, COMPARE_TYPE>,
-  opt: SortByOptions = {},
+  opt: SortOptions = {},
 ): T[] {
   const mod = opt.dir === 'desc' ? -1 : 1
 

package/src/datetime/localDate.ts

@@ -1,3 +1,4 @@
+import type { MutateOptions, SortOptions } from '../array/array.util.js'
 import { _assert } from '../error/assert.js'
 import { Iterable2 } from '../iter/iterable2.js'
 import type {
@@ -5,7 +6,6 @@ import type {
   IsoDate,
   IsoDateTime,
   MonthId,
-  SortDirection,
   UnixTimestamp,
   UnixTimestampMillis,
 } from '../types.js'
@@ -41,8 +41,8 @@ export class LocalDate {
     return unit === 'year' ? this.year : unit === 'month' ? this.month : this.day
   }
 
-  set(unit: LocalDateUnitStrict, v: number, mutate = false): LocalDate {
-    const t = mutate ? this : this.clone()
+  set(unit: LocalDateUnitStrict, v: number, opt: MutateOptions = {}): LocalDate {
+    const t = opt.mutate ? this : this.clone()
 
     if (unit === 'year') {
       t.year = v
@@ -325,7 +325,7 @@ export class LocalDate {
     return this.plus(-num, 'year')
   }
 
-  plus(num: number, unit: LocalDateUnit, mutate = false): LocalDate {
+  plus(num: number, unit: LocalDateUnit, opt: MutateOptions = {}): LocalDate {
     num = Math.floor(num) // if a fractional number like 0.5 is passed - it will be floored, as LocalDate only deals with "whole days" as minimal unit
     let { day, month, year } = this
 
@@ -386,7 +386,7 @@ export class LocalDate {
       }
     }
 
-    if (mutate) {
+    if (opt.mutate) {
       this.year = year
       this.month = month
       this.day = day
@@ -396,8 +396,8 @@ export class LocalDate {
     return new LocalDate(year, month, day)
   }
 
-  minus(num: number, unit: LocalDateUnit, mutate = false): LocalDate {
-    return this.plus(-num, unit, mutate)
+  minus(num: number, unit: LocalDateUnit, opt: MutateOptions = {}): LocalDate {
+    return this.plus(-num, unit, opt)
   }
 
   startOf(unit: LocalDateUnitStrict): LocalDate {
@@ -716,9 +716,9 @@ class LocalDateFactory {
   /**
    * Sorts an array of LocalDates in `dir` order (ascending by default).
    */
-  sort(items: LocalDate[], dir: SortDirection = 'asc', mutate = false): LocalDate[] {
-    const mod = dir === 'desc' ? -1 : 1
-    return (mutate ? items : [...items]).sort((a, b) => a.compare(b) * mod)
+  sort(items: LocalDate[], opt: SortOptions = {}): LocalDate[] {
+    const mod = opt.dir === 'desc' ? -1 : 1
+    return (opt.mutate ? items : [...items]).sort((a, b) => a.compare(b) * mod)
   }
 
   /**
@@ -809,7 +809,7 @@ class LocalDateFactory {
     if (value.isSameOrAfter($min)) {
       // ok
     } else {
-      value.plus(1, stepUnit, true)
+      value.plus(1, stepUnit, { mutate: true })
     }
 
     const rightInclusive = incl[1] === ']'

package/src/datetime/localTime.ts

@@ -1,3 +1,4 @@
+import type { MutateOptions } from '../array/array.util.js'
 import { _assert } from '../error/assert.js'
 import { _ms } from '../time/time.util.js'
 import type {
@@ -189,8 +190,8 @@ export class LocalTime {
     return this.$date.getSeconds()
   }
 
-  set(unit: LocalTimeUnit, v: number, mutate = false): LocalTime {
-    const t = mutate ? this : this.clone()
+  set(unit: LocalTimeUnit, v: number, opt: MutateOptions = {}): LocalTime {
+    const t = opt.mutate ? this : this.clone()
 
     if (unit === 'year') {
       t.$date.setFullYear(v)
@@ -205,7 +206,7 @@ export class LocalTime {
     } else if (unit === 'second') {
       t.$date.setSeconds(v)
     } else if (unit === 'week') {
-      setWeek(t.$date, v, true)
+      setWeek(t.$date, v, { mutate: true })
     }
 
     return t
@@ -297,8 +298,8 @@ export class LocalTime {
     return this.plus(delta, 'day')
   }
 
-  setComponents(c: Partial<DateTimeObject>, mutate = false): LocalTime {
-    const d = mutate ? this.$date : new Date(this.$date)
+  setComponents(c: Partial<DateTimeObject>, opt: MutateOptions = {}): LocalTime {
+    const d = opt.mutate ? this.$date : new Date(this.$date)
 
     // Year, month and day set all-at-once, to avoid 30/31 (and 28/29) mishap
     if (c.day || c.month !== undefined || c.year !== undefined) {
@@ -319,7 +320,7 @@ export class LocalTime {
       d.setSeconds(c.second)
     }
 
-    return mutate ? this : new LocalTime(d)
+    return opt.mutate ? this : new LocalTime(d)
   }
 
   plusSeconds(num: number): LocalTime {
@@ -378,22 +379,22 @@ export class LocalTime {
     return this.plus(-num, 'year')
   }
 
-  plus(num: number, unit: LocalTimeUnit, mutate = false): LocalTime {
+  plus(num: number, unit: LocalTimeUnit, opt: MutateOptions = {}): LocalTime {
     if (unit === 'week') {
       num *= 7
       unit = 'day'
     }
 
     if (unit === 'year' || unit === 'month') {
-      const d = addMonths(this.$date, unit === 'month' ? num : num * 12, mutate)
-      return mutate ? this : localTime.fromInput(d)
+      const d = addMonths(this.$date, unit === 'month' ? num : num * 12, opt)
+      return opt.mutate ? this : localTime.fromInput(d)
     }
 
-    return this.set(unit, this.get(unit) + num, mutate)
+    return this.set(unit, this.get(unit) + num, opt)
   }
 
-  minus(num: number, unit: LocalTimeUnit, mutate = false): LocalTime {
-    return this.plus(num * -1, unit, mutate)
+  minus(num: number, unit: LocalTimeUnit, opt: MutateOptions = {}): LocalTime {
+    return this.plus(num * -1, unit, opt)
   }
 
   absDiff(other: LocalTimeInput, unit: LocalTimeUnit): number {
@@ -429,9 +430,9 @@ export class LocalTime {
     return Math.trunc(r) || 0
   }
 
-  startOf(unit: LocalTimeUnit, mutate = false): LocalTime {
+  startOf(unit: LocalTimeUnit, opt: MutateOptions = {}): LocalTime {
     if (unit === 'second') return this
-    const d = mutate ? this.$date : new Date(this.$date)
+    const d = opt.mutate ? this.$date : new Date(this.$date)
     d.setSeconds(0, 0)
 
     if (unit !== 'minute') {
@@ -448,18 +449,18 @@ export class LocalTime {
             d.setDate(1)
           } else {
             // week
-            startOfWeek(d, true)
+            startOfWeek(d, { mutate: true })
           }
         }
       }
     }
 
-    return mutate ? this : new LocalTime(d)
+    return opt.mutate ? this : new LocalTime(d)
   }
 
-  endOf(unit: LocalTimeUnit, mutate = false): LocalTime {
+  endOf(unit: LocalTimeUnit, opt: MutateOptions = {}): LocalTime {
     if (unit === 'second') return this
-    const d = mutate ? this.$date : new Date(this.$date)
+    const d = opt.mutate ? this.$date : new Date(this.$date)
     d.setSeconds(59, 0)
 
     if (unit !== 'minute') {
@@ -474,7 +475,7 @@ export class LocalTime {
           }
 
           if (unit === 'week') {
-            endOfWeek(d, true)
+            endOfWeek(d, { mutate: true })
           } else {
             // year or month
             const lastDay = localDate.getMonthLength(d.getFullYear(), d.getMonth() + 1)
@@ -484,7 +485,7 @@ export class LocalTime {
       }
     }
 
-    return mutate ? this : new LocalTime(d)
+    return opt.mutate ? this : new LocalTime(d)
   }
 
   /**
@@ -1003,9 +1004,9 @@ class LocalTimeFactory {
     return Intl.supportedValuesOf('timeZone').includes(tz)
   }
 
-  sort(items: LocalTime[], dir: SortDirection = 'asc', mutate = false): LocalTime[] {
+  sort(items: LocalTime[], dir: SortDirection = 'asc', opt: MutateOptions = {}): LocalTime[] {
     const mod = dir === 'desc' ? -1 : 1
-    return (mutate ? items : [...items]).sort((a, b) => {
+    return (opt.mutate ? items : [...items]).sort((a, b) => {
       const v1 = a.$date.valueOf()
       const v2 = b.$date.valueOf()
       if (v1 === v2) return 0
@@ -1056,8 +1057,8 @@ function getWeek(date: Date): number {
   return Math.round(diff / MILLISECONDS_IN_WEEK) + 1
 }
 
-function setWeek(date: Date, week: number, mutate = false): Date {
-  const d = mutate ? date : new Date(date)
+function setWeek(date: Date, week: number, opt: MutateOptions = {}): Date {
+  const d = opt.mutate ? date : new Date(date)
   const diff = getWeek(d) - week
   d.setDate(d.getDate() - diff * 7)
   return d
@@ -1069,7 +1070,7 @@ function startOfWeekYear(date: Date): Date {
   const fourthOfJanuary = new Date(0)
   fourthOfJanuary.setFullYear(year, 0, 4)
   fourthOfJanuary.setHours(0, 0, 0, 0)
-  return startOfWeek(fourthOfJanuary, true)
+  return startOfWeek(fourthOfJanuary, { mutate: true })
 }
 
 // based on: https://github.com/date-fns/date-fns/blob/fd6bb1a0bab143f2da068c05a9c562b9bee1357d/src/getISOWeekYear/index.ts
@@ -1079,12 +1080,12 @@ function getWeekYear(date: Date): number {
   const fourthOfJanuaryOfNextYear = new Date(0)
   fourthOfJanuaryOfNextYear.setFullYear(year + 1, 0, 4)
   fourthOfJanuaryOfNextYear.setHours(0, 0, 0, 0)
-  const startOfNextYear = startOfWeek(fourthOfJanuaryOfNextYear, true)
+  const startOfNextYear = startOfWeek(fourthOfJanuaryOfNextYear, { mutate: true })
 
   const fourthOfJanuaryOfThisYear = new Date(0)
   fourthOfJanuaryOfThisYear.setFullYear(year, 0, 4)
   fourthOfJanuaryOfThisYear.setHours(0, 0, 0, 0)
-  const startOfThisYear = startOfWeek(fourthOfJanuaryOfThisYear, true)
+  const startOfThisYear = startOfWeek(fourthOfJanuaryOfThisYear, { mutate: true })
 
   if (date.getTime() >= startOfNextYear.getTime()) {
     return year + 1
@@ -1096,8 +1097,8 @@ function getWeekYear(date: Date): number {
 }
 
 // based on: https://github.com/date-fns/date-fns/blob/fd6bb1a0bab143f2da068c05a9c562b9bee1357d/src/startOfWeek/index.ts
-function startOfWeek(date: Date, mutate = false): Date {
-  const d = mutate ? date : new Date(date)
+function startOfWeek(date: Date, opt: MutateOptions = {}): Date {
+  const d = opt.mutate ? date : new Date(date)
 
   const day = d.getDay()
   const diff = (day < weekStartsOn ? 7 : 0) + day - weekStartsOn
@@ -1108,8 +1109,8 @@ function startOfWeek(date: Date, mutate = false): Date {
 }
 
 // based on: https://github.com/date-fns/date-fns/blob/master/src/endOfWeek/index.ts
-function endOfWeek(date: Date, mutate = false): Date {
-  const d = mutate ? date : new Date(date)
+function endOfWeek(date: Date, opt: MutateOptions = {}): Date {
+  const d = opt.mutate ? date : new Date(date)
 
   const day = d.getDay()
   const diff = (day < weekStartsOn ? -7 : 0) + 6 - (day - weekStartsOn)
@@ -1118,8 +1119,8 @@ function endOfWeek(date: Date, mutate = false): Date {
   return d
 }
 
-function addMonths(d: Date, num: number, mutate = false): Date {
-  if (!mutate) d = new Date(d)
+function addMonths(d: Date, num: number, opt: MutateOptions = {}): Date {
+  if (!opt.mutate) d = new Date(d)
 
   let day = d.getDate()
   let month = d.getMonth() + 1 + num

package/src/log/commonLogger.ts

@@ -1,4 +1,6 @@
 // copy-pasted to avoid weird circular dependency
+import type { MutateOptions } from '../array/array.util.js'
+
 const _noop = (..._args: any[]): undefined => undefined
 
 /**
@@ -57,10 +59,10 @@ export const commonLoggerNoop: CommonLogger = {
 export function commonLoggerMinLevel(
   logger: CommonLogger,
   minLevel: CommonLogLevel,
-  mutate = false,
+  opt: MutateOptions = {},
 ): CommonLogger {
   const level = commonLogLevelNumber[minLevel]
-  if (mutate) {
+  if (opt.mutate) {
     if (level > commonLogLevelNumber['log']) {
       logger.log = _noop
       if (level > commonLogLevelNumber['warn']) {

package/src/number/number.util.ts

@@ -1,4 +1,5 @@
-import type { Inclusiveness, SortDirection } from '../types.js'
+import type { SortOptions } from '../array/array.util.js'
+import type { Inclusiveness } from '../types.js'
 
 export function _randomInt(minIncl: number, maxIncl: number): number {
   return Math.floor(Math.random() * (maxIncl - minIncl + 1) + minIncl)
@@ -63,13 +64,9 @@ export function _clamp(x: number, minIncl: number, maxIncl: number): number {
  * _sortNumbers([1, 3, 2])
  * // [1, 2, 3]
  */
-export function _sortNumbers(
-  numbers: number[],
-  mutate = false,
-  dir: SortDirection = 'asc',
-): number[] {
-  const mod = dir === 'desc' ? -1 : 1
-  return (mutate ? numbers : [...numbers]).sort((a, b) => (a - b) * mod)
+export function _sortNumbers(numbers: number[], opt: SortOptions = {}): number[] {
+  const mod = opt.dir === 'desc' ? -1 : 1
+  return (opt.mutate ? numbers : [...numbers]).sort((a, b) => (a - b) * mod)
 }
 
 /**

package/src/object/object.util.ts

@@ -6,6 +6,7 @@ import type {
   ObjectMapper,
   ObjectPredicate,
   Reviver,
+  StringMap,
   ValueOf,
 } from '../types.js'
 import { _objectEntries, SKIP } from '../types.js'
@@ -246,6 +247,24 @@ export function _deepCopy<T>(o: T, reviver?: Reviver): T {
   return JSON.parse(JSON.stringify(o), reviver)
 }
 
+/**
+ * Performance-optimized implementation of merging two objects
+ * without mutating any of them.
+ * (if you are allowed to mutate - there can be a faster implementation).
+ *
+ * Gives ~40% speedup with map sizes between 10 and 100k items,
+ * compared to {...obj1, ...obj2} or Object.assign({}, obj1, obj2).
+ *
+ * Only use it in hot paths that are known to be performance bottlenecks,
+ * otherwise it's not worth it (use normal object spread then).
+ */
+export function _mergeObjects<T>(obj1: StringMap<T>, obj2: StringMap<T>): StringMap<T> {
+  const map: StringMap<T> = {}
+  for (const k of Object.keys(obj1)) map[k] = obj1[k]
+  for (const k of Object.keys(obj2)) map[k] = obj2[k]
+  return map
+}
+
 /**
  * Returns `undefined` if it's empty (according to `_isEmpty()` specification),
  * otherwise returns the original object.

package/src/semver.ts

@@ -1,6 +1,6 @@
+import type { SortOptions } from './array/array.util.js'
 import { _range } from './array/range.js'
 import { _assert } from './error/assert.js'
-import type { SortDirection } from './types.js'
 
 export type SemverInput = string | Semver
 export type SemverInputNullable = SemverInput | null | undefined
@@ -134,9 +134,9 @@ class SemverFactory {
   /**
    * Sorts an array of Semvers in `dir` order (ascending by default).
    */
-  sort(items: Semver[], dir: SortDirection = 'asc', mutate = false): Semver[] {
-    const mod = dir === 'desc' ? -1 : 1
-    return (mutate ? items : [...items]).sort((a, b) => a.compare(b) * mod)
+  sort(items: Semver[], opt: SortOptions = {}): Semver[] {
+    const mod = opt.dir === 'desc' ? -1 : 1
+    return (opt.mutate ? items : [...items]).sort((a, b) => a.compare(b) * mod)
   }
 }