Document new module

Author: bkeepers

README.md

@@ -4,13 +4,10 @@
 
 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. 😢
+> [!CAUTION]
+> **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
 
@@ -20,6 +17,8 @@ npm install neaps
 
 # Usage
 
+## Tide Extremes Prediction
+
 ```typescript
 import { getExtremesPrediction } from 'neaps'
 
@@ -46,3 +45,122 @@ console.log(extremes)
 //   ]
 // }
 ```
+
+## Get Timeline Prediction
+
+```typescript
+import { getTimelinePrediction } from 'neaps'
+
+const timeline = getTimelinePrediction({
+  lat: 26.7,
+  lon: -80.05,
+  start: new Date('2025-12-19T00:00:00-05:00'),
+  end: new Date('2025-12-19T01:00:00-05:00')
+})
+
+console.log(timeline)
+// {
+//   datum: 'MLLW',
+//   station: {
+//     id: 'us-fl-port-of-west-palm-beach',
+//     name: 'Port of West Palm Beach',
+//     // ...
+//   },
+//   timeline: [
+//     { time: 2025-12-19T05:00:00.000Z, hour: 0, level: 0.07269280868130157 },
+//     { time: 2025-12-19T05:10:00.000Z, hour: 0.16666666666666666, level: 0.054517202710722634 },
+//     { time: 2025-12-19T05:20:00.000Z, hour: 0.3333333333333333, level: 0.0387568479105333 },
+//     { time: 2025-12-19T05:30:00.000Z, hour: 0.5, level: 0.025594147655661648 },
+//     { time: 2025-12-19T05:40:00.000Z, hour: 0.6666666666666666, level: 0.015185512178782279 },
+//     { time: 2025-12-19T05:50:00.000Z, hour: 0.8333333333333334, level: 0.00765764296563648 },
+//     { time: 2025-12-19T06:00:00.000Z, hour: 1, level: 0.0031046829237997287 }
+//   ]
+// }
+```
+
+## Get Water Level at Specific Time
+
+```typescript
+import { getWaterLevelAtTime } from 'neaps'
+
+const prediction = getWaterLevelAtTime({
+  lat: 26.7,
+  lon: -80.05,
+  time: new Date('2025-12-19T00:30:00-05:00'),
+  datum: 'MSL'
+})
+
+console.log(prediction)
+// {
+//   datum: 'MSL',
+//   station: {
+//     id: 'us-fl-port-of-west-palm-beach',
+//     name: 'Port of West Palm Beach',
+//     // ...
+//   },
+//   time: 2025-12-19T05:30:00.000Z,
+//   hour: 0,
+//   level: -0.43840585181640557
+// }
+```
+
+## Finding stations
+
+Neaps uses [@neaps/tide-database](https://github.com/neaps/tide-database) to find station data. You can find stations by location or ID.
+
+### Nearest Station
+
+```typescript
+import { nearestStation } from 'neaps'
+
+const station = nearestStation({ lat: 26.7, lon: -80.05 })
+console.log(`${station.name} (${station.source.id})`) // Fort Lauderdale, FL (8722588)
+```
+
+Once you've found a station, you can get predictions, timeline, or water level at a specific time for that station:
+
+```typescript
+// Get extremes prediction for the nearest station
+station.getExtremesPrediction({
+  start: new Date('2025-12-17'),
+  end: new Date('2025-12-18')
+})
+
+// Get timeline prediction for the nearest station
+station.getTimelinePrediction({
+  start: new Date('2025-12-19'),
+  end: new Date('2025-12-20')
+})
+
+// Get timeline prediction for the nearest station
+station.getWaterLevelAt({ time: new Date('2025-12-19T00:30:00-00:00') })
+```
+
+### List Nearby Stations
+
+```typescript
+import { stationsNear } from 'neaps'
+
+stationsNear({ latitude: 45.6, longitude: -122.7 }, 5).forEach((s) => {
+  console.log(
+    `${s.name} (${s.source.id}) - ${(s.distance / 1000).toFixed(2)} km away`
+  )
+})
+// Vancouver (9440083) - 3.49 km away
+// Portland Morrison Street Bridge (9439221) - 10.24 km away
+// KNAPP(THORNES)LNDG, WILLOW BAR (9440171) - 16.34 km away
+// Rocky Point (9439189) - 16.93 km away
+// WASHOUGAL, COLUMBIA RIVER (9440047) - 24.89 km away
+```
+
+### Find station by ID
+
+```typescript
+import { findStation } from 'neaps'
+
+// Find station by Neaps ID
+findStation('us-wa-seattle') // Seattle
+
+// Find station by source ID (e.g. NOAA)
+findStation('9440083') // Vancouver
+```

package.json

@@ -1,5 +1,6 @@
 {
   "private": true,
+  "type": "module",
   "scripts": {
     "test": "vitest",
     "coverage": "vitest run --coverage",

packages/neaps/src/index.ts

@@ -94,48 +94,48 @@ export function findStation(query: string) {
   return useStation(found)
 }
 
-export function useStation(metadata: Station, distance?: number) {
+export function useStation(station: Station, distance?: number) {
   // Use MLLW as the default datum if available
-  const defaultDatum = 'MLLW' in metadata.datums ? 'MLLW' : undefined
+  const defaultDatum = 'MLLW' in station.datums ? 'MLLW' : undefined
 
   function getPredictor({ datum = defaultDatum }: DatumOption = {}) {
     let offset = 0
 
     if (datum) {
-      const datumOffset = metadata.datums?.[datum]
-      const mslOffset = metadata.datums?.['MSL']
+      const datumOffset = station.datums?.[datum]
+      const mslOffset = station.datums?.['MSL']
 
       if (!datumOffset) {
         throw new Error(
-          `Station ${metadata.id} missing ${datum} datum. Available datums: ${Object.keys(metadata.datums || {}).join(', ')}`
+          `Station ${station.id} missing ${datum} datum. Available datums: ${Object.keys(station.datums || {}).join(', ')}`
         )
       }
 
       if (!mslOffset) {
         throw new Error(
-          `Station ${metadata.id} missing MSL datum, so predictions can't be given in ${datum}.`
+          `Station ${station.id} missing MSL datum, so predictions can't be given in ${datum}.`
         )
       }
 
       offset = mslOffset - datumOffset
     }
 
-    return tidePredictor(metadata.harmonic_constituents, {
+    return tidePredictor(station.harmonic_constituents, {
       phaseKey: 'phase_UTC',
       offset
     })
   }
 
   return {
-    metadata,
+    ...station,
     distance,
     defaultDatum,
     getExtremesPrediction({ datum = defaultDatum, ...input }: ExtremesOptions) {
       return {
         datum,
         distance,
-        station: metadata,
-        predictions: getPredictor({ datum }).getExtremesPrediction(input)
+        station,
+        extremes: getPredictor({ datum }).getExtremesPrediction(input)
       }
     },
 
@@ -145,15 +145,15 @@ export function useStation(metadata: Station, distance?: number) {
     }: TimelineOptions) {
       return {
         datum,
-        station: metadata,
+        station,
         timeline: getPredictor({ datum }).getTimelinePrediction(params)
       }
     },
 
     getWaterLevelAtTime({ time, datum = defaultDatum }: WaterLevelOptions) {
       return {
         datum,
-        station: metadata,
+        station,
         ...getPredictor({ datum }).getWaterLevelAtTime({ time })
       }
     }

packages/neaps/test/index.test.ts

@@ -15,7 +15,7 @@ process.env.TZ = 'UTC'
 
 describe('getExtremesPrediction', () => {
   test('gets extremes from nearest station', () => {
-    const extremes = getExtremesPrediction({
+    const prediction = getExtremesPrediction({
       lat: 26.7,
       lon: -80.05,
       start: new Date('2025-12-18T00:00:00-05:00'),
@@ -24,16 +24,16 @@ describe('getExtremesPrediction', () => {
       datum: 'MLLW'
     })
 
-    expect(extremes.station.id).toEqual('us-fl-port-of-west-palm-beach')
-    expect(extremes.datum).toBe('MLLW')
+    expect(prediction.station.id).toEqual('us-fl-port-of-west-palm-beach')
+    expect(prediction.datum).toBe('MLLW')
 
-    const { predictions } = extremes
-    expect(predictions.length).toBe(4)
-    expect(predictions[0].time).toEqual(new Date('2025-12-18T05:29:48.000Z'))
-    expect(predictions[0].level).toBeCloseTo(0.02, 2)
-    expect(predictions[0].high).toBe(false)
-    expect(predictions[0].low).toBe(true)
-    expect(predictions[0].label).toBe('Low')
+    const { extremes } = prediction
+    expect(extremes.length).toBe(4)
+    expect(extremes[0].time).toEqual(new Date('2025-12-18T05:29:48.000Z'))
+    expect(extremes[0].level).toBeCloseTo(0.02, 2)
+    expect(extremes[0].high).toBe(false)
+    expect(extremes[0].low).toBe(true)
+    expect(extremes[0].label).toBe('Low')
   })
 })
 
@@ -54,17 +54,17 @@ describe('getTimelinePrediction', () => {
 
 describe('getWaterLevelAtTime', () => {
   test('gets water level at specific time from nearest station', () => {
-    const waterLevel = getWaterLevelAtTime({
+    const prediction = getWaterLevelAtTime({
       lat: 26.7,
       lon: -80.05,
       time: new Date('2025-12-19T00:30:00-05:00'),
       datum: 'MSL'
     })
 
-    expect(waterLevel.station.id).toEqual('us-fl-port-of-west-palm-beach')
-    expect(waterLevel.datum).toBe('MSL')
-    expect(waterLevel.time).toEqual(new Date('2025-12-19T05:30:00.000Z'))
-    expect(typeof waterLevel.level).toBe('number')
+    expect(prediction.station.id).toEqual('us-fl-port-of-west-palm-beach')
+    expect(prediction.datum).toBe('MSL')
+    expect(prediction.time).toEqual(new Date('2025-12-19T05:30:00.000Z'))
+    expect(typeof prediction.level).toBe('number')
   })
 })
 
@@ -78,7 +78,7 @@ describe('for a specific station', () => {
       const start = new Date('2025-12-17T00:00:00-05:00')
       const end = new Date('2025-12-18T05:00:00-05:00')
 
-      const { predictions } = station.getExtremesPrediction({
+      const { extremes: predictions } = station.getExtremesPrediction({
         start,
         end,
         timeFidelity: 6,
@@ -121,9 +121,9 @@ describe('for a specific station', () => {
 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)
+    expect(station.source.id).toBe('8722588')
+    expect(station.latitude).toBeCloseTo(26.77)
+    expect(station.longitude).toBeCloseTo(-80.0517)
   })
   ;[
     { lat: 26.7, lon: -80.05 },
@@ -132,7 +132,7 @@ describe('nearestStation', () => {
   ].forEach((position) => {
     test(`finds station with ${Object.keys(position).join('/')}`, () => {
       const station = nearestStation(position)
-      expect(station.metadata.id).toEqual('us-fl-port-of-west-palm-beach')
+      expect(station.id).toEqual('us-fl-port-of-west-palm-beach')
     })
   })
 })
@@ -145,14 +145,14 @@ describe('findStation', () => {
   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.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.id).toBe('us-ma-boston')
     expect(station.getExtremesPrediction).toBeDefined()
   })
 })
@@ -213,6 +213,6 @@ describe('datum', () => {
     })
 
     expect(extremes.datum).toBeUndefined()
-    expect(extremes.predictions.length).toBeGreaterThan(0)
+    expect(extremes.extremes.length).toBeGreaterThan(0)
   })
 })