@neaps/tide-predictor 0.0.5 → 0.2.0

package/README.md

@@ -1,62 +1,55 @@
-![example workflow](https://github.com/neaps/tide-predictor/actions/workflows/test.yml/badge.svg) [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fneaps%2Ftide-predictor.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fneaps%2Ftide-predictor?ref=badge_shield)
+# @neaps/tide-predictor
 
-# Tide predictor
-
-A Javascript tide harmonic calculator.
+A tide harmonic calculator written in TypeScript.
 
 <!-- START DOCS -->
 
-## 🚨Warning🚨
-
-**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. 😢
+> [!WARNING]
+> **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
 
-```
-# yarn
-yarn install @neaps/tide-prediction
-
-#npm
-npm install --save @neaps/tide-prediction
+```sh
+npm install @neaps/tide-predictor
 ```
 
 # Usage
 
-Neaps requires that you [provide your own tidal harmonics information](#constituent-object) to generate a prediction.
-
-Because many constituent datum come with multiple phases (in the case of NOAA's data, they are `phase_local` and `phase_GMT`), there is a `phaseKey` option for choosing which to use.
+`@neaps/tide-predictor` requires that you [provide your own tidal harmonics information](#constituent-object) to generate a prediction. For a complete tide prediction solution, including finding nearby stations and their harmonics, check out the [`neaps` package](https://github.com/neaps/neaps).
 
-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.
+```typescript
+import TidePredictor from '@neaps/tide-predictor'
 
-```javascript
-import TidePrediction from '@neaps/tide-prediction'
 const constituents = [
   {
     phase_GMT: 98.7,
     phase_local: 313.7,
     amplitude: 2.687,
     name: 'M2',
-    speed: 28.984104,
-  },
+    speed: 28.984104
+  }
   //....there are usually many, read the docs
 ]
 
-const highLowTides = tidePrediction(constituents, {
-  phaseKey: 'phase_GMT',
-}).getExtremesPrediction(new Date('2019-01-01'), new Date('2019-01-10'))
+const highLowTides = TidePredictor(constituents, {
+  phaseKey: 'phase_GMT'
+}).getExtremesPrediction({
+  start: new Date('2019-01-01'),
+  end: new Date('2019-01-10')
+})
 ```
 
+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.
+
 ## Tide prediction object
 
-Calling `tidePrediction` will generate a new tide prediction object. It accepts the following arguments:
+Calling `tidePredictor` will generate a new tide prediction object. It accepts the following arguments:
 
 - `constituents` - An array of [constituent objects](#constituent-object)
 - `options` - An object with one of:
-  - `phaseKey` - The name of the parameter within constituents that is considered the "phase"
+  - `phaseKey` - The name of the parameter within constituents that is considered the "phase" because many constituent datum come with multiple phases (in the case of NOAA's data, they are `phase_local` and `phase_GMT`).
   - `offset` - A value to add to **all** values predicted. This is useful if you want to, for example, offset tides by mean high water, etc.
 
 ### Tide prediction methods
@@ -67,36 +60,36 @@ The returned tide prediction object has various methods. All of these return reg
 
 Returns the predicted high and low tides between a start and end date.
 
-```javascript
+```typescript
 const startDate = new Date()
 const endDate = new Date(startDate + 3 * 24 * 60 * 60 * 1000)
-const tides = tidePrediction(constituents).getExtremesPrediction({
+const tides = TidePredictor(constituents).getExtremesPrediction({
   start: startDate,
   end: endDate,
   labels: {
     //optional human-readable labels
     high: 'High tide',
-    low: 'Low tide',
-  },
+    low: 'Low tide'
+  }
 })
 ```
 
 If you want predictions for a subservient station, first set the reference station in the prediction, and pass the [subservient station offests](#subservient-station) to the `getExtremesPrediction` method:
 
-```javascript
-const tides = tidePrediction(constituents).getExtremesPrediction({
+```typescript
+const tides = TidePredictor(constituents).getExtremesPrediction({
   start: startDate,
   end: endDate,
   offset: {
     height_offset: {
       high: 1,
-      low: 2,
+      low: 2
     },
     time_offset: {
       high: 1,
-      low: 2,
-    },
-  },
+      low: 2
+    }
+  }
 })
 ```
 
@@ -126,9 +119,9 @@ High and low tides are returned as arrays of objects:
 
 Gives you the predicted water level at a specific time.
 
-```javascript
-const waterLevel = tidePrediction(constituents).getWaterLevelAtTime({
-  time: new Date(),
+```typescript
+const waterLevel = TidePredictor(constituents).getWaterLevelAtTime({
+  time: new Date()
 })
 ```
 
@@ -172,22 +165,22 @@ Tidal constituents should be an array of objects with at least:
 
 ### <a name="subservient-station"></a>Subservient station definitions
 
-Some stations do not have defined harmonic data, but do have published offets and a reference station. These include the offsets in time or amplitude of the high and low tides. Subservient station definitions are objects that include:
+Some stations do not have defined harmonic data, but do have published offsets and a reference station. These include the offsets in time or amplitude of the high and low tides. Subservient station definitions are objects that include:
 
-- `height_offset` - **object** - An object of height offets, in the same units as the reference station.
+- `height` - **object** - An object of height offsets, in the same units as the reference station.
   - `high` - **float** - The offset to be added to high tide (can be negative)
   - `low` - **float** - The offset to be added to low tide (can be negative)
-- `time_offset` - **object** - An object of time offets, in number of minutes
+- `time` - **object** - An object of time offsets, in number of minutes
   - `high` - **float** - The number of minutes to add to high tide times (can be negative)
   - `low` - **float** - The number of minutes to add to low tide times (can be negative)
 
 ```
 {
-  height_offset: {
+  height: {
     high: 1,
     low: 2
   },
-  time_offset: {
+  time: {
     high: 1,
     low: 2
   }