Add meta package to pull together predictor and db

Author: bkeepers

README.md

@@ -0,0 +1,48 @@
+![example workflow](https://github.com/neaps/tide-predictor/actions/workflows/test.yml/badge.svg) [![codecov](https://codecov.io/gh/neaps/tide-predictor/branch/main/graph/badge.svg?token=KEJK5NQR5H)](https://codecov.io/gh/neaps/tide-predictor)
+
+# Neaps
+
+A tide prediction engine written in TypeScript.
+
+## 🚨Not for navigational use🚨
+
+**Do not use calculations from this project for navigation, or depend on them in any situation where inaccuracies could result in harm to a person or property.**
+
+Tide predictions are only as good as the harmonics data available, and these can be inconsistent and vary widely based on the accuracy of the source data and local conditions.
+
+The tide predictions do not factor events such as storm surge, wind waves, uplift, tsunamis, or sadly, climate change. 😢
+
+# Installation
+
+```sh
+npm install neaps
+```
+
+# Usage
+
+```typescript
+import { getExtremesPrediction } from 'neaps'
+
+const prediction = getExtremesPrediction({
+  latitude: 26.7, // or `lat`
+  longitude: -80.05, // or `lng` or `lon`
+  start: new Date('2025-12-17'),
+  end: new Date('2025-12-18'),
+  datum: 'MLLW', // optional, defaults to MLLW if available
+})
+
+console.log(extremes)
+// {
+//   datum: 'MLLW',
+//   station: {
+//     id: '8723214',
+//     name: 'Fort Lauderdale, FL',
+//     // ...
+//   },
+//   distance: 12.3,
+//   extremes: [
+//     { time: 2019-01-01T03:12:00.000Z, level: 3.2, high: true, low: false, label: 'High' },
+//     { time: 2019-01-01T09:45:00.000Z, level: 0.5, high: false, low: true, label: 'Low' },
+//   ]
+// }
+```

src/index.ts

@@ -0,0 +1,113 @@
+import { getDistance } from 'geolib'
+import stations, { type Station } from '@neaps/tide-stations'
+import tidePredictor, { type ExtremesInput } from '@neaps/tide-predictor'
+import type { GeolibInputCoordinates } from 'geolib/es/types'
+
+export type ExtremesOptions = ExtremesInput & {
+  /** Datum to return predictions in. Defaults to 'MLLW' if available for the nearest station. */
+  datum?: string
+}
+
+/**
+ * Get extremes prediction using the nearest station to the given position.
+ *
+ * @example
+ * ```ts
+ * import { getExtremesPrediction } from 'neaps'
+ *
+ * const prediction = getExtremesPrediction({
+ *   latitude: 26.7, // or `lat`
+ *   longitude: -80.05, // or `lng` or `lon`
+ *   start: new Date('2025-12-17'),
+ *   end: new Date('2025-12-18'),
+ *   datum: 'MLLW', // optional, defaults to MLLW if available
+ * })
+ */
+export function getExtremesPrediction(
+  options: GeolibInputCoordinates & ExtremesOptions
+) {
+  return nearestStation(options).getExtremesPrediction(options)
+}
+
+/**
+ * Find the nearest station to the given position.
+ */
+export function nearestStation(position: GeolibInputCoordinates) {
+  return stationsNear(position, 1)[0]
+}
+
+/**
+ * Find stations closest to the given position.
+ */
+export function stationsNear(position: GeolibInputCoordinates, limit = 10) {
+  return stations
+    .map((station) => ({ station, distance: getDistance(position, station) }))
+    .sort((a, b) => a.distance - b.distance)
+    .slice(0, limit)
+    .map(({ station, distance }) => createStation(station, distance))
+}
+
+/**
+ * Find a station by its ID or source ID.
+ */
+export function findStation(query: string) {
+  const searches = [
+    (s: Station) => s.id === query,
+    (s: Station) => s.source.id === query
+  ]
+
+  let found: Station | undefined = undefined
+
+  for (const search of searches) {
+    found = stations.find(search)
+    if (found) break
+  }
+
+  if (!found) throw new Error(`Station not found: ${query}`)
+
+  return createStation(found)
+}
+
+function createStation(metadata: Station, distance?: number) {
+  // Use MLLW as the default datum if available
+  const defaultDatum = 'MLLW' in metadata.datums ? 'MLLW' : undefined
+
+  return {
+    metadata,
+    distance,
+    getExtremesPrediction({ datum = defaultDatum, ...input }: ExtremesOptions) {
+      let offset = 0
+
+      if (datum) {
+        const datumOffset = metadata.datums?.[datum]
+        const mslOffset = metadata.datums?.['MSL']
+
+        if (!datum) {
+          throw new Error(
+            `Station ${metadata.id} missing ${datum} datum. Available datums: ${Object.keys(metadata.datums || {}).join(', ')}`
+          )
+        }
+
+        if (!mslOffset) {
+          throw new Error(
+            `Station ${metadata.id} missing MSL datum, so predictions can't be given in ${datum}.`
+          )
+        }
+
+        offset = mslOffset - datumOffset
+      }
+
+      const predictor = tidePredictor(metadata.harmonic_constituents, {
+        phaseKey: 'phase_UTC',
+        offset
+      })
+
+      return {
+        datum,
+        distance,
+        station: metadata,
+        predictions: predictor.getExtremesPrediction(input)
+      }
+    }
+  }
+}

test/index.test.ts

@@ -0,0 +1,90 @@
+import {
+  getExtremesPrediction,
+  nearestStation,
+  findStation
+} from '../src/index.js'
+import { describe, test, expect } from 'vitest'
+
+describe('getExtremesPrediction', () => {
+  test('gets extremes from nearest station', () => {
+    const { predictions } = getExtremesPrediction({
+      lat: 26.7,
+      lon: -80.05,
+      start: new Date('2025-12-17 00:00'),
+      end: new Date('2025-12-18 00:00'),
+      timeFidelity: 6,
+      datum: 'MLLW'
+    })
+
+    expect(predictions.length).toBe(4)
+    expect(predictions[0].time).toEqual(new Date('2025-12-17T09:47:36.000Z')) // 04:47 EST
+    expect(predictions[0].level).toBeCloseTo(0.03, 1) // NOAA prediction is 0.03, neaps is 0.05
+    expect(predictions[0].high).toBe(false)
+    expect(predictions[0].low).toBe(true)
+    expect(predictions[0].label).toBe('Low')
+  })
+  ;[
+    { lat: 26.7, lon: -80.05 },
+    { lat: 26.7, lng: -80.05 },
+    { latitude: 26.7, longitude: -80.05 }
+  ].forEach((position) => {
+    test(`accepts position with ${Object.keys(position).join('/')}`, () => {
+      const { predictions } = getExtremesPrediction({
+        ...position,
+        start: new Date('2025-12-17 00:00'),
+        end: new Date('2025-12-18 00:00')
+      })
+      expect(predictions.length).toBe(4)
+    })
+  })
+})
+
+describe('nearestStation', () => {
+  test('finds the nearest station', () => {
+    const station = nearestStation({ lat: 26.7, lon: -80.05 })
+    expect(station.metadata.source.id).toBe('8722588')
+    expect(station.metadata.latitude).toBeCloseTo(26.77)
+    expect(station.metadata.longitude).toBeCloseTo(-80.0517)
+  })
+
+  test('can return extremes from station', () => {
+    const station = nearestStation({ lat: 26.7, lon: -80.05 })
+
+    const start = new Date('2025-12-17 00:00')
+    const end = new Date('2025-12-18 00:00')
+
+    const { predictions } = station.getExtremesPrediction({
+      start,
+      end,
+      timeFidelity: 6,
+      datum: 'MLLW'
+    })
+
+    expect(predictions.length).toBe(4)
+    expect(predictions[0].time).toEqual(new Date('2025-12-17T09:47:36.000Z')) // 04:47 EST
+    expect(predictions[0].level).toBeCloseTo(0.03, 1) // NOAA prediction is 0.03, neaps is 0.05
+    expect(predictions[0].high).toBe(false)
+    expect(predictions[0].low).toBe(true)
+    expect(predictions[0].label).toBe('Low')
+  })
+})
+
+describe('findStation', () => {
+  test('raises error for unknown station', () => {
+    expect(() => findStation('unknown')).toThrow('Station not found: unknown')
+  })
+
+  test('finds station by id', () => {
+    const station = findStation('us-fl-ankona-indian-river')
+    expect(station).toBeDefined()
+    expect(station.metadata.id).toBe('us-fl-ankona-indian-river')
+    expect(station.getExtremesPrediction).toBeDefined()
+  })
+
+  test('finds station by source id', () => {
+    const station = findStation('8443970')
+    expect(station).toBeDefined()
+    expect(station.metadata.id).toBe('us-ma-boston')
+    expect(station.getExtremesPrediction).toBeDefined()
+  })
+})