@oceanmetrics/engine 0.0.0-stage → 0.1.0

package/src/erddap.ts

@@ -0,0 +1,271 @@
+// ERDDAP griddap client. no proxy of ours in the path: the browser talks to the ERDDAP server.
+//
+// URL shape (griddap): {base}/griddap/{dataset}.{fmt}?{var}[(t0):1:(t1)][(lat0):1:(lat1)][(lon0):1:(lon1)]
+// each constraint's square brackets are percent-encoded (%5B / %5D); the rest of the query is left
+// literal, because ERDDAP will not accept a fully encoded query string. constraint values go in the
+// axis's own direction (latitude descends on the CRW grid, so [(22.4):1:(18.8)]). a 4-D grid
+// (time, depth, latitude, longitude) gets one more constraint, a single depth level, after time.
+
+import { fetchRetry, type RetryOpts } from './fetchRetry.js'
+
+export type Format = 'parquet' | 'parquetWMeta' | 'csvp' | 'jsonp'
+/** the two Parquet rungs are handled identically once the bytes are in hand. */
+export const isParquet = (f: Format) => f === 'parquet' || f === 'parquetWMeta'
+
+export interface ErddapMeta { version?: string; cors?: boolean; formats?: string[] }
+export interface Collection { erddap: ErddapMeta }
+
+export interface GriddapSpec {
+  base          : string
+  datasetId     : string
+  variable      : string
+  time          : [string, string]
+  lat           : [number, number]  // [min, max], any order; reordered per latDescending
+  lon           : [number, number]
+  latDescending?: boolean
+  /** a depth axis between time and latitude (CMEMS): the single level to slice, e.g. 0.494 (surface) */
+  depth        ?: number
+  format        ?: Format
+  callback      ?: string           // jsonp only
+}
+
+const enc = (s: string) => s.replace(/\[/g, '%5B').replace(/\]/g, '%5D')
+const stripSlash = (s: string) => s.replace(/\/+$/, '')
+/** one axis constraint, `[(lo):1:(hi)]` with the brackets encoded. */
+export function constraint(lo: string | number, hi: string | number, stride = 1): string {
+  return enc(`[(${lo}):${stride}:(${hi})]`)
+}
+/** an ISO instant at 12:00Z for a Date or a yyyy-mm-dd string (ERDDAP daily grids sit at noon). */
+export function noonZ(d: Date | string): string {
+  const iso = typeof d === 'string' ? d.slice(0, 10) : d.toISOString().slice(0, 10)
+  return `${iso}T12:00:00Z`
+}
+
+const EXT: Record<Format, string> = {
+  parquet: '.parquet', parquetWMeta: '.parquetWMeta', csvp: '.csvp', jsonp: '.json',
+}
+
+/** the griddap request URL for one lobe. */
+export function griddapUrl(s: GriddapSpec): string {
+  const fmt  = s.format ?? 'parquet'
+  const desc = s.latDescending ?? true
+  const [y0, y1] = [Math.min(...s.lat), Math.max(...s.lat)]
+  const [x0, x1] = [Math.min(...s.lon), Math.max(...s.lon)]
+  const q =
+    s.variable +
+    constraint(s.time[0], s.time[1]) +
+    (s.depth != null && Number.isFinite(s.depth) ? constraint(s.depth, s.depth) : '') +
+    (desc ? constraint(y1, y0) : constraint(y0, y1)) +
+    constraint(x0, x1)
+  const tail = fmt === 'jsonp' ? `&.jsonp=${s.callback ?? 'erddapCb'}` : ''
+  return `${stripSlash(s.base)}/griddap/${s.datasetId}${EXT[fmt]}?${q}${tail}`
+}
+
+/**
+ * the griddap URL for ONE time step (`[(t):1:(t)]`), for the map when the statistics come from the
+ * precomputed file: the same axis order, longitude range and depth as griddapUrl(), but a single step
+ * (`at` is the ISO instant of that step, e.g. the dataset's last time).
+ */
+export function griddapSliceUrl(s: Omit<GriddapSpec, 'time'> & { at: string }): string {
+  const { at, ...rest } = s
+  return griddapUrl({ ...rest, time: [at, at] })
+}
+
+/** one URL per polygon lobe (bbox = [lonMin, latMin, lonMax, latMax]). */
+export function griddapUrls(s: Omit<GriddapSpec, 'lat' | 'lon'>, bboxes: Array<[number, number, number, number]>): string[] {
+  return bboxes.map((b) => griddapUrl({ ...s, lon: [b[0], b[2]], lat: [b[1], b[3]] }))
+}
+
+// ── tabledap ──────────────────────────────────────────────────────────────────
+// URL shape: {base}/tabledap/{dataset}.{fmt}?{col},{col},…&{col}{op}{value}&…
+// the column list is comma-separated and ERDDAP wants the commas percent-encoded (%2C); each
+// constraint's operator is encoded too (%3E= / %3C= / %3D), and the values are left literal, which
+// is what an ERDDAP 2.30 server accepts (verified against erddap.calcofi.io).
+
+export type TableOp = '>=' | '<=' | '>' | '<' | '=' | '!=' | '=~'
+export interface TableConstraint { column: string; op: TableOp; value: string | number }
+export interface TabledapSpec {
+  base       : string
+  datasetId  : string
+  columns    : string[]
+  constraints?: TableConstraint[]
+  format    ?: Format
+  callback  ?: string
+  /** extra server-side functions, e.g. `distinct()` or `orderByMax("time")`, appended literally. */
+  functions ?: string[]
+}
+
+// only the comparison characters are encoded; `=` stays literal, as ERDDAP's own example URLs do
+const OPS: Record<TableOp, string> = {
+  '>=': '%3E=', '<=': '%3C=', '>': '%3E', '<': '%3C', '=': '=', '!=': '!=', '=~': '=~',
+}
+/** one tabledap constraint, `column%3E=value`. */
+export function tableConstraint(c: TableConstraint): string {
+  return `${c.column}${OPS[c.op] ?? c.op}${c.value}`
+}
+
+/** the tabledap request URL: the encoded column list, then one `&constraint` each. */
+export function tabledapUrl(s: TabledapSpec): string {
+  const fmt = s.format ?? 'parquetWMeta'
+  const q = [
+    s.columns.join('%2C'),
+    ...(s.constraints ?? []).map(tableConstraint),
+    ...(s.functions ?? []),
+  ]
+  const tail = fmt === 'jsonp' ? `&.jsonp=${s.callback ?? 'erddapCb'}` : ''
+  return `${stripSlash(s.base)}/tabledap/${s.datasetId}${EXT[fmt]}?${q.join('&')}${tail}`
+}
+
+/**
+ * The constraints for one place lobe and one time window: a bbox and a half-open-ish time range,
+ * plus the long-format row filter when the dataset keeps its variables in a `measurement_type`
+ * column (`erddap-places:long_format` in the STAC Collection).
+ */
+export function tabledapPlaceConstraints(o: {
+  bbox: [number, number, number, number]   // [lonMin, latMin, lonMax, latMax]
+  from: string                              // yyyy-mm-dd or an ISO instant
+  to  : string
+  typeColumn?: string
+  typeValue ?: string
+}): TableConstraint[] {
+  const iso = (d: string, end = false) => (d.length > 10 ? d : `${d}T${end ? '23:59:59' : '00:00:00'}Z`)
+  const cs: TableConstraint[] = [
+    { column: 'time',      op: '>=', value: iso(o.from) },
+    { column: 'time',      op: '<=', value: iso(o.to, true) },
+    { column: 'longitude', op: '>=', value: o.bbox[0] },
+    { column: 'longitude', op: '<=', value: o.bbox[2] },
+    { column: 'latitude',  op: '>=', value: o.bbox[1] },
+    { column: 'latitude',  op: '<=', value: o.bbox[3] },
+  ]
+  // a string value is quoted, and the quotes percent-encoded (%22), as ERDDAP requires
+  if (o.typeColumn && o.typeValue) cs.push({ column: o.typeColumn, op: '=', value: `%22${o.typeValue}%22` })
+  return cs
+}
+
+// ── axis vectors ──────────────────────────────────────────────────────────────
+/**
+ * per-attempt timeout of an axis request. small, but a busy server is slow whatever the size: PacIOOS answered
+ * `dhw_5km` latitude requests in 13–19 s on 2026-10-20, past the old 15 s, so a live run failed while the server
+ * was up ("did not answer (no response within 15 s, 2 tries)").
+ */
+export const AXIS_TIMEOUT_MS = 45_000
+/** per-attempt timeout of the map's one-step slice: as small, and as slow on a busy server (PacIOOS took 27–31 s for 45 days of one pixel) */
+export const SLICE_TIMEOUT_MS = 45_000
+
+/**
+ * `dataset.json?latitude[(min):1:(max)]` -> the axis values, in the server's own order. `AXIS_TIMEOUT_MS` per
+ * attempt and one retry by default (`retry` overrides them; the precompute waits longer).
+ */
+export async function fetchAxis(base: string, datasetId: string, axis: string, min: number, max: number, descending = false,
+                                signal?: AbortSignal, retry: Omit<RetryOpts, 'signal'> = {}): Promise<number[]> {
+  const c   = descending ? constraint(max, min) : constraint(min, max)
+  const url = `${stripSlash(base)}/griddap/${datasetId}.json?${axis}${c}`
+  return fetchRetry(url, { timeoutMs: AXIS_TIMEOUT_MS, ...retry, signal }, async (res) => {
+    if (!res.ok) throw new Error(`${url}: ${res.status} ${res.statusText}`)
+    const j: { table: { columnNames: string[]; rows: number[][] } } = await res.json()
+    return j.table.rows.map((r) => Number(r[0]))
+  })
+}
+
+// ── format rung ───────────────────────────────────────────────────────────────
+/**
+ * Best format this server can serve us: Parquet -> CSV (`.csvp`) -> JSONP.
+ * CORS off means only JSONP (a `<script>` tag is not subject to CORS).
+ */
+export function pickFormat(collection: Collection): Format {
+  const e    = collection?.erddap ?? {}
+  const fmts = (e.formats ?? []).map((f) => f.replace(/^\./, '').toLowerCase())
+  if (e.cors === false) return 'jsonp'
+  if (fmts.length === 0) return 'parquet'
+  // parquetWMeta is plain Parquet with ERDDAP's metadata in the file footer: prefer it when offered
+  if (fmts.includes('parquetwmeta')) return 'parquetWMeta'
+  if (fmts.includes('parquet')) return 'parquet'
+  if (fmts.includes('csvp') || fmts.includes('csv')) return 'csvp'
+  return 'jsonp'
+}
+
+// ── fetch ─────────────────────────────────────────────────────────────────────
+export interface Slab {
+  url    : string
+  format : Format
+  ms     : number
+  bytes ?: number
+  buffer?: Uint8Array                    // parquet
+  rows  ?: Record<string, unknown>[]     // csvp / jsonp
+  text  ?: string                        // csvp, raw
+}
+
+/** load a `.json?...&.jsonp=cb` URL through a <script> tag (browser only; no CORS needed). */
+export function fetchJsonp(url: string, cbName: string, timeoutMs = 120_000, signal?: AbortSignal): Promise<any> {
+  return new Promise((resolve, reject) => {
+    if (typeof document === 'undefined') return reject(new Error('jsonp needs a browser document'))
+    const done = (fn: () => void) => { clearTimeout(timer); delete (window as any)[cbName]; script.remove(); fn() }
+    const timer = setTimeout(() => done(() => reject(new Error(`jsonp timeout: ${url}`))), timeoutMs)
+    ;(window as any)[cbName] = (data: any) => done(() => resolve(data))
+    // a <script> tag cannot be cancelled, but a superseded run must stop waiting on it
+    signal?.addEventListener('abort', () => done(() => reject(new DOMException('aborted', 'AbortError'))), { once: true })
+    const script  = document.createElement('script')
+    script.src    = url
+    script.onerror = () => done(() => reject(new Error(`jsonp failed: ${url}`)))
+    document.head.appendChild(script)
+  })
+}
+
+/** `{table:{columnNames, rows}}` -> array of objects. */
+export function tableToRows(t: { table: { columnNames: string[]; rows: unknown[][] } }): Record<string, unknown>[] {
+  const { columnNames, rows } = t.table
+  return rows.map((r) => Object.fromEntries(columnNames.map((c, i) => [c, r[i]])))
+}
+
+/** minimal CSV parse for `.csvp` (ERDDAP quotes with " and doubles inner quotes). */
+export function parseCsvp(text: string): Record<string, unknown>[] {
+  const lines = text.split('\n').filter((l) => l.length)
+  if (!lines.length) return []
+  const split = (l: string) => {
+    const out: string[] = []; let cur = '', q = false
+    for (let i = 0; i < l.length; i++) {
+      const ch = l[i]
+      if (q) { if (ch === '"') { if (l[i + 1] === '"') { cur += '"'; i++ } else q = false } else cur += ch }
+      else if (ch === '"') q = true
+      else if (ch === ',') { out.push(cur); cur = '' }
+      else if (ch !== '\r') cur += ch
+    }
+    out.push(cur); return out
+  }
+  const head = split(lines[0]).map((h) => h.replace(/\s*\(.*\)$/, '')) // strip the " (degree_C)" units suffix
+  return lines.slice(1).map((l) => {
+    const f = split(l)
+    return Object.fromEntries(head.map((h, i) => {
+      const v = f[i]
+      const n = v === '' || v === 'NaN' ? null : Number(v)
+      return [h, n === null || Number.isNaN(n) ? v : n]
+    }))
+  })
+}
+
+/**
+ * fetch one slab in the given format. Parquet comes back as bytes for `registerFileBuffer`. `retry`
+ * sets the per-attempt timeout and the tries (fetchRetry: 20 s and one retry unless the caller says
+ * otherwise: a whole live window can take longer than the one-step map slice).
+ */
+export async function fetchSlab(url: string, format: Format = 'parquet', callback = 'erddapCb', signal?: AbortSignal,
+                                retry: Omit<RetryOpts, 'signal'> = {}): Promise<Slab> {
+  const t0 = (globalThis.performance ?? Date).now()
+  if (format === 'jsonp') {
+    const data = await fetchJsonp(url, callback, retry.timeoutMs ?? 120_000, signal)
+    return { url, format, ms: (globalThis.performance ?? Date).now() - t0, rows: tableToRows(data) }
+  }
+  return fetchRetry(url, { ...retry, signal }, async (res): Promise<Slab> => {
+    if (!res.ok) {
+      const msg = (await res.text().catch(() => '')).slice(0, 400)
+      throw new Error(`${res.status} ${res.statusText} from ERDDAP: ${msg}`)
+    }
+    if (format === 'csvp') {
+      const text = await res.text()
+      return { url, format, ms: (globalThis.performance ?? Date).now() - t0, bytes: text.length, text, rows: parseCsvp(text) }
+    }
+    // parquet and parquetWMeta alike: raw bytes for registerFileBuffer
+    const buffer = new Uint8Array(await res.arrayBuffer())
+    return { url, format, ms: (globalThis.performance ?? Date).now() - t0, bytes: buffer.byteLength, buffer }
+  })
+}

package/src/extent.ts

@@ -0,0 +1,172 @@
+// live time extent of an ERDDAP grid dataset, from `<base>/erddap/info/<datasetID>/index.json`.
+//
+// the STAC `cube:dimensions.time.extent` end is null (or stale) for near-real-time grids, and every
+// dataset ends at a different instant: AOML Seascapes is an 8-day product months behind, CRW is a
+// couple of days behind. asking the server means the default window always lands inside the data,
+// instead of 404ing with `"Start" is greater than the axis maximum=…`.
+//
+// the parsing and clamping here are pure functions (see extent.test.ts); only fetchTimeExtent()
+// touches the network.
+import { fetchRetry, type RetryOpts } from './fetchRetry.js'
+
+export interface TimeExtent {
+  start     : string          // ISO instant of the first time step, e.g. 2002-08-29T12:00:00Z
+  end       : string          // ISO instant of the last time step
+  stepDays ?: number          // average spacing in days (1 for daily, 8 for the 8-day product)
+  stepLabel?: string          // 'daily', '8-day', 'monthly', …
+  nValues  ?: number
+}
+
+export interface InfoTable { table: { columnNames: string[]; rows: unknown[][] } }
+
+const isoZ = (secs: number) => new Date(secs * 1000).toISOString().replace(/\.\d{3}Z$/, 'Z')
+/** the UTC calendar day (yyyy-mm-dd) of an ISO instant. */
+export const day = (iso: string) => iso.slice(0, 10)
+const dayMs = 864e5
+/** yyyy-mm-dd, n days after `d` (n may be negative). */
+export function addDays(d: string, n: number): string {
+  return new Date(Date.parse(`${day(d)}T00:00:00Z`) + n * dayMs).toISOString().slice(0, 10)
+}
+/** whole days from `a` to `b`, by UTC calendar day. */
+export const daysBetween = (a: string, b: string) =>
+  Math.round((Date.parse(`${day(b)}T00:00:00Z`) - Date.parse(`${day(a)}T00:00:00Z`)) / dayMs)
+
+/** `8 days 0h 7m 57s` / `1 day` / `12h` -> days. */
+export function parseSpacing(s: string): number | undefined {
+  const m = s.match(/([\d.]+)\s*days?/i)
+  let days = m ? Number(m[1]) : 0
+  const h = s.match(/(\d+)\s*h\b/), mn = s.match(/(\d+)\s*m\b/), sec = s.match(/(\d+)\s*s\b/)
+  days += (h ? Number(h[1]) / 24 : 0) + (mn ? Number(mn[1]) / 1440 : 0) + (sec ? Number(sec[1]) / 86400 : 0)
+  return days > 0 ? days : undefined
+}
+
+/** a human label for a time step in days. */
+export function stepLabel(days: number | undefined): string | undefined {
+  if (!days || !Number.isFinite(days)) return undefined
+  const d = Math.round(days)
+  if (days < 1)  return 'sub-daily'
+  if (d === 1)   return 'daily'
+  if (d === 7)   return 'weekly'
+  if (d >= 28 && d <= 31) return 'monthly'
+  if (d >= 360 && d <= 366) return 'annual'
+  return `${d}-day`
+}
+
+/** the ERDDAP `info/<id>/index.json` table -> the dataset's live time extent. */
+export function parseInfoExtent(info: InfoTable, axis = 'time'): TimeExtent | null {
+  const rows = (info?.table?.rows ?? []).map((r) => r.map((c) => (c == null ? '' : String(c))))
+  const find = (type: string, varName: string, attr: string) =>
+    rows.find((r) => r[0] === type && r[1] === varName && r[2] === attr)?.[4]
+
+  let start: string | undefined, end: string | undefined
+  const range = find('attribute', axis, 'actual_range')
+  if (range) {
+    const [a, b] = range.split(',').map((x) => Number(x.trim()))
+    if (Number.isFinite(a) && Number.isFinite(b)) {
+      const [lo, hi] = a <= b ? [a, b] : [b, a]
+      start = isoZ(lo); end = isoZ(hi)
+    }
+  }
+  // fall back to the NC_GLOBAL coverage attributes (already ISO strings)
+  start ??= find('attribute', 'NC_GLOBAL', 'time_coverage_start')
+  end   ??= find('attribute', 'NC_GLOBAL', 'time_coverage_end')
+  if (!start || !end) return null
+
+  const dim   = rows.find((r) => r[0] === 'dimension' && r[1] === axis)?.[4] ?? ''
+  const step  = parseSpacing((dim.match(/averageSpacing=([^,]+)/)?.[1] ?? '').trim())
+  const nVals = Number(dim.match(/nValues=(\d+)/)?.[1])
+  return {
+    start, end,
+    stepDays : step,
+    stepLabel: stepLabel(step),
+    nValues  : Number.isFinite(nVals) ? nVals : undefined,
+  }
+}
+
+// ── the date window ───────────────────────────────────────────────────────────
+export interface Window { start: string; end: string }   // yyyy-mm-dd, UTC calendar days
+export interface ClampResult extends Window { snapped: boolean; reason?: string }
+
+export interface WindowOpts {
+  days    ?: number   // the default span for a daily dataset
+  minSteps?: number   // at least this many time steps for a coarser dataset
+  maxDays ?: number   // never span more than this
+}
+
+/** how many days a default window should span for a dataset of this step. */
+export function spanDays(ext: TimeExtent | null, o: WindowOpts = {}): number {
+  const { days = 30, minSteps = 8, maxDays = 90 } = o
+  const step = ext?.stepDays ?? 1
+  return Math.min(maxDays, Math.max(days, step > 1 ? Math.ceil(minSteps * step) : days))
+}
+
+/** the last `days` (or `minSteps` steps) ending at the dataset's last time step. */
+export function defaultWindow(ext: TimeExtent | null, o: WindowOpts = {}): Window {
+  const end = ext ? day(ext.end) : addDays(new Date().toISOString(), -2)
+  const span = spanDays(ext, o)
+  let start = addDays(end, -(span - 1))
+  if (ext && daysBetween(ext.start, start) < 0) start = day(ext.start)
+  return { start, end }
+}
+
+/**
+ * Keep a user's window inside the dataset's extent.
+ * A start after the last time step (or an end before the first) snaps the whole window back to the
+ * default one, with a `reason` for the status line, so nothing out-of-range is ever requested.
+ */
+export function clampWindow(w: Window, ext: TimeExtent | null, o: WindowOpts = {}): ClampResult {
+  if (!ext) return { ...w, snapped: false }
+  const lo = day(ext.start), hi = day(ext.end)
+  if (daysBetween(w.start, hi) < 0 || daysBetween(lo, w.end) < 0) {
+    const d = defaultWindow(ext, o)
+    const why = daysBetween(w.start, hi) < 0
+      ? `the requested window starts after this dataset ends (${hi})`
+      : `the requested window ends before this dataset starts (${lo})`
+    return { ...d, snapped: true, reason: `${why}; showing ${d.start} to ${d.end} instead` }
+  }
+  const start = daysBetween(lo, w.start) < 0 ? lo : w.start
+  const end   = daysBetween(w.end, hi)   < 0 ? hi : w.end
+  const snapped = start !== w.start || end !== w.end
+  return {
+    start, end, snapped,
+    reason: snapped ? `clamped to the dataset extent (${lo} to ${hi})` : undefined,
+  }
+}
+
+/**
+ * The ISO instant to put in a griddap time constraint for a calendar day. The extent's own endpoints
+ * are used verbatim, so a request never overshoots an axis whose steps are not at 12:00Z (MUR sits
+ * at 09:00Z); any interior day falls back to noon.
+ */
+export function timeInstant(date: string, ext: TimeExtent | null, noon: (d: string) => string): string {
+  if (ext) {
+    if (day(date) === day(ext.end))   return ext.end
+    if (day(date) === day(ext.start)) return ext.start
+  }
+  return noon(date)
+}
+
+// ── fetch ─────────────────────────────────────────────────────────────────────
+const cache = new Map<string, Promise<TimeExtent | null>>()
+const stripSlash = (s: string) => s.replace(/\/+$/, '')
+
+/**
+ * `<base>/info/<datasetID>/index.json` -> the live extent, memoised per base+dataset. The fetch is
+ * shared by every caller, so no caller's signal is passed to it (a superseded run must not cancel it
+ * for the next one); fetchRetry bounds it instead (`INFO_TIMEOUT_MS` per attempt, one retry). null on failure,
+ * and a failure is forgotten, so the next call asks again.
+ */
+/** per-attempt timeout of the info request (PacIOOS took 4–9 s on 2026-10-20, and 20 s on 2026-10-09) */
+export const INFO_TIMEOUT_MS = 30_000
+
+export function fetchTimeExtent(base: string, datasetId: string, axis = 'time', retry: Omit<RetryOpts, 'signal'> = {}): Promise<TimeExtent | null> {
+  const url = `${stripSlash(base)}/info/${datasetId}/index.json`
+  const hit = cache.get(url)
+  if (hit) return hit
+  const p = fetchRetry(url, { timeoutMs: INFO_TIMEOUT_MS, ...retry }, async (res) => {
+    if (!res.ok) throw new Error(`${url}: ${res.status} ${res.statusText}`)
+    return parseInfoExtent(await res.json(), axis)
+  }).catch((e) => { cache.delete(url); console.warn('extent:', e); return null })
+  cache.set(url, p)
+  return p
+}

package/src/fetchRetry.ts

@@ -0,0 +1,71 @@
+// fetch with a per-attempt timeout and a retry, for requests to a server that is not ours (ERDDAP).
+//
+// a browser fetch has no timeout of its own: a host that accepts the connection and then stalls holds
+// a run for minutes, and a dropped connection surfaces as the bare "Failed to fetch" (PacIOOS, 2026-10-09:
+// a 20 s info request, then a failed map slice). here every attempt gives up after `timeoutMs`, a network
+// error, a timeout or a 5xx is retried after `backoffMs`, and the last failure is an ErddapUnreachable
+// whose message names the host and what happened, so the toast can say something a person can act on.
+// a 4xx is the server's answer (a bad constraint) and is not retried; the caller's own abort (a newer
+// run) passes straight through as the AbortError it is.
+
+export interface RetryOpts {
+  signal   ?: AbortSignal
+  /** give up on one attempt after this long (ms) */
+  timeoutMs?: number
+  /** tries in all (1 = no retry) */
+  attempts ?: number
+  /** pause before each retry (ms) */
+  backoffMs?: number
+  /** for tests */
+  fetchFn  ?: typeof fetch
+  wait     ?: (ms: number) => Promise<unknown>
+}
+
+/** the last failure after every attempt: the host did not answer, or answered with a 5xx. */
+export class ErddapUnreachable extends Error {
+  constructor(readonly host: string, readonly reason: string, readonly attempts: number, readonly url: string) {
+    super(`${host} did not answer (${reason}${attempts > 1 ? `, ${attempts} tries` : ''})`)
+    this.name = 'ErddapUnreachable'
+  }
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+export const hostOf = (url: string) => { try { return new URL(url).host } catch { return url } }
+
+/**
+ * fetch `url` and `read` the response (the default returns it unread), inside the same timeout: a
+ * stall while the body downloads is a timeout too. A network error (a TypeError, the browser's
+ * "Failed to fetch"), a timeout or a 5xx is retried; a 4xx goes to `read` (which may throw the
+ * server's message), and whatever `read` throws for its own reasons is not retried.
+ */
+export async function fetchRetry<T = Response>(url: string, o: RetryOpts = {},
+                                               read: (res: Response) => Promise<T> = async (r) => r as T): Promise<T> {
+  const { signal, timeoutMs = 20_000, attempts = 2, backoffMs = 1_500, fetchFn = fetch, wait = sleep } = o
+  let reason = ''
+  for (let i = 0; i < attempts; i++) {
+    if (i > 0) await wait(backoffMs)
+    if (signal?.aborted) throw signal.reason ?? new DOMException('aborted', 'AbortError')
+    const timer = AbortSignal.timeout(timeoutMs)
+    const sig = signal ? AbortSignal.any([signal, timer]) : timer
+    try {
+      const res = await fetchFn(url, { signal: sig })
+      if (res.status >= 500) { reason = `HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ''}`; continue }
+      return await read(res)
+    } catch (e) {
+      if (signal?.aborted) throw e                                    // superseded: not a failure
+      if (timer.aborted) reason = `no response within ${Math.round(timeoutMs / 1000)} s`
+      else if (e instanceof TypeError) reason = `network error: ${e.message}`
+      else throw e                                                    // read()'s own error, e.g. a 4xx message
+    }
+  }
+  throw new ErddapUnreachable(hostOf(url), reason, attempts, url)
+}
+
+/**
+ * The toast's words when the live map step fails after the precomputed statistics are on screen:
+ * which host, what happened, and that the statistics are not affected.
+ */
+export function mapFailMessage(e: unknown): string {
+  const why = e instanceof Error ? e.message : String(e)
+  return `The map's latest time step did not load: ${why}. The precomputed statistics are unaffected; retry the map from the Time strip.`
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// @oceanmetrics/engine: the browser engine of Ocean Metrics. the mask, the lobes, the ERDDAP requests, the SQL templates
+// shared with the Python engine (om_extract), DuckDB-WASM as the statistics engine, the chunked live preview and the
+// map's grid slice. see the README for what moved from where.
+export { axisEdges, countVertices, gridMask, pointMask, polygonParts, reduceRing, reduceRings } from './mask.js'
+export type { GeoInput, MaskCell, MaskMethod, MaskOptions, MaskPoint, MaskResult, PointMaskResult } from './mask.js'
+export { polygonCoordinates, wkbToGeoJSON } from './wkb.js'
+export { placeLobes } from './lobes.js'
+export type { Lobe, LobePlace } from './lobes.js'
+export {
+  AXIS_TIMEOUT_MS, SLICE_TIMEOUT_MS, constraint, fetchAxis, fetchJsonp, fetchSlab, griddapSliceUrl, griddapUrl, griddapUrls,
+  isParquet, noonZ, parseCsvp, pickFormat, tableConstraint, tableToRows, tabledapPlaceConstraints, tabledapUrl,
+} from './erddap.js'
+export type { Collection, ErddapMeta, Format, GriddapSpec, Slab, TableConstraint, TableOp, TabledapSpec } from './erddap.js'
+export {
+  INFO_TIMEOUT_MS, addDays, clampWindow, day, daysBetween, defaultWindow, fetchTimeExtent, parseInfoExtent, parseSpacing,
+  spanDays, stepLabel, timeInstant,
+} from './extent.js'
+export type { ClampResult, InfoTable, TimeExtent, Window, WindowOpts } from './extent.js'
+export { ErddapUnreachable, fetchRetry, hostOf, mapFailMessage } from './fetchRetry.js'
+export type { RetryOpts } from './fetchRetry.js'
+export { axisSpacing, cellPoints, cellSquares, indexBounds, normalizeLon, pickCenter, placeMapBounds } from './cells.js'
+export type { CellPoints, CellProps, CellSquares, CellSquaresOptions, LonCenter, ValueCell } from './cells.js'
+export {
+  isCategorical, lobeLonSpan, resolveDataset, statsTemplate, toDataset, toDatasetLon, toLongFormat, valueExpr, valueLabel,
+} from './dataset.js'
+export type { CubeVariable, Dataset, LongFormat } from './dataset.js'
+export { MAX_CHUNK_DAYS, MAX_REQUEST_VALUES, chunkDaysFor, chunks, window } from './chunks.js'
+export type { ChunkLimits } from './chunks.js'
+export { lit, render, template, templateNames } from './sql.js'
+export type { Param, Params, TemplateName } from './sql.js'
+export { TEMPLATES } from './sqlTemplates.js'
+export { Engine, connectBrowser, toRows } from './engine.js'
+export type { Duck, DuckConnLike, DuckDbLike, EngineEvent, Row } from './engine.js'
+export { isoDay, lobeAxes, lobeMasks, previewWindow, runPreview, sliceSource } from './preview.js'
+export type {
+  LobeAxes, PreviewChunk, PreviewDataset, PreviewOptions, PreviewResult, SliceCell, SliceSource, SliceSourceOptions,
+} from './preview.js'

package/src/lobes.ts

@@ -0,0 +1,66 @@
+// the lobe split of a place: one griddap request per lobe. moved from erddap-places `app/src/lib/gazetteer.ts`
+// (`placeLobes`, `Lobe`, `partBbox`); the logic is unchanged (the Python twin `om_extract.geom.place_lobes` and the
+// parity fixtures in extract/tests/fixtures/mask were generated from it). `LobePlace` is the slice of the gazetteer's
+// `Place` the split reads.
+import { polygonCoordinates } from './wkb.js'
+import type { Feature, FeatureCollection, Geometry, Polygon } from 'geojson'
+
+/** what placeLobes() reads of a place: its id and its (Multi)Polygon, already split at ±180 */
+export interface LobePlace { place_id: string; geometry: Geometry }
+// the name the moved function text uses (kept, so its text stays byte-identical to the original)
+type Place = LobePlace
+
+/** one griddap request's worth of a place: its own bbox and the polygons inside it. */
+export interface Lobe {
+  id      : string
+  bbox    : [number, number, number, number]
+  geojson : FeatureCollection
+  nParts  : number
+}
+
+const partBbox = (rings: number[][][]): [number, number, number, number] => {
+  let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity
+  for (const [x, y] of rings[0]) {
+    if (x < x0) x0 = x; if (x > x1) x1 = x
+    if (y < y0) y0 = y; if (y > y1) y1 = y
+  }
+  return [x0, y0, x1, y1]
+}
+
+/**
+ * Split a place into the lobes that each get one griddap request.
+ *
+ * Parts are grouped by side of the antimeridian, and only when the place actually spans it (a
+ * lon extent wider than 180°, as for PMNM): a place wholly on one side stays a single request
+ * covering all its parts. The polygon parts themselves are never modified — the gazetteer has
+ * already split them at ±180.
+ */
+export function placeLobes(place: Place): Lobe[] {
+  const parts = polygonCoordinates(place.geometry)
+  if (!parts.length) return []
+  const boxes = parts.map(partBbox)
+  const x0 = Math.min(...boxes.map((b) => b[0])), x1 = Math.max(...boxes.map((b) => b[2]))
+  const split = x1 - x0 > 180
+
+  const groups = new Map<string, number[]>()
+  boxes.forEach((b, i) => {
+    const g = !split ? 'all' : (b[0] + b[2]) / 2 < 0 ? 'W' : 'E'
+    ;(groups.get(g) ?? groups.set(g, []).get(g)!).push(i)
+  })
+
+  const lobes: Lobe[] = []
+  for (const [g, idx] of groups) {
+    const feats: Feature<Polygon>[] = idx.map((i) => ({
+      type: 'Feature', properties: { place_id: place.place_id },
+      geometry: { type: 'Polygon', coordinates: parts[i] },
+    }))
+    lobes.push({
+      id     : `${place.place_id}${g === 'all' ? '' : `:${g}`}`,
+      bbox   : [Math.min(...idx.map((i) => boxes[i][0])), Math.min(...idx.map((i) => boxes[i][1])),
+                Math.max(...idx.map((i) => boxes[i][2])), Math.max(...idx.map((i) => boxes[i][3]))],
+      geojson: { type: 'FeatureCollection', features: feats },
+      nParts : idx.length,
+    })
+  }
+  return lobes.sort((a, b) => a.bbox[0] - b.bbox[0])
+}