@lbd-sh/date-tz 1.0.1

package/README.md

@@ -0,0 +1,147 @@
+# DateTz Class Documentation
+
+## Overview
+
+The `DateTz` class represents a date and time in a specific timezone. It provides utilities for formatting, parsing, comparing, and manipulating date and time values with full timezone support.
+
+---
+
+## Constructor
+
+```ts
+new DateTz(value: IDateTz)
+new DateTz(value: number, tz?: string)
+```
+
+- Accepts either an `IDateTz` object or a Unix timestamp with an optional timezone.
+- Throws an error if the provided timezone is invalid.
+
+---
+
+## Properties
+
+### Instance Properties
+
+- `timestamp: number` — Milliseconds since Unix epoch (UTC).
+- `timezone: string` — The timezone identifier (e.g., `"UTC"`, `"Europe/Rome"`).
+
+### Static Properties
+
+- `DateTz.defaultFormat: string` — Default string format pattern: `'YYYY-MM-DD HH:mm:ss'`.
+
+---
+
+## Getters
+
+- `timezoneOffset: number` — Returns the timezone offset in minutes.
+- `year: number` — Returns the full year.
+- `month: number` — Returns the month (0–11).
+- `day: number` — Returns the day of the month (1–31).
+- `hour: number` — Returns the hour (0–23).
+- `minute: number` — Returns the minute (0–59).
+- `dayOfWeek: number` — Returns the day of the week (0–6).
+
+---
+
+## Methods
+
+### `compare(other: IDateTz): number`
+
+Compares this instance with another `DateTz`. Throws if timezones differ.
+
+### `isComparable(other: IDateTz): boolean`
+
+Returns `true` if the two instances share the same timezone.
+
+### `toString(pattern?: string): string`
+
+Returns the string representation using the provided format.
+
+#### Format Tokens
+
+| Token      | Meaning         |
+| ---------- | --------------- |
+| YYYY, yyyy | Full year       |
+| YY, yy     | Last 2 digits   |
+| MM         | Month (01–12)   |
+| DD         | Day (01–31)     |
+| HH         | Hour (00–23)    |
+| hh         | Hour (01–12)    |
+| mm         | Minute (00–59)  |
+| ss         | Second (00–59)  |
+| aa, AA     | AM/PM marker    |
+| tz         | Timezone string |
+
+### `add(value: number, unit: 'minute' | 'hour' | 'day' | 'month' | 'year'): this`
+
+Adds the given time to the instance.
+
+### `set(value: number, unit: 'year' | 'month' | 'day' | 'hour' | 'minute'): this`
+
+Sets a specific part of the date/time.
+
+### `convertToTimezone(tz: string): this`
+
+Changes the timezone of the instance in place.
+
+### `cloneToTimezone(tz: string): DateTz`
+
+Returns a new instance in the specified timezone.
+
+---
+
+## Static Methods
+
+### `DateTz.parse(dateString: string, pattern?: string, tz?: string): DateTz`
+
+Parses a string to a `DateTz` instance.
+
+### `DateTz.now(tz?: string): DateTz`
+
+Returns the current date/time as a `DateTz` instance.
+
+---
+
+## Utility Methods (Private)
+
+- `stripSMs(timestamp: number): number` — Removes seconds and milliseconds.
+- `isLeapYear(year: number): boolean` — Determines if the year is a leap year.
+- `daysInYear(year: number): number` — Returns days in a year.
+
+---
+
+## Example
+
+```ts
+const dt = new DateTz(1719146400000, 'Europe/Rome');
+console.log(dt.toString());
+
+dt.add(1, 'day');
+console.log(dt.day);
+
+const parsed = DateTz.parse("2025-06-23 14:00:00", "YYYY-MM-DD HH:mm:ss", "Europe/Rome");
+console.log(parsed.toString());
+```
+
+---
+
+## Error Handling
+
+- Throws on invalid timezone.
+- Throws if trying to compare across timezones.
+- Throws if parsing a 12-hour format without AM/PM marker.
+
+---
+
+## Requirements
+
+Requires:
+- `timezones` object mapping timezone identifiers to UTC offsets.
+- `daysPerMonth`, `MS_PER_DAY`, `MS_PER_HOUR`, `MS_PER_MINUTE`, `epochYear` constants.
+
+---
+
+## Summary
+
+`DateTz` is ideal for handling precise and consistent date/time values across multiple timezones with customizable formatting, parsing, and manipulation options.
+

package/date-tz.d.ts

@@ -0,0 +1,41 @@
+import { IDateTz } from "./idate-tz";
+export declare class DateTz implements IDateTz {
+    timestamp: number;
+    timezone: string;
+    private offsetCache?;
+    static defaultFormat: string;
+    constructor(value: IDateTz);
+    constructor(value: number, tz?: string);
+    get timezoneOffset(): import("./timezones").TimezoneOffset;
+    compare(other: IDateTz): number;
+    isComparable(other: IDateTz): boolean;
+    toString(): string;
+    toString(pattern: string): string;
+    add(value: number, unit: 'minute' | 'hour' | 'day' | 'month' | 'year'): this;
+    private _year;
+    private _month;
+    private _day;
+    private _hour;
+    private _minute;
+    private _dayOfWeek;
+    convertToTimezone(tz: string): this;
+    cloneToTimezone(tz: string): DateTz;
+    private stripSMs;
+    private invalidateOffsetCache;
+    private getOffsetSeconds;
+    private getOffsetInfo;
+    private computeOffsetInfo;
+    private getIntlOffsetSeconds;
+    set(value: number, unit: 'year' | 'month' | 'day' | 'hour' | 'minute'): this;
+    private isLeapYear;
+    private daysInYear;
+    static parse(dateString: string, pattern?: string, tz?: string): DateTz;
+    static now(tz?: string): DateTz;
+    get isDst(): boolean;
+    get year(): number;
+    get month(): number;
+    get day(): number;
+    get hour(): number;
+    get minute(): number;
+    get dayOfWeek(): number;
+}

package/date-tz.js

@@ -0,0 +1,503 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DateTz = void 0;
+const timezones_1 = require("./timezones");
+const MS_PER_MINUTE = 60000;
+const MS_PER_HOUR = 3600000;
+const MS_PER_DAY = 86400000;
+const epochYear = 1970;
+const daysPerMonth = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+class DateTz {
+    constructor(value, tz) {
+        if (typeof value === 'object') {
+            this.timestamp = value.timestamp;
+            this.timezone = value.timezone || 'UTC';
+            if (!timezones_1.timezones[this.timezone]) {
+                throw new Error(`Invalid timezone: ${value.timezone}`);
+            }
+        }
+        else {
+            this.timezone = tz || 'UTC';
+            if (!timezones_1.timezones[this.timezone]) {
+                throw new Error(`Invalid timezone: ${tz}`);
+            }
+            this.timestamp = this.stripSMs(value);
+        }
+        this.invalidateOffsetCache();
+    }
+    get timezoneOffset() {
+        return timezones_1.timezones[this.timezone];
+    }
+    compare(other) {
+        if (this.isComparable(other)) {
+            return this.timestamp - other.timestamp;
+        }
+        throw new Error('Cannot compare dates with different timezones');
+    }
+    isComparable(other) {
+        return this.timezone === other.timezone;
+    }
+    toString(pattern, locale) {
+        if (!pattern)
+            pattern = 'YYYY-MM-DD HH:mm:ss';
+        const offsetInfo = this.getOffsetInfo();
+        const offset = offsetInfo.offsetSeconds * 1000;
+        let remainingMs = this.timestamp + offset;
+        let year = epochYear;
+        while (true) {
+            const daysInYear = this.isLeapYear(year) ? 366 : 365;
+            const msInYear = daysInYear * MS_PER_DAY;
+            if (remainingMs >= msInYear) {
+                remainingMs -= msInYear;
+                year++;
+            }
+            else {
+                break;
+            }
+        }
+        let month = 0;
+        while (month < 12) {
+            const daysInMonth = month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month];
+            const msInMonth = daysInMonth * MS_PER_DAY;
+            if (remainingMs >= msInMonth) {
+                remainingMs -= msInMonth;
+                month++;
+            }
+            else {
+                break;
+            }
+        }
+        const day = Math.floor(remainingMs / MS_PER_DAY) + 1;
+        remainingMs %= MS_PER_DAY;
+        const hour = Math.floor(remainingMs / MS_PER_HOUR);
+        remainingMs %= MS_PER_HOUR;
+        const minute = Math.floor(remainingMs / MS_PER_MINUTE);
+        remainingMs %= MS_PER_MINUTE;
+        const second = Math.floor(remainingMs / 1000);
+        const pm = hour >= 12 ? 'PM' : 'AM';
+        const hour12 = hour % 12 || 12;
+        if (!locale)
+            locale = 'en';
+        let monthStr = new Date(year, month, 3).toLocaleString(locale || 'en', { month: 'long' });
+        monthStr = monthStr.charAt(0).toUpperCase() + monthStr.slice(1);
+        const tokens = {
+            YYYY: year,
+            YY: String(year).slice(-2),
+            yyyy: year.toString(),
+            yy: String(year).slice(-2),
+            MM: String(month + 1).padStart(2, '0'),
+            LM: monthStr,
+            DD: String(day).padStart(2, '0'),
+            HH: String(hour).padStart(2, '0'),
+            mm: String(minute).padStart(2, '0'),
+            ss: String(second).padStart(2, '0'),
+            aa: pm.toLowerCase(),
+            AA: pm,
+            hh: hour12.toString().padStart(2, '0'),
+            tz: this.timezone,
+        };
+        return pattern.replace(/YYYY|yyyy|YY|yy|MM|LM|DD|HH|hh|mm|ss|aa|AA|tz/g, (match) => tokens[match]);
+    }
+    add(value, unit) {
+        let remainingMs = this.timestamp;
+        let year = 1970;
+        let days = Math.floor(remainingMs / MS_PER_DAY);
+        remainingMs %= MS_PER_DAY;
+        let hour = Math.floor(remainingMs / MS_PER_HOUR);
+        remainingMs %= MS_PER_HOUR;
+        let minute = Math.floor(remainingMs / MS_PER_MINUTE);
+        let second = Math.floor((remainingMs % MS_PER_MINUTE) / 1000);
+        while (days >= this.daysInYear(year)) {
+            days -= this.daysInYear(year);
+            year++;
+        }
+        let month = 0;
+        while (days >= (month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month])) {
+            days -= month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month];
+            month++;
+        }
+        let day = days + 1;
+        switch (unit) {
+            case 'minute':
+                minute += value;
+                break;
+            case 'hour':
+                hour += value;
+                break;
+            case 'day':
+                day += value;
+                break;
+            case 'month':
+                month += value;
+                break;
+            case 'year':
+                year += value;
+                break;
+            default:
+                throw new Error(`Unsupported unit: ${unit}`);
+        }
+        while (minute >= 60) {
+            minute -= 60;
+            hour++;
+        }
+        while (hour >= 24) {
+            hour -= 24;
+            day++;
+        }
+        while (month >= 12) {
+            month -= 12;
+            year++;
+        }
+        while (day > (month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month])) {
+            day -= month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month];
+            month++;
+            if (month >= 12) {
+                month = 0;
+                year++;
+            }
+        }
+        const newTimestamp = (() => {
+            let totalMs = 0;
+            for (let y = 1970; y < year; y++) {
+                totalMs += this.daysInYear(y) * MS_PER_DAY;
+            }
+            for (let m = 0; m < month; m++) {
+                totalMs += (m === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[m]) * MS_PER_DAY;
+            }
+            totalMs += (day - 1) * MS_PER_DAY;
+            totalMs += hour * MS_PER_HOUR;
+            totalMs += minute * MS_PER_MINUTE;
+            totalMs += second * 1000;
+            return totalMs;
+        })();
+        this.timestamp = newTimestamp;
+        this.invalidateOffsetCache();
+        return this;
+    }
+    _year(considerDst = false) {
+        const offset = this.getOffsetSeconds(considerDst) * 1000;
+        let remainingMs = this.timestamp + offset;
+        let year = 1970;
+        let days = Math.floor(remainingMs / MS_PER_DAY);
+        while (days >= this.daysInYear(year)) {
+            days -= this.daysInYear(year);
+            year++;
+        }
+        return year;
+    }
+    _month(considerDst = false) {
+        const offset = this.getOffsetSeconds(considerDst) * 1000;
+        let remainingMs = this.timestamp + offset;
+        let year = 1970;
+        let days = Math.floor(remainingMs / MS_PER_DAY);
+        while (days >= this.daysInYear(year)) {
+            days -= this.daysInYear(year);
+            year++;
+        }
+        let month = 0;
+        while (days >= (month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month])) {
+            days -= month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month];
+            month++;
+        }
+        return month;
+    }
+    _day(considerDst = false) {
+        const offset = this.getOffsetSeconds(considerDst) * 1000;
+        let remainingMs = this.timestamp + offset;
+        let year = 1970;
+        let days = Math.floor(remainingMs / MS_PER_DAY);
+        while (days >= this.daysInYear(year)) {
+            days -= this.daysInYear(year);
+            year++;
+        }
+        let month = 0;
+        while (days >= (month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month])) {
+            days -= month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month];
+            month++;
+        }
+        return days + 1;
+    }
+    _hour(considerDst = false) {
+        const offset = this.getOffsetSeconds(considerDst) * 1000;
+        let remainingMs = this.timestamp + offset;
+        remainingMs %= MS_PER_DAY;
+        let hour = Math.floor(remainingMs / MS_PER_HOUR);
+        return hour;
+    }
+    _minute(considerDst = false) {
+        const offset = this.getOffsetSeconds(considerDst) * 1000;
+        let remainingMs = this.timestamp + offset;
+        remainingMs %= MS_PER_HOUR;
+        let minute = Math.floor(remainingMs / MS_PER_MINUTE);
+        return minute;
+    }
+    _dayOfWeek(considerDst = false) {
+        const offset = this.getOffsetSeconds(considerDst) * 1000;
+        let remainingMs = this.timestamp + offset;
+        const date = new Date(remainingMs);
+        return date.getDay();
+    }
+    convertToTimezone(tz) {
+        if (!timezones_1.timezones[tz]) {
+            throw new Error(`Invalid timezone: ${tz}`);
+        }
+        this.timezone = tz;
+        this.invalidateOffsetCache();
+        return this;
+    }
+    cloneToTimezone(tz) {
+        if (!timezones_1.timezones[tz]) {
+            throw new Error(`Invalid timezone: ${tz}`);
+        }
+        const clone = new DateTz(this);
+        clone.timezone = tz;
+        clone.invalidateOffsetCache();
+        return clone;
+    }
+    stripSMs(timestamp) {
+        const days = Math.floor(timestamp / MS_PER_DAY);
+        const remainingAfterDays = timestamp % MS_PER_DAY;
+        const hours = Math.floor(remainingAfterDays / MS_PER_HOUR);
+        const remainingAfterHours = remainingAfterDays % MS_PER_HOUR;
+        const minutes = Math.floor(remainingAfterHours / MS_PER_MINUTE);
+        return days * MS_PER_DAY + hours * MS_PER_HOUR + minutes * MS_PER_MINUTE;
+    }
+    invalidateOffsetCache() {
+        this.offsetCache = undefined;
+    }
+    getOffsetSeconds(considerDst) {
+        const tzInfo = timezones_1.timezones[this.timezone];
+        if (!tzInfo) {
+            throw new Error(`Invalid timezone: ${this.timezone}`);
+        }
+        if (!considerDst) {
+            return tzInfo.sdt;
+        }
+        return this.getOffsetInfo().offsetSeconds;
+    }
+    getOffsetInfo() {
+        if (this.offsetCache && this.offsetCache.timestamp === this.timestamp) {
+            return this.offsetCache.info;
+        }
+        const info = this.computeOffsetInfo();
+        this.offsetCache = { timestamp: this.timestamp, info };
+        return info;
+    }
+    computeOffsetInfo() {
+        const tzInfo = timezones_1.timezones[this.timezone];
+        if (!tzInfo) {
+            throw new Error(`Invalid timezone: ${this.timezone}`);
+        }
+        if (tzInfo.dst === tzInfo.sdt) {
+            return { offsetSeconds: tzInfo.sdt, isDst: false };
+        }
+        const actual = this.getIntlOffsetSeconds(this.timestamp);
+        if (actual !== null) {
+            if (actual !== tzInfo.sdt && actual !== tzInfo.dst) {
+                return { offsetSeconds: actual, isDst: actual > tzInfo.sdt };
+            }
+            return { offsetSeconds: actual, isDst: actual === tzInfo.dst };
+        }
+        return { offsetSeconds: tzInfo.sdt, isDst: false };
+    }
+    getIntlOffsetSeconds(timestamp) {
+        try {
+            const formatter = new Intl.DateTimeFormat('en-US', {
+                timeZone: this.timezone,
+                hour12: false,
+                year: 'numeric',
+                month: '2-digit',
+                day: '2-digit',
+                hour: '2-digit',
+                minute: '2-digit',
+                second: '2-digit'
+            });
+            const parts = formatter.formatToParts(new Date(timestamp));
+            const lookup = (type) => {
+                const part = parts.find(p => p.type === type);
+                if (!part) {
+                    throw new Error(`Missing part ${type}`);
+                }
+                return Number(part.value);
+            };
+            const adjusted = Date.UTC(lookup('year'), lookup('month') - 1, lookup('day'), lookup('hour'), lookup('minute'), lookup('second'));
+            return Math.round((adjusted - timestamp) / 1000);
+        }
+        catch {
+            return null;
+        }
+    }
+    set(value, unit) {
+        let remainingMs = this.timestamp;
+        let year = 1970;
+        let days = Math.floor(remainingMs / MS_PER_DAY);
+        remainingMs %= MS_PER_DAY;
+        let hour = Math.floor(remainingMs / MS_PER_HOUR);
+        remainingMs %= MS_PER_HOUR;
+        let minute = Math.floor(remainingMs / MS_PER_MINUTE);
+        let second = Math.floor((remainingMs % MS_PER_MINUTE) / 1000);
+        while (days >= this.daysInYear(year)) {
+            days -= this.daysInYear(year);
+            year++;
+        }
+        let month = 0;
+        while (days >= (month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month])) {
+            days -= month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month];
+            month++;
+        }
+        let day = days + 1;
+        switch (unit) {
+            case 'year':
+                year = value;
+                break;
+            case 'month':
+                month = value - 1;
+                break;
+            case 'day':
+                day = value;
+                break;
+            case 'hour':
+                hour = value;
+                break;
+            case 'minute':
+                minute = value;
+                break;
+            default:
+                throw new Error(`Unsupported unit: ${unit}`);
+        }
+        while (month >= 12) {
+            month -= 12;
+            year++;
+        }
+        while (day > (month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month])) {
+            day -= month === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[month];
+            month++;
+            if (month >= 12) {
+                month = 0;
+                year++;
+            }
+        }
+        const newTimestamp = (() => {
+            let totalMs = 0;
+            for (let y = 1970; y < year; y++) {
+                totalMs += this.daysInYear(y) * MS_PER_DAY;
+            }
+            for (let m = 0; m < month; m++) {
+                totalMs += (m === 1 && this.isLeapYear(year) ? 29 : daysPerMonth[m]) * MS_PER_DAY;
+            }
+            totalMs += (day - 1) * MS_PER_DAY;
+            totalMs += hour * MS_PER_HOUR;
+            totalMs += minute * MS_PER_MINUTE;
+            totalMs += second * 1000;
+            return totalMs;
+        })();
+        this.timestamp = newTimestamp;
+        this.invalidateOffsetCache();
+        return this;
+    }
+    isLeapYear(year) {
+        return (year % 4 === 0 && year % 100 !== 0) || (year % 400 === 0);
+    }
+    daysInYear(year) {
+        return this.isLeapYear(year) ? 366 : 365;
+    }
+    static parse(dateString, pattern, tz) {
+        if (!pattern)
+            pattern = DateTz.defaultFormat;
+        if (!tz)
+            tz = 'UTC';
+        if (!timezones_1.timezones[tz]) {
+            throw new Error(`Invalid timezone: ${tz}`);
+        }
+        if (pattern.includes('hh') && (!pattern.includes('aa') || !pattern.includes('AA'))) {
+            throw new Error('AM/PM marker (aa or AA) is required when using 12-hour format (hh)');
+        }
+        const regex = /YYYY|yyyy|MM|DD|HH|hh|mm|ss|aa|AA/g;
+        const dateComponents = {
+            YYYY: 1970,
+            yyyy: 1970,
+            MM: 0,
+            DD: 0,
+            HH: 0,
+            hh: 0,
+            aa: 'am',
+            AA: "AM",
+            mm: 0,
+            ss: 0,
+        };
+        let match;
+        let index = 0;
+        while ((match = regex.exec(pattern)) !== null) {
+            const token = match[0];
+            const value = parseInt(dateString.substring(match.index, match.index + token.length), 10);
+            dateComponents[token] = value;
+            index += token.length + 1;
+        }
+        const year = dateComponents.YYYY || dateComponents.yyyy;
+        const month = dateComponents.MM - 1;
+        const day = dateComponents.DD;
+        let hour = 0;
+        const ampm = (dateComponents.a || dateComponents.A);
+        if (ampm) {
+            hour = ampm.toUpperCase() === 'AM' ? dateComponents.hh : dateComponents.hh + 12;
+        }
+        else {
+            hour = dateComponents.HH;
+        }
+        const minute = dateComponents.mm;
+        const second = dateComponents.ss;
+        const daysInYear = (year) => (year % 4 === 0 && year % 100 !== 0) || (year % 400 === 0) ? 366 : 365;
+        const daysInMonth = (year, month) => month === 1 && daysInYear(year) === 366 ? 29 : daysPerMonth[month];
+        let timestamp = 0;
+        for (let y = 1970; y < year; y++) {
+            timestamp += daysInYear(y) * MS_PER_DAY;
+        }
+        for (let m = 0; m < month; m++) {
+            timestamp += daysInMonth(year, m) * MS_PER_DAY;
+        }
+        timestamp += (day - 1) * MS_PER_DAY;
+        timestamp += hour * MS_PER_HOUR;
+        timestamp += minute * MS_PER_MINUTE;
+        timestamp += second * 1000;
+        const offset = (timezones_1.timezones[tz].sdt) * 1000;
+        let remainingMs = timestamp - offset;
+        const date = new DateTz(remainingMs, tz);
+        date.timestamp -= date.isDst ? (timezones_1.timezones[tz].dst - timezones_1.timezones[tz].sdt) * 1000 : 0;
+        date.invalidateOffsetCache();
+        return date;
+    }
+    static now(tz) {
+        if (!tz)
+            tz = 'UTC';
+        const timezone = timezones_1.timezones[tz];
+        if (!timezone) {
+            throw new Error(`Invalid timezone: ${tz}`);
+        }
+        const date = new DateTz(Date.now(), tz);
+        return date;
+    }
+    get isDst() {
+        return this.getOffsetInfo().isDst;
+    }
+    get year() {
+        return this._year(true);
+    }
+    get month() {
+        return this._month(true);
+    }
+    get day() {
+        return this._day(true);
+    }
+    get hour() {
+        return this._hour(true);
+    }
+    get minute() {
+        return this._minute(true);
+    }
+    get dayOfWeek() {
+        return this._dayOfWeek(true);
+    }
+}
+exports.DateTz = DateTz;
+DateTz.defaultFormat = 'YYYY-MM-DD HH:mm:ss';
+//# sourceMappingURL=date-tz.js.map