@naturalcycles/js-lib 14.260.0 → 14.261.0

package/dist/datetime/localDate.d.ts

@@ -1,9 +1,9 @@
 import { Iterable2 } from '../iter/iterable2';
-import type { Inclusiveness, IsoDateString, IsoDateTimeString, MonthId, SortDirection, UnixTimestamp, UnixTimestampMillis } from '../types';
+import type { Inclusiveness, IsoDate, IsoDateTime, MonthId, SortDirection, UnixTimestamp, UnixTimestampMillis } from '../types';
 import { DateObject, ISODayOfWeek, LocalTime } from './localTime';
 export type LocalDateUnit = LocalDateUnitStrict | 'week';
 export type LocalDateUnitStrict = 'year' | 'month' | 'day';
-export type LocalDateInput = LocalDate | Date | IsoDateString;
+export type LocalDateInput = LocalDate | Date | IsoDate;
 export type LocalDateInputNullable = LocalDateInput | null | undefined;
 export type LocalDateFormatter = (ld: LocalDate) => string;
 /**
@@ -119,18 +119,18 @@ export declare class LocalDate {
     /**
      * Returns e.g: `1984-06-21`
      */
-    toISODate(): IsoDateString;
+    toISODate(): IsoDate;
     /**
      * Returns e.g: `1984-06-21T00:00:00`
      * Hours, minutes and seconds are 0.
      */
-    toISODateTime(): IsoDateTimeString;
+    toISODateTime(): IsoDateTime;
     /**
      * Returns e.g: `1984-06-21T00:00:00Z` (notice the Z at the end, which indicates UTC).
      * Hours, minutes and seconds are 0.
      */
-    toISODateTimeInUTC(): IsoDateTimeString;
-    toString(): IsoDateString;
+    toISODateTimeInUTC(): IsoDateTime;
+    toString(): IsoDate;
     /**
      * Returns e.g: `19840621`
      */
@@ -147,7 +147,7 @@ export declare class LocalDate {
      * Same as .unix(), but in milliseconds.
      */
     get unixMillis(): UnixTimestampMillis;
-    toJSON(): IsoDateString;
+    toJSON(): IsoDate;
     format(fmt: Intl.DateTimeFormat | LocalDateFormatter): string;
 }
 declare class LocalDateFactory {
@@ -170,9 +170,9 @@ declare class LocalDateFactory {
      */
     todayInUTC(): LocalDate;
     /**
-     Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
+     Convenience function to return current today's IsoDate representation, e.g `2024-06-21`
      */
-    todayString(): IsoDateString;
+    todayString(): IsoDate;
     /**
      * Create LocalDate from LocalDateInput.
      * Input can already be a LocalDate - it is returned as-is in that case.
@@ -199,9 +199,9 @@ declare class LocalDateFactory {
     try(input: LocalDateInputNullable): LocalDate | undefined;
     /**
      * Performs STRICT parsing.
-     * Only allows IsoDateString input, nothing else.
+     * Only allows IsoDate input, nothing else.
      */
-    fromString(s: IsoDateString): LocalDate;
+    fromString(s: IsoDate): LocalDate;
     /**
      * Parses "compact iso8601 format", e.g `19840621` into LocalDate.
      * Throws if it fails to do so.

package/dist/datetime/localDate.js

@@ -385,14 +385,14 @@ class LocalDate {
      * Hours, minutes and seconds are 0.
      */
     toISODateTime() {
-        return this.toISODate() + 'T00:00:00';
+        return (this.toISODate() + 'T00:00:00');
     }
     /**
      * Returns e.g: `1984-06-21T00:00:00Z` (notice the Z at the end, which indicates UTC).
      * Hours, minutes and seconds are 0.
      */
     toISODateTimeInUTC() {
-        return this.toISODateTime() + 'Z';
+        return (this.toISODateTime() + 'Z');
     }
     toString() {
         return this.toISODate();
@@ -464,7 +464,7 @@ class LocalDateFactory {
         return this.fromDateInUTC(new Date());
     }
     /**
-     Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
+     Convenience function to return current today's IsoDate representation, e.g `2024-06-21`
      */
     todayString() {
         return this.fromDate(new Date()).toISODate();
@@ -524,7 +524,7 @@ class LocalDateFactory {
     }
     /**
      * Performs STRICT parsing.
-     * Only allows IsoDateString input, nothing else.
+     * Only allows IsoDate input, nothing else.
      */
     fromString(s) {
         return this.parseToLocalDate(DATE_REGEX, s);

package/dist/datetime/localTime.d.ts

@@ -1,4 +1,4 @@
-import type { Inclusiveness, IsoDateString, IsoDateTimeString, MonthId, NumberOfHours, NumberOfMinutes, SortDirection, UnixTimestamp, UnixTimestampMillis } from '../types';
+import type { Inclusiveness, IsoDate, IsoDateTime, MonthId, NumberOfHours, NumberOfMinutes, SortDirection, UnixTimestamp, UnixTimestampMillis } from '../types';
 import { LocalDate } from './localDate';
 import { WallTime } from './wallTime';
 export type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
@@ -11,7 +11,7 @@ export declare enum ISODayOfWeek {
     SATURDAY = 6,
     SUNDAY = 7
 }
-export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestamp;
+export type LocalTimeInput = LocalTime | Date | IsoDate | IsoDateTime | UnixTimestamp;
 export type LocalTimeInputNullable = LocalTimeInput | null | undefined;
 export type LocalTimeFormatter = (ld: LocalTime) => string;
 export type DateTimeObject = DateObject & TimeObject;
@@ -195,15 +195,15 @@ export declare class LocalTime {
      * or (if seconds=false):
      * `1984-06-21 17:56`
      */
-    toPretty(seconds?: boolean): IsoDateTimeString;
+    toPretty(seconds?: boolean): IsoDateTime;
     /**
      * Returns e.g: `1984-06-21T17:56:21`
      */
-    toISODateTime(): IsoDateTimeString;
+    toISODateTime(): IsoDateTime;
     /**
      * Returns e.g: `1984-06-21`, only the date part of DateTime
      */
-    toISODate(): IsoDateString;
+    toISODate(): IsoDate;
     /**
      * Returns e.g: `17:03:15` (or `17:03` with seconds=false)
      */
@@ -212,7 +212,7 @@ export declare class LocalTime {
      * Returns e.g: `19840621_1705`
      */
     toStringCompact(seconds?: boolean): string;
-    toString(): string;
+    toString(): IsoDateTime;
     toJSON(): UnixTimestamp;
     toMonthId(): MonthId;
     format(fmt: Intl.DateTimeFormat | LocalTimeFormatter): string;
@@ -253,7 +253,7 @@ declare class LocalTimeFactory {
     /**
      * Returns true if isoString is a valid iso8601 string like `yyyy-mm-ddThh:mm:dd`.
      */
-    isValidString(isoString: string | undefined | null): boolean;
+    isValidString(isoString: IsoDateTime | IsoDate | undefined | null): boolean;
     /**
      * Tries to convert/parse the input into LocalTime.
      * Uses LOOSE parsing.
@@ -262,14 +262,14 @@ declare class LocalTimeFactory {
     try(input: LocalTimeInputNullable): LocalTime | undefined;
     /**
      * Performs STRICT parsing.
-     * Only allows IsoDateTimeString or IsoDateString input, nothing else.
+     * Only allows IsoDateTime or IsoDate input, nothing else.
      */
-    fromIsoDateTimeString(s: IsoDateTimeString | IsoDateString): LocalTime;
+    fromIsoDateTimeString(s: IsoDateTime | IsoDate): LocalTime;
     /**
      * Performs LOOSE parsing.
      * Tries to coerce imprefect/incorrect string input into IsoDateTimeString.
      * Use with caution.
-     * Allows to input IsoDateString, will set h:m:s to zeros.
+     * Allows to input IsoDate, will set h:m:s to zeros.
      */
     parse(s: string): LocalTime;
     private parseStrictlyOrUndefined;

package/dist/datetime/localTime.js

@@ -549,7 +549,7 @@ class LocalTime {
      * `1984-06-21 17:56`
      */
     toPretty(seconds = true) {
-        return this.toISODate() + ' ' + this.toISOTime(seconds);
+        return (this.toISODate() + ' ' + this.toISOTime(seconds));
         // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
         // const s = this.$date.toISOString()
         // return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16)
@@ -558,7 +558,7 @@ class LocalTime {
      * Returns e.g: `1984-06-21T17:56:21`
      */
     toISODateTime() {
-        return this.toISODate() + 'T' + this.toISOTime();
+        return (this.toISODate() + 'T' + this.toISOTime());
         // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
         // return this.$date.toISOString().slice(0, 19)
     }
@@ -717,9 +717,8 @@ class LocalTimeFactory {
     }
     /**
      * Performs STRICT parsing.
-     * Only allows IsoDateTimeString or IsoDateString input, nothing else.
+     * Only allows IsoDateTime or IsoDate input, nothing else.
      */
-    // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents
     fromIsoDateTimeString(s) {
         const d = this.parseStrictlyOrUndefined(s);
         (0, assert_1._assert)(d, `Cannot parse "${s}" into LocalTime`);
@@ -729,7 +728,7 @@ class LocalTimeFactory {
      * Performs LOOSE parsing.
      * Tries to coerce imprefect/incorrect string input into IsoDateTimeString.
      * Use with caution.
-     * Allows to input IsoDateString, will set h:m:s to zeros.
+     * Allows to input IsoDate, will set h:m:s to zeros.
      */
     parse(s) {
         const d = this.parseLooselyOrUndefined(String(s));

package/dist/types.d.ts

@@ -30,8 +30,8 @@ export type AnyEnum = NumberEnum;
 export type NumberEnum = Record<string, number | string>;
 export type StringEnum = Record<string, string>;
 export type CreatedUpdated = {
-    created: number;
-    updated: number;
+    created: UnixTimestamp;
+    updated: UnixTimestamp;
 };
 export interface CreatedUpdatedId extends CreatedUpdated {
     id: string;
@@ -172,20 +172,22 @@ export interface InstanceId {
     instanceId: string;
 }
 /**
- * Interface explicitly states that the value is an ISO Date string (without time).
+ * ISO 8601 date (without time).
+ * Branded type.
  *
  * @example '2019-06-21'
  */
-export type IsoDateString = string;
+export type IsoDate = Branded<string, 'IsoDate'>;
 /**
- * Interface explicitly states that the value is an ISO DateTime string (with time).
+ * ISO 8601 date (date+time).
+ * Branded type.
  *
  * @example '2019-06-21T05:21:73Z'
  */
-export type IsoDateTimeString = string;
+export type IsoDateTime = Branded<string, 'IsoDateTime'>;
 /**
  * Identifies the Month.
- * Like IsoDateString, but without the Day token.
+ * Like IsoDate, but without the Day token.
  *
  * @example '2023-09'
  */

package/dist-esm/datetime/localDate.js

@@ -382,14 +382,14 @@ export class LocalDate {
      * Hours, minutes and seconds are 0.
      */
     toISODateTime() {
-        return this.toISODate() + 'T00:00:00';
+        return (this.toISODate() + 'T00:00:00');
     }
     /**
      * Returns e.g: `1984-06-21T00:00:00Z` (notice the Z at the end, which indicates UTC).
      * Hours, minutes and seconds are 0.
      */
     toISODateTimeInUTC() {
-        return this.toISODateTime() + 'Z';
+        return (this.toISODateTime() + 'Z');
     }
     toString() {
         return this.toISODate();
@@ -460,7 +460,7 @@ class LocalDateFactory {
         return this.fromDateInUTC(new Date());
     }
     /**
-     Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
+     Convenience function to return current today's IsoDate representation, e.g `2024-06-21`
      */
     todayString() {
         return this.fromDate(new Date()).toISODate();
@@ -520,7 +520,7 @@ class LocalDateFactory {
     }
     /**
      * Performs STRICT parsing.
-     * Only allows IsoDateString input, nothing else.
+     * Only allows IsoDate input, nothing else.
      */
     fromString(s) {
         return this.parseToLocalDate(DATE_REGEX, s);

package/dist-esm/datetime/localTime.js

@@ -546,7 +546,7 @@ export class LocalTime {
      * `1984-06-21 17:56`
      */
     toPretty(seconds = true) {
-        return this.toISODate() + ' ' + this.toISOTime(seconds);
+        return (this.toISODate() + ' ' + this.toISOTime(seconds));
         // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
         // const s = this.$date.toISOString()
         // return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16)
@@ -555,7 +555,7 @@ export class LocalTime {
      * Returns e.g: `1984-06-21T17:56:21`
      */
     toISODateTime() {
-        return this.toISODate() + 'T' + this.toISOTime();
+        return (this.toISODate() + 'T' + this.toISOTime());
         // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
         // return this.$date.toISOString().slice(0, 19)
     }
@@ -713,9 +713,8 @@ class LocalTimeFactory {
     }
     /**
      * Performs STRICT parsing.
-     * Only allows IsoDateTimeString or IsoDateString input, nothing else.
+     * Only allows IsoDateTime or IsoDate input, nothing else.
      */
-    // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents
     fromIsoDateTimeString(s) {
         const d = this.parseStrictlyOrUndefined(s);
         _assert(d, `Cannot parse "${s}" into LocalTime`);
@@ -725,7 +724,7 @@ class LocalTimeFactory {
      * Performs LOOSE parsing.
      * Tries to coerce imprefect/incorrect string input into IsoDateTimeString.
      * Use with caution.
-     * Allows to input IsoDateString, will set h:m:s to zeros.
+     * Allows to input IsoDate, will set h:m:s to zeros.
      */
     parse(s) {
         const d = this.parseLooselyOrUndefined(String(s));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.260.0",
+  "version": "14.261.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",

package/src/datetime/dateInterval.ts

@@ -1,4 +1,4 @@
-import { Inclusiveness } from '../types'
+import { Inclusiveness, IsoDate } from '../types'
 import { LocalDate, localDate, LocalDateInput, LocalDateUnit } from './localDate'
 
 export type DateIntervalConfig = DateInterval | DateIntervalString
@@ -25,7 +25,7 @@ export class DateInterval {
   static parse(d: DateIntervalConfig): DateInterval {
     if (d instanceof DateInterval) return d
 
-    const [start, end] = d.split('/')
+    const [start, end] = d.split('/') as IsoDate[]
 
     if (!end || !start) {
       throw new Error(`Cannot parse "${d}" into DateInterval`)

package/src/datetime/localDate.ts

@@ -2,8 +2,8 @@ import { _assert } from '../error/assert'
 import { Iterable2 } from '../iter/iterable2'
 import type {
   Inclusiveness,
-  IsoDateString,
-  IsoDateTimeString,
+  IsoDate,
+  IsoDateTime,
   MonthId,
   SortDirection,
   UnixTimestamp,
@@ -21,7 +21,7 @@ const MDAYS = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
 const DATE_REGEX = /^(\d\d\d\d)-(\d\d)-(\d\d)/
 const COMPACT_DATE_REGEX = /^(\d\d\d\d)(\d\d)(\d\d)$/
 
-export type LocalDateInput = LocalDate | Date | IsoDateString
+export type LocalDateInput = LocalDate | Date | IsoDate
 export type LocalDateInputNullable = LocalDateInput | null | undefined
 export type LocalDateFormatter = (ld: LocalDate) => string
 
@@ -442,31 +442,31 @@ export class LocalDate {
   /**
    * Returns e.g: `1984-06-21`
    */
-  toISODate(): IsoDateString {
+  toISODate(): IsoDate {
     return [
       String(this.year).padStart(4, '0'),
       String(this.month).padStart(2, '0'),
       String(this.day).padStart(2, '0'),
-    ].join('-')
+    ].join('-') as IsoDate
   }
 
   /**
    * Returns e.g: `1984-06-21T00:00:00`
    * Hours, minutes and seconds are 0.
    */
-  toISODateTime(): IsoDateTimeString {
-    return this.toISODate() + 'T00:00:00'
+  toISODateTime(): IsoDateTime {
+    return (this.toISODate() + 'T00:00:00') as IsoDateTime
   }
 
   /**
    * Returns e.g: `1984-06-21T00:00:00Z` (notice the Z at the end, which indicates UTC).
    * Hours, minutes and seconds are 0.
    */
-  toISODateTimeInUTC(): IsoDateTimeString {
-    return this.toISODateTime() + 'Z'
+  toISODateTimeInUTC(): IsoDateTime {
+    return (this.toISODateTime() + 'Z') as IsoDateTime
   }
 
-  toString(): IsoDateString {
+  toString(): IsoDate {
     return this.toISODate()
   }
 
@@ -502,7 +502,7 @@ export class LocalDate {
     return this.toDate().valueOf() as UnixTimestampMillis
   }
 
-  toJSON(): IsoDateString {
+  toJSON(): IsoDate {
     return this.toISODate()
   }
 
@@ -547,9 +547,9 @@ class LocalDateFactory {
   }
 
   /**
-   Convenience function to return current today's IsoDateString representation, e.g `2024-06-21`
+   Convenience function to return current today's IsoDate representation, e.g `2024-06-21`
    */
-  todayString(): IsoDateString {
+  todayString(): IsoDate {
     return this.fromDate(new Date()).toISODate()
   }
 
@@ -605,9 +605,9 @@ class LocalDateFactory {
 
   /**
    * Performs STRICT parsing.
-   * Only allows IsoDateString input, nothing else.
+   * Only allows IsoDate input, nothing else.
    */
-  fromString(s: IsoDateString): LocalDate {
+  fromString(s: IsoDate): LocalDate {
     return this.parseToLocalDate(DATE_REGEX, s)
   }
 

package/src/datetime/localTime.ts

@@ -2,8 +2,8 @@ import { _assert } from '../error/assert'
 import { _ms } from '../time/time.util'
 import type {
   Inclusiveness,
-  IsoDateString,
-  IsoDateTimeString,
+  IsoDate,
+  IsoDateTime,
   MonthId,
   NumberOfHours,
   NumberOfMinutes,
@@ -26,7 +26,7 @@ export enum ISODayOfWeek {
   SUNDAY = 7,
 }
 
-export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestamp
+export type LocalTimeInput = LocalTime | Date | IsoDate | IsoDateTime | UnixTimestamp
 export type LocalTimeInputNullable = LocalTimeInput | null | undefined
 export type LocalTimeFormatter = (ld: LocalTime) => string
 
@@ -659,8 +659,8 @@ export class LocalTime {
    * or (if seconds=false):
    * `1984-06-21 17:56`
    */
-  toPretty(seconds = true): IsoDateTimeString {
-    return this.toISODate() + ' ' + this.toISOTime(seconds)
+  toPretty(seconds = true): IsoDateTime {
+    return (this.toISODate() + ' ' + this.toISOTime(seconds)) as IsoDateTime
     // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
     // const s = this.$date.toISOString()
     // return s.slice(0, 10) + ' ' + s.slice(11, seconds ? 19 : 16)
@@ -669,8 +669,8 @@ export class LocalTime {
   /**
    * Returns e.g: `1984-06-21T17:56:21`
    */
-  toISODateTime(): IsoDateTimeString {
-    return this.toISODate() + 'T' + this.toISOTime()
+  toISODateTime(): IsoDateTime {
+    return (this.toISODate() + 'T' + this.toISOTime()) as IsoDateTime
     // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
     // return this.$date.toISOString().slice(0, 19)
   }
@@ -678,14 +678,14 @@ export class LocalTime {
   /**
    * Returns e.g: `1984-06-21`, only the date part of DateTime
    */
-  toISODate(): IsoDateString {
+  toISODate(): IsoDate {
     const { year, month, day } = this.toDateObject()
 
     return [
       String(year).padStart(4, '0'),
       String(month).padStart(2, '0'),
       String(day).padStart(2, '0'),
-    ].join('-')
+    ].join('-') as IsoDate
 
     // !! Not using toISOString(), as it returns time in UTC, not in local timezone (unexpected!)
     // return this.$date.toISOString().slice(0, 10)
@@ -726,7 +726,7 @@ export class LocalTime {
     ].join('')
   }
 
-  toString(): string {
+  toString(): IsoDateTime {
     return this.toISODateTime()
   }
 
@@ -818,7 +818,7 @@ class LocalTimeFactory {
   /**
    * Returns true if isoString is a valid iso8601 string like `yyyy-mm-ddThh:mm:dd`.
    */
-  isValidString(isoString: string | undefined | null): boolean {
+  isValidString(isoString: IsoDateTime | IsoDate | undefined | null): boolean {
     return !!this.parseStrictlyOrUndefined(isoString)
   }
 
@@ -843,10 +843,10 @@ class LocalTimeFactory {
 
   /**
    * Performs STRICT parsing.
-   * Only allows IsoDateTimeString or IsoDateString input, nothing else.
+   * Only allows IsoDateTime or IsoDate input, nothing else.
    */
-  // eslint-disable-next-line @typescript-eslint/no-duplicate-type-constituents
-  fromIsoDateTimeString(s: IsoDateTimeString | IsoDateString): LocalTime {
+
+  fromIsoDateTimeString(s: IsoDateTime | IsoDate): LocalTime {
     const d = this.parseStrictlyOrUndefined(s)
     _assert(d, `Cannot parse "${s}" into LocalTime`)
     return new LocalTime(d)
@@ -856,7 +856,7 @@ class LocalTimeFactory {
    * Performs LOOSE parsing.
    * Tries to coerce imprefect/incorrect string input into IsoDateTimeString.
    * Use with caution.
-   * Allows to input IsoDateString, will set h:m:s to zeros.
+   * Allows to input IsoDate, will set h:m:s to zeros.
    */
   parse(s: string): LocalTime {
     const d = this.parseLooselyOrUndefined(String(s))

package/src/types.ts

@@ -38,8 +38,8 @@ export type StringEnum = Record<string, string>
 
 // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
 export type CreatedUpdated = {
-  created: number
-  updated: number
+  created: UnixTimestamp
+  updated: UnixTimestamp
 }
 
 export interface CreatedUpdatedId extends CreatedUpdated {
@@ -227,22 +227,24 @@ export interface InstanceId {
 }
 
 /**
- * Interface explicitly states that the value is an ISO Date string (without time).
+ * ISO 8601 date (without time).
+ * Branded type.
  *
  * @example '2019-06-21'
  */
-export type IsoDateString = string
+export type IsoDate = Branded<string, 'IsoDate'>
 
 /**
- * Interface explicitly states that the value is an ISO DateTime string (with time).
+ * ISO 8601 date (date+time).
+ * Branded type.
  *
  * @example '2019-06-21T05:21:73Z'
  */
-export type IsoDateTimeString = string
+export type IsoDateTime = Branded<string, 'IsoDateTime'>
 
 /**
  * Identifies the Month.
- * Like IsoDateString, but without the Day token.
+ * Like IsoDate, but without the Day token.
  *
  * @example '2023-09'
  */