fix(dora): timezone support for Dora.parse() and utcOffset fix (#84)

* fix(dora): fix $utcOffset calculation, add readonly fields, clarify add() overflow prevention

- Fix $utcOffset calculation: replace short-circuit OR logic with explicit
  Date.UTC subtraction to correctly handle year/month boundary crossing
- Add readonly to all date component fields ($y $M $D $W $H $m $s $ms)
- Rename WEEKDAY_NAME to WEEKDAY_ABBR in date-tools.ts and remove export
  to distinguish it from the full-name WEEKDAY_NAME in dora.ts
- Add comments on add('year') and add('month') explaining the date(5) pin trick
- Add utc_offset() tests covering UTC+/UTC-/UTC+14/UTC-11 year boundaries
  and non-whole-hour offset (UTC+5:30)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat(dora): support timezone parameter in Dora.parse()

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore: add tarpit logo image

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* chore: release @tarpit/dora@2.3.0

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: isatiso

docs/static/img/tarpit-logo.png

@@ -1,5 +1,16 @@
 # @tarpit/dora
 
+## 2.3.0
+
+### Minor Changes
+
+- Add timezone support to `Dora.parse()` and fix date calculation issues.
+
+  - Add `timezone` parameter to `Dora.parse()` for parsing date strings in a specific timezone
+  - Fix `$utcOffset` calculation to correctly reflect the parsed timezone offset
+  - Add readonly fields to improve immutability guarantees
+  - Clarify `add()` method overflow prevention behavior
+
 ## 2.0.1
 
 ### Patch Changes

packages/dora/CHANGELOG.md

@@ -1,6 +1,6 @@
 {
     "name": "@tarpit/dora",
-    "version": "2.1.1",
+    "version": "2.3.0",
     "description": "Out of the box Date Object based on native Date.",
     "author": "Cao Jiahang <sieglive@gmail.com>",
     "homepage": "https://github.com/isatiso/node-tarpit#readme",

packages/dora/package.json

@@ -6,7 +6,7 @@
  * found in the LICENSE file at source root.
  */
 
-export const WEEKDAY_NAME = 'Sun_Mon_Tue_Wed_Thu_Fri_Sat'.split('_')
+const WEEKDAY_ABBR = 'Sun_Mon_Tue_Wed_Thu_Fri_Sat'.split('_')
 
 export interface DateFields {
     year: number
@@ -48,7 +48,7 @@ export function parse_date_field(date: Date, timezone: string): DateFields {
                     res.date = +item.value
                     break
                 case 'weekday':
-                    res.weekday = Math.floor(WEEKDAY_NAME.indexOf(item.value))
+                    res.weekday = Math.floor(WEEKDAY_ABBR.indexOf(item.value))
                     break
                 case 'hour':
                     res.hour = +item.value

packages/dora/src/date-tools.ts

@@ -122,6 +122,41 @@ describe('dora.ts', function() {
             it('should throw error if can\'t parse time string', function() {
                 expect(() => Dora.parse('20220102123212')).toThrow()
             })
+
+            it('should interpret timezone-less string as wall-clock time in given timezone', function() {
+                const m = Dora.parse('2020-10-08 15:32:01.158', 'Asia/Shanghai')
+                expect(m.timezone()).toEqual('Asia/Shanghai')
+                expect(m.year()).toEqual(2020)
+                expect(m.month()).toEqual(9)
+                expect(m.date()).toEqual(8)
+                expect(m.hour()).toEqual(15)
+                expect(m.minute()).toEqual(32)
+                expect(m.second()).toEqual(1)
+                expect(m.millisecond()).toEqual(158)
+                expect(m.format('Z')).toEqual('+08:00')
+            })
+
+            it('should use string timezone as the UTC moment, display in given timezone', function() {
+                const m = Dora.parse('2020-10-08 11:03:16.158+08:00', 'Asia/Yangon')
+                expect(m.timezone()).toEqual('Asia/Yangon')
+                expect(m.hour()).toEqual(9)
+                expect(m.minute()).toEqual(33)
+                expect(m.format('Z')).toEqual('+06:30')
+            })
+
+            it('should correctly handle timezone-less ISO string with given timezone', function() {
+                const shanghai = Dora.parse('2022-05-16T15:38:28.000', 'Asia/Shanghai')
+                expect(shanghai.format()).toEqual('2022-05-16T15:38:28.000+08:00')
+                const utc = Dora.parse('2022-05-16T15:38:28.000', 'UTC')
+                expect(utc.format()).toEqual('2022-05-16T15:38:28.000+00:00')
+            })
+
+            it('should fall back gracefully for non-ISO timezone-less string with given timezone', function() {
+                // 'Mon May 16 2022 15:38:28' → first-space-to-T → 'Mon May 16T2022 15:38:28Z' which is invalid ISO
+                const m = Dora.parse('Mon May 16 2022 15:38:28', 'Asia/Shanghai')
+                expect(m).toBeInstanceOf(Dora)
+                expect(m.timezone()).toEqual('Asia/Shanghai')
+            })
         })
 
         describe('.format()', function() {
@@ -437,5 +472,56 @@ describe('dora.ts', function() {
                 expect(m.end_of('isoWeek').format()).toEqual('2022-05-22T23:59:59.999+08:00')
             })
         })
+
+        describe('.utc_offset()', function() {
+
+            it('should return negative value for UTC+ timezone', function() {
+                // UTC+8: internal offset = UTC fields - local fields = -480
+                const m = new Dora(1652686708000, 'Asia/Shanghai')
+                expect(m.utc_offset()).toEqual(-480)
+            })
+
+            it('should return positive value for UTC- timezone', function() {
+                // UTC-6: internal offset = UTC fields - local fields = +360
+                const m = new Dora(1652686708000, 'America/Inuvik')
+                expect(m.utc_offset()).toEqual(360)
+            })
+
+            it('should return zero for UTC timezone', function() {
+                const m = new Dora(1652686708000, 'UTC')
+                expect(m.utc_offset()).toEqual(0)
+            })
+
+            it('should correctly compute offset for UTC+14 crossing year boundary', function() {
+                // Pacific/Kiritimati is UTC+14
+                // 2022-12-31T22:00:00Z = 2023-01-01T12:00:00+14:00 (year boundary crossed)
+                const ts = new Date('2022-12-31T22:00:00Z').getTime()
+                const m = new Dora(ts, 'Pacific/Kiritimati')
+                expect(m.year()).toEqual(2023)
+                expect(m.month()).toEqual(0)
+                expect(m.date()).toEqual(1)
+                expect(m.utc_offset()).toEqual(-840)
+                expect(m.format('Z')).toEqual('+14:00')
+            })
+
+            it('should correctly compute offset for UTC-11 crossing year boundary', function() {
+                // Pacific/Pago_Pago is UTC-11
+                // 2023-01-01T10:00:00Z = 2022-12-31T23:00:00-11:00 (year boundary crossed)
+                const ts = new Date('2023-01-01T10:00:00Z').getTime()
+                const m = new Dora(ts, 'Pacific/Pago_Pago')
+                expect(m.year()).toEqual(2022)
+                expect(m.month()).toEqual(11)
+                expect(m.date()).toEqual(31)
+                expect(m.utc_offset()).toEqual(660)
+                expect(m.format('Z')).toEqual('-11:00')
+            })
+
+            it('should correctly compute offset for UTC+5:30 (non-whole-hour offset)', function() {
+                // Asia/Kolkata is UTC+5:30
+                const m = new Dora(1652686708000, 'Asia/Kolkata')
+                expect(m.utc_offset()).toEqual(-330)
+                expect(m.format('Z')).toEqual('+05:30')
+            })
+        })
     })
 })

packages/dora/src/dora.spec.ts

@@ -55,14 +55,14 @@ export class Dora {
     }
 
     public readonly $d: Date
-    public $y: number
-    public $M: number
-    public $D: number
-    public $W: number
-    public $H: number
-    public $m: number
-    public $s: number
-    public $ms: number
+    public readonly $y: number
+    public readonly $M: number
+    public readonly $D: number
+    public readonly $W: number
+    public readonly $H: number
+    public readonly $m: number
+    public readonly $s: number
+    public readonly $ms: number
     public readonly $utcOffset: number
     private readonly $z: string
 
@@ -78,9 +78,9 @@ export class Dora {
         this.$m = fields.minute
         this.$s = fields.second
         this.$ms = fields.millisecond
-        this.$utcOffset = (this.$d.getUTCFullYear() - this.$y || this.$d.getUTCMonth() - this.$M || this.$d.getUTCDate() - this.$D) * 24 * 60
-            + (this.$d.getUTCHours() - this.$H) * 60
-            + this.$d.getUTCMinutes() - this.$m
+        const day_diff = (Date.UTC(this.$d.getUTCFullYear(), this.$d.getUTCMonth(), this.$d.getUTCDate())
+            - Date.UTC(this.$y, this.$M, this.$D)) / (60 * 1000)
+        this.$utcOffset = day_diff + (this.$d.getUTCHours() - this.$H) * 60 + this.$d.getUTCMinutes() - this.$m
     }
 
     static guess_timezone() {
@@ -117,12 +117,37 @@ export class Dora {
         }
     }
 
-    static parse(date_str: string) {
+    /**
+     * Parse a date string into a Dora instance.
+     *
+     * @param timezone - Optional timezone for the result.
+     *   - If the string **contains** timezone info (e.g. `+08:00`, `Z`), the string's
+     *     timezone determines the UTC moment; `timezone` only changes the display view.
+     *   - If the string **has no** timezone info, the wall-clock time is interpreted as
+     *     being in `timezone`, making it both the source and the display timezone.
+     */
+    static parse(date_str: string, timezone?: string) {
         const ts = Date.parse(date_str)
         if (isNaN(ts)) {
             throw new Error()
         }
-        return new Dora(ts)
+        if (timezone === undefined) {
+            return new Dora(ts)
+        }
+        const has_tz = /[Zz]$|[+-]\d{2}:?\d{2}$/.test(date_str.trim())
+        if (has_tz) {
+            return new Dora(ts, timezone)
+        }
+        // No TZ in string: interpret the wall-clock time in the given timezone.
+        // Append 'Z' to force UTC interpretation and extract components reliably.
+        const d = new Date(date_str.trim().replace(' ', 'T') + 'Z')
+        if (isNaN(d.getTime())) {
+            return new Dora(ts, timezone)
+        }
+        return Dora.from([
+            d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(),
+            d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), d.getUTCMilliseconds(),
+        ], { timezone })
     }
 
     format(format: string = DEFAULT_FORMAT) {
@@ -175,11 +200,15 @@ export class Dora {
         switch (unit) {
             case 'year': {
                 const date = this.date()
+                // Pin to 5th to prevent month-end overflow (e.g. Jan 31 + 1 month → Feb 31),
+                // then restore the original date after adjusting the year.
                 const nd = new Date(this.date(5).valueOf())
                 return new Dora(nd.setUTCFullYear(nd.getUTCFullYear() + int), this.$z).date(date)
             }
             case 'month': {
                 const date = this.date()
+                // Pin to 5th to prevent month-end overflow (e.g. Jan 31 + 1 month → Feb 31),
+                // then restore the original date after adjusting the month.
                 const nd = new Date(this.date(5).valueOf())
                 return new Dora(nd.setUTCMonth(nd.getUTCMonth() + int), this.$z).date(date)
             }