@naturalcycles/js-lib 14.88.0 → 14.91.0

package/dist/datetime/localDate.d.ts

@@ -0,0 +1,80 @@
+import { Sequence } from '../seq/seq';
+import { IsoDate } from '../types';
+export declare type LocalDateUnit = 'year' | 'month' | 'day';
+export declare type LocalDateConfig = LocalDate | string;
+/**
+ * @experimental
+ */
+export declare class LocalDate {
+    year: number;
+    month: number;
+    day: number;
+    private constructor();
+    static create(year: number, month: number, day: number): LocalDate;
+    /**
+     * Parses input String into LocalDate.
+     * Input can already be a LocalDate - it is returned as-is in that case.
+     */
+    static of(d: LocalDateConfig): LocalDate;
+    static parseCompact(d: string): LocalDate;
+    static fromDate(d: Date): LocalDate;
+    /**
+     * Returns null if invalid.
+     */
+    static parseOrNull(d: LocalDateConfig): LocalDate | null;
+    static isValid(iso: string): boolean;
+    static today(): LocalDate;
+    static sort(items: LocalDate[], mutate?: boolean, descending?: boolean): LocalDate[];
+    static earliestOrUndefined(items: LocalDate[]): LocalDate | undefined;
+    static earliest(items: LocalDate[]): LocalDate;
+    static latestOrUndefined(items: LocalDate[]): LocalDate | undefined;
+    static latest(items: LocalDate[]): LocalDate;
+    static range(minIncl: LocalDateConfig, maxExcl: LocalDateConfig, step?: number, stepUnit?: LocalDateUnit): LocalDate[];
+    static rangeSeq(minIncl: LocalDateConfig, maxExcl: LocalDateConfig, step?: number, stepUnit?: LocalDateUnit): Sequence<LocalDate>;
+    static rangeString(minIncl: LocalDateConfig, maxExcl: LocalDateConfig, step?: number, stepUnit?: LocalDateUnit): IsoDate[];
+    static rangeIncl(minIncl: LocalDateConfig, maxIncl: LocalDateConfig, step?: number, stepUnit?: LocalDateUnit): LocalDate[];
+    static rangeInclString(minIncl: LocalDateConfig, maxIncl: LocalDateConfig, step?: number, stepUnit?: LocalDateUnit): IsoDate[];
+    isSame(d: LocalDateConfig): boolean;
+    isBefore(d: LocalDateConfig): boolean;
+    isSameOrBefore(d: LocalDateConfig): boolean;
+    isAfter(d: LocalDateConfig): boolean;
+    isSameOrAfter(d: LocalDateConfig): boolean;
+    /**
+     * Returns 1 if this > d
+     * returns 0 if they are equal
+     * returns -1 if this < d
+     */
+    cmp(d: LocalDateConfig): -1 | 0 | 1;
+    /**
+     * Same as Math.abs( diff )
+     */
+    absDiff(d: LocalDateConfig, unit: LocalDateUnit): number;
+    /**
+     * Returns the number of **full** units difference (aka `Math.ceil`).
+     *
+     * a.diff(b) means "a minus b"
+     */
+    diff(d: LocalDateConfig, unit: LocalDateUnit): number;
+    add(num: number, unit: LocalDateUnit, mutate?: boolean): LocalDate;
+    subtract(num: number, unit: LocalDateUnit, mutate?: boolean): LocalDate;
+    startOf(unit: LocalDateUnit): LocalDate;
+    endOf(unit: LocalDateUnit): LocalDate;
+    static getYearLength(year: number): number;
+    static getMonthLength(year: number, month: number): number;
+    static isLeapYear(year: number): boolean;
+    clone(): LocalDate;
+    /**
+     * Converts LocalDate into instance of Date.
+     * Year, month and day will match.
+     * Hour, minute, second, ms will be 0.
+     * Timezone will match local timezone.
+     */
+    toDate(): Date;
+    toString(): IsoDate;
+    toStringCompact(): string;
+    toJSON(): IsoDate;
+}
+/**
+ * Shortcut wrapper around `LocalDate.parse` / `LocalDate.today`
+ */
+export declare function localDate(d?: LocalDateConfig): LocalDate;

package/dist/datetime/localDate.js

@@ -0,0 +1,310 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localDate = exports.LocalDate = void 0;
+const assert_1 = require("../error/assert");
+const seq_1 = require("../seq/seq");
+const types_1 = require("../types");
+const m31 = new Set([1, 3, 5, 7, 8, 10, 12]);
+/**
+ * @experimental
+ */
+class LocalDate {
+    constructor(year, month, day) {
+        this.year = year;
+        this.month = month;
+        this.day = day;
+    }
+    static create(year, month, day) {
+        return new LocalDate(year, month, day);
+    }
+    /**
+     * Parses input String into LocalDate.
+     * Input can already be a LocalDate - it is returned as-is in that case.
+     */
+    static of(d) {
+        const t = this.parseOrNull(d);
+        if (t === null) {
+            throw new Error(`Cannot parse "${d}" into LocalDate`);
+        }
+        return t;
+    }
+    static parseCompact(d) {
+        const [year, month, day] = [d.slice(0, 4), d.slice(4, 2), d.slice(6, 2)].map(Number);
+        if (!day || !month || !year) {
+            throw new Error(`Cannot parse "${d}" into LocalDate`);
+        }
+        return new LocalDate(year, month, day);
+    }
+    static fromDate(d) {
+        return new LocalDate(d.getFullYear(), d.getMonth() + 1, d.getDate());
+    }
+    /**
+     * Returns null if invalid.
+     */
+    static parseOrNull(d) {
+        if (d instanceof LocalDate)
+            return d;
+        // todo: explore more performant options
+        const [year, month, day] = d.slice(0, 10).split('-').map(Number);
+        if (!year ||
+            !month ||
+            month < 1 ||
+            month > 12 ||
+            !day ||
+            day < 1 ||
+            day > this.getMonthLength(year, month)) {
+            return null;
+        }
+        return new LocalDate(year, month, day);
+    }
+    static isValid(iso) {
+        return this.parseOrNull(iso) !== null;
+    }
+    static today() {
+        return this.fromDate(new Date());
+    }
+    static sort(items, mutate = false, descending = false) {
+        const mod = descending ? -1 : 1;
+        return (mutate ? items : [...items]).sort((a, b) => a.cmp(b) * mod);
+    }
+    static earliestOrUndefined(items) {
+        return items.length ? LocalDate.earliest(items) : undefined;
+    }
+    static earliest(items) {
+        (0, assert_1._assert)(items.length, 'LocalDate.earliest called on empty array');
+        return items.reduce((min, item) => (min.isSameOrBefore(item) ? min : item));
+    }
+    static latestOrUndefined(items) {
+        return items.length ? LocalDate.latest(items) : undefined;
+    }
+    static latest(items) {
+        (0, assert_1._assert)(items.length, 'LocalDate.latest called on empty array');
+        return items.reduce((max, item) => (max.isSameOrAfter(item) ? max : item));
+    }
+    static range(minIncl, maxExcl, step = 1, stepUnit = 'day') {
+        const days = [];
+        let current = LocalDate.of(minIncl).startOf(stepUnit);
+        const max = LocalDate.of(maxExcl).startOf(stepUnit);
+        do {
+            days.push(current);
+            current = current.add(step, stepUnit);
+        } while (current.isBefore(max));
+        return days;
+    }
+    static rangeSeq(minIncl, maxExcl, step = 1, stepUnit = 'day') {
+        const min = LocalDate.of(minIncl).startOf(stepUnit);
+        const max = LocalDate.of(maxExcl).startOf(stepUnit);
+        return seq_1.Sequence.create(min, d => {
+            const next = d.add(step, stepUnit);
+            return next.isAfter(max) ? types_1.END : next;
+        });
+    }
+    static rangeString(minIncl, maxExcl, step = 1, stepUnit = 'day') {
+        return LocalDate.range(minIncl, maxExcl, step, stepUnit).map(ld => ld.toString());
+    }
+    static rangeIncl(minIncl, maxIncl, step = 1, stepUnit = 'day') {
+        return LocalDate.range(minIncl, LocalDate.of(maxIncl).add(1, stepUnit), step, stepUnit);
+    }
+    static rangeInclString(minIncl, maxIncl, step = 1, stepUnit = 'day') {
+        return LocalDate.range(minIncl, LocalDate.of(maxIncl).add(1, stepUnit), step, stepUnit).map(ld => ld.toString());
+    }
+    isSame(d) {
+        d = LocalDate.of(d);
+        return this.day === d.day && this.month === d.month && this.year === d.year;
+    }
+    isBefore(d) {
+        return this.cmp(d) === -1;
+    }
+    isSameOrBefore(d) {
+        return this.cmp(d) <= 0;
+    }
+    isAfter(d) {
+        return this.cmp(d) === 1;
+    }
+    isSameOrAfter(d) {
+        return this.cmp(d) >= 0;
+    }
+    /**
+     * Returns 1 if this > d
+     * returns 0 if they are equal
+     * returns -1 if this < d
+     */
+    cmp(d) {
+        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;
+        return 0;
+    }
+    /**
+     * Same as Math.abs( diff )
+     */
+    absDiff(d, unit) {
+        return Math.abs(this.diff(d, unit));
+    }
+    /**
+     * Returns the number of **full** units difference (aka `Math.ceil`).
+     *
+     * a.diff(b) means "a minus b"
+     */
+    diff(d, unit) {
+        d = LocalDate.of(d);
+        if (unit === 'year') {
+            return this.year - d.year;
+        }
+        if (unit === 'month') {
+            return (this.year - d.year) * 12 + (this.month - d.month);
+        }
+        // unit is 'day'
+        let days = this.day - d.day;
+        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++) {
+                days -= LocalDate.getYearLength(year);
+            }
+        }
+        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);
+            }
+        }
+        return days;
+    }
+    add(num, unit, mutate = false) {
+        let { day, month, year } = this;
+        if (unit === 'day') {
+            day += num;
+        }
+        else if (unit === 'month') {
+            month += num;
+        }
+        else if (unit === 'year') {
+            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;
+            }
+            monLen = LocalDate.getMonthLength(year, month);
+        }
+        while (day < 1) {
+            day += monLen;
+            month -= 1;
+            if (month < 1) {
+                year -= 1;
+                month += 12;
+            }
+            monLen = LocalDate.getMonthLength(year, month);
+        }
+        // check month overflow
+        while (month > 12) {
+            year += 1;
+            month -= 12;
+        }
+        while (month < 1) {
+            year -= 1;
+            month += 12;
+        }
+        if (mutate) {
+            this.year = year;
+            this.month = month;
+            this.day = day;
+            return this;
+        }
+        return new LocalDate(year, month, day);
+    }
+    subtract(num, unit, mutate = false) {
+        return this.add(-num, unit, mutate);
+    }
+    startOf(unit) {
+        if (unit === 'day')
+            return this;
+        if (unit === 'month')
+            return LocalDate.create(this.year, this.month, 1);
+        // year
+        return LocalDate.create(this.year, 1, 1);
+    }
+    endOf(unit) {
+        if (unit === 'day')
+            return this;
+        if (unit === 'month')
+            return LocalDate.create(this.year, this.month, LocalDate.getMonthLength(this.year, this.month));
+        // year
+        return LocalDate.create(this.year, 12, 31);
+    }
+    static getYearLength(year) {
+        return this.isLeapYear(year) ? 366 : 365;
+    }
+    static getMonthLength(year, month) {
+        if (month === 2)
+            return this.isLeapYear(year) ? 29 : 28;
+        return m31.has(month) ? 31 : 30;
+    }
+    static isLeapYear(year) {
+        if (year % 4 !== 0)
+            return false;
+        if (year % 100 !== 0)
+            return true;
+        return year % 400 === 0;
+    }
+    clone() {
+        return new LocalDate(this.year, this.month, this.day);
+    }
+    /**
+     * Converts LocalDate into instance of Date.
+     * Year, month and day will match.
+     * Hour, minute, second, ms will be 0.
+     * Timezone will match local timezone.
+     */
+    toDate() {
+        return new Date(this.year, this.month - 1, this.day);
+    }
+    toString() {
+        return [
+            String(this.year).padStart(4, '0'),
+            String(this.month).padStart(2, '0'),
+            String(this.day).padStart(2, '0'),
+        ].join('-');
+    }
+    toStringCompact() {
+        return [
+            String(this.year).padStart(4, '0'),
+            String(this.month).padStart(2, '0'),
+            String(this.day).padStart(2, '0'),
+        ].join('');
+    }
+    toJSON() {
+        return this.toString();
+    }
+}
+exports.LocalDate = LocalDate;
+/**
+ * Shortcut wrapper around `LocalDate.parse` / `LocalDate.today`
+ */
+function localDate(d) {
+    return d ? LocalDate.of(d) : LocalDate.today();
+}
+exports.localDate = localDate;

package/dist/datetime/localTime.d.ts

@@ -0,0 +1,87 @@
+import { IsoDateTime, UnixTimestamp } from '../types';
+export declare type LocalTimeUnit = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second';
+export declare type LocalTimeConfig = LocalTime | Date | IsoDateTime | UnixTimestamp;
+export interface LocalTimeComponents {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+}
+/**
+ * @experimental
+ */
+export declare class LocalTime {
+    private $date;
+    private constructor();
+    /**
+     * Parses input String into LocalDate.
+     * Input can already be a LocalDate - it is returned as-is in that case.
+     */
+    static of(d: LocalTimeConfig): LocalTime;
+    /**
+     * Returns null if invalid
+     */
+    static parseOrNull(d: LocalTimeConfig): LocalTime | null;
+    static isValid(d: LocalTimeConfig): boolean;
+    static unix(ts: UnixTimestamp): LocalTime;
+    static now(): LocalTime;
+    static fromComponents(c: {
+        year: number;
+        month: number;
+    } & Partial<LocalTimeComponents>): LocalTime;
+    get(unit: LocalTimeUnit): number;
+    set(unit: LocalTimeUnit, v: number, mutate?: boolean): LocalTime;
+    year(): number;
+    year(v: number): LocalTime;
+    month(): number;
+    month(v: number): LocalTime;
+    date(): number;
+    date(v: number): LocalTime;
+    hour(): number;
+    hour(v: number): LocalTime;
+    minute(): number;
+    minute(v: number): LocalTime;
+    second(): number;
+    second(v: number): LocalTime;
+    setComponents(c: Partial<LocalTimeComponents>, mutate?: boolean): LocalTime;
+    add(num: number, unit: LocalTimeUnit, mutate?: boolean): LocalTime;
+    subtract(num: number, unit: LocalTimeUnit, mutate?: boolean): LocalTime;
+    absDiff(other: LocalTimeConfig, unit: LocalTimeUnit): number;
+    diff(other: LocalTimeConfig, unit: LocalTimeUnit): number;
+    startOf(unit: LocalTimeUnit, mutate?: boolean): LocalTime;
+    static sort(items: LocalTime[], mutate?: boolean, descending?: boolean): LocalTime[];
+    static earliestOrUndefined(items: LocalTime[]): LocalTime | undefined;
+    static earliest(items: LocalTime[]): LocalTime;
+    static latestOrUndefined(items: LocalTime[]): LocalTime | undefined;
+    static latest(items: LocalTime[]): LocalTime;
+    isSame(d: LocalTimeConfig): boolean;
+    isBefore(d: LocalTimeConfig): boolean;
+    isSameOrBefore(d: LocalTimeConfig): boolean;
+    isAfter(d: LocalTimeConfig): boolean;
+    isSameOrAfter(d: LocalTimeConfig): boolean;
+    /**
+     * Returns 1 if this > d
+     * returns 0 if they are equal
+     * returns -1 if this < d
+     */
+    cmp(d: LocalTimeConfig): -1 | 0 | 1;
+    components(): LocalTimeComponents;
+    getDate(): Date;
+    clone(): LocalTime;
+    unix(): UnixTimestamp;
+    valueOf(): UnixTimestamp;
+    toISO8601(): IsoDateTime;
+    toPretty(seconds?: boolean): IsoDateTime;
+    /**
+     * Returns e.g: `19840621_1705`
+     */
+    toStringCompact(seconds?: boolean): string;
+    toString(): string;
+    toJSON(): UnixTimestamp;
+}
+/**
+ * Shortcut wrapper around `LocalDate.parse` / `LocalDate.today`
+ */
+export declare function localTime(d?: LocalTimeConfig): LocalTime;