@naturalcycles/js-lib 14.95.1 → 14.97.0

package/src/datetime/localDate.ts

@@ -1,6 +1,6 @@
 import { _assert } from '../error/assert'
 import { Sequence } from '../seq/seq'
-import { END, IsoDate, UnixTimestamp } from '../types'
+import { END, IsoDateString, UnixTimestampNumber } from '../types'
 import { LocalTime } from './localTime'
 
 export type LocalDateUnit = 'year' | 'month' | 'day'
@@ -10,11 +10,13 @@ const m31 = new Set<number>([1, 3, 5, 7, 8, 10, 12])
 
 export type LocalDateConfig = LocalDate | string
 
+/* eslint-disable no-dupe-class-members */
+
 /**
  * @experimental
  */
 export class LocalDate {
-  private constructor(public year: number, public month: number, public day: number) {}
+  private constructor(private $year: number, private $month: number, private $day: number) {}
 
   static create(year: number, month: number, day: number): LocalDate {
     return new LocalDate(year, month, day)
@@ -151,7 +153,7 @@ export class LocalDate {
     maxExcl: LocalDateConfig,
     step = 1,
     stepUnit: LocalDateUnit = 'day',
-  ): IsoDate[] {
+  ): IsoDateString[] {
     return LocalDate.range(minIncl, maxExcl, step, stepUnit).map(ld => ld.toString())
   }
 
@@ -169,15 +171,49 @@ export class LocalDate {
     maxIncl: LocalDateConfig,
     step = 1,
     stepUnit: LocalDateUnit = 'day',
-  ): IsoDate[] {
+  ): IsoDateString[] {
     return LocalDate.range(minIncl, LocalDate.of(maxIncl).add(1, stepUnit), step, stepUnit).map(
       ld => ld.toString(),
     )
   }
 
+  get(unit: LocalDateUnit): number {
+    return unit === 'year' ? this.$year : unit === 'month' ? this.$month : this.$day
+  }
+
+  set(unit: LocalDateUnit, v: number, mutate = false): LocalDate {
+    const t = mutate ? this : this.clone()
+
+    if (unit === 'year') {
+      t.$year = v
+    } else if (unit === 'month') {
+      t.$month = v
+    } else {
+      t.$day = v
+    }
+
+    return t
+  }
+
+  year(): number
+  year(v: number): LocalDate
+  year(v?: number): number | LocalDate {
+    return v === undefined ? this.$year : this.set('year', v)
+  }
+  month(): number
+  month(v: number): LocalDate
+  month(v?: number): number | LocalDate {
+    return v === undefined ? this.$month : this.set('month', v)
+  }
+  day(): number
+  day(v: number): LocalDate
+  day(v?: number): number | LocalDate {
+    return v === undefined ? this.$day : this.set('day', v)
+  }
+
   isSame(d: LocalDateConfig): boolean {
     d = LocalDate.of(d)
-    return this.day === d.day && this.month === d.month && this.year === d.year
+    return this.$day === d.$day && this.$month === d.$month && this.$year === d.$year
   }
 
   isBefore(d: LocalDateConfig): boolean {
@@ -211,12 +247,12 @@ export class LocalDate {
    */
   cmp(d: LocalDateConfig): -1 | 0 | 1 {
     d = LocalDate.of(d)
-    if (this.year < d.year) return -1
-    if (this.year > d.year) return 1
-    if (this.month < d.month) return -1
-    if (this.month > d.month) return 1
-    if (this.day < d.day) return -1
-    if (this.day > d.day) return 1
+    if (this.$year < d.$year) return -1
+    if (this.$year > d.$year) return 1
+    if (this.$month < d.$month) return -1
+    if (this.$month > d.$month) return 1
+    if (this.$day < d.$day) return -1
+    if (this.$day > d.$day) return 1
     return 0
   }
 
@@ -236,33 +272,33 @@ export class LocalDate {
     d = LocalDate.of(d)
 
     if (unit === 'year') {
-      return this.year - d.year
+      return this.$year - d.$year
     }
 
     if (unit === 'month') {
-      return (this.year - d.year) * 12 + (this.month - d.month)
+      return (this.$year - d.$year) * 12 + (this.$month - d.$month)
     }
 
     // unit is 'day'
-    let days = this.day - d.day
+    let days = this.$day - d.$day
 
-    if (d.year < this.year) {
-      for (let year = d.year; year < this.year; year++) {
+    if (d.$year < this.$year) {
+      for (let year = d.$year; year < this.$year; year++) {
         days += LocalDate.getYearLength(year)
       }
-    } else if (this.year < d.year) {
-      for (let year = this.year; year < d.year; year++) {
+    } else if (this.$year < d.$year) {
+      for (let year = this.$year; year < d.$year; year++) {
         days -= LocalDate.getYearLength(year)
       }
     }
 
-    if (d.month < this.month) {
-      for (let month = d.month; month < this.month; month++) {
-        days += LocalDate.getMonthLength(this.year, month)
+    if (d.$month < this.$month) {
+      for (let month = d.$month; month < this.$month; month++) {
+        days += LocalDate.getMonthLength(this.$year, month)
       }
-    } else if (this.month < d.month) {
-      for (let month = this.month; month < d.month; month++) {
-        days -= LocalDate.getMonthLength(d.year, month)
+    } else if (this.$month < d.$month) {
+      for (let month = this.$month; month < d.$month; month++) {
+        days -= LocalDate.getMonthLength(d.$year, month)
       }
     }
 
@@ -270,57 +306,57 @@ export class LocalDate {
   }
 
   add(num: number, unit: LocalDateUnit, mutate = false): LocalDate {
-    let { day, month, year } = this
+    let { $day, $month, $year } = this
 
     if (unit === 'day') {
-      day += num
+      $day += num
     } else if (unit === 'month') {
-      month += num
+      $month += num
     } else if (unit === 'year') {
-      year += num
+      $year += num
     }
 
     // check day overflow
-    let monLen = LocalDate.getMonthLength(year, month)
-    while (day > monLen) {
-      day -= monLen
-      month += 1
-      if (month > 12) {
-        year += 1
-        month -= 12
+    let monLen = LocalDate.getMonthLength($year, $month)
+    while ($day > monLen) {
+      $day -= monLen
+      $month += 1
+      if ($month > 12) {
+        $year += 1
+        $month -= 12
       }
 
-      monLen = LocalDate.getMonthLength(year, month)
+      monLen = LocalDate.getMonthLength($year, $month)
     }
-    while (day < 1) {
-      day += monLen
-      month -= 1
-      if (month < 1) {
-        year -= 1
-        month += 12
+    while ($day < 1) {
+      $day += monLen
+      $month -= 1
+      if ($month < 1) {
+        $year -= 1
+        $month += 12
       }
 
-      monLen = LocalDate.getMonthLength(year, month)
+      monLen = LocalDate.getMonthLength($year, $month)
     }
 
     // check month overflow
-    while (month > 12) {
-      year += 1
-      month -= 12
+    while ($month > 12) {
+      $year += 1
+      $month -= 12
     }
-    while (month < 1) {
-      year -= 1
-      month += 12
+    while ($month < 1) {
+      $year -= 1
+      $month += 12
     }
 
     if (mutate) {
-      this.year = year
-      this.month = month
-      this.day = day
+      this.$year = $year
+      this.$month = $month
+      this.$day = $day
       return this
     }
 
-    return new LocalDate(year, month, day)
+    return new LocalDate($year, $month, $day)
   }
 
   subtract(num: number, unit: LocalDateUnit, mutate = false): LocalDate {
@@ -329,21 +365,21 @@ export class LocalDate {
 
   startOf(unit: LocalDateUnit): LocalDate {
     if (unit === 'day') return this
-    if (unit === 'month') return LocalDate.create(this.year, this.month, 1)
+    if (unit === 'month') return LocalDate.create(this.$year, this.$month, 1)
     // year
-    return LocalDate.create(this.year, 1, 1)
+    return LocalDate.create(this.$year, 1, 1)
   }
 
   endOf(unit: LocalDateUnit): LocalDate {
     if (unit === 'day') return this
     if (unit === 'month')
       return LocalDate.create(
-        this.year,
-        this.month,
-        LocalDate.getMonthLength(this.year, this.month),
+        this.$year,
+        this.$month,
+        LocalDate.getMonthLength(this.$year, this.$month),
       )
     // year
-    return LocalDate.create(this.year, 12, 31)
+    return LocalDate.create(this.$year, 12, 31)
   }
 
   static getYearLength(year: number): number {
@@ -362,7 +398,7 @@ export class LocalDate {
   }
 
   clone(): LocalDate {
-    return new LocalDate(this.year, this.month, this.day)
+    return new LocalDate(this.$year, this.$month, this.$day)
   }
 
   /**
@@ -372,35 +408,35 @@ export class LocalDate {
    * Timezone will match local timezone.
    */
   toDate(): Date {
-    return new Date(this.year, this.month - 1, this.day)
+    return new Date(this.$year, this.$month - 1, this.$day)
   }
 
   toLocalTime(): LocalTime {
     return LocalTime.of(this.toDate())
   }
 
-  toISODate(): IsoDate {
+  toISODate(): IsoDateString {
     return this.toString()
   }
 
-  toString(): IsoDate {
+  toString(): IsoDateString {
     return [
-      String(this.year).padStart(4, '0'),
-      String(this.month).padStart(2, '0'),
-      String(this.day).padStart(2, '0'),
+      String(this.$year).padStart(4, '0'),
+      String(this.$month).padStart(2, '0'),
+      String(this.$day).padStart(2, '0'),
     ].join('-')
   }
 
   toStringCompact(): string {
     return [
-      String(this.year).padStart(4, '0'),
-      String(this.month).padStart(2, '0'),
-      String(this.day).padStart(2, '0'),
+      String(this.$year).padStart(4, '0'),
+      String(this.$month).padStart(2, '0'),
+      String(this.$day).padStart(2, '0'),
     ].join('')
   }
 
   // May be not optimal, as LocalTime better suits it
-  unix(): UnixTimestamp {
+  unix(): UnixTimestampNumber {
     return Math.floor(this.toDate().valueOf() / 1000)
   }
 
@@ -408,7 +444,7 @@ export class LocalDate {
     return this.toDate().valueOf()
   }
 
-  toJSON(): IsoDate {
+  toJSON(): IsoDateString {
     return this.toString()
   }
 }

package/src/datetime/localTime.ts

@@ -1,11 +1,11 @@
 import { _assert } from '../error/assert'
 import { _ms } from '../time/time.util'
-import { IsoDate, IsoDateTime, UnixTimestamp } from '../types'
+import { IsoDateString, IsoDateTimeString, UnixTimestampNumber } from '../types'
 import { Inclusiveness, LocalDate } from './localDate'
 
 export type LocalTimeUnit = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second'
 
-export type LocalTimeConfig = LocalTime | Date | IsoDateTime | UnixTimestamp
+export type LocalTimeConfig = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber
 
 export interface LocalTimeComponents {
   year: number
@@ -18,18 +18,6 @@ export interface LocalTimeComponents {
 
 /* eslint-disable no-dupe-class-members */
 
-// Design choices:
-// No milliseconds
-// No timezone support, ISO8601 is parsed as LocalDateTime, discarding Timezone information
-// Formats as unix timestamp, ISO8601 or "pretty string"
-// toString and .toJSON formats as unix timestamp
-// No "unixMillis", just pure unixtimestamp
-// .valueOf returns unix timestamp (no millis)
-// Prevents dayjs(undefined) being dayjs.now()
-// Validates on parse, throws if invalid. Doesn't allow invalid objects
-// No arbitrary .format('') (which is slow to parse) vs well-defined (opinionated) formats
-// Separate LocalTime, powered by native js Date, and LocalDate - a smaller functionality class when
-// you only need "whole dates", no time, no timezone worry
 /**
  * @experimental
  */
@@ -156,9 +144,9 @@ export class LocalTime {
   month(v?: number): number | LocalTime {
     return v === undefined ? this.get('month') : this.set('month', v)
   }
-  date(): number
-  date(v: number): LocalTime
-  date(v?: number): number | LocalTime {
+  day(): number
+  day(v: number): LocalTime
+  day(v?: number): number | LocalTime {
     return v === undefined ? this.get('day') : this.set('day', v)
   }
   hour(): number
@@ -387,7 +375,7 @@ export class LocalTime {
     return new LocalTime(new Date(this.$date), this.utcMode)
   }
 
-  unix(): UnixTimestamp {
+  unix(): UnixTimestampNumber {
     return Math.floor(this.$date.valueOf() / 1000)
   }
 
@@ -395,7 +383,7 @@ export class LocalTime {
     return this.$date.valueOf()
   }
 
-  valueOf(): UnixTimestamp {
+  valueOf(): UnixTimestampNumber {
     return Math.floor(this.$date.valueOf() / 1000)
   }
 
@@ -415,7 +403,7 @@ export class LocalTime {
     )
   }
 
-  toPretty(seconds = true): IsoDateTime {
+  toPretty(seconds = true): IsoDateTimeString {
     const { year, month, day, hour, minute, second } = this.components()
 
     return (
@@ -444,14 +432,14 @@ export class LocalTime {
   /**
    * Returns e.g: `1984-06-21T17:56:21`, only the date part of DateTime
    */
-  toISODateTime(): IsoDateTime {
+  toISODateTime(): IsoDateTimeString {
     return this.$date.toISOString().slice(0, 19)
   }
 
   /**
    * Returns e.g: `1984-06-21`, only the date part of DateTime
    */
-  toISODate(): IsoDate {
+  toISODate(): IsoDateString {
     const { year, month, day } = this.components()
 
     return [
@@ -500,7 +488,7 @@ export class LocalTime {
     return String(this.unix())
   }
 
-  toJSON(): UnixTimestamp {
+  toJSON(): UnixTimestampNumber {
     return this.unix()
   }
 }

package/src/error/try.ts

@@ -6,18 +6,24 @@ import { AppError } from './app.error'
  * Allows to write shorter code that avoids `try/catch`.
  * Useful e.g. in unit tests.
  *
- * Similar to pTuple, but for sync functions.
+ * Similar to pTry, but for sync functions.
  *
  * For convenience, second argument type is non-optional,
  * so you can use it without `!`. But you SHOULD always check `if (err)` first!
  *
+ * ERR is typed as Error, not `unknown`. While unknown would be more correct,
+ * according to recent TypeScript, Error gives more developer convenience.
+ * In our code we NEVER throw non-errors.
+ * Only possibility of non-error is in the 3rd-party library code, in these cases it
+ * can be manually cast to `unknown` for extra safety.
+ *
  * @example
  *
  * const [err, v] = _try(() => someFunction())
  * if (err) ...do something...
  * v // go ahead and use v
  */
-export function _try<ERR = unknown, RETURN = void>(
+export function _try<ERR = Error, RETURN = void>(
   fn: () => RETURN,
 ): [err: ERR | null, value: RETURN] {
   try {
@@ -33,7 +39,7 @@ export function _try<ERR = unknown, RETURN = void>(
  * Also, intentionally types second return item as non-optional,
  * but you should check for `err` presense first!
  */
-export async function pTry<ERR = unknown, RETURN = void>(
+export async function pTry<ERR = Error, RETURN = void>(
   promise: Promise<RETURN>,
 ): Promise<[err: ERR | null, value: Awaited<RETURN>]> {
   try {
@@ -50,7 +56,7 @@ export async function pTry<ERR = unknown, RETURN = void>(
  */
 export class UnexpectedPassError extends AppError {
   constructor() {
-    super('_expectedError passed unexpectedly')
+    super('expected error was not thrown')
   }
 }
 

package/src/error/tryCatch.ts

@@ -1,4 +1,4 @@
-import { _since, _stringifyAny, CommonLogger } from '../index'
+import { _anyToError, _since, _stringifyAny, CommonLogger } from '../index'
 import { AnyFunction } from '../types'
 
 export interface TryCatchOptions {
@@ -6,7 +6,7 @@ export interface TryCatchOptions {
    * The value returned from the function will be returned from the wrapped method (!).
    * onError function may be asynchronous.
    */
-  onError?: (err: unknown) => any
+  onError?: (err: Error) => any
 
   /**
    * @default false
@@ -59,7 +59,7 @@ export function _tryCatch<T extends AnyFunction>(fn: T, opt: TryCatchOptions = {
 
       if (onError) {
         try {
-          return await onError(err) // eslint-disable-line @typescript-eslint/return-await
+          return await onError(_anyToError(err)) // eslint-disable-line @typescript-eslint/return-await
         } catch {}
       }
       // returns undefined, but doesn't rethrow

package/src/index.ts

@@ -78,7 +78,6 @@ export * from './promise/pProps'
 import { pRetry, pRetryFn, PRetryOptions } from './promise/pRetry'
 export * from './promise/pState'
 import { pTimeout, pTimeoutFn, PTimeoutOptions } from './promise/pTimeout'
-export * from './promise/pTuple'
 export * from './string/case'
 export * from './string/json.util'
 export * from './string/string.util'
@@ -106,7 +105,8 @@ import {
   BatchResult,
   InstanceId,
   IsoDate,
-  IsoDateTime,
+  IsoDateString,
+  IsoDateTimeString,
   KeyValueTuple,
   Mapper,
   ObjectMapper,
@@ -118,6 +118,7 @@ import {
   Reviver,
   SavedDBEntity,
   StringMap,
+  UnixTimestampNumber,
   UnixTimestamp,
   Integer,
   ValueOf,
@@ -198,7 +199,8 @@ export type {
   ObjectPredicate,
   InstanceId,
   IsoDate,
-  IsoDateTime,
+  IsoDateString,
+  IsoDateTimeString,
   Reviver,
   PMapOptions,
   Mapper,
@@ -219,6 +221,7 @@ export type {
   ConditionalPick,
   ConditionalExcept,
   Class,
+  UnixTimestampNumber,
   UnixTimestamp,
   Integer,
   BaseDBEntity,

package/src/types.ts

@@ -150,6 +150,11 @@ export interface InstanceId {
  *
  * @example '2019-06-21'
  */
+export type IsoDateString = string
+
+/**
+ * @deprecated use IsoDateString
+ */
 export type IsoDate = string
 
 /**
@@ -157,13 +162,18 @@ export type IsoDate = string
  *
  * @example '2019-06-21T05:21:73Z'
  */
-export type IsoDateTime = string
+export type IsoDateTimeString = string
 
 /**
  * Interface explicitly states that the value is a Unix timestamp (in seconds).
  *
  * @example 1628945450
  */
+export type UnixTimestampNumber = number
+
+/**
+ * @deprecated use UnixTimestampNumber
+ */
 export type UnixTimestamp = number
 
 /**
@@ -180,12 +190,12 @@ export interface SavedDBEntity<ID = string> {
   /**
    * unixTimestamp of when the entity was first created (in the DB).
    */
-  created: UnixTimestamp
+  created: UnixTimestampNumber
 
   /**
    * unixTimestamp of when the entity was last updated (in the DB).
    */
-  updated: UnixTimestamp
+  updated: UnixTimestampNumber
 }
 
 /**

package/dist/promise/pTuple.d.ts

@@ -1,7 +0,0 @@
-/**
- * Wraps async calls in try catch blocks
- * to simplify syntax.
- *
- * source: https://github.com/scopsy/await-to-js/blob/master/src/await-to-js.ts
- */
-export declare function pTuple<RETURN, ERR = Error>(promise: Promise<RETURN>): Promise<[ERR, undefined] | [null, RETURN]>;

package/dist/promise/pTuple.js

@@ -1,13 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pTuple = void 0;
-/**
- * Wraps async calls in try catch blocks
- * to simplify syntax.
- *
- * source: https://github.com/scopsy/await-to-js/blob/master/src/await-to-js.ts
- */
-async function pTuple(promise) {
-    return promise.then(data => [null, data]).catch(err => [err, undefined]);
-}
-exports.pTuple = pTuple;

package/dist-esm/promise/pTuple.js

@@ -1,9 +0,0 @@
-/**
- * Wraps async calls in try catch blocks
- * to simplify syntax.
- *
- * source: https://github.com/scopsy/await-to-js/blob/master/src/await-to-js.ts
- */
-export async function pTuple(promise) {
-    return promise.then(data => [null, data]).catch(err => [err, undefined]);
-}

package/src/promise/pTuple.ts

@@ -1,11 +0,0 @@
-/**
- * Wraps async calls in try catch blocks
- * to simplify syntax.
- *
- * source: https://github.com/scopsy/await-to-js/blob/master/src/await-to-js.ts
- */
-export async function pTuple<RETURN, ERR = Error>(
-  promise: Promise<RETURN>,
-): Promise<[ERR, undefined] | [null, RETURN]> {
-  return promise.then(data => [null, data] as [null, RETURN]).catch(err => [err as ERR, undefined])
-}