@neaps/tide-database 0.0.20251220

package/LICENSE

@@ -0,0 +1,25 @@
+THE FOLLOWING LICENSE INFORMATION COVERS ONLY THE DOCUMENTATION AND ANY CODE
+NOT WITHIN THE "data" DIRECTORY. EACH DATA FILE HAS ITS OWN LICENSE INFORMATION.
+
+The MIT License (MIT)
+
+Copyright (c) 2015 gatsbyjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,79 @@
+## Tide harmonics database
+
+The availability of good harmonic constituent data varies from country
+to country, resulting in very different tide predeictions depending on
+what products you use. Within the United States, NOAA provides excellent
+harmonic constituents for free, but internationally it is a different
+story.
+
+We first observed these challenges in Gulfo Nuevo in Argentina. The gulf
+is very deep, with a narrow mouth to the Atlantic and sloping benthic
+profile. As a result, the difference between high and low tides is
+consistently 5 meters or more. Various websites and products we used had
+different levels of accuracy when predicting the tides. We found one
+that was just predicting tides from a station over 200km away, outside
+the gulf, and therefore completely different in terms of water level and
+timing.
+
+The various surf or weather report apps either use old data, or base
+large areas of coastline on one station. Many people are still using
+pre-2004 data published in Xtide's Harmbase. Harmbase is great, but it's
+data is locked in binary files and SQL, and the maintainer [has given up on maintaining it outside the US](https://flaterco.com/xtide/faq.html#60)
+.
+
+**All** constituent data is delivered in Meters.
+
+Much effort has been made to cover the [requirements from libTCD](https://flaterco.com/xtide/libtcd.html).
+
+## Submitting data
+
+If you have **at least a year** of hourly water level observations, you can convert those to harmonic constituents and [submit them to this database online](https://neaps.js.org/harmonics) with a simple form.
+
+Your submission will be automatically converted to a Pull Request to this repository.
+
+## Installation
+
+```bash
+npm install @neaps/tide-stations
+```
+
+## Usage
+
+```typescript
+import { nearest, near, stations } from '@neaps/tide-stations';
+
+// All stations
+console.log('Total stations:', stations.length);
+
+// Find the nearest station to a given lat/lon
+console.log(`Nearest station:`, nearest({ lat: 26.722, lon: -80.031 }));
+
+// Find the 10 nearest stations to a given lat/lon, in order of distance
+console.log('5 nearest stations:', near({ lat: 26.722, lon: -80.031 }, 10));
+```
+
+## Maintenance
+
+A GitHub Action runs monthly on the 1st of each month to automatically update NOAA tide station data. The workflow:
+- Fetches the latest station list and harmonic constituents from NOAA's API
+- Updates existing station files with new data
+- Adds any newly discovered reference stations
+- Creates a pull request if changes are detected
+
+You can also manually trigger the workflow from the Actions tab in GitHub.
+
+To manually update NOAA stations:
+
+```bash
+$ tools/update-noaa-stations
+```
+
+This will scan all existing NOAA station files, fetch any new stations from NOAA's API, and update harmonic constituents for all stations.
+
+## Versioning
+
+Releases of this database use [Semantic Versioning](https://semver.org/), with these added semantics:
+
+* Major version changes indicate breaking changes to the data structure or APIs. However, as long as the version is "0.x", breaking changes may occur without a major version bump.
+* Minor version changes indicate backward-compatible additions to the data structure or APIs, such as new fields.
+* Patch version changes indicate updates to station data, and will always be the current date. For example, "0.1.20260101".

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+type HarmonicConstituent = {
+    name: string;
+    description?: string;
+    amplitude: number;
+    phase_UTC: number;
+    phase_local: number;
+    speed?: number;
+};
+export interface Station {
+    id: string;
+    name: string;
+    continent: string;
+    country: string;
+    region: string;
+    timezone: string;
+    disclaimers: string;
+    type: 'reference' | 'subordinate';
+    latitude: number;
+    longitude: number;
+    source: {
+        name: string;
+        id: string;
+        published_harmonics: boolean;
+        url: string;
+        source_url: string;
+    };
+    license: {
+        type: string;
+        commercial_use: boolean;
+        url: string;
+        notes?: string;
+    };
+    harmonic_constituents: HarmonicConstituent[];
+    offsets?: {
+        reference: string;
+        height: {
+            high: number;
+            low: number;
+            type: 'ratio' | 'fixed';
+        };
+        time: {
+            high: number;
+            low: number;
+        };
+    };
+    datums: Record<string, number>;
+}
+declare const stations: Station[];
+export default stations;