@naturalcycles/js-lib 15.8.1 → 15.9.1

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

@@ -90,6 +90,18 @@ export declare function _mapBy<ITEM, KEY>(items: readonly ITEM[], mapper: Mapper
  * Returning `undefined` from the Mapper will EXCLUDE the item.
  */
 export declare function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<T[]>;
+export interface MutateOptions {
+    /**
+     * Defaults to false.
+     */
+    mutate?: boolean;
+}
+export interface SortOptions extends MutateOptions {
+    /**
+     * Defaults to 'asc'.
+     */
+    dir?: SortDirection;
+}
 /**
  * _sortBy([{age: 20}, {age: 10}], 'age')
  * // => [{age: 10}, {age: 20}]
@@ -97,11 +109,7 @@ export declare function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>)
  * Same:
  * _sortBy([{age: 20}, {age: 10}], o => o.age)
  */
-export declare function _sortBy<T>(items: T[], mapper: Mapper<T, any>, mutate?: boolean, dir?: SortDirection): T[];
-/**
- * Alias for _sortBy with descending order.
- */
-export declare function _sortDescBy<T>(items: T[], mapper: Mapper<T, any>, mutate?: boolean): 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.
  *
@@ -194,7 +202,7 @@ export declare function _mapToObject<T, V>(array: Iterable<T>, mapper: (item: T)
  * Fisher–Yates algorithm.
  * Based on: https://stackoverflow.com/a/12646864/4919972
  */
-export declare function _shuffle<T>(array: T[], mutate?: boolean): T[];
+export declare function _shuffle<T>(array: T[], opt?: MutateOptions): T[];
 /**
  * Returns last item of non-empty array.
  * Throws if array is empty.

package/dist/array/array.util.js

@@ -50,9 +50,9 @@ export function _pushUniq(a, ...items) {
  * Mutates the array (same as normal `push`).
  */
 export function _pushUniqBy(a, mapper, ...items) {
-    const mappedSet = new Set(a.map((item, i) => mapper(item, i)));
-    items.forEach((item, i) => {
-        const mapped = mapper(item, i);
+    const mappedSet = new Set(a.map(mapper));
+    items.forEach(item => {
+        const mapped = mapper(item);
         if (!mappedSet.has(mapped)) {
             a.push(item);
             mappedSet.add(mapped);
@@ -79,8 +79,9 @@ export function _pushUniqBy(a, mapper, ...items) {
  */
 export function _uniqBy(arr, mapper) {
     const map = new Map();
-    for (const [i, item] of arr.entries()) {
-        const key = item === undefined || item === null ? item : mapper(item, i);
+    for (let i = 0; i < arr.length; i++) {
+        const item = arr[i];
+        const key = item === undefined || item === null ? item : mapper(item);
         if (!map.has(key))
             map.set(key, item);
     }
@@ -107,13 +108,29 @@ export function _uniqBy(arr, mapper) {
  * Returning `undefined` from the Mapper will EXCLUDE the item.
  */
 export function _by(items, mapper) {
-    return Object.fromEntries(items.map((item, i) => [mapper(item, i), item]).filter(([k]) => k !== undefined));
+    const map = {};
+    for (let i = 0; i < items.length; i++) {
+        const v = items[i];
+        const k = mapper(v);
+        if (k !== undefined) {
+            map[k] = v;
+        }
+    }
+    return map;
 }
 /**
  * Map an array of items by a key, that is calculated by a Mapper.
  */
 export function _mapBy(items, mapper) {
-    return new Map(items.map((item, i) => [mapper(item, i), item]).filter(([k]) => k !== undefined));
+    const map = new Map();
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        const key = mapper(item);
+        if (key !== undefined) {
+            map.set(key, item);
+        }
+    }
+    return map;
 }
 /**
  * const a = [1, 2, 3, 4, 5]
@@ -128,11 +145,13 @@ export function _mapBy(items, mapper) {
  */
 export function _groupBy(items, mapper) {
     const map = {};
-    for (const [i, item] of items.entries()) {
-        const key = mapper(item, i);
-        if (key === undefined)
-            continue;
-        (map[key] ||= []).push(item);
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        const key = mapper(item);
+        if (key !== undefined) {
+            ;
+            (map[key] ||= []).push(item);
+        }
     }
     return map;
 }
@@ -143,28 +162,30 @@ export function _groupBy(items, mapper) {
  * Same:
  * _sortBy([{age: 20}, {age: 10}], o => o.age)
  */
-export function _sortBy(items, mapper, mutate = false, dir = 'asc') {
-    const mod = dir === 'desc' ? -1 : 1;
-    return (mutate ? items : [...items]).sort((_a, _b) => {
-        const [a, b] = [_a, _b].map(mapper);
-        if (typeof a === 'number' && typeof b === 'number')
-            return (a - b) * mod;
-        return String(a).localeCompare(String(b)) * mod;
+export function _sortBy(items, mapper, opt = {}) {
+    const mod = opt.dir === 'desc' ? -1 : 1;
+    return (opt.mutate ? items : [...items]).sort((_a, _b) => {
+        // This implementation may call mapper more than once per item,
+        // but the benchmarks show no significant difference in performance.
+        const a = mapper(_a);
+        const b = mapper(_b);
+        // if (typeof a === 'number' && typeof b === 'number') return (a - b) * mod
+        // return String(a).localeCompare(String(b)) * mod
+        if (a > b)
+            return mod;
+        if (a < b)
+            return -mod;
+        return 0;
     });
 }
-/**
- * Alias for _sortBy with descending order.
- */
-export function _sortDescBy(items, mapper, mutate = false) {
-    return _sortBy(items, mapper, mutate, 'desc');
-}
 /**
  * Similar to `Array.find`, but the `predicate` may return `END` to stop the iteration early.
  *
  * Use `Array.find` if you don't need to stop the iteration early.
  */
 export function _find(items, predicate) {
-    for (const [i, item] of items.entries()) {
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
         const result = predicate(item, i);
         if (result === END)
             return;
@@ -241,9 +262,8 @@ export function _count(items, predicate, limit) {
 }
 export function _countBy(items, mapper) {
     const map = {};
-    let i = 0;
     for (const item of items) {
-        const key = mapper(item, i++);
+        const key = mapper(item);
         map[key] = (map[key] || 0) + 1;
     }
     return map;
@@ -301,9 +321,8 @@ export function _sum(items) {
 }
 export function _sumBy(items, mapper) {
     let sum = 0;
-    let i = 0;
     for (const n of items) {
-        const v = mapper(n, i++);
+        const v = mapper(n);
         if (typeof v === 'number') {
             // count only numbers, nothing else
             sum = (sum + v);
@@ -339,8 +358,8 @@ export function _mapToObject(array, mapper) {
  * Fisher–Yates algorithm.
  * Based on: https://stackoverflow.com/a/12646864/4919972
  */
-export function _shuffle(array, mutate = false) {
-    const a = mutate ? array : [...array];
+export function _shuffle(array, opt = {}) {
+    const a = opt.mutate ? array : [...array];
     for (let i = a.length - 1; i > 0; i--) {
         const j = Math.floor(Math.random() * (i + 1));
         [a[i], a[j]] = [a[j], a[i]];
@@ -425,8 +444,9 @@ export function _maxByOrUndefined(array, mapper) {
         return;
     let maxItem;
     let max;
-    for (const [i, item] of array.entries()) {
-        const v = mapper(item, i);
+    for (let i = 0; i < array.length; i++) {
+        const item = array[i];
+        const v = mapper(item);
         if (v !== undefined && (max === undefined || v > max)) {
             maxItem = item;
             max = v;
@@ -439,8 +459,9 @@ export function _minByOrUndefined(array, mapper) {
         return;
     let minItem;
     let min;
-    for (const [i, item] of array.entries()) {
-        const v = mapper(item, i);
+    for (let i = 0; i < array.length; i++) {
+        const item = array[i];
+        const v = mapper(item);
         if (v !== undefined && (min === undefined || v < min)) {
             minItem = item;
             min = v;

package/dist/datetime/dateInterval.d.ts

@@ -1,4 +1,3 @@
-import type { Inclusiveness } from '../types.js';
 import type { LocalDate, LocalDateInput, LocalDateUnit } from './localDate.js';
 export type DateIntervalConfig = DateInterval | DateIntervalString;
 export type DateIntervalString = string;
@@ -24,18 +23,18 @@ export declare class DateInterval {
     /**
      * Ranges of DateInterval (start, end) are INCLUSIVE.
      */
-    includes(d: LocalDateInput, incl?: Inclusiveness): boolean;
-    intersects(int: DateIntervalConfig, inclusive?: boolean): boolean;
+    includes(d: LocalDateInput): boolean;
+    intersects(int: DateIntervalConfig): boolean;
     /**
      * DateIntervals compare by start date.
      * If it's the same - then by end date.
      */
     cmp(d: DateIntervalConfig): -1 | 0 | 1;
-    getDays(incl?: Inclusiveness): LocalDate[];
+    getDays(): LocalDate[];
     /**
      * Returns an array of LocalDates that are included in the interval.
      */
-    range(incl?: Inclusiveness, step?: number, stepUnit?: LocalDateUnit): LocalDate[];
+    range(step?: number, stepUnit?: LocalDateUnit): LocalDate[];
     toString(): DateIntervalString;
     toJSON(): DateIntervalString;
 }

package/dist/datetime/dateInterval.js

@@ -46,15 +46,12 @@ export class DateInterval {
     /**
      * Ranges of DateInterval (start, end) are INCLUSIVE.
      */
-    includes(d, incl = '[]') {
-        d = localDate(d);
-        // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
-        return d.isAfter(this.start, incl[0] === '[') && d.isBefore(this.end, incl[1] === ']');
+    includes(d) {
+        return localDate(d).isBetween(this.start, this.end, '[]');
     }
-    intersects(int, inclusive = true) {
+    intersects(int) {
         const $int = DateInterval.parse(int);
-        const incl = inclusive ? '[]' : '()';
-        return this.includes($int.start, incl) || this.includes($int.end, incl);
+        return this.includes($int.start) || this.includes($int.end);
     }
     /**
      * DateIntervals compare by start date.
@@ -64,14 +61,14 @@ export class DateInterval {
         d = DateInterval.parse(d);
         return this.start.compare(d.start) || this.end.compare(d.end);
     }
-    getDays(incl = '[]') {
-        return localDate.range(this.start, this.end, incl, 1, 'day');
+    getDays() {
+        return localDate.range(this.start, this.end, '[]', 1, 'day');
     }
     /**
      * Returns an array of LocalDates that are included in the interval.
      */
-    range(incl = '[]', step = 1, stepUnit = 'day') {
-        return localDate.range(this.start, this.end, incl, step, stepUnit);
+    range(step = 1, stepUnit = 'day') {
+        return localDate.range(this.start, this.end, '[]', step, stepUnit);
     }
     toString() {
         return [this.start, this.end].join('/');

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;
@@ -38,7 +39,7 @@ export declare class LocalDate {
     isSameOrBefore(d: LocalDateInput): boolean;
     isAfter(d: LocalDateInput, inclusive?: boolean): boolean;
     isSameOrAfter(d: LocalDateInput): boolean;
-    isBetween(min: LocalDateInput, max: LocalDateInput, incl?: Inclusiveness): boolean;
+    isBetween(min: LocalDateInput, max: LocalDateInput, incl: Inclusiveness): boolean;
     /**
      * Checks if this localDate is older (<) than "today" by X units.
      *
@@ -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.
      */
@@ -269,12 +270,12 @@ declare class LocalDateFactory {
      * Returns the range (array) of LocalDates between min and max.
      * By default, min is included, max is excluded.
      */
-    range(min: LocalDateInput, max: LocalDateInput, incl?: Inclusiveness, step?: number, stepUnit?: LocalDateUnit): LocalDate[];
+    range(min: LocalDateInput, max: LocalDateInput, incl: Inclusiveness, step?: number, stepUnit?: LocalDateUnit): LocalDate[];
     /**
      * Returns the Iterable2 of LocalDates between min and max.
      * By default, min is included, max is excluded.
      */
-    rangeIterable(min: LocalDateInput, max: LocalDateInput, incl?: Inclusiveness, step?: number, stepUnit?: LocalDateUnit): Iterable2<LocalDate>;
+    rangeIterable(min: LocalDateInput, max: LocalDateInput, incl: Inclusiveness, step?: number, stepUnit?: LocalDateUnit): Iterable2<LocalDate>;
     getYearLength(year: number): number;
     getMonthLength(year: number, month: number): number;
     isLeapYear(year: number): boolean;

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;
         }
@@ -88,10 +88,9 @@ export class LocalDate {
     isSameOrAfter(d) {
         return this.compare(d) >= 0;
     }
-    isBetween(min, max, incl = '[)') {
+    isBetween(min, max, incl) {
         let r = this.compare(min);
-        // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
-        if (r < 0 || (r === 0 && incl[0] === '('))
+        if (r < 0)
             return false;
         r = this.compare(max);
         if (r > 0 || (r === 0 && incl[1] === ')'))
@@ -267,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') {
@@ -324,7 +323,7 @@ export class LocalDate {
                 }
             }
         }
-        if (mutate) {
+        if (opt.mutate) {
             this.year = year;
             this.month = month;
             this.day = day;
@@ -332,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')
@@ -613,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.
@@ -669,14 +668,14 @@ class LocalDateFactory {
      * Returns the range (array) of LocalDates between min and max.
      * By default, min is included, max is excluded.
      */
-    range(min, max, incl = '[)', step = 1, stepUnit = 'day') {
+    range(min, max, incl, step = 1, stepUnit = 'day') {
         return this.rangeIterable(min, max, incl, step, stepUnit).toArray();
     }
     /**
      * Returns the Iterable2 of LocalDates between min and max.
      * By default, min is included, max is excluded.
      */
-    rangeIterable(min, max, incl = '[)', step = 1, stepUnit = 'day') {
+    rangeIterable(min, max, incl, step = 1, stepUnit = 'day') {
         if (stepUnit === 'week') {
             step *= 7;
             stepUnit = 'day';
@@ -684,12 +683,11 @@ class LocalDateFactory {
         const $min = this.fromInput(min).startOf(stepUnit);
         const $max = this.fromInput(max).startOf(stepUnit);
         let value = $min;
-        // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
-        if (value.isAfter($min, incl[0] === '[')) {
+        if (value.isSameOrAfter($min)) {
             // 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.
@@ -148,7 +149,7 @@ export declare class LocalTime {
     isSameOrBefore(d: LocalTimeInput): boolean;
     isAfter(d: LocalTimeInput, inclusive?: boolean): boolean;
     isSameOrAfter(d: LocalTimeInput): boolean;
-    isBetween(min: LocalTimeInput, max: LocalTimeInput, incl?: Inclusiveness): boolean;
+    isBetween(min: LocalTimeInput, max: LocalTimeInput, incl: Inclusiveness): boolean;
     /**
      * Checks if this localTime is older (<) than "now" by X units.
      *
@@ -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;