@naturalcycles/js-lib 14.228.0 → 14.230.0

package/dist/datetime/localDate.d.ts

@@ -97,6 +97,11 @@ export declare class LocalDate {
     minus(num: number, unit: LocalDateUnit, mutate?: boolean): LocalDate;
     startOf(unit: LocalDateUnitStrict): LocalDate;
     endOf(unit: LocalDateUnitStrict): LocalDate;
+    /**
+     * Returns how many days are in the current month.
+     * E.g 31 for January.
+     */
+    daysInMonth(): number;
     static getYearLength(year: number): number;
     static getMonthLength(year: number, month: number): number;
     static isLeapYear(year: number): boolean;
@@ -145,3 +150,7 @@ export declare function localDateOrUndefined(d?: LocalDateInput | null): LocalDa
  * Creates a LocalDate from the input, unless it's falsy - then returns LocalDate.today.
  */
 export declare function localDateOrToday(d?: LocalDateInput | null): LocalDate;
+/**
+ Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
+ */
+export declare function todayIsoDateString(): IsoDateString;

package/dist/datetime/localDate.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.localDateOrToday = exports.localDateOrUndefined = exports.localDateToday = exports.localDate = exports.localDateRangeIterable = exports.localDateRange = exports.LocalDate = void 0;
+exports.todayIsoDateString = exports.localDateOrToday = exports.localDateOrUndefined = exports.localDateToday = exports.localDate = exports.localDateRangeIterable = exports.localDateRange = exports.LocalDate = void 0;
 const assert_1 = require("../error/assert");
 const iterable2_1 = require("../iter/iterable2");
 const localTime_1 = require("./localTime");
@@ -361,6 +361,13 @@ class LocalDate {
         // year
         return LocalDate.create(this.$year, 12, 31);
     }
+    /**
+     * Returns how many days are in the current month.
+     * E.g 31 for January.
+     */
+    daysInMonth() {
+        return LocalDate.getMonthLength(this.$year, this.$month);
+    }
     static getYearLength(year) {
         return this.isLeapYear(year) ? 366 : 365;
     }
@@ -496,3 +503,11 @@ function localDateOrToday(d) {
     return d ? LocalDate.of(d) : LocalDate.today();
 }
 exports.localDateOrToday = localDateOrToday;
+/**
+ Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
+ */
+function todayIsoDateString() {
+    // It was benchmarked to be faster than by concatenating individual Date components
+    return new Date().toISOString().slice(0, 10);
+}
+exports.todayIsoDateString = todayIsoDateString;

package/dist/datetime/localTime.d.ts

@@ -1,4 +1,4 @@
-import type { Inclusiveness, IsoDateString, IsoDateTimeString, MonthId, SortDirection, UnixTimestampMillisNumber, UnixTimestampNumber } from '../types';
+import type { Inclusiveness, IsoDateString, IsoDateTimeString, MonthId, NumberOfHours, NumberOfMinutes, SortDirection, UnixTimestampMillisNumber, UnixTimestampNumber } from '../types';
 import { LocalDate } from './localDate';
 export type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
 export declare enum ISODayOfWeek {
@@ -75,6 +75,11 @@ export declare class LocalTime {
     diff(other: LocalTimeInput, unit: LocalTimeUnit): number;
     startOf(unit: LocalTimeUnit, mutate?: boolean): LocalTime;
     endOf(unit: LocalTimeUnit, mutate?: boolean): LocalTime;
+    /**
+     * Returns how many days are in the current month.
+     * E.g 31 for January.
+     */
+    daysInMonth(): number;
     static sort(items: LocalTime[], mutate?: boolean, dir?: SortDirection): LocalTime[];
     static earliestOrUndefined(items: LocalTimeInput[]): LocalTime | undefined;
     static earliest(items: LocalTimeInput[]): LocalTime;
@@ -173,3 +178,21 @@ export declare function localTimeOrNow(d?: LocalTimeInput | null): LocalTime;
  Like Date.now(), but in seconds.
  */
 export declare function nowUnix(): UnixTimestampNumber;
+/**
+ * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
+ * to the local time to get UTC time.
+ *
+ * E.g utcOffset for CEST is -120,
+ * which means that you need to add -120 minutes to the local time to get UTC time.
+ *
+ * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+ */
+export declare function getUTCOffsetMinutes(): NumberOfMinutes;
+/**
+ * Same as getUTCOffsetMinutes, but rounded to hours.
+ *
+ * E.g for CEST it is -2.
+ *
+ * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+ */
+export declare function getUTCOffsetHours(): NumberOfHours;

package/dist/datetime/localTime.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.nowUnix = exports.localTimeOrNow = exports.localTimeOrUndefined = exports.localTimeNow = exports.localTime = exports.LocalTime = exports.ISODayOfWeek = void 0;
+exports.getUTCOffsetHours = exports.getUTCOffsetMinutes = exports.nowUnix = exports.localTimeOrNow = exports.localTimeOrUndefined = exports.localTimeNow = exports.localTime = exports.LocalTime = exports.ISODayOfWeek = void 0;
 const assert_1 = require("../error/assert");
 const time_util_1 = require("../time/time.util");
 const localDate_1 = require("./localDate");
@@ -302,6 +302,13 @@ class LocalTime {
         }
         return mutate ? this : new LocalTime(d);
     }
+    /**
+     * Returns how many days are in the current month.
+     * E.g 31 for January.
+     */
+    daysInMonth() {
+        return localDate_1.LocalDate.getMonthLength(this.$date.getFullYear(), this.$date.getMonth() + 1);
+    }
     static sort(items, mutate = false, dir = 'asc') {
         const mod = dir === 'desc' ? -1 : 1;
         return (mutate ? items : [...items]).sort((a, b) => {
@@ -443,25 +450,8 @@ class LocalTime {
         return localDate_1.LocalDate.fromDate(this.$date);
     }
     toPretty(seconds = true) {
-        const { year, month, day, hour, minute, second } = this.components();
-        return ([
-            String(year).padStart(4, '0'),
-            String(month).padStart(2, '0'),
-            String(day).padStart(2, '0'),
-        ].join('-') +
-            ' ' +
-            [
-                String(hour).padStart(2, '0'),
-                String(minute).padStart(2, '0'),
-                seconds && String(second).padStart(2, '0'),
-            ]
-                .filter(Boolean)
-                .join(':'));
-        // return this.$date
-        //   .toISOString()
-        //   .slice(0, seconds ? 19 : 16)
-        //   .split('T')
-        //   .join(' ')
+        const s = this.$date.toISOString();
+        return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16);
     }
     /**
      * Returns e.g: `1984-06-21T17:56:21`
@@ -473,27 +463,13 @@ class LocalTime {
      * Returns e.g: `1984-06-21`, only the date part of DateTime
      */
     toISODate() {
-        const { year, month, day } = this.components();
-        return [
-            String(year).padStart(4, '0'),
-            String(month).padStart(2, '0'),
-            String(day).padStart(2, '0'),
-        ].join('-');
-        // return this.$date.toISOString().slice(0, 10)
+        return this.$date.toISOString().slice(0, 10);
     }
     /**
      * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
      */
     toISOTime(seconds = true) {
-        // return this.$date.toISOString().slice(11, seconds ? 19 : 16)
-        const { hour, minute, second } = this.components();
-        return [
-            String(hour).padStart(2, '0'),
-            String(minute).padStart(2, '0'),
-            seconds && String(second).padStart(2, '0'),
-        ]
-            .filter(Boolean)
-            .join(':');
+        return this.$date.toISOString().slice(11, seconds ? 19 : 16);
     }
     /**
      * Returns e.g: `19840621_1705`
@@ -565,6 +541,30 @@ function nowUnix() {
     return Math.floor(Date.now() / 1000);
 }
 exports.nowUnix = nowUnix;
+/**
+ * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
+ * to the local time to get UTC time.
+ *
+ * E.g utcOffset for CEST is -120,
+ * which means that you need to add -120 minutes to the local time to get UTC time.
+ *
+ * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+ */
+function getUTCOffsetMinutes() {
+    return -new Date().getTimezoneOffset() || 0;
+}
+exports.getUTCOffsetMinutes = getUTCOffsetMinutes;
+/**
+ * Same as getUTCOffsetMinutes, but rounded to hours.
+ *
+ * E.g for CEST it is -2.
+ *
+ * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+ */
+function getUTCOffsetHours() {
+    return Math.round(getUTCOffsetMinutes() / 60);
+}
+exports.getUTCOffsetHours = getUTCOffsetHours;
 // based on: https://github.com/date-fns/date-fns/blob/master/src/getISOWeek/index.ts
 function getWeek(date) {
     const diff = startOfWeek(date).getTime() - startOfWeekYear(date).getTime();

package/dist-esm/datetime/localDate.js

@@ -358,6 +358,13 @@ export class LocalDate {
         // year
         return LocalDate.create(this.$year, 12, 31);
     }
+    /**
+     * Returns how many days are in the current month.
+     * E.g 31 for January.
+     */
+    daysInMonth() {
+        return LocalDate.getMonthLength(this.$year, this.$month);
+    }
     static getYearLength(year) {
         return this.isLeapYear(year) ? 366 : 365;
     }
@@ -486,3 +493,10 @@ export function localDateOrUndefined(d) {
 export function localDateOrToday(d) {
     return d ? LocalDate.of(d) : LocalDate.today();
 }
+/**
+ Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
+ */
+export function todayIsoDateString() {
+    // It was benchmarked to be faster than by concatenating individual Date components
+    return new Date().toISOString().slice(0, 10);
+}

package/dist-esm/datetime/localTime.js

@@ -300,6 +300,13 @@ export class LocalTime {
         }
         return mutate ? this : new LocalTime(d);
     }
+    /**
+     * Returns how many days are in the current month.
+     * E.g 31 for January.
+     */
+    daysInMonth() {
+        return LocalDate.getMonthLength(this.$date.getFullYear(), this.$date.getMonth() + 1);
+    }
     static sort(items, mutate = false, dir = 'asc') {
         const mod = dir === 'desc' ? -1 : 1;
         return (mutate ? items : [...items]).sort((a, b) => {
@@ -441,25 +448,8 @@ export class LocalTime {
         return LocalDate.fromDate(this.$date);
     }
     toPretty(seconds = true) {
-        const { year, month, day, hour, minute, second } = this.components();
-        return ([
-            String(year).padStart(4, '0'),
-            String(month).padStart(2, '0'),
-            String(day).padStart(2, '0'),
-        ].join('-') +
-            ' ' +
-            [
-                String(hour).padStart(2, '0'),
-                String(minute).padStart(2, '0'),
-                seconds && String(second).padStart(2, '0'),
-            ]
-                .filter(Boolean)
-                .join(':'));
-        // return this.$date
-        //   .toISOString()
-        //   .slice(0, seconds ? 19 : 16)
-        //   .split('T')
-        //   .join(' ')
+        const s = this.$date.toISOString();
+        return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16);
     }
     /**
      * Returns e.g: `1984-06-21T17:56:21`
@@ -471,27 +461,13 @@ export class LocalTime {
      * Returns e.g: `1984-06-21`, only the date part of DateTime
      */
     toISODate() {
-        const { year, month, day } = this.components();
-        return [
-            String(year).padStart(4, '0'),
-            String(month).padStart(2, '0'),
-            String(day).padStart(2, '0'),
-        ].join('-');
-        // return this.$date.toISOString().slice(0, 10)
+        return this.$date.toISOString().slice(0, 10);
     }
     /**
      * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
      */
     toISOTime(seconds = true) {
-        // return this.$date.toISOString().slice(11, seconds ? 19 : 16)
-        const { hour, minute, second } = this.components();
-        return [
-            String(hour).padStart(2, '0'),
-            String(minute).padStart(2, '0'),
-            seconds && String(second).padStart(2, '0'),
-        ]
-            .filter(Boolean)
-            .join(':');
+        return this.$date.toISOString().slice(11, seconds ? 19 : 16);
     }
     /**
      * Returns e.g: `19840621_1705`
@@ -557,6 +533,28 @@ export function localTimeOrNow(d) {
 export function nowUnix() {
     return Math.floor(Date.now() / 1000);
 }
+/**
+ * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
+ * to the local time to get UTC time.
+ *
+ * E.g utcOffset for CEST is -120,
+ * which means that you need to add -120 minutes to the local time to get UTC time.
+ *
+ * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+ */
+export function getUTCOffsetMinutes() {
+    return -new Date().getTimezoneOffset() || 0;
+}
+/**
+ * Same as getUTCOffsetMinutes, but rounded to hours.
+ *
+ * E.g for CEST it is -2.
+ *
+ * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+ */
+export function getUTCOffsetHours() {
+    return Math.round(getUTCOffsetMinutes() / 60);
+}
 // based on: https://github.com/date-fns/date-fns/blob/master/src/getISOWeek/index.ts
 function getWeek(date) {
     const diff = startOfWeek(date).getTime() - startOfWeekYear(date).getTime();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.228.0",
+  "version": "14.230.0",
   "scripts": {
     "prepare": "husky",
     "build-prod": "build-prod-esm-cjs",

package/src/datetime/localDate.ts

@@ -438,6 +438,14 @@ export class LocalDate {
     return LocalDate.create(this.$year, 12, 31)
   }
 
+  /**
+   * Returns how many days are in the current month.
+   * E.g 31 for January.
+   */
+  daysInMonth(): number {
+    return LocalDate.getMonthLength(this.$year, this.$month)
+  }
+
   static getYearLength(year: number): number {
     return this.isLeapYear(year) ? 366 : 365
   }
@@ -602,3 +610,11 @@ export function localDateOrUndefined(d?: LocalDateInput | null): LocalDate | und
 export function localDateOrToday(d?: LocalDateInput | null): LocalDate {
   return d ? LocalDate.of(d) : LocalDate.today()
 }
+
+/**
+ Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
+ */
+export function todayIsoDateString(): IsoDateString {
+  // It was benchmarked to be faster than by concatenating individual Date components
+  return new Date().toISOString().slice(0, 10)
+}

package/src/datetime/localTime.ts

@@ -5,6 +5,8 @@ import type {
   IsoDateString,
   IsoDateTimeString,
   MonthId,
+  NumberOfHours,
+  NumberOfMinutes,
   SortDirection,
   UnixTimestampMillisNumber,
   UnixTimestampNumber,
@@ -376,6 +378,14 @@ export class LocalTime {
     return mutate ? this : new LocalTime(d)
   }
 
+  /**
+   * Returns how many days are in the current month.
+   * E.g 31 for January.
+   */
+  daysInMonth(): number {
+    return LocalDate.getMonthLength(this.$date.getFullYear(), this.$date.getMonth() + 1)
+  }
+
   static sort(items: LocalTime[], mutate = false, dir: SortDirection = 'asc'): LocalTime[] {
     const mod = dir === 'desc' ? -1 : 1
     return (mutate ? items : [...items]).sort((a, b) => {
@@ -541,29 +551,8 @@ export class LocalTime {
   }
 
   toPretty(seconds = true): IsoDateTimeString {
-    const { year, month, day, hour, minute, second } = this.components()
-
-    return (
-      [
-        String(year).padStart(4, '0'),
-        String(month).padStart(2, '0'),
-        String(day).padStart(2, '0'),
-      ].join('-') +
-      ' ' +
-      [
-        String(hour).padStart(2, '0'),
-        String(minute).padStart(2, '0'),
-        seconds && String(second).padStart(2, '0'),
-      ]
-        .filter(Boolean)
-        .join(':')
-    )
-
-    // return this.$date
-    //   .toISOString()
-    //   .slice(0, seconds ? 19 : 16)
-    //   .split('T')
-    //   .join(' ')
+    const s = this.$date.toISOString()
+    return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16)
   }
 
   /**
@@ -577,31 +566,14 @@ export class LocalTime {
    * Returns e.g: `1984-06-21`, only the date part of DateTime
    */
   toISODate(): IsoDateString {
-    const { year, month, day } = this.components()
-
-    return [
-      String(year).padStart(4, '0'),
-      String(month).padStart(2, '0'),
-      String(day).padStart(2, '0'),
-    ].join('-')
-
-    // return this.$date.toISOString().slice(0, 10)
+    return this.$date.toISOString().slice(0, 10)
   }
 
   /**
    * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
    */
   toISOTime(seconds = true): string {
-    // return this.$date.toISOString().slice(11, seconds ? 19 : 16)
-    const { hour, minute, second } = this.components()
-
-    return [
-      String(hour).padStart(2, '0'),
-      String(minute).padStart(2, '0'),
-      seconds && String(second).padStart(2, '0'),
-    ]
-      .filter(Boolean)
-      .join(':')
+    return this.$date.toISOString().slice(11, seconds ? 19 : 16)
   }
 
   /**
@@ -680,6 +652,30 @@ export function nowUnix(): UnixTimestampNumber {
   return Math.floor(Date.now() / 1000)
 }
 
+/**
+ * UTC offset is the opposite of "timezone offset" - it's the number of minutes to add
+ * to the local time to get UTC time.
+ *
+ * E.g utcOffset for CEST is -120,
+ * which means that you need to add -120 minutes to the local time to get UTC time.
+ *
+ * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+ */
+export function getUTCOffsetMinutes(): NumberOfMinutes {
+  return -new Date().getTimezoneOffset() || 0
+}
+
+/**
+ * Same as getUTCOffsetMinutes, but rounded to hours.
+ *
+ * E.g for CEST it is -2.
+ *
+ * Instead of -0 it returns 0, for the peace of mind and less weird test/snapshot differences.
+ */
+export function getUTCOffsetHours(): NumberOfHours {
+  return Math.round(getUTCOffsetMinutes() / 60)
+}
+
 // based on: https://github.com/date-fns/date-fns/blob/master/src/getISOWeek/index.ts
 function getWeek(date: Date): number {
   const diff = startOfWeek(date).getTime() - startOfWeekYear(date).getTime()