provider

(no submodules)

Purpose

Adapts the three tide-prediction backends — TICON-style harmonic constituents, the ADMIRALTY HTTP API, and the equilibrium-tide physics model — to the universal TidalProvider shape from @suaveplan/types. Every factory returns a pair of methods (predictHeight, getExtremes) that accept a PlanetConfig, a SphericalCoord, and a Date, so callers can swap backends without changing call sites or domain logic. This is the recommended entry point for any consumer that doesn't need the lower-level station-rooted AdmiraltyProvider API.

Features

createTiconProvider(constituents, meanSeaLevel?) — pure, offline, deterministic. Wraps predictHeight/findExtremes from @suaveplan/tides/harmonic.
createAdmiraltyProvider(options) — async, network-bound. Routes via getNearestStation so callers can pass any UK coordinate.
createPhysicsBasedProvider() — zero-config, no network, no constituents. Equilibrium-tide model from @suaveplan/tides physics.
All three return objects matching TidalProvider from @suaveplan/types, so they compose with anything in the universe stack expecting that contract.
AbortSignal is forwarded for the ADMIRALTY adapter; ignored for the deterministic backends.

Usage: Basic Example

import { createTiconProvider } from "@suaveplan/tides";

const provider = createTiconProvider([
    { name: "M2", amplitude: 1.0, phase: 0, speed: 28.984104 },
]);
const earth = { name: "Earth", radius: 6_371_000, rotationPeriod: 86_164 };
const height = await provider.predictHeight(
    earth,
    { latitude: 51.5074, longitude: -0.1278 },
    new Date("2024-06-15T12:00:00Z")
);

Usage: Advanced Example

import {
    createAdmiraltyProvider,
    createPhysicsBasedProvider,
    createTiconProvider,
} from "@suaveplan/tides";
import type { TidalProvider } from "@suaveplan/types";

function pickProvider(input: {
    apiKey?: string;
    constituents?: Parameters<typeof createTiconProvider>[0];
}): TidalProvider {
    if (input.constituents?.length)
        return createTiconProvider(input.constituents);
    if (input.apiKey) return createAdmiraltyProvider({ apiKey: input.apiKey });
    return createPhysicsBasedProvider();
}

API Reference

createTiconProvider(constituents: readonly HarmonicConstituent[], meanSeaLevel?: number): TidalProvider.
createAdmiraltyProvider(options: AdmiraltyProviderOptions): TidalProvider — internally wraps a station-rooted AdmiraltyProvider.
createPhysicsBasedProvider(): TidalProvider.
Each TidalProvider exposes:
- predictHeight(planet, coord, time, signal?): Promise<number>.
- getExtremes(planet, coord, date, signal?): Promise<TideExtreme[]>.

Implementation Notes

The _planet parameter is currently unused by every backend — it is preserved on the contract so future backends (e.g. Mars or exoplanet equilibrium tide models) can vary behaviour without breaking call sites. The ADMIRALTY adapter performs an extra getNearestStation round-trip per call; for batch workloads, consider hoisting that to once-per-coord and operating on the station-rooted AdmiraltyProvider API directly to amortise it. The TICON and physics adapters are synchronous internally but return Promises to satisfy the universal contract — they never reject and never await, so await is essentially zero-cost. getExtremes for the TICON adapter scans the full UTC day containing date (startOfDay → +24h) regardless of the time-of-day component on the input.

3.5 KiB Raw Blame History