@naturalcycles/js-lib 14.243.1 → 14.245.0

package/dist/datetime/localTime.d.ts

@@ -15,6 +15,7 @@ export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestam
 export type LocalTimeInputNullable = LocalTimeInput | null | undefined;
 export type LocalTimeFormatter = (ld: LocalTime) => string;
 export type DateTimeObject = DateObject & TimeObject;
+export type DateTimeObjectInput = DateObject & Partial<TimeObject>;
 export interface DateObject {
     year: number;
     month: number;
@@ -32,12 +33,12 @@ export declare class LocalTime {
      * Returns [cloned] LocalTime that is based on the same unixtimestamp, but in UTC timezone.
      * Opposite of `.local()` method.
      */
-    utc(): LocalTime;
+    toUTC(): LocalTime;
     /**
      * Returns [cloned] LocalTime that is based on the same unixtimestamp, but in local timezone.
      * Opposite of `.utc()` method.
      */
-    local(): LocalTime;
+    toLocal(): LocalTime;
     /**
      * Returns [cloned] fake LocalTime that has yyyy-mm-dd hh:mm:ss in the provided timezone.
      * It is a fake LocalTime in a sense that it's timezone is not real.
@@ -85,25 +86,25 @@ export declare class LocalTime {
     getUTCOffsetString(tz: string): string;
     get(unit: LocalTimeUnit): number;
     set(unit: LocalTimeUnit, v: number, mutate?: boolean): LocalTime;
-    year(): number;
-    year(v: number): LocalTime;
-    month(): number;
-    month(v: number): LocalTime;
-    week(): number;
-    week(v: number): LocalTime;
-    day(): number;
-    day(v: number): LocalTime;
+    get year(): number;
+    setYear(v: number): LocalTime;
+    get month(): number;
+    setMonth(v: number): LocalTime;
+    get week(): number;
+    setWeek(v: number): LocalTime;
+    get day(): number;
+    setDay(v: number): LocalTime;
+    get hour(): number;
+    setHour(v: number): LocalTime;
+    get minute(): number;
+    setMinute(v: number): LocalTime;
+    get second(): number;
+    setSecond(v: number): LocalTime;
     /**
      * Based on ISO: 1-7 is Mon-Sun.
      */
-    dayOfWeek(): ISODayOfWeek;
-    dayOfWeek(v: ISODayOfWeek): LocalTime;
-    hour(): number;
-    hour(v: number): LocalTime;
-    minute(): number;
-    minute(v: number): LocalTime;
-    second(): number;
-    second(v: number): LocalTime;
+    get dayOfWeek(): ISODayOfWeek;
+    setDayOfWeek(v: ISODayOfWeek): LocalTime;
     setComponents(c: Partial<DateTimeObject>, mutate?: boolean): LocalTime;
     plusSeconds(num: number): LocalTime;
     plusMinutes(num: number): LocalTime;
@@ -129,7 +130,7 @@ export declare class LocalTime {
      * Returns how many days are in the current month.
      * E.g 31 for January.
      */
-    daysInMonth(): number;
+    get daysInMonth(): number;
     isSame(d: LocalTimeInput): boolean;
     isBefore(d: LocalTimeInput, inclusive?: boolean): boolean;
     isSameOrBefore(d: LocalTimeInput): boolean;
@@ -176,15 +177,15 @@ export declare class LocalTime {
      * returns 0 if they are equal
      * returns -1 if this < d
      */
-    cmp(d: LocalTimeInput): -1 | 0 | 1;
-    getDateTimeObject(): DateTimeObject;
-    getDateObject(): DateObject;
-    getTimeObject(): TimeObject;
-    fromNow(now?: LocalTimeInput): string;
-    getDate(): Date;
+    compare(d: LocalTimeInput): -1 | 0 | 1;
+    toDateTimeObject(): DateTimeObject;
+    toDateObject(): DateObject;
+    toTimeObject(): TimeObject;
+    toFromNowString(now?: LocalTimeInput): string;
+    toDate(): Date;
     clone(): LocalTime;
-    unix(): UnixTimestampNumber;
-    unixMillis(): UnixTimestampMillisNumber;
+    get unix(): UnixTimestampNumber;
+    get unixMillis(): UnixTimestampMillisNumber;
     valueOf(): UnixTimestampNumber;
     toLocalDate(): LocalDate;
     /**
@@ -216,20 +217,71 @@ export declare class LocalTime {
 }
 declare class LocalTimeFactory {
     /**
-     * Parses input String into LocalDate.
-     * Input can already be a LocalDate - it is returned as-is in that case.
+     * Creates a LocalTime from the input, unless it's falsy - then returns undefined.
+     *
+     * `localTime` function will instead return LocalTime of `now` for falsy input.
      */
-    of(d: LocalTimeInput): LocalTime;
+    orUndefined(input: LocalTimeInputNullable): LocalTime | undefined;
     /**
-     * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
+     * Creates a LocalTime from the input, unless it's falsy - then returns LocalTime.now
+     */
+    orNow(input: LocalTimeInputNullable): LocalTime;
+    now(): LocalTime;
+    /**
+     Convenience function to return current Unix timestamp in seconds.
+     Like Date.now(), but in seconds.
+     */
+    nowUnix(): UnixTimestampNumber;
+    /**
+     * Create LocalTime from LocalTimeInput.
+     * Input can already be a LocalTime - it is returned as-is in that case.
+     * Date - will be used as-is.
+     * String - will be parsed as strict `yyyy-mm-ddThh:mm:ss`.
+     * Number - will be treated as unix timestamp in seconds.
+     */
+    fromInput(input: LocalTimeInput): LocalTime;
+    /**
+     * Returns true if input is valid to create LocalTime.
+     */
+    isValid(input: LocalTimeInputNullable): boolean;
+    /**
+     * Returns true if isoString is a valid iso8601 string like `yyyy-mm-ddThh:mm:dd`.
+     */
+    isValidString(isoString: string | undefined | null): boolean;
+    /**
+     * Tries to convert/parse the input into LocalTime.
+     * Uses LOOSE parsing.
+     * If invalid - doesn't throw, but returns undefined instead.
      */
-    ofMillis(millis: UnixTimestampMillisNumber): LocalTime;
+    try(input: LocalTimeInputNullable): LocalTime | undefined;
     /**
-     * Returns null if invalid
+     * Performs STRICT parsing.
+     * Only allows IsoDateTimeString or IsoDateString input, nothing else.
      */
-    parseOrNull(d: LocalTimeInputNullable): LocalTime | null;
-    private parseStringToDateOrNull;
-    isValid(d: LocalTimeInputNullable): boolean;
+    fromIsoDateTimeString(s: IsoDateTimeString | IsoDateString): 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.
+     */
+    parse(s: string): LocalTime;
+    private parseStrictlyOrUndefined;
+    private parseLooselyOrUndefined;
+    /**
+     * Throws on invalid value.
+     */
+    private validateDateTimeObject;
+    isDateTimeObjectValid(o: DateTimeObject): boolean;
+    isTimeObjectValid({ hour, minute, second }: TimeObject): boolean;
+    fromDate(date: Date): LocalTime;
+    fromUnix(ts: UnixTimestampNumber): LocalTime;
+    /**
+     * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
+     */
+    fromMillis(millis: UnixTimestampMillisNumber): LocalTime;
+    fromDateTimeObject(o: DateTimeObjectInput): LocalTime;
+    private createDateFromDateTimeObject;
     /**
      * Returns the IANA timezone e.g `Europe/Stockholm`.
      * https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
@@ -243,21 +295,6 @@ declare class LocalTimeFactory {
      * consider caching the Intl.supportedValuesOf values as Set and reuse that.
      */
     isTimezoneValid(tz: string): boolean;
-    now(): LocalTime;
-    /**
-     * Creates a LocalTime from the input, unless it's falsy - then returns undefined.
-     *
-     * `localTime` function will instead return LocalTime of `now` for falsy input.
-     */
-    orUndefined(d: LocalTimeInputNullable): LocalTime | undefined;
-    /**
-     * Creates a LocalTime from the input, unless it's falsy - then returns LocalTime.now
-     */
-    orNow(d: LocalTimeInputNullable): LocalTime;
-    fromComponents(c: {
-        year: number;
-        month: number;
-    } & Partial<DateTimeObject>): LocalTime;
     sort(items: LocalTime[], dir?: SortDirection, mutate?: boolean): LocalTime[];
     minOrUndefined(items: LocalTimeInputNullable[]): LocalTime | undefined;
     min(items: LocalTimeInputNullable[]): LocalTime;
@@ -268,9 +305,4 @@ interface LocalTimeFn extends LocalTimeFactory {
     (d: LocalTimeInput): LocalTime;
 }
 export declare const localTime: LocalTimeFn;
-/**
- Convenience function to return current Unix timestamp in seconds.
- Like Date.now(), but in seconds.
- */
-export declare function nowUnix(): UnixTimestampNumber;
 export {};