@naturalcycles/js-lib 14.229.0 → 14.230.1

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;
@@ -148,4 +153,4 @@ 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;
+export declare function todayString(): IsoDateString;

package/dist/datetime/localDate.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.todayIsoDateString = exports.localDateOrToday = exports.localDateOrUndefined = exports.localDateToday = exports.localDate = exports.localDateRangeIterable = exports.localDateRange = exports.LocalDate = void 0;
+exports.todayString = 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;
     }
@@ -499,8 +506,8 @@ exports.localDateOrToday = localDateOrToday;
 /**
  Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
  */
-function todayIsoDateString() {
+function todayString() {
     // It was benchmarked to be faster than by concatenating individual Date components
     return new Date().toISOString().slice(0, 10);
 }
-exports.todayIsoDateString = todayIsoDateString;
+exports.todayString = todayString;

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) => {
@@ -534,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;
     }
@@ -489,7 +496,7 @@ export function localDateOrToday(d) {
 /**
  Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
  */
-export function todayIsoDateString() {
+export function todayString() {
     // 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) => {
@@ -526,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.229.0",
+  "version": "14.230.1",
   "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
   }
@@ -606,7 +614,7 @@ export function localDateOrToday(d?: LocalDateInput | null): LocalDate {
 /**
  Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
  */
-export function todayIsoDateString(): IsoDateString {
+export function todayString(): 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) => {
@@ -642,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()