@naturalcycles/js-lib 15.8.0 → 15.9.0

package/dist/object/object.util.js

@@ -4,8 +4,8 @@ import { _objectEntries, SKIP } from '../types.js';
  * Returns clone of `obj` with only `props` preserved.
  * Opposite of Omit.
  */
-export function _pick(obj, props, mutate = false) {
-    if (mutate) {
+export function _pick(obj, props, opt = {}) {
+    if (opt.mutate) {
         // Start as original object (mutable), DELETE properties that are not whitelisted
         for (const k of Object.keys(obj)) {
             if (!props.includes(k))
@@ -25,8 +25,8 @@ export function _pick(obj, props, mutate = false) {
  * Sets all properties of an object except passed ones to `undefined`.
  * This is a more performant alternative to `_pick` that does picking/deleting.
  */
-export function _pickWithUndefined(obj, props, mutate = false) {
-    const r = mutate ? obj : { ...obj };
+export function _pickWithUndefined(obj, props, opt = {}) {
+    const r = opt.mutate ? obj : { ...obj };
     for (const k of Object.keys(r)) {
         if (!props.includes(k)) {
             r[k] = undefined;
@@ -38,8 +38,8 @@ export function _pickWithUndefined(obj, props, mutate = false) {
  * Returns clone of `obj` with `props` omitted.
  * Opposite of Pick.
  */
-export function _omit(obj, props, mutate = false) {
-    if (mutate) {
+export function _omit(obj, props, opt = {}) {
+    if (opt.mutate) {
         for (const k of props) {
             delete obj[k];
         }
@@ -56,8 +56,8 @@ export function _omit(obj, props, mutate = false) {
  * Sets all passed properties of an object to `undefined`.
  * This is a more performant alternative to `_omit` that does picking/deleting.
  */
-export function _omitWithUndefined(obj, props, mutate = false) {
-    const r = mutate ? obj : { ...obj };
+export function _omitWithUndefined(obj, props, opt = {}) {
+    const r = opt.mutate ? obj : { ...obj };
     for (const k of props) {
         r[k] = undefined;
     }
@@ -71,8 +71,8 @@ export function _omitWithUndefined(obj, props, mutate = false) {
  *  'account.updated',
  * ])
  */
-export function _mask(obj, props, mutate = false) {
-    const r = mutate ? obj : _deepCopy(obj);
+export function _mask(obj, props, opt = {}) {
+    const r = opt.mutate ? obj : _deepCopy(obj);
     for (const k of props) {
         _unset(r, k);
     }
@@ -81,31 +81,31 @@ export function _mask(obj, props, mutate = false) {
 /**
  * Removes "falsy" values from the object.
  */
-export function _filterFalsyValues(obj, mutate = false) {
-    return _filterObject(obj, (_k, v) => !!v, mutate);
+export function _filterFalsyValues(obj, opt = {}) {
+    return _filterObject(obj, (_k, v) => !!v, opt);
 }
 /**
  * Removes values from the object that are `null` or `undefined`.
  */
-export function _filterNullishValues(obj, mutate = false) {
-    return _filterObject(obj, (_k, v) => v !== undefined && v !== null, mutate);
+export function _filterNullishValues(obj, opt = {}) {
+    return _filterObject(obj, (_k, v) => v !== undefined && v !== null, opt);
 }
 /**
  * Removes values from the object that are `undefined`.
  * Only `undefined` values are removed. `null` values are kept!
  */
-export function _filterUndefinedValues(obj, mutate = false) {
-    return _filterObject(obj, (_k, v) => v !== undefined, mutate);
+export function _filterUndefinedValues(obj, opt = {}) {
+    return _filterObject(obj, (_k, v) => v !== undefined, opt);
 }
-export function _filterEmptyArrays(obj, mutate = false) {
-    return _filterObject(obj, (_k, v) => !Array.isArray(v) || v.length > 0, mutate);
+export function _filterEmptyArrays(obj, opt = {}) {
+    return _filterObject(obj, (_k, v) => !Array.isArray(v) || v.length > 0, opt);
 }
 /**
  * Returns clone of `obj` without properties that does not pass `predicate`.
  * Allows filtering by both key and value.
  */
-export function _filterObject(obj, predicate, mutate = false) {
-    if (mutate) {
+export function _filterObject(obj, predicate, opt = {}) {
+    if (opt.mutate) {
         for (const [k, v] of _objectEntries(obj)) {
             if (!predicate(k, v, obj)) {
                 delete obj[k];
@@ -132,8 +132,8 @@ export function _filterObject(obj, predicate, mutate = false) {
  *
  * To skip some key-value pairs - use _mapObject instead.
  */
-export function _mapValues(obj, mapper, mutate = false) {
-    const map = mutate ? obj : {};
+export function _mapValues(obj, mapper, opt = {}) {
+    const map = opt.mutate ? obj : {};
     for (const [k, v] of Object.entries(obj)) {
         map[k] = mapper(k, v, obj);
     }
@@ -183,8 +183,8 @@ export function _mapObject(obj, mapper) {
 export function _findKeyByValue(obj, v) {
     return Object.entries(obj).find(([_, value]) => value === v)?.[0];
 }
-export function _objectNullValuesToUndefined(obj, mutate = false) {
-    return _mapValues(obj, (_k, v) => (v === null ? undefined : v), mutate);
+export function _objectNullValuesToUndefined(obj, opt = {}) {
+    return _mapValues(obj, (_k, v) => (v === null ? undefined : v), opt);
 }
 /**
  * Deep copy object (by json parse/stringify, since it has unbeatable performance+simplicity combo).
@@ -202,8 +202,8 @@ export function _undefinedIfEmpty(obj) {
 /**
  * Filters the object by removing all key-value pairs where Value is Empty (according to _isEmpty() specification).
  */
-export function _filterEmptyValues(obj, mutate = false) {
-    return _filterObject(obj, (_k, v) => !_isEmpty(v), mutate);
+export function _filterEmptyValues(obj, opt = {}) {
+    return _filterObject(obj, (_k, v) => !_isEmpty(v), opt);
 }
 /**
  * Recursively merges own and inherited enumerable properties of source

package/dist/types.d.ts

@@ -117,10 +117,12 @@ export declare const MISS: unique symbol;
 /**
  * Function which is called for every item in `input`. Expected to return a `Promise` or value.
  */
-export type AsyncMapper<IN = any, OUT = any> = (input: IN, index: number) => OUT | PromiseLike<OUT>;
-export type Mapper<IN = any, OUT = any> = (input: IN, index: number) => OUT;
-export declare const _passthroughMapper: Mapper;
-export declare const _passUndefinedMapper: Mapper<any, void>;
+export type AsyncMapper<IN = any, OUT = any> = (input: IN) => OUT | PromiseLike<OUT>;
+export type AsyncIndexedMapper<IN = any, OUT = any> = (input: IN, index: number) => OUT | PromiseLike<OUT>;
+export type Mapper<IN = any, OUT = any> = (input: IN) => OUT;
+export type IndexedMapper<IN = any, OUT = any> = (input: IN, index: number) => OUT;
+export declare const _passthroughMapper: IndexedMapper;
+export declare const _passUndefinedMapper: IndexedMapper<any, void>;
 /**
  * Function that does nothings and returns `undefined`.
  */
@@ -326,7 +328,7 @@ export declare const _objectAssign: <T extends AnyObject>(target: T, part: Parti
  */
 export type ErrorDataTuple<T = unknown, ERR = Error> = [err: null, data: T] | [err: ERR, data: null];
 export type SortDirection = 'asc' | 'desc';
-export type Inclusiveness = '()' | '[]' | '[)' | '(]';
+export type Inclusiveness = '[]' | '[)';
 /**
  * @experimental
  */

package/dist/types.js

@@ -24,7 +24,7 @@ export const _passNothingPredicate = () => false;
  * Like _stringMapValues, but values are sorted.
  */
 export function _stringMapValuesSorted(map, mapper, dir = 'asc') {
-    return _sortBy(_stringMapValues(map), mapper, false, dir);
+    return _sortBy(_stringMapValues(map), mapper, { dir });
 }
 /**
  * Needed due to https://github.com/microsoft/TypeScript/issues/13778

package/package.json

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

package/src/array/array.util.ts

@@ -61,9 +61,9 @@ export function _pushUniq<T>(a: T[], ...items: T[]): T[] {
  * Mutates the array (same as normal `push`).
  */
 export function _pushUniqBy<T>(a: T[], mapper: Mapper<T, any>, ...items: T[]): T[] {
-  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)
@@ -91,8 +91,9 @@ export function _pushUniqBy<T>(a: T[], mapper: Mapper<T, any>, ...items: T[]): T
  */
 export function _uniqBy<T>(arr: readonly T[], mapper: Mapper<T, any>): T[] {
   const map = new Map<any, T>()
-  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)
   }
   return [...map.values()]
@@ -119,9 +120,16 @@ export function _uniqBy<T>(arr: readonly T[], mapper: Mapper<T, any>): T[] {
  * Returning `undefined` from the Mapper will EXCLUDE the item.
  */
 export function _by<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<T> {
-  return Object.fromEntries(
-    items.map((item, i) => [mapper(item, i), item]).filter(([k]) => k !== undefined) as [any, T][],
-  )
+  const map: StringMap<T> = {}
+  for (let i = 0; i < items.length; i++) {
+    const v = items[i]!
+    const k = mapper(v)
+    if (k !== undefined) {
+      map[k] = v
+    }
+  }
+
+  return map
 }
 
 /**
@@ -131,12 +139,15 @@ export function _mapBy<ITEM, KEY>(
   items: readonly ITEM[],
   mapper: Mapper<ITEM, KEY>,
 ): Map<KEY, ITEM> {
-  return new Map(
-    items.map((item, i) => [mapper(item, i), item]).filter(([k]) => k !== undefined) as [
-      KEY,
-      ITEM,
-    ][],
-  )
+  const map = new Map<KEY, ITEM>()
+  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
 }
 
 /**
@@ -152,14 +163,31 @@ export function _mapBy<ITEM, KEY>(
  */
 export function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): StringMap<T[]> {
   const map: StringMap<T[]> = {}
-  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
 }
 
+export interface MutateOptions {
+  /**
+   * Defaults to false.
+   */
+  mutate?: boolean
+}
+
+export interface SortByOptions extends MutateOptions {
+  /**
+   * Defaults to 'asc'.
+   */
+  dir?: SortDirection
+}
+
 /**
  * _sortBy([{age: 20}, {age: 10}], 'age')
  * // => [{age: 10}, {age: 20}]
@@ -167,34 +195,34 @@ export function _groupBy<T>(items: readonly T[], mapper: Mapper<T, any>): String
  * Same:
  * _sortBy([{age: 20}, {age: 10}], o => o.age)
  */
-export function _sortBy<T>(
+export function _sortBy<T, COMPARE_TYPE extends string | number>(
   items: T[],
-  mapper: Mapper<T, any>,
-  mutate = false,
-  dir: SortDirection = 'asc',
+  mapper: Mapper<T, COMPARE_TYPE>,
+  opt: SortByOptions = {},
 ): T[] {
-  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
+  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<T>(items: T[], mapper: Mapper<T, any>, mutate = false): T[] {
-  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<T>(items: readonly T[], predicate: AbortablePredicate<T>): T | undefined {
-  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
     if (result) return item
@@ -290,9 +318,8 @@ export function _count<T>(
 export function _countBy<T>(items: Iterable<T>, mapper: Mapper<T, any>): StringMap<number> {
   const map: StringMap<number> = {}
 
-  let i = 0
   for (const item of items) {
-    const key = mapper(item, i++)
+    const key = mapper(item)
     map[key] = (map[key] || 0) + 1
   }
 
@@ -360,10 +387,9 @@ export function _sumBy<T, N extends number>(
   mapper: Mapper<T, N | undefined>,
 ): N {
   let sum = 0 as N
-  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) as N
@@ -407,8 +433,8 @@ export function _mapToObject<T, V>(
  * Fisher–Yates algorithm.
  * Based on: https://stackoverflow.com/a/12646864/4919972
  */
-export function _shuffle<T>(array: T[], mutate = false): T[] {
-  const a = mutate ? array : [...array]
+export function _shuffle<T>(array: T[], opt: MutateOptions = {}): T[] {
+  const a = opt.mutate ? array : [...array]
 
   for (let i = a.length - 1; i > 0; i--) {
     const j = Math.floor(Math.random() * (i + 1))
@@ -505,8 +531,9 @@ export function _maxByOrUndefined<T>(
   let maxItem: T | undefined
   let max: number | string | undefined
 
-  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
@@ -524,8 +551,9 @@ export function _minByOrUndefined<T>(
   let minItem: T | undefined
   let min: number | string | undefined
 
-  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/src/array/range.ts

@@ -36,7 +36,7 @@ export function _range(fromIncl: Integer, toExcl?: Integer, step = 1): number[]
  * Fill is Primitive, because it's safe to shallow-copy.
  * If it was an object - it'll paste the same object reference, which can create bugs.
  */
-export function _rangeFilled<T extends Primitive>(length: Integer, fill: T): T[] {
+export function _arrayFilled<T extends Primitive>(length: Integer, fill: T): T[] {
   // biome-ignore lint/style/useConsistentBuiltinInstantiation: ok
   return Array(length).fill(fill)
 }

package/src/datetime/dateInterval.ts

@@ -1,4 +1,4 @@
-import type { Inclusiveness, IsoDate } from '../types.js'
+import type { IsoDate } from '../types.js'
 import type { LocalDate, LocalDateInput, LocalDateUnit } from './localDate.js'
 import { localDate } from './localDate.js'
 
@@ -60,16 +60,13 @@ export class DateInterval {
   /**
    * Ranges of DateInterval (start, end) are INCLUSIVE.
    */
-  includes(d: LocalDateInput, incl: Inclusiveness = '[]'): boolean {
-    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: LocalDateInput): boolean {
+    return localDate(d).isBetween(this.start, this.end, '[]')
   }
 
-  intersects(int: DateIntervalConfig, inclusive = true): boolean {
+  intersects(int: DateIntervalConfig): boolean {
     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)
   }
 
   /**
@@ -81,15 +78,15 @@ export class DateInterval {
     return this.start.compare(d.start) || this.end.compare(d.end)
   }
 
-  getDays(incl: Inclusiveness = '[]'): LocalDate[] {
-    return localDate.range(this.start, this.end, incl, 1, 'day')
+  getDays(): LocalDate[] {
+    return localDate.range(this.start, this.end, '[]', 1, 'day')
   }
 
   /**
    * Returns an array of LocalDates that are included in the interval.
    */
-  range(incl: Inclusiveness = '[]', step = 1, stepUnit: LocalDateUnit = 'day'): LocalDate[] {
-    return localDate.range(this.start, this.end, incl, step, stepUnit)
+  range(step = 1, stepUnit: LocalDateUnit = 'day'): LocalDate[] {
+    return localDate.range(this.start, this.end, '[]', step, stepUnit)
   }
 
   toString(): DateIntervalString {

package/src/datetime/localDate.ts

@@ -117,10 +117,9 @@ export class LocalDate {
     return this.compare(d) >= 0
   }
 
-  isBetween(min: LocalDateInput, max: LocalDateInput, incl: Inclusiveness = '[)'): boolean {
+  isBetween(min: LocalDateInput, max: LocalDateInput, incl: Inclusiveness): boolean {
     let r = this.compare(min)
-    // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
-    if (r < 0 || (r === 0 && incl[0] === '(')) return false
+    if (r < 0) return false
     r = this.compare(max)
     if (r > 0 || (r === 0 && incl[1] === ')')) return false
     return true
@@ -779,7 +778,7 @@ class LocalDateFactory {
   range(
     min: LocalDateInput,
     max: LocalDateInput,
-    incl: Inclusiveness = '[)',
+    incl: Inclusiveness,
     step = 1,
     stepUnit: LocalDateUnit = 'day',
   ): LocalDate[] {
@@ -793,7 +792,7 @@ class LocalDateFactory {
   rangeIterable(
     min: LocalDateInput,
     max: LocalDateInput,
-    incl: Inclusiveness = '[)',
+    incl: Inclusiveness,
     step = 1,
     stepUnit: LocalDateUnit = 'day',
   ): Iterable2<LocalDate> {
@@ -806,8 +805,8 @@ class LocalDateFactory {
     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)

package/src/datetime/localTime.ts

@@ -517,10 +517,9 @@ export class LocalTime {
     return this.compare(d) >= 0
   }
 
-  isBetween(min: LocalTimeInput, max: LocalTimeInput, incl: Inclusiveness = '[)'): boolean {
+  isBetween(min: LocalTimeInput, max: LocalTimeInput, incl: Inclusiveness): boolean {
     let r = this.compare(min)
-    // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
-    if (r < 0 || (r === 0 && incl[0] === '(')) return false
+    if (r < 0) return false
     r = this.compare(max)
     if (r > 0 || (r === 0 && incl[1] === ')')) return false
     return true

package/src/datetime/timeInterval.ts

@@ -1,4 +1,4 @@
-import type { Inclusiveness, UnixTimestamp } from '../types.js'
+import type { UnixTimestamp } from '../types.js'
 import type { LocalTime, LocalTimeInput } from './localTime.js'
 import { localTime } from './localTime.js'
 
@@ -74,11 +74,10 @@ export class TimeInterval {
     return this.cmp(d) >= 0
   }
 
-  includes(d: LocalTimeInput, incl: Inclusiveness = '[)'): boolean {
+  includes(d: LocalTimeInput): boolean {
     d = localTime.fromInput(d).unix
-    // eslint-disable-next-line @typescript-eslint/prefer-string-starts-ends-with
-    if (d < this.$start || (d === this.$start && incl[0] === '(')) return false
-    if (d > this.$end || (d === this.$end && incl[1] === ')')) return false
+    if (d < this.$start) return false
+    if (d > this.$end) return false
     return true
   }
 

package/src/http/fetcher.ts

@@ -803,7 +803,7 @@ export class Fetcher {
     }
 
     // Because all header values are stringified, so `a: undefined` becomes `undefined` as a string
-    _filterNullishValues(req.init.headers, true)
+    _filterNullishValues(req.init.headers, { mutate: true })
 
     // setup url
     const baseUrl = opt.baseUrl || this.cfg.baseUrl

package/src/json-schema/jsonSchema.util.ts

@@ -32,5 +32,5 @@ export function mergeJsonSchemaObjects<T1 extends AnyObject, T2 extends AnyObjec
 
   // `additionalProperties` remains the same
 
-  return _filterNullishValues(s1, true) as any
+  return _filterNullishValues(s1, { mutate: true }) as any
 }

package/src/math/math.util.ts

@@ -29,7 +29,6 @@ export function _averageOrNull(values: number[] | undefined | null): number | nu
 export function _averageWeighted(values: number[], weights: number[]): number {
   let numerator = 0
   let denominator = 0
-  // eslint-disable-next-line unicorn/no-for-loop
   for (let i = 0; i < values.length; i++) {
     numerator += values[i]! * weights[i]!
     denominator += weights[i]!

package/src/number/number.util.ts

@@ -42,18 +42,11 @@ export function _isBetween<T extends number | string>(
   x: T,
   min: T,
   max: T,
-  incl: Inclusiveness = '[)',
+  incl: Inclusiveness,
 ): boolean {
-  if (incl === '[)') {
-    return x >= min && x < max
-  }
-  if (incl === '[]') {
-    return x >= min && x <= max
-  }
-  if (incl === '(]') {
-    return x > min && x <= max
-  }
-  return x > min && x < max
+  if (x < min || x > max) return false
+  if (x === max && incl === '[)') return false
+  return true
 }
 
 export function _clamp(x: number, minIncl: number, maxIncl: number): number {