neaps 0.1.0

package/dist/index.cjs

@@ -0,0 +1,157 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let geolib = require("geolib");
+let _neaps_tide_database = require("@neaps/tide-database");
+_neaps_tide_database = __toESM(_neaps_tide_database);
+let _neaps_tide_predictor = require("@neaps/tide-predictor");
+_neaps_tide_predictor = __toESM(_neaps_tide_predictor);
+
+//#region src/index.ts
+/**
+* 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
+* })
+*/
+function getExtremesPrediction(options) {
+	return nearestStation(options).getExtremesPrediction(options);
+}
+/**
+* Get timeline prediction using the nearest station to the given position.
+*/
+function getTimelinePrediction(options) {
+	return nearestStation(options).getTimelinePrediction(options);
+}
+/**
+* Get water level at a specific time using the nearest station to the given position.
+*/
+function getWaterLevelAtTime(options) {
+	return nearestStation(options).getWaterLevelAtTime(options);
+}
+/**
+* Find the nearest station to the given position.
+*/
+function nearestStation(position) {
+	return stationsNear(position, 1)[0];
+}
+/**
+* Find stations near the given position.
+* @param limit Maximum number of stations to return (default: 10)
+*/
+function stationsNear(position, limit = 10) {
+	return _neaps_tide_database.default.map((station) => ({
+		station,
+		distance: (0, geolib.getDistance)(position, station)
+	})).sort((a, b) => a.distance - b.distance).slice(0, limit).map(({ station, distance }) => useStation(station, distance));
+}
+/**
+* Find a specific station by its ID or source ID.
+*/
+function findStation(query) {
+	const searches = [(s) => s.id === query, (s) => s.source.id === query];
+	let found = void 0;
+	for (const search of searches) {
+		found = _neaps_tide_database.default.find(search);
+		if (found) break;
+	}
+	if (!found) throw new Error(`Station not found: ${query}`);
+	return useStation(found);
+}
+function useStation(station, distance) {
+	let reference = station;
+	if (station.type === "subordinate") reference = findStation(station.offsets?.reference || "");
+	const { datums, harmonic_constituents } = reference;
+	const defaultDatum = "MLLW" in datums ? "MLLW" : void 0;
+	function getPredictor({ datum = defaultDatum } = {}) {
+		let offset = 0;
+		if (datum) {
+			const datumOffset = datums?.[datum];
+			const mslOffset = datums?.["MSL"];
+			if (typeof datumOffset !== "number") throw new Error(`Station ${station.id} missing ${datum} datum. Available datums: ${Object.keys(datums || {}).join(", ")}`);
+			if (typeof mslOffset !== "number") throw new Error(`Station ${station.id} missing MSL datum, so predictions can't be given in ${datum}.`);
+			offset = mslOffset - datumOffset;
+		}
+		return (0, _neaps_tide_predictor.default)(harmonic_constituents, {
+			phaseKey: "phase_UTC",
+			offset
+		});
+	}
+	return {
+		...station,
+		distance,
+		datums,
+		harmonic_constituents,
+		defaultDatum,
+		getExtremesPrediction({ datum = defaultDatum, ...input }) {
+			return {
+				datum,
+				distance,
+				station,
+				extremes: getPredictor({ datum }).getExtremesPrediction({
+					...input,
+					offsets: station.offsets
+				})
+			};
+		},
+		getTimelinePrediction({ datum = defaultDatum, ...params }) {
+			if (station.type === "subordinate") throw new Error(`Timeline predictions are not supported for subordinate stations.`);
+			return {
+				datum,
+				station,
+				timeline: getPredictor({ datum }).getTimelinePrediction(params)
+			};
+		},
+		getWaterLevelAtTime({ time, datum = defaultDatum }) {
+			if (station.type === "subordinate") throw new Error(`Water level predictions are not supported for subordinate stations.`);
+			return {
+				datum,
+				station,
+				...getPredictor({ datum }).getWaterLevelAtTime({ time })
+			};
+		}
+	};
+}
+
+//#endregion
+exports.findStation = findStation;
+exports.getExtremesPrediction = getExtremesPrediction;
+exports.getTimelinePrediction = getTimelinePrediction;
+exports.getWaterLevelAtTime = getWaterLevelAtTime;
+exports.nearestStation = nearestStation;
+exports.stationsNear = stationsNear;
+exports.useStation = useStation;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["stations","found: Station | undefined"],"sources":["../src/index.ts"],"sourcesContent":["import { getDistance } from 'geolib'\nimport stations, { type Station } from '@neaps/tide-database'\nimport tidePredictor, {\n  type TimeSpan,\n  type ExtremesInput\n} from '@neaps/tide-predictor'\nimport type { GeolibInputCoordinates } from 'geolib/es/types'\n\ntype DatumOption = {\n  /** Datum to return predictions in. Defaults to 'MLLW' if available for the nearest station. */\n  datum?: string\n}\n\nexport type ExtremesOptions = ExtremesInput & DatumOption\nexport type TimelineOptions = TimeSpan & DatumOption\nexport type WaterLevelOptions = { time: Date } & DatumOption\n\n/**\n * Get extremes prediction using the nearest station to the given position.\n *\n * @example\n * ```ts\n * import { getExtremesPrediction } from 'neaps'\n *\n * const prediction = getExtremesPrediction({\n *   latitude: 26.7, // or `lat`\n *   longitude: -80.05, // or `lng` or `lon`\n *   start: new Date('2025-12-17'),\n *   end: new Date('2025-12-18'),\n *   datum: 'MLLW', // optional, defaults to MLLW if available\n * })\n */\nexport function getExtremesPrediction(\n  options: GeolibInputCoordinates & ExtremesOptions\n) {\n  return nearestStation(options).getExtremesPrediction(options)\n}\n\n/**\n * Get timeline prediction using the nearest station to the given position.\n */\nexport function getTimelinePrediction(\n  options: GeolibInputCoordinates & TimelineOptions\n) {\n  return nearestStation(options).getTimelinePrediction(options)\n}\n\n/**\n * Get water level at a specific time using the nearest station to the given position.\n */\nexport function getWaterLevelAtTime(\n  options: GeolibInputCoordinates & WaterLevelOptions\n) {\n  return nearestStation(options).getWaterLevelAtTime(options)\n}\n\n/**\n * Find the nearest station to the given position.\n */\nexport function nearestStation(position: GeolibInputCoordinates) {\n  return stationsNear(position, 1)[0]\n}\n\n/**\n * Find stations near the given position.\n * @param limit Maximum number of stations to return (default: 10)\n */\nexport function stationsNear(position: GeolibInputCoordinates, limit = 10) {\n  return stations\n    .map((station) => ({ station, distance: getDistance(position, station) }))\n    .sort((a, b) => a.distance - b.distance)\n    .slice(0, limit)\n    .map(({ station, distance }) => useStation(station, distance))\n}\n\n/**\n * Find a specific station by its ID or source ID.\n */\nexport function findStation(query: string) {\n  const searches = [\n    (s: Station) => s.id === query,\n    (s: Station) => s.source.id === query\n  ]\n\n  let found: Station | undefined = undefined\n\n  for (const search of searches) {\n    found = stations.find(search)\n    if (found) break\n  }\n\n  if (!found) throw new Error(`Station not found: ${query}`)\n\n  return useStation(found)\n}\n\nexport function useStation(station: Station, distance?: number) {\n  // If subordinate station, use the reference station for datums and constituents\n  let reference = station\n  if (station.type === 'subordinate') {\n    reference = findStation(station.offsets?.reference || '')\n  }\n  const { datums, harmonic_constituents } = reference\n\n  // Use MLLW as the default datum if available\n  const defaultDatum = 'MLLW' in datums ? 'MLLW' : undefined\n\n  function getPredictor({ datum = defaultDatum }: DatumOption = {}) {\n    let offset = 0\n\n    if (datum) {\n      const datumOffset = datums?.[datum]\n      const mslOffset = datums?.['MSL']\n\n      if (typeof datumOffset !== 'number') {\n        throw new Error(\n          `Station ${station.id} missing ${datum} datum. Available datums: ${Object.keys(datums || {}).join(', ')}`\n        )\n      }\n\n      if (typeof mslOffset !== 'number') {\n        throw new Error(\n          `Station ${station.id} missing MSL datum, so predictions can't be given in ${datum}.`\n        )\n      }\n\n      offset = mslOffset - datumOffset\n    }\n\n    return tidePredictor(harmonic_constituents, {\n      phaseKey: 'phase_UTC',\n      offset\n    })\n  }\n\n  return {\n    ...station,\n    distance,\n    datums,\n    harmonic_constituents,\n    defaultDatum,\n    getExtremesPrediction({ datum = defaultDatum, ...input }: ExtremesOptions) {\n      return {\n        datum,\n        distance,\n        station,\n        extremes: getPredictor({ datum }).getExtremesPrediction({\n          ...input,\n          offsets: station.offsets\n        })\n      }\n    },\n\n    getTimelinePrediction({\n      datum = defaultDatum,\n      ...params\n    }: TimelineOptions) {\n      if (station.type === 'subordinate') {\n        throw new Error(\n          `Timeline predictions are not supported for subordinate stations.`\n        )\n      }\n\n      return {\n        datum,\n        station,\n        timeline: getPredictor({ datum }).getTimelinePrediction(params)\n      }\n    },\n\n    getWaterLevelAtTime({ time, datum = defaultDatum }: WaterLevelOptions) {\n      if (station.type === 'subordinate') {\n        throw new Error(\n          `Water level predictions are not supported for subordinate stations.`\n        )\n      }\n\n      return {\n        datum,\n        station,\n        ...getPredictor({ datum }).getWaterLevelAtTime({ time })\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,sBACd,SACA;AACA,QAAO,eAAe,QAAQ,CAAC,sBAAsB,QAAQ;;;;;AAM/D,SAAgB,sBACd,SACA;AACA,QAAO,eAAe,QAAQ,CAAC,sBAAsB,QAAQ;;;;;AAM/D,SAAgB,oBACd,SACA;AACA,QAAO,eAAe,QAAQ,CAAC,oBAAoB,QAAQ;;;;;AAM7D,SAAgB,eAAe,UAAkC;AAC/D,QAAO,aAAa,UAAU,EAAE,CAAC;;;;;;AAOnC,SAAgB,aAAa,UAAkC,QAAQ,IAAI;AACzE,QAAOA,6BACJ,KAAK,aAAa;EAAE;EAAS,kCAAsB,UAAU,QAAQ;EAAE,EAAE,CACzE,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,SAAS,CACvC,MAAM,GAAG,MAAM,CACf,KAAK,EAAE,SAAS,eAAe,WAAW,SAAS,SAAS,CAAC;;;;;AAMlE,SAAgB,YAAY,OAAe;CACzC,MAAM,WAAW,EACd,MAAe,EAAE,OAAO,QACxB,MAAe,EAAE,OAAO,OAAO,MACjC;CAED,IAAIC,QAA6B;AAEjC,MAAK,MAAM,UAAU,UAAU;AAC7B,UAAQD,6BAAS,KAAK,OAAO;AAC7B,MAAI,MAAO;;AAGb,KAAI,CAAC,MAAO,OAAM,IAAI,MAAM,sBAAsB,QAAQ;AAE1D,QAAO,WAAW,MAAM;;AAG1B,SAAgB,WAAW,SAAkB,UAAmB;CAE9D,IAAI,YAAY;AAChB,KAAI,QAAQ,SAAS,cACnB,aAAY,YAAY,QAAQ,SAAS,aAAa,GAAG;CAE3D,MAAM,EAAE,QAAQ,0BAA0B;CAG1C,MAAM,eAAe,UAAU,SAAS,SAAS;CAEjD,SAAS,aAAa,EAAE,QAAQ,iBAA8B,EAAE,EAAE;EAChE,IAAI,SAAS;AAEb,MAAI,OAAO;GACT,MAAM,cAAc,SAAS;GAC7B,MAAM,YAAY,SAAS;AAE3B,OAAI,OAAO,gBAAgB,SACzB,OAAM,IAAI,MACR,WAAW,QAAQ,GAAG,WAAW,MAAM,4BAA4B,OAAO,KAAK,UAAU,EAAE,CAAC,CAAC,KAAK,KAAK,GACxG;AAGH,OAAI,OAAO,cAAc,SACvB,OAAM,IAAI,MACR,WAAW,QAAQ,GAAG,uDAAuD,MAAM,GACpF;AAGH,YAAS,YAAY;;AAGvB,4CAAqB,uBAAuB;GAC1C,UAAU;GACV;GACD,CAAC;;AAGJ,QAAO;EACL,GAAG;EACH;EACA;EACA;EACA;EACA,sBAAsB,EAAE,QAAQ,cAAc,GAAG,SAA0B;AACzE,UAAO;IACL;IACA;IACA;IACA,UAAU,aAAa,EAAE,OAAO,CAAC,CAAC,sBAAsB;KACtD,GAAG;KACH,SAAS,QAAQ;KAClB,CAAC;IACH;;EAGH,sBAAsB,EACpB,QAAQ,cACR,GAAG,UACe;AAClB,OAAI,QAAQ,SAAS,cACnB,OAAM,IAAI,MACR,mEACD;AAGH,UAAO;IACL;IACA;IACA,UAAU,aAAa,EAAE,OAAO,CAAC,CAAC,sBAAsB,OAAO;IAChE;;EAGH,oBAAoB,EAAE,MAAM,QAAQ,gBAAmC;AACrE,OAAI,QAAQ,SAAS,cACnB,OAAM,IAAI,MACR,sEACD;AAGH,UAAO;IACL;IACA;IACA,GAAG,aAAa,EAAE,OAAO,CAAC,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACzD;;EAEJ"}

package/dist/index.d.cts

@@ -0,0 +1,367 @@
+import * as _neaps_tide_predictor0 from "@neaps/tide-predictor";
+import { ExtremesInput, TimeSpan } from "@neaps/tide-predictor";
+import { Station } from "@neaps/tide-database";
+import { GeolibInputCoordinates } from "geolib/es/types";
+
+//#region src/index.d.ts
+type DatumOption = {
+  /** Datum to return predictions in. Defaults to 'MLLW' if available for the nearest station. */
+  datum?: string;
+};
+type ExtremesOptions = ExtremesInput & DatumOption;
+type TimelineOptions = TimeSpan & DatumOption;
+type WaterLevelOptions = {
+  time: Date;
+} & DatumOption;
+/**
+ * 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
+ * })
+ */
+declare function getExtremesPrediction(options: GeolibInputCoordinates & ExtremesOptions): {
+  datum: string | undefined;
+  distance: number | undefined;
+  station: Station;
+  extremes: _neaps_tide_predictor0.Extreme[];
+};
+/**
+ * Get timeline prediction using the nearest station to the given position.
+ */
+declare function getTimelinePrediction(options: GeolibInputCoordinates & TimelineOptions): {
+  datum: string | undefined;
+  station: Station;
+  timeline: _neaps_tide_predictor0.TimelinePoint[];
+};
+/**
+ * Get water level at a specific time using the nearest station to the given position.
+ */
+declare function getWaterLevelAtTime(options: GeolibInputCoordinates & WaterLevelOptions): {
+  time: Date;
+  hour: number;
+  level: number;
+  datum: string | undefined;
+  station: Station;
+};
+/**
+ * Find the nearest station to the given position.
+ */
+declare function nearestStation(position: GeolibInputCoordinates): {
+  distance: number | undefined;
+  datums: Record<string, number>;
+  harmonic_constituents: {
+    name: string;
+    description?: string;
+    amplitude: number;
+    phase_UTC: number;
+    phase_local: number;
+    speed?: number;
+  }[];
+  defaultDatum: string | undefined;
+  getExtremesPrediction({
+    datum,
+    ...input
+  }: ExtremesOptions): {
+    datum: string | undefined;
+    distance: number | undefined;
+    station: Station;
+    extremes: _neaps_tide_predictor0.Extreme[];
+  };
+  getTimelinePrediction({
+    datum,
+    ...params
+  }: TimelineOptions): {
+    datum: string | undefined;
+    station: Station;
+    timeline: _neaps_tide_predictor0.TimelinePoint[];
+  };
+  getWaterLevelAtTime({
+    time,
+    datum
+  }: WaterLevelOptions): {
+    time: Date;
+    hour: number;
+    level: number;
+    datum: string | undefined;
+    station: 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;
+  };
+  offsets?: {
+    reference: string;
+    height: {
+      high: number;
+      low: number;
+      type: "ratio" | "fixed";
+    };
+    time: {
+      high: number;
+      low: number;
+    };
+  };
+};
+/**
+ * Find stations near the given position.
+ * @param limit Maximum number of stations to return (default: 10)
+ */
+declare function stationsNear(position: GeolibInputCoordinates, limit?: number): {
+  distance: number | undefined;
+  datums: Record<string, number>;
+  harmonic_constituents: {
+    name: string;
+    description?: string;
+    amplitude: number;
+    phase_UTC: number;
+    phase_local: number;
+    speed?: number;
+  }[];
+  defaultDatum: string | undefined;
+  getExtremesPrediction({
+    datum,
+    ...input
+  }: ExtremesOptions): {
+    datum: string | undefined;
+    distance: number | undefined;
+    station: Station;
+    extremes: _neaps_tide_predictor0.Extreme[];
+  };
+  getTimelinePrediction({
+    datum,
+    ...params
+  }: TimelineOptions): {
+    datum: string | undefined;
+    station: Station;
+    timeline: _neaps_tide_predictor0.TimelinePoint[];
+  };
+  getWaterLevelAtTime({
+    time,
+    datum
+  }: WaterLevelOptions): {
+    time: Date;
+    hour: number;
+    level: number;
+    datum: string | undefined;
+    station: 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;
+  };
+  offsets?: {
+    reference: string;
+    height: {
+      high: number;
+      low: number;
+      type: "ratio" | "fixed";
+    };
+    time: {
+      high: number;
+      low: number;
+    };
+  };
+}[];
+/**
+ * Find a specific station by its ID or source ID.
+ */
+declare function findStation(query: string): {
+  distance: number | undefined;
+  datums: Record<string, number>;
+  harmonic_constituents: {
+    name: string;
+    description?: string;
+    amplitude: number;
+    phase_UTC: number;
+    phase_local: number;
+    speed?: number;
+  }[];
+  defaultDatum: string | undefined;
+  getExtremesPrediction({
+    datum,
+    ...input
+  }: ExtremesOptions): {
+    datum: string | undefined;
+    distance: number | undefined;
+    station: Station;
+    extremes: _neaps_tide_predictor0.Extreme[];
+  };
+  getTimelinePrediction({
+    datum,
+    ...params
+  }: TimelineOptions): {
+    datum: string | undefined;
+    station: Station;
+    timeline: _neaps_tide_predictor0.TimelinePoint[];
+  };
+  getWaterLevelAtTime({
+    time,
+    datum
+  }: WaterLevelOptions): {
+    time: Date;
+    hour: number;
+    level: number;
+    datum: string | undefined;
+    station: 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;
+  };
+  offsets?: {
+    reference: string;
+    height: {
+      high: number;
+      low: number;
+      type: "ratio" | "fixed";
+    };
+    time: {
+      high: number;
+      low: number;
+    };
+  };
+};
+declare function useStation(station: Station, distance?: number): {
+  distance: number | undefined;
+  datums: Record<string, number>;
+  harmonic_constituents: {
+    name: string;
+    description?: string;
+    amplitude: number;
+    phase_UTC: number;
+    phase_local: number;
+    speed?: number;
+  }[];
+  defaultDatum: string | undefined;
+  getExtremesPrediction({
+    datum,
+    ...input
+  }: ExtremesOptions): {
+    datum: string | undefined;
+    distance: number | undefined;
+    station: Station;
+    extremes: _neaps_tide_predictor0.Extreme[];
+  };
+  getTimelinePrediction({
+    datum,
+    ...params
+  }: TimelineOptions): {
+    datum: string | undefined;
+    station: Station;
+    timeline: _neaps_tide_predictor0.TimelinePoint[];
+  };
+  getWaterLevelAtTime({
+    time,
+    datum
+  }: WaterLevelOptions): {
+    time: Date;
+    hour: number;
+    level: number;
+    datum: string | undefined;
+    station: 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;
+  };
+  offsets?: {
+    reference: string;
+    height: {
+      high: number;
+      low: number;
+      type: "ratio" | "fixed";
+    };
+    time: {
+      high: number;
+      low: number;
+    };
+  };
+};
+//#endregion
+export { ExtremesOptions, TimelineOptions, WaterLevelOptions, findStation, getExtremesPrediction, getTimelinePrediction, getWaterLevelAtTime, nearestStation, stationsNear, useStation };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -0,0 +1,367 @@
+import { Station } from "@neaps/tide-database";
+import * as _neaps_tide_predictor0 from "@neaps/tide-predictor";
+import { ExtremesInput, TimeSpan } from "@neaps/tide-predictor";
+import { GeolibInputCoordinates } from "geolib/es/types";
+
+//#region src/index.d.ts
+type DatumOption = {
+  /** Datum to return predictions in. Defaults to 'MLLW' if available for the nearest station. */
+  datum?: string;
+};
+type ExtremesOptions = ExtremesInput & DatumOption;
+type TimelineOptions = TimeSpan & DatumOption;
+type WaterLevelOptions = {
+  time: Date;
+} & DatumOption;
+/**
+ * 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
+ * })
+ */
+declare function getExtremesPrediction(options: GeolibInputCoordinates & ExtremesOptions): {
+  datum: string | undefined;
+  distance: number | undefined;
+  station: Station;
+  extremes: _neaps_tide_predictor0.Extreme[];
+};
+/**
+ * Get timeline prediction using the nearest station to the given position.
+ */
+declare function getTimelinePrediction(options: GeolibInputCoordinates & TimelineOptions): {
+  datum: string | undefined;
+  station: Station;
+  timeline: _neaps_tide_predictor0.TimelinePoint[];
+};
+/**
+ * Get water level at a specific time using the nearest station to the given position.
+ */
+declare function getWaterLevelAtTime(options: GeolibInputCoordinates & WaterLevelOptions): {
+  time: Date;
+  hour: number;
+  level: number;
+  datum: string | undefined;
+  station: Station;
+};
+/**
+ * Find the nearest station to the given position.
+ */
+declare function nearestStation(position: GeolibInputCoordinates): {
+  distance: number | undefined;
+  datums: Record<string, number>;
+  harmonic_constituents: {
+    name: string;
+    description?: string;
+    amplitude: number;
+    phase_UTC: number;
+    phase_local: number;
+    speed?: number;
+  }[];
+  defaultDatum: string | undefined;
+  getExtremesPrediction({
+    datum,
+    ...input
+  }: ExtremesOptions): {
+    datum: string | undefined;
+    distance: number | undefined;
+    station: Station;
+    extremes: _neaps_tide_predictor0.Extreme[];
+  };
+  getTimelinePrediction({
+    datum,
+    ...params
+  }: TimelineOptions): {
+    datum: string | undefined;
+    station: Station;
+    timeline: _neaps_tide_predictor0.TimelinePoint[];
+  };
+  getWaterLevelAtTime({
+    time,
+    datum
+  }: WaterLevelOptions): {
+    time: Date;
+    hour: number;
+    level: number;
+    datum: string | undefined;
+    station: 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;
+  };
+  offsets?: {
+    reference: string;
+    height: {
+      high: number;
+      low: number;
+      type: "ratio" | "fixed";
+    };
+    time: {
+      high: number;
+      low: number;
+    };
+  };
+};
+/**
+ * Find stations near the given position.
+ * @param limit Maximum number of stations to return (default: 10)
+ */
+declare function stationsNear(position: GeolibInputCoordinates, limit?: number): {
+  distance: number | undefined;
+  datums: Record<string, number>;
+  harmonic_constituents: {
+    name: string;
+    description?: string;
+    amplitude: number;
+    phase_UTC: number;
+    phase_local: number;
+    speed?: number;
+  }[];
+  defaultDatum: string | undefined;
+  getExtremesPrediction({
+    datum,
+    ...input
+  }: ExtremesOptions): {
+    datum: string | undefined;
+    distance: number | undefined;
+    station: Station;
+    extremes: _neaps_tide_predictor0.Extreme[];
+  };
+  getTimelinePrediction({
+    datum,
+    ...params
+  }: TimelineOptions): {
+    datum: string | undefined;
+    station: Station;
+    timeline: _neaps_tide_predictor0.TimelinePoint[];
+  };
+  getWaterLevelAtTime({
+    time,
+    datum
+  }: WaterLevelOptions): {
+    time: Date;
+    hour: number;
+    level: number;
+    datum: string | undefined;
+    station: 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;
+  };
+  offsets?: {
+    reference: string;
+    height: {
+      high: number;
+      low: number;
+      type: "ratio" | "fixed";
+    };
+    time: {
+      high: number;
+      low: number;
+    };
+  };
+}[];
+/**
+ * Find a specific station by its ID or source ID.
+ */
+declare function findStation(query: string): {
+  distance: number | undefined;
+  datums: Record<string, number>;
+  harmonic_constituents: {
+    name: string;
+    description?: string;
+    amplitude: number;
+    phase_UTC: number;
+    phase_local: number;
+    speed?: number;
+  }[];
+  defaultDatum: string | undefined;
+  getExtremesPrediction({
+    datum,
+    ...input
+  }: ExtremesOptions): {
+    datum: string | undefined;
+    distance: number | undefined;
+    station: Station;
+    extremes: _neaps_tide_predictor0.Extreme[];
+  };
+  getTimelinePrediction({
+    datum,
+    ...params
+  }: TimelineOptions): {
+    datum: string | undefined;
+    station: Station;
+    timeline: _neaps_tide_predictor0.TimelinePoint[];
+  };
+  getWaterLevelAtTime({
+    time,
+    datum
+  }: WaterLevelOptions): {
+    time: Date;
+    hour: number;
+    level: number;
+    datum: string | undefined;
+    station: 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;
+  };
+  offsets?: {
+    reference: string;
+    height: {
+      high: number;
+      low: number;
+      type: "ratio" | "fixed";
+    };
+    time: {
+      high: number;
+      low: number;
+    };
+  };
+};
+declare function useStation(station: Station, distance?: number): {
+  distance: number | undefined;
+  datums: Record<string, number>;
+  harmonic_constituents: {
+    name: string;
+    description?: string;
+    amplitude: number;
+    phase_UTC: number;
+    phase_local: number;
+    speed?: number;
+  }[];
+  defaultDatum: string | undefined;
+  getExtremesPrediction({
+    datum,
+    ...input
+  }: ExtremesOptions): {
+    datum: string | undefined;
+    distance: number | undefined;
+    station: Station;
+    extremes: _neaps_tide_predictor0.Extreme[];
+  };
+  getTimelinePrediction({
+    datum,
+    ...params
+  }: TimelineOptions): {
+    datum: string | undefined;
+    station: Station;
+    timeline: _neaps_tide_predictor0.TimelinePoint[];
+  };
+  getWaterLevelAtTime({
+    time,
+    datum
+  }: WaterLevelOptions): {
+    time: Date;
+    hour: number;
+    level: number;
+    datum: string | undefined;
+    station: 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;
+  };
+  offsets?: {
+    reference: string;
+    height: {
+      high: number;
+      low: number;
+      type: "ratio" | "fixed";
+    };
+    time: {
+      high: number;
+      low: number;
+    };
+  };
+};
+//#endregion
+export { ExtremesOptions, TimelineOptions, WaterLevelOptions, findStation, getExtremesPrediction, getTimelinePrediction, getWaterLevelAtTime, nearestStation, stationsNear, useStation };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,122 @@
+import { getDistance } from "geolib";
+import stations from "@neaps/tide-database";
+import tidePredictor from "@neaps/tide-predictor";
+
+//#region src/index.ts
+/**
+* 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
+* })
+*/
+function getExtremesPrediction(options) {
+	return nearestStation(options).getExtremesPrediction(options);
+}
+/**
+* Get timeline prediction using the nearest station to the given position.
+*/
+function getTimelinePrediction(options) {
+	return nearestStation(options).getTimelinePrediction(options);
+}
+/**
+* Get water level at a specific time using the nearest station to the given position.
+*/
+function getWaterLevelAtTime(options) {
+	return nearestStation(options).getWaterLevelAtTime(options);
+}
+/**
+* Find the nearest station to the given position.
+*/
+function nearestStation(position) {
+	return stationsNear(position, 1)[0];
+}
+/**
+* Find stations near the given position.
+* @param limit Maximum number of stations to return (default: 10)
+*/
+function stationsNear(position, limit = 10) {
+	return stations.map((station) => ({
+		station,
+		distance: getDistance(position, station)
+	})).sort((a, b) => a.distance - b.distance).slice(0, limit).map(({ station, distance }) => useStation(station, distance));
+}
+/**
+* Find a specific station by its ID or source ID.
+*/
+function findStation(query) {
+	const searches = [(s) => s.id === query, (s) => s.source.id === query];
+	let found = void 0;
+	for (const search of searches) {
+		found = stations.find(search);
+		if (found) break;
+	}
+	if (!found) throw new Error(`Station not found: ${query}`);
+	return useStation(found);
+}
+function useStation(station, distance) {
+	let reference = station;
+	if (station.type === "subordinate") reference = findStation(station.offsets?.reference || "");
+	const { datums, harmonic_constituents } = reference;
+	const defaultDatum = "MLLW" in datums ? "MLLW" : void 0;
+	function getPredictor({ datum = defaultDatum } = {}) {
+		let offset = 0;
+		if (datum) {
+			const datumOffset = datums?.[datum];
+			const mslOffset = datums?.["MSL"];
+			if (typeof datumOffset !== "number") throw new Error(`Station ${station.id} missing ${datum} datum. Available datums: ${Object.keys(datums || {}).join(", ")}`);
+			if (typeof mslOffset !== "number") throw new Error(`Station ${station.id} missing MSL datum, so predictions can't be given in ${datum}.`);
+			offset = mslOffset - datumOffset;
+		}
+		return tidePredictor(harmonic_constituents, {
+			phaseKey: "phase_UTC",
+			offset
+		});
+	}
+	return {
+		...station,
+		distance,
+		datums,
+		harmonic_constituents,
+		defaultDatum,
+		getExtremesPrediction({ datum = defaultDatum, ...input }) {
+			return {
+				datum,
+				distance,
+				station,
+				extremes: getPredictor({ datum }).getExtremesPrediction({
+					...input,
+					offsets: station.offsets
+				})
+			};
+		},
+		getTimelinePrediction({ datum = defaultDatum, ...params }) {
+			if (station.type === "subordinate") throw new Error(`Timeline predictions are not supported for subordinate stations.`);
+			return {
+				datum,
+				station,
+				timeline: getPredictor({ datum }).getTimelinePrediction(params)
+			};
+		},
+		getWaterLevelAtTime({ time, datum = defaultDatum }) {
+			if (station.type === "subordinate") throw new Error(`Water level predictions are not supported for subordinate stations.`);
+			return {
+				datum,
+				station,
+				...getPredictor({ datum }).getWaterLevelAtTime({ time })
+			};
+		}
+	};
+}
+
+//#endregion
+export { findStation, getExtremesPrediction, getTimelinePrediction, getWaterLevelAtTime, nearestStation, stationsNear, useStation };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["found: Station | undefined"],"sources":["../src/index.ts"],"sourcesContent":["import { getDistance } from 'geolib'\nimport stations, { type Station } from '@neaps/tide-database'\nimport tidePredictor, {\n  type TimeSpan,\n  type ExtremesInput\n} from '@neaps/tide-predictor'\nimport type { GeolibInputCoordinates } from 'geolib/es/types'\n\ntype DatumOption = {\n  /** Datum to return predictions in. Defaults to 'MLLW' if available for the nearest station. */\n  datum?: string\n}\n\nexport type ExtremesOptions = ExtremesInput & DatumOption\nexport type TimelineOptions = TimeSpan & DatumOption\nexport type WaterLevelOptions = { time: Date } & DatumOption\n\n/**\n * Get extremes prediction using the nearest station to the given position.\n *\n * @example\n * ```ts\n * import { getExtremesPrediction } from 'neaps'\n *\n * const prediction = getExtremesPrediction({\n *   latitude: 26.7, // or `lat`\n *   longitude: -80.05, // or `lng` or `lon`\n *   start: new Date('2025-12-17'),\n *   end: new Date('2025-12-18'),\n *   datum: 'MLLW', // optional, defaults to MLLW if available\n * })\n */\nexport function getExtremesPrediction(\n  options: GeolibInputCoordinates & ExtremesOptions\n) {\n  return nearestStation(options).getExtremesPrediction(options)\n}\n\n/**\n * Get timeline prediction using the nearest station to the given position.\n */\nexport function getTimelinePrediction(\n  options: GeolibInputCoordinates & TimelineOptions\n) {\n  return nearestStation(options).getTimelinePrediction(options)\n}\n\n/**\n * Get water level at a specific time using the nearest station to the given position.\n */\nexport function getWaterLevelAtTime(\n  options: GeolibInputCoordinates & WaterLevelOptions\n) {\n  return nearestStation(options).getWaterLevelAtTime(options)\n}\n\n/**\n * Find the nearest station to the given position.\n */\nexport function nearestStation(position: GeolibInputCoordinates) {\n  return stationsNear(position, 1)[0]\n}\n\n/**\n * Find stations near the given position.\n * @param limit Maximum number of stations to return (default: 10)\n */\nexport function stationsNear(position: GeolibInputCoordinates, limit = 10) {\n  return stations\n    .map((station) => ({ station, distance: getDistance(position, station) }))\n    .sort((a, b) => a.distance - b.distance)\n    .slice(0, limit)\n    .map(({ station, distance }) => useStation(station, distance))\n}\n\n/**\n * Find a specific station by its ID or source ID.\n */\nexport function findStation(query: string) {\n  const searches = [\n    (s: Station) => s.id === query,\n    (s: Station) => s.source.id === query\n  ]\n\n  let found: Station | undefined = undefined\n\n  for (const search of searches) {\n    found = stations.find(search)\n    if (found) break\n  }\n\n  if (!found) throw new Error(`Station not found: ${query}`)\n\n  return useStation(found)\n}\n\nexport function useStation(station: Station, distance?: number) {\n  // If subordinate station, use the reference station for datums and constituents\n  let reference = station\n  if (station.type === 'subordinate') {\n    reference = findStation(station.offsets?.reference || '')\n  }\n  const { datums, harmonic_constituents } = reference\n\n  // Use MLLW as the default datum if available\n  const defaultDatum = 'MLLW' in datums ? 'MLLW' : undefined\n\n  function getPredictor({ datum = defaultDatum }: DatumOption = {}) {\n    let offset = 0\n\n    if (datum) {\n      const datumOffset = datums?.[datum]\n      const mslOffset = datums?.['MSL']\n\n      if (typeof datumOffset !== 'number') {\n        throw new Error(\n          `Station ${station.id} missing ${datum} datum. Available datums: ${Object.keys(datums || {}).join(', ')}`\n        )\n      }\n\n      if (typeof mslOffset !== 'number') {\n        throw new Error(\n          `Station ${station.id} missing MSL datum, so predictions can't be given in ${datum}.`\n        )\n      }\n\n      offset = mslOffset - datumOffset\n    }\n\n    return tidePredictor(harmonic_constituents, {\n      phaseKey: 'phase_UTC',\n      offset\n    })\n  }\n\n  return {\n    ...station,\n    distance,\n    datums,\n    harmonic_constituents,\n    defaultDatum,\n    getExtremesPrediction({ datum = defaultDatum, ...input }: ExtremesOptions) {\n      return {\n        datum,\n        distance,\n        station,\n        extremes: getPredictor({ datum }).getExtremesPrediction({\n          ...input,\n          offsets: station.offsets\n        })\n      }\n    },\n\n    getTimelinePrediction({\n      datum = defaultDatum,\n      ...params\n    }: TimelineOptions) {\n      if (station.type === 'subordinate') {\n        throw new Error(\n          `Timeline predictions are not supported for subordinate stations.`\n        )\n      }\n\n      return {\n        datum,\n        station,\n        timeline: getPredictor({ datum }).getTimelinePrediction(params)\n      }\n    },\n\n    getWaterLevelAtTime({ time, datum = defaultDatum }: WaterLevelOptions) {\n      if (station.type === 'subordinate') {\n        throw new Error(\n          `Water level predictions are not supported for subordinate stations.`\n        )\n      }\n\n      return {\n        datum,\n        station,\n        ...getPredictor({ datum }).getWaterLevelAtTime({ time })\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,sBACd,SACA;AACA,QAAO,eAAe,QAAQ,CAAC,sBAAsB,QAAQ;;;;;AAM/D,SAAgB,sBACd,SACA;AACA,QAAO,eAAe,QAAQ,CAAC,sBAAsB,QAAQ;;;;;AAM/D,SAAgB,oBACd,SACA;AACA,QAAO,eAAe,QAAQ,CAAC,oBAAoB,QAAQ;;;;;AAM7D,SAAgB,eAAe,UAAkC;AAC/D,QAAO,aAAa,UAAU,EAAE,CAAC;;;;;;AAOnC,SAAgB,aAAa,UAAkC,QAAQ,IAAI;AACzE,QAAO,SACJ,KAAK,aAAa;EAAE;EAAS,UAAU,YAAY,UAAU,QAAQ;EAAE,EAAE,CACzE,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,SAAS,CACvC,MAAM,GAAG,MAAM,CACf,KAAK,EAAE,SAAS,eAAe,WAAW,SAAS,SAAS,CAAC;;;;;AAMlE,SAAgB,YAAY,OAAe;CACzC,MAAM,WAAW,EACd,MAAe,EAAE,OAAO,QACxB,MAAe,EAAE,OAAO,OAAO,MACjC;CAED,IAAIA,QAA6B;AAEjC,MAAK,MAAM,UAAU,UAAU;AAC7B,UAAQ,SAAS,KAAK,OAAO;AAC7B,MAAI,MAAO;;AAGb,KAAI,CAAC,MAAO,OAAM,IAAI,MAAM,sBAAsB,QAAQ;AAE1D,QAAO,WAAW,MAAM;;AAG1B,SAAgB,WAAW,SAAkB,UAAmB;CAE9D,IAAI,YAAY;AAChB,KAAI,QAAQ,SAAS,cACnB,aAAY,YAAY,QAAQ,SAAS,aAAa,GAAG;CAE3D,MAAM,EAAE,QAAQ,0BAA0B;CAG1C,MAAM,eAAe,UAAU,SAAS,SAAS;CAEjD,SAAS,aAAa,EAAE,QAAQ,iBAA8B,EAAE,EAAE;EAChE,IAAI,SAAS;AAEb,MAAI,OAAO;GACT,MAAM,cAAc,SAAS;GAC7B,MAAM,YAAY,SAAS;AAE3B,OAAI,OAAO,gBAAgB,SACzB,OAAM,IAAI,MACR,WAAW,QAAQ,GAAG,WAAW,MAAM,4BAA4B,OAAO,KAAK,UAAU,EAAE,CAAC,CAAC,KAAK,KAAK,GACxG;AAGH,OAAI,OAAO,cAAc,SACvB,OAAM,IAAI,MACR,WAAW,QAAQ,GAAG,uDAAuD,MAAM,GACpF;AAGH,YAAS,YAAY;;AAGvB,SAAO,cAAc,uBAAuB;GAC1C,UAAU;GACV;GACD,CAAC;;AAGJ,QAAO;EACL,GAAG;EACH;EACA;EACA;EACA;EACA,sBAAsB,EAAE,QAAQ,cAAc,GAAG,SAA0B;AACzE,UAAO;IACL;IACA;IACA;IACA,UAAU,aAAa,EAAE,OAAO,CAAC,CAAC,sBAAsB;KACtD,GAAG;KACH,SAAS,QAAQ;KAClB,CAAC;IACH;;EAGH,sBAAsB,EACpB,QAAQ,cACR,GAAG,UACe;AAClB,OAAI,QAAQ,SAAS,cACnB,OAAM,IAAI,MACR,mEACD;AAGH,UAAO;IACL;IACA;IACA,UAAU,aAAa,EAAE,OAAO,CAAC,CAAC,sBAAsB,OAAO;IAChE;;EAGH,oBAAoB,EAAE,MAAM,QAAQ,gBAAmC;AACrE,OAAI,QAAQ,SAAS,cACnB,OAAM,IAAI,MACR,sEACD;AAGH,UAAO;IACL;IACA;IACA,GAAG,aAAa,EAAE,OAAO,CAAC,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACzD;;EAEJ"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "neaps",
+  "version": "0.1.0",
+  "description": "Tide predictions",
+  "keywords": [
+    "tides",
+    "harmonics"
+  ],
+  "homepage": "https://github.com/neaps/neaps#readme",
+  "bugs": {
+    "url": "https://github.com/neaps/neaps/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neaps/neaps.git",
+    "directory": "packages/neaps"
+  },
+  "license": "MIT",
+  "author": "Brandon Keepers <brandon@openwaters.io>",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@neaps/tide-predictor": "^0.2.0",
+    "@neaps/tide-database": "^0.0",
+    "geolib": "^3.3.4"
+  }
+}

package/src/index.ts

@@ -0,0 +1,185 @@
+import { getDistance } from 'geolib'
+import stations, { type Station } from '@neaps/tide-database'
+import tidePredictor, {
+  type TimeSpan,
+  type ExtremesInput
+} from '@neaps/tide-predictor'
+import type { GeolibInputCoordinates } from 'geolib/es/types'
+
+type DatumOption = {
+  /** Datum to return predictions in. Defaults to 'MLLW' if available for the nearest station. */
+  datum?: string
+}
+
+export type ExtremesOptions = ExtremesInput & DatumOption
+export type TimelineOptions = TimeSpan & DatumOption
+export type WaterLevelOptions = { time: Date } & DatumOption
+
+/**
+ * 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)
+}
+
+/**
+ * Get timeline prediction using the nearest station to the given position.
+ */
+export function getTimelinePrediction(
+  options: GeolibInputCoordinates & TimelineOptions
+) {
+  return nearestStation(options).getTimelinePrediction(options)
+}
+
+/**
+ * Get water level at a specific time using the nearest station to the given position.
+ */
+export function getWaterLevelAtTime(
+  options: GeolibInputCoordinates & WaterLevelOptions
+) {
+  return nearestStation(options).getWaterLevelAtTime(options)
+}
+
+/**
+ * Find the nearest station to the given position.
+ */
+export function nearestStation(position: GeolibInputCoordinates) {
+  return stationsNear(position, 1)[0]
+}
+
+/**
+ * Find stations near the given position.
+ * @param limit Maximum number of stations to return (default: 10)
+ */
+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 }) => useStation(station, distance))
+}
+
+/**
+ * Find a specific 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 useStation(found)
+}
+
+export function useStation(station: Station, distance?: number) {
+  // If subordinate station, use the reference station for datums and constituents
+  let reference = station
+  if (station.type === 'subordinate') {
+    reference = findStation(station.offsets?.reference || '')
+  }
+  const { datums, harmonic_constituents } = reference
+
+  // Use MLLW as the default datum if available
+  const defaultDatum = 'MLLW' in datums ? 'MLLW' : undefined
+
+  function getPredictor({ datum = defaultDatum }: DatumOption = {}) {
+    let offset = 0
+
+    if (datum) {
+      const datumOffset = datums?.[datum]
+      const mslOffset = datums?.['MSL']
+
+      if (typeof datumOffset !== 'number') {
+        throw new Error(
+          `Station ${station.id} missing ${datum} datum. Available datums: ${Object.keys(datums || {}).join(', ')}`
+        )
+      }
+
+      if (typeof mslOffset !== 'number') {
+        throw new Error(
+          `Station ${station.id} missing MSL datum, so predictions can't be given in ${datum}.`
+        )
+      }
+
+      offset = mslOffset - datumOffset
+    }
+
+    return tidePredictor(harmonic_constituents, {
+      phaseKey: 'phase_UTC',
+      offset
+    })
+  }
+
+  return {
+    ...station,
+    distance,
+    datums,
+    harmonic_constituents,
+    defaultDatum,
+    getExtremesPrediction({ datum = defaultDatum, ...input }: ExtremesOptions) {
+      return {
+        datum,
+        distance,
+        station,
+        extremes: getPredictor({ datum }).getExtremesPrediction({
+          ...input,
+          offsets: station.offsets
+        })
+      }
+    },
+
+    getTimelinePrediction({
+      datum = defaultDatum,
+      ...params
+    }: TimelineOptions) {
+      if (station.type === 'subordinate') {
+        throw new Error(
+          `Timeline predictions are not supported for subordinate stations.`
+        )
+      }
+
+      return {
+        datum,
+        station,
+        timeline: getPredictor({ datum }).getTimelinePrediction(params)
+      }
+    },
+
+    getWaterLevelAtTime({ time, datum = defaultDatum }: WaterLevelOptions) {
+      if (station.type === 'subordinate') {
+        throw new Error(
+          `Water level predictions are not supported for subordinate stations.`
+        )
+      }
+
+      return {
+        datum,
+        station,
+        ...getPredictor({ datum }).getWaterLevelAtTime({ time })
+      }
+    }
+  }
+}