@slackwater/database 1.0.0-beta.0

package/dist/worker/index.d.ts

@@ -0,0 +1,283 @@
+//#region src/attribution.d.ts
+/**
+ * The project half of every notice. A station's full notice opens with this,
+ * then adds whatever its source and licence require.
+ */
+export declare const PROJECT_CREDIT = "Slackwater database (https://github.com/openwatersio/slackwater-database)";
+/** Where a redistributor is pointed to find what this project changed. */
+export declare const MODIFICATIONS_URL = "https://github.com/openwatersio/slackwater-database#modifications-to-source-data";
+/** Whether a source name has a credit decision recorded. */
+export declare function isKnownSource(sourceName: string): boolean;
+/**
+ * Assemble a station's complete notice, so displaying it is the whole of a
+ * consumer's obligation. Under a Creative Commons licence that means the
+ * creator credit, the licence and its URI, and an indication that the material
+ * was modified — the three things CC BY 4.0 section 3(a)(1) requires be passed
+ * on. Licence is taken per station rather than per source because it varies
+ * within one source: TICON stations relayed from CMEMS are CC BY-NC while the
+ * rest are CC BY.
+ */
+export declare function attributionFor(sourceName: string | undefined, license: {
+  type: string;
+  url: string;
+} | undefined): string;
+//#endregion
+//#region src/types.d.ts
+interface HarmonicConstituent {
+  name: string;
+  description?: string;
+  amplitude: number;
+  phase: number;
+  speed?: number;
+}
+interface Constituent {
+  name: string;
+  description: string | null;
+  speed: number;
+}
+interface StationRouteInput {
+  slug: string;
+  station_ids: string[];
+  former_paths?: string[];
+}
+interface StationRoute {
+  slug: string;
+  stationIds: string[];
+  formerPaths: string[];
+}
+interface DatabaseRoutes {
+  tide: StationRouteInput[];
+  current: StationRouteInput[];
+}
+interface StationData {
+  name: string;
+  continent: string;
+  country: string;
+  country_code?: string;
+  locality?: string;
+  region?: string;
+  region_code?: string;
+  timezone: string;
+  context?: string;
+  context_derived?: boolean;
+  cities?: string[];
+  disclaimers?: string;
+  type: "reference" | "subordinate";
+  latitude: number;
+  longitude: number;
+  source: {
+    name: string;
+    id: string;
+    published_harmonics: boolean;
+    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>;
+  datums_source?: "observed" | "harmonic";
+  chart_datum?: string;
+  epoch?: {
+    start: string;
+    end: string;
+  };
+  aliases?: string[];
+}
+interface TideDerivedCurrentData {
+  reference: string;
+  high_water_lag_minutes: number;
+  low_water_lag_minutes: number;
+}
+interface CurrentData {
+  /** Degrees true. */
+  flood_direction?: number;
+  ebb_direction?: number;
+  /** Knots; the constant term added to the harmonic sum. */
+  mean_flow?: number;
+  /** Id of the tide station whose extremes pair with this current, if any. */
+  tide_reference?: string;
+  magnitude_note?: string;
+  derived?: TideDerivedCurrentData;
+  /** Subordinate currents only. Times in minutes, ratios dimensionless. */
+  offsets?: {
+    reference: string;
+    slack_before_flood?: number;
+    slack_before_ebb?: number;
+    flood_time?: number;
+    ebb_time?: number;
+    flood_speed_ratio?: number;
+    ebb_speed_ratio?: number;
+  };
+}
+/**
+ * What buildDatabase accepts: a station id plus whatever fields the catalog
+ * has. Downstream generators can pass filtered stations from this package or
+ * records of their own (including current stations).
+ */
+type StationInput = {
+  id: string;
+  kind?: "tide" | "current";
+  current?: CurrentData;
+  quality?: StationQuality;
+} & Partial<StationData>;
+interface StationQuality {
+  /** The station's id — not stored in the database, filled from identity. */
+  id: string;
+  accepted: boolean;
+  score: number;
+  /** Scoring factors, each 0-1. */
+  factors?: {
+    epoch: number;
+    recency: number;
+    source: number;
+    quality: number;
+    amplitude: number;
+    coverage: number;
+  };
+  /** Human-readable findings, e.g. "MLW (3.827) < LAT (3.831)". */
+  issues?: string[];
+  /** Rejection category ("duplicate", "datum", "constituents", ...), if rejected. */
+  reason?: string;
+  /** Id of the station that makes this one redundant, if any. */
+  redundant?: string;
+}
+/** The floor and ceiling of a station's predictions, in metres above its chart datum. */
+interface AstronomicalBounds {
+  /** Lowest Astronomical Tide. */
+  lat: number;
+  /** Highest Astronomical Tide. */
+  hat: number;
+}
+interface Station extends StationData {
+  id: string;
+  country_code: string;
+  kind: "tide" | "current";
+  current?: CurrentData;
+  quality?: StationQuality;
+  /**
+   * Lowest and highest astronomical tide, in metres above this station's chart
+   * datum; absent when the station predicting for this one has no LAT and HAT.
+   * A subordinate's is the reference's range reduced through `offsets.height`,
+   * the floor of a prediction rather than a hydrographic datum — which is why
+   * it is here and not in `datums`. See docs/datums.md.
+   */
+  astronomical_bounds?: AstronomicalBounds;
+  /**
+   * The credit to display when showing or redistributing this station, ready
+   * to render as-is. Derived from `source`; see src/attribution.ts.
+   */
+  attribution: string;
+}
+type StationMetaKey = "name" | "latitude" | "longitude" | "locality" | "region" | "region_code" | "country" | "country_code" | "continent" | "context" | "context_derived" | "cities" | "aliases" | "timezone" | "type" | "source";
+type StationMeta = {
+  id: string;
+} & Pick<StationData, StationMetaKey>;
+//#endregion
+//#region src/stations.d.ts
+/** All datum keys present across the database (e.g. "MLLW", "MSL", "NAVD88"). */
+export declare const datums: string[];
+export declare const allStations: Station[];
+export declare const stationsById: Map<string, Station>;
+export declare const qualityMap: Map<string, StationQuality>;
+export declare function qualityFilter(station: Station): boolean;
+export declare const stations: Station[];
+//#endregion
+//#region src/routes.d.ts
+export declare function stationRouteBySlug(kind: "tide" | "current", slug: string): StationRoute | undefined;
+export declare function stationRoutes(kind: "tide" | "current"): StationRoute[];
+//#endregion
+//#region src/search/index.d.ts
+export type Position = Latitude & Longitude;
+type Latitude = {
+  latitude: number;
+} | {
+  lat: number;
+};
+type Longitude = {
+  longitude: number;
+} | {
+  lon: number;
+} | {
+  lng: number;
+};
+export type Filter = (station: Station) => boolean;
+export type NearestOptions = Position & {
+  maxDistance?: number;
+  /** Include all stations, not just quality-filtered ones. */
+  includeAll?: boolean;
+  filter?: Filter;
+};
+export type NearOptions = NearestOptions & {
+  maxResults?: number;
+};
+export type BboxOptions = {
+  /** Include all stations, not just quality-filtered ones. */
+  includeAll?: boolean;
+  filter?: Filter;
+};
+export type TextSearchOptions = {
+  /** Include all stations, not just quality-filtered ones. */
+  includeAll?: boolean;
+  filter?: Filter;
+  maxResults?: number;
+};
+/**
+ * A tuple of a station and its distance from a given point, in kilometers.
+ */
+export type StationWithDistance = [Station, number];
+/**
+ * Find stations near a given position.
+ */
+export declare function near({ maxDistance, maxResults, includeAll, filter, ...position }: NearOptions): StationWithDistance[];
+/**
+ * Find the single nearest station to a given position.
+ */
+export declare function nearest(options: NearestOptions): StationWithDistance | null;
+/**
+ * Find stations within a bounding box.
+ */
+export declare function bbox([minLon, minLat, maxLon, maxLat]: [number, number, number, number], { includeAll, filter }?: BboxOptions): Station[];
+export declare function positionToPoint(options: Position): [number, number];
+/**
+ * Search for stations by text across name, region, country, and continent.
+ * Supports fuzzy matching and prefix search.
+ */
+export declare function search(query: string, { includeAll, filter, maxResults }?: TextSearchOptions): Station[];
+//#endregion
+//#region src/database/builder.d.ts
+/**
+ * Serialize stations into the FlatBuffers database format
+ * (schemas/database.fbs). Stations are sorted by id — the vector key — so
+ * readers can binary-search the buffer.
+ *
+ * Build order matters and the schema cannot express it: FlatBuffers writes back
+ * to front, so the prediction data (constituents and datums vectors) is written
+ * first for every station, landing together at the tail of the file, and the
+ * station tables are written together after, landing at the head. A naive
+ * per-station loop would interleave ~100 bytes of identity with ~1,300 bytes of
+ * constituents, making an identity scan over a memory-mapped file fault in
+ * every page. test/database.test.ts asserts the layout.
+ */
+export declare function buildDatabase(stations: StationInput[], { version, routes }?: {
+  version?: string;
+  routes?: DatabaseRoutes;
+}): Uint8Array;
+//#endregion
+export type { AstronomicalBounds, Constituent, CurrentData, DatabaseRoutes, HarmonicConstituent, Station, StationData, StationInput, StationMeta, StationMetaKey, StationQuality, StationRoute, StationRouteInput, TideDerivedCurrentData };
+//# sourceMappingURL=index.d.ts.map

package/dist/worker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/attribution.ts","../../src/types.ts","../../src/stations.ts","../../src/routes.ts","../../src/search/index.ts","../../src/database/builder.ts"],"mappings":";;;;;qBAIa;;qBAIA;;wBAiCG,cAAc;;;;;;;;;;wBAad,eACd,gCACA;EAAW;EAAc;;;;UCxDV;EACf;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA;;UAGe;EACf;EACA;EACA;;UAGe;EACf;EACA;EACA;;UAGe;EACf,MAAM;EACN,SAAS;;UAGM;EAEf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EAGA;EACA;EACA;EACA;EAGA;IACE;IACA;IACA;IACA;;EAIF;IACE;IACA;IACA;IACA;;EAIF,uBAAuB;EAGvB;IACE;IACA;MAAU;MAAc;MAAa;;IACrC;MAAQ;MAAc;;;EAGxB,QAAQ;EAIR;EAGA;EAGA;IACE;IACA;;EAIF;;UAMe;EACf;EACA;EACA;;UAGe;;EAEf;EACA;;EAEA;;EAEA;EACA;EACA,UAAU;;EAEV;IACE;IACA;IACA;IACA;IACA;IACA;IACA;;;;;;;;KASQ;EACV;EACA;EACA,UAAU;EACV,UAAU;IACR,QAAQ;UAIK;;EAEf;EACA;EACA;;EAEA;IACE;IACA;IACA;IACA;IACA;IACA;;;EAGF;;EAEA;;EAEA;;;UAIe;;EAEf;;EAEA;;UAGe,gBAAgB;EAC/B;EACA;EACA;EACA,UAAU;EACV,UAAU;;;;;;;;EAQV,sBAAsB;;;;;EAKtB;;KAMU;KAkBA;EAAgB;IAAe,KAAK,aAAa;;;;qBChLhD;qBA+SA,aAAa;qBAOb,cAAY,YAAA;qBAEZ,YAAU,YAAA;wBAIP,cAAc,SAAS;qBAI1B,UAAU;;;wBClVP,mBACd,0BACA,eACC;wBAkBa,cAAc,2BAA2B;;;YChC7C,WAAW,WAAW;KAC7B;EAAa;;EAAuB;;KACpC;EAAc;;EAAwB;;EAAkB;;YAEjD,UAAU,SAAS;YAEnB,iBAAiB;EAC3B;;EAEA;EACA,SAAS;;YAGC,cAAc;EACxB;;YAGU;;EAEV;EACA,SAAS;;YAGC;;EAEV;EACA,SAAS;EACT;;;;;YAMU,uBAAuB;;;;wBAgCnB,OACd,aACA,YACA,YACA,WACG,YACF,cAAc;;;;wBAqBD,QAAQ,SAAS,iBAAiB;;;;wBAQlC,MACb,QAAQ,QAAQ,QAAQ,6CACvB,YAAoB,WAAU,cAC/B;wBAOa,gBAAgB,SAAS;;;;;wBAezB,OACd,iBACE,YAAY,QAAQ,eAAmB,oBACxC;;;;;;;;;;;;;;;;wBC9Fa,cACd,UAAU,kBAER,SACA;EACG;EAAkB,SAAS;IAC/B"}