Merge pull request #183 from neaps/utc

Fix timezone handling by using UTC internally

Author: bkeepers

benchmarks/noaa.ts

@@ -6,8 +6,6 @@ import { findStation } from 'neaps'
 import { stations as db } from '@neaps/tide-database'
 import createFetch from 'make-fetch-happen'
 
-process.env.TZ = 'UTC'
-
 const __dirname = new URL('.', import.meta.url).pathname
 const fetch = createFetch.defaults({
   cachePath: join(__dirname, '.cache'),
@@ -59,7 +57,7 @@ for (const id of stations) {
 
   const noaaEvents: Extreme[] | undefined = (
     await fetchNOAAdata(id, datum)
-  ).predictions?.map((e) => ({
+  ).predictions?.map((e: { t: string; v: string; type: 'H' | 'L' }) => ({
     time: new Date(e.t + ' GMT').getTime(),
     level: parseFloat(e.v),
     type: e.type
@@ -90,8 +88,14 @@ for (const id of stations) {
   const dtMinutes: number[] = []
   const dhMeters: number[] = []
 
-  const noaa = Object.groupBy(noaaEvents, (e) => e.type)
-  const neaps = Object.groupBy(neapsEvents, (e) => e.type)
+  const noaa = Object.groupBy(noaaEvents, (e) => e.type) as Record<
+    'H' | 'L',
+    Extreme[] | undefined
+  >
+  const neaps = Object.groupBy(neapsEvents, (e) => e.type) as Record<
+    'H' | 'L',
+    Extreme[] | undefined
+  >
 
   const matchAndCollect = (noaaList: Extreme[], neapsList: Extreme[]) => {
     let j = 0
@@ -152,8 +156,8 @@ for (const id of stations) {
   matchAndCollect(noaa.H ?? [], neaps.H ?? [])
   matchAndCollect(noaa.L ?? [], neaps.L ?? [])
 
-  const events_noaa = noaa.H.length + noaa.L.length
-  const events_model = neaps.H.length + neaps.L.length
+  const events_noaa = (noaa.H?.length ?? 0) + (noaa.L?.length ?? 0)
+  const events_model = (neaps.H?.length ?? 0) + (neaps.L?.length ?? 0)
 
   // Timing metrics (minutes)
   const absDt = sort(dtMinutes.map((v) => Math.abs(v)))

packages/neaps/test/index.test.ts

@@ -9,9 +9,49 @@ import {
 } from '../src/index.js'
 import { describe, test, expect } from 'vitest'
 
-// FIXME: this is required for these tests to pass. I can't figure out how to get accurate
-// predictions for a station in a non-UTC timezone without this.
-process.env.TZ = 'UTC'
+describe('timezone independence', () => {
+  const location = { lat: 26.772, lon: -80.05 }
+
+  test('equivalent instants yield identical extremes', () => {
+    const station = nearestStation(location)
+
+    // Same instant range expressed in different offsets
+    const utc = {
+      start: new Date('2025-12-18T00:00:00Z'),
+      end: new Date('2025-12-19T00:00:00Z'),
+      timeFidelity: 60,
+      datum: 'MLLW' as const
+    }
+    const newYork = {
+      start: new Date('2025-12-17T19:00:00-05:00'),
+      end: new Date('2025-12-18T19:00:00-05:00'),
+      timeFidelity: 60,
+      datum: 'MLLW' as const
+    }
+    const tokyo = {
+      start: new Date('2025-12-18T09:00:00+09:00'),
+      end: new Date('2025-12-19T09:00:00+09:00'),
+      timeFidelity: 60,
+      datum: 'MLLW' as const
+    }
+
+    const baseline = station.getExtremesPrediction(utc).extremes
+    const ny = station.getExtremesPrediction(newYork).extremes
+    const jp = station.getExtremesPrediction(tokyo).extremes
+
+    ;[ny, jp].forEach((result) => {
+      expect(result.length).toBe(baseline.length)
+      result.forEach((extreme, index) => {
+        const base = baseline[index]
+        expect(extreme.time.valueOf()).toBe(base.time.valueOf())
+        expect(extreme.high).toBe(base.high)
+        expect(extreme.low).toBe(base.low)
+        expect(extreme.label).toBe(base.label)
+        expect(extreme.level).toBeCloseTo(base.level, 6)
+      })
+    })
+  })
+})
 
 describe('getExtremesPrediction', () => {
   const options = {

packages/tide-predictor/README.md

@@ -41,7 +41,7 @@ const highLowTides = TidePredictor(constituents, {
 })
 ```
 
-Note that, for now, Neaps **will not** do any timezone corrections. This means you need to pass date objects that align with whatever timezone the constituents are in.
+Note that all times internally are evaluated as UTC, so be sure to specify a timezone offset when constructing dates if you want to work in a local time. For example, to get tides for January 1st, 2019 in New York (UTC-5), create a date `new Date('2019-01-01T00:00:00-05:00')`
 
 ## Tide prediction object
 

packages/tide-predictor/src/astronomy/index.ts

@@ -52,14 +52,14 @@ const T = (t: Date): number => {
 
 // Meeus formula 7.1
 const JD = (t: Date): number => {
-  let Y = t.getFullYear()
-  let M = t.getMonth() + 1
+  let Y = t.getUTCFullYear()
+  let M = t.getUTCMonth() + 1
   const D =
-    t.getDate() +
-    t.getHours() / 24.0 +
-    t.getMinutes() / (24.0 * 60.0) +
-    t.getSeconds() / (24.0 * 60.0 * 60.0) +
-    t.getMilliseconds() / (24.0 * 60.0 * 60.0 * 1e6)
+    t.getUTCDate() +
+    t.getUTCHours() / 24.0 +
+    t.getUTCMinutes() / (24.0 * 60.0) +
+    t.getUTCSeconds() / (24.0 * 60.0 * 60.0) +
+    t.getUTCMilliseconds() / (24.0 * 60.0 * 60.0 * 1e6)
   if (M <= 2) {
     Y = Y - 1
     M = M + 12

packages/tide-predictor/test/astronomy/index.test.ts

@@ -11,14 +11,7 @@ import astro, {
   _nupp
 } from '../../src/astronomy/index.js'
 
-const sampleTime = new Date()
-sampleTime.setFullYear(2019)
-sampleTime.setMonth(9)
-sampleTime.setDate(4)
-sampleTime.setHours(10)
-sampleTime.setMinutes(15)
-sampleTime.setSeconds(40)
-sampleTime.setMilliseconds(10)
+const sampleTime = new Date('2019-10-04T10:15:40.010Z')
 
 describe('astronomy', () => {
   it('complete astronomic calculation', () => {
@@ -63,11 +56,12 @@ describe('astronomy', () => {
   })
 
   it('evaluates Meeus formula 7.1 (JD) correctly', () => {
-    sampleTime.setMonth(9)
-    expect(JD(sampleTime)).toBeCloseTo(2458760.92755, 2)
+    const time = new Date(sampleTime)
+    time.setUTCMonth(9)
+    expect(JD(time)).toBeCloseTo(2458760.92755, 2)
     // Months of less than 2 go back a year
-    sampleTime.setMonth(0)
-    expect(JD(sampleTime)).toBeCloseTo(2458487.92755, 2)
+    time.setUTCMonth(0)
+    expect(JD(time)).toBeCloseTo(2458487.92755, 2)
   })
 
   it('evaluates Meeus formula 11.1 (T) correctly', () => {

packages/tide-predictor/test/constituents/compound-constituent.test.ts

@@ -3,15 +3,7 @@ import compoundConstituent from '../../src/constituents/compound-constituent.js'
 import Constituent from '../../src/constituents/constituent.js'
 import astro from '../../src/astronomy/index.js'
 
-const sampleTime = new Date()
-sampleTime.setFullYear(2019)
-sampleTime.setMonth(9)
-sampleTime.setDate(4)
-sampleTime.setHours(10)
-sampleTime.setMinutes(15)
-sampleTime.setSeconds(40)
-sampleTime.setMilliseconds(10)
-
+const sampleTime = new Date('2019-10-04T10:15:40.010Z')
 const testAstro = astro(sampleTime)
 
 // This is a made-up doodson number for a test coefficient

packages/tide-predictor/test/constituents/constituent.test.ts

@@ -6,15 +6,7 @@ import constituent, {
 } from '../../src/constituents/constituent.js'
 import astro from '../../src/astronomy/index.js'
 
-const sampleTime = new Date()
-sampleTime.setFullYear(2019)
-sampleTime.setMonth(9)
-sampleTime.setDate(4)
-sampleTime.setHours(10)
-sampleTime.setMinutes(15)
-sampleTime.setSeconds(40)
-sampleTime.setMilliseconds(10)
-
+const sampleTime = new Date('2019-10-04T10:15:40.010Z')
 const testAstro = astro(sampleTime)
 
 // This is a made-up doodson number for a test coefficient

packages/tide-predictor/test/constituents/index.test.ts

@@ -2,15 +2,7 @@ import { describe, it, expect } from 'vitest'
 import constituents from '../../src/constituents/index.js'
 import astro from '../../src/astronomy/index.js'
 
-const sampleTime = new Date()
-sampleTime.setFullYear(2019)
-sampleTime.setMonth(9)
-sampleTime.setDate(4)
-sampleTime.setHours(10)
-sampleTime.setMinutes(15)
-sampleTime.setSeconds(40)
-sampleTime.setMilliseconds(10)
-
+const sampleTime = new Date('2019-10-04T10:15:40.010Z')
 const testAstro = astro(sampleTime)
 
 describe('Base constituent definitions', () => {

packages/tide-predictor/test/harmonics/prediction.test.ts

@@ -2,32 +2,9 @@ import { describe, it, expect } from 'vitest'
 import harmonics, { ExtremeOffsets } from '../../src/harmonics/index.js'
 import mockHarmonicConstituents from '../_mocks/constituents.js'
 
-const startDate = new Date()
-startDate.setFullYear(2019)
-startDate.setMonth(8)
-startDate.setDate(1)
-startDate.setHours(0)
-startDate.setMinutes(0)
-startDate.setSeconds(0)
-startDate.setMilliseconds(0)
-
-const endDate = new Date()
-endDate.setFullYear(2019)
-endDate.setMonth(8)
-endDate.setDate(1)
-endDate.setHours(6)
-endDate.setMinutes(0)
-endDate.setSeconds(0)
-endDate.setMilliseconds(0)
-
-const extremesEndDate = new Date()
-extremesEndDate.setFullYear(2019)
-extremesEndDate.setMonth(8)
-extremesEndDate.setDate(3)
-extremesEndDate.setHours(0)
-extremesEndDate.setMinutes(0)
-extremesEndDate.setSeconds(0)
-extremesEndDate.setMilliseconds(0)
+const startDate = new Date('2019-09-01T00:00:00Z')
+const endDate = new Date('2019-09-01T06:00:00Z')
+const extremesEndDate = new Date('2019-09-03T00:00:00Z')
 
 const setUpPrediction = () => {
   const harmonic = harmonics({

packages/tide-predictor/test/index.test.ts

@@ -2,23 +2,8 @@ import { describe, it, expect } from 'vitest'
 import mockConstituents from './_mocks/constituents.js'
 import tidePrediction from '../src/index.js'
 
-const startDate = new Date()
-startDate.setFullYear(2019)
-startDate.setMonth(8)
-startDate.setDate(1)
-startDate.setHours(0)
-startDate.setMinutes(0)
-startDate.setSeconds(0)
-startDate.setMilliseconds(0)
-
-const endDate = new Date()
-endDate.setFullYear(2019)
-endDate.setMonth(8)
-endDate.setDate(1)
-endDate.setHours(6)
-endDate.setMinutes(0)
-endDate.setSeconds(0)
-endDate.setMilliseconds(0)
+const startDate = new Date('2019-09-01T00:00:00Z')
+const endDate = new Date('2019-09-01T06:00:00Z')
 
 describe('Tidal station', () => {
   it('it is created correctly', () => {