@oceanmetrics/engine 0.0.0-stage → 0.1.0

package/dist/erddap.js

@@ -0,0 +1,224 @@
+// 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 } from './fetchRetry.js';
+/** the two Parquet rungs are handled identically once the bytes are in hand. */
+export const isParquet = (f) => f === 'parquet' || f === 'parquetWMeta';
+const enc = (s) => s.replace(/\[/g, '%5B').replace(/\]/g, '%5D');
+const stripSlash = (s) => s.replace(/\/+$/, '');
+/** one axis constraint, `[(lo):1:(hi)]` with the brackets encoded. */
+export function constraint(lo, hi, stride = 1) {
+    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) {
+    const iso = typeof d === 'string' ? d.slice(0, 10) : d.toISOString().slice(0, 10);
+    return `${iso}T12:00:00Z`;
+}
+const EXT = {
+    parquet: '.parquet', parquetWMeta: '.parquetWMeta', csvp: '.csvp', jsonp: '.json',
+};
+/** the griddap request URL for one lobe. */
+export function griddapUrl(s) {
+    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) {
+    const { at, ...rest } = s;
+    return griddapUrl({ ...rest, time: [at, at] });
+}
+/** one URL per polygon lobe (bbox = [lonMin, latMin, lonMax, latMax]). */
+export function griddapUrls(s, bboxes) {
+    return bboxes.map((b) => griddapUrl({ ...s, lon: [b[0], b[2]], lat: [b[1], b[3]] }));
+}
+// only the comparison characters are encoded; `=` stays literal, as ERDDAP's own example URLs do
+const OPS = {
+    '>=': '%3E=', '<=': '%3C=', '>': '%3E', '<': '%3C', '=': '=', '!=': '!=', '=~': '=~',
+};
+/** one tabledap constraint, `column%3E=value`. */
+export function tableConstraint(c) {
+    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) {
+    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) {
+    const iso = (d, end = false) => (d.length > 10 ? d : `${d}T${end ? '23:59:59' : '00:00:00'}Z`);
+    const cs = [
+        { 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, datasetId, axis, min, max, descending = false, signal, retry = {}) {
+    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 = 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) {
+    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';
+}
+/** load a `.json?...&.jsonp=cb` URL through a <script> tag (browser only; no CORS needed). */
+export function fetchJsonp(url, cbName, timeoutMs = 120_000, signal) {
+    return new Promise((resolve, reject) => {
+        if (typeof document === 'undefined')
+            return reject(new Error('jsonp needs a browser document'));
+        const done = (fn) => { clearTimeout(timer); delete window[cbName]; script.remove(); fn(); };
+        const timer = setTimeout(() => done(() => reject(new Error(`jsonp timeout: ${url}`))), timeoutMs);
+        window[cbName] = (data) => 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) {
+    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) {
+    const lines = text.split('\n').filter((l) => l.length);
+    if (!lines.length)
+        return [];
+    const split = (l) => {
+        const out = [];
+        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, format = 'parquet', callback = 'erddapCb', signal, retry = {}) {
+    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) => {
+        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/dist/extent.d.ts

@@ -0,0 +1,64 @@
+import { type RetryOpts } from './fetchRetry.js';
+export interface TimeExtent {
+    start: string;
+    end: string;
+    stepDays?: number;
+    stepLabel?: string;
+    nValues?: number;
+}
+export interface InfoTable {
+    table: {
+        columnNames: string[];
+        rows: unknown[][];
+    };
+}
+/** the UTC calendar day (yyyy-mm-dd) of an ISO instant. */
+export declare const day: (iso: string) => string;
+/** yyyy-mm-dd, n days after `d` (n may be negative). */
+export declare function addDays(d: string, n: number): string;
+/** whole days from `a` to `b`, by UTC calendar day. */
+export declare const daysBetween: (a: string, b: string) => number;
+/** `8 days 0h 7m 57s` / `1 day` / `12h` -> days. */
+export declare function parseSpacing(s: string): number | undefined;
+/** a human label for a time step in days. */
+export declare function stepLabel(days: number | undefined): string | undefined;
+/** the ERDDAP `info/<id>/index.json` table -> the dataset's live time extent. */
+export declare function parseInfoExtent(info: InfoTable, axis?: string): TimeExtent | null;
+export interface Window {
+    start: string;
+    end: string;
+}
+export interface ClampResult extends Window {
+    snapped: boolean;
+    reason?: string;
+}
+export interface WindowOpts {
+    days?: number;
+    minSteps?: number;
+    maxDays?: number;
+}
+/** how many days a default window should span for a dataset of this step. */
+export declare function spanDays(ext: TimeExtent | null, o?: WindowOpts): number;
+/** the last `days` (or `minSteps` steps) ending at the dataset's last time step. */
+export declare function defaultWindow(ext: TimeExtent | null, o?: WindowOpts): Window;
+/**
+ * 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 declare function clampWindow(w: Window, ext: TimeExtent | null, o?: WindowOpts): ClampResult;
+/**
+ * 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 declare function timeInstant(date: string, ext: TimeExtent | null, noon: (d: string) => string): string;
+/**
+ * `<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 declare const INFO_TIMEOUT_MS = 30000;
+export declare function fetchTimeExtent(base: string, datasetId: string, axis?: string, retry?: Omit<RetryOpts, 'signal'>): Promise<TimeExtent | null>;

package/dist/extent.js

@@ -0,0 +1,151 @@
+// 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 } from './fetchRetry.js';
+const isoZ = (secs) => 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) => iso.slice(0, 10);
+const dayMs = 864e5;
+/** yyyy-mm-dd, n days after `d` (n may be negative). */
+export function addDays(d, n) {
+    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, b) => 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) {
+    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) {
+    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, axis = 'time') {
+    const rows = (info?.table?.rows ?? []).map((r) => r.map((c) => (c == null ? '' : String(c))));
+    const find = (type, varName, attr) => rows.find((r) => r[0] === type && r[1] === varName && r[2] === attr)?.[4];
+    let start, end;
+    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,
+    };
+}
+/** how many days a default window should span for a dataset of this step. */
+export function spanDays(ext, o = {}) {
+    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, o = {}) {
+    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, ext, o = {}) {
+    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, ext, noon) {
+    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();
+const stripSlash = (s) => 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, datasetId, axis = 'time', retry = {}) {
+    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/dist/fetchRetry.d.ts

@@ -0,0 +1,33 @@
+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 declare class ErddapUnreachable extends Error {
+    readonly host: string;
+    readonly reason: string;
+    readonly attempts: number;
+    readonly url: string;
+    constructor(host: string, reason: string, attempts: number, url: string);
+}
+export declare const hostOf: (url: string) => string;
+/**
+ * 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 declare function fetchRetry<T = Response>(url: string, o?: RetryOpts, read?: (res: Response) => Promise<T>): Promise<T>;
+/**
+ * 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 declare function mapFailMessage(e: unknown): string;

package/dist/fetchRetry.js

@@ -0,0 +1,76 @@
+// 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.
+/** the last failure after every attempt: the host did not answer, or answered with a 5xx. */
+export class ErddapUnreachable extends Error {
+    host;
+    reason;
+    attempts;
+    url;
+    constructor(host, reason, attempts, url) {
+        super(`${host} did not answer (${reason}${attempts > 1 ? `, ${attempts} tries` : ''})`);
+        this.host = host;
+        this.reason = reason;
+        this.attempts = attempts;
+        this.url = url;
+        this.name = 'ErddapUnreachable';
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const hostOf = (url) => { 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(url, o = {}, read = async (r) => r) {
+    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) {
+    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/dist/index.d.ts

@@ -0,0 +1,24 @@
+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/dist/index.js

@@ -0,0 +1,16 @@
+// @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 { polygonCoordinates, wkbToGeoJSON } from './wkb.js';
+export { placeLobes } 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 { INFO_TIMEOUT_MS, addDays, clampWindow, day, daysBetween, defaultWindow, fetchTimeExtent, parseInfoExtent, parseSpacing, spanDays, stepLabel, timeInstant, } from './extent.js';
+export { ErddapUnreachable, fetchRetry, hostOf, mapFailMessage } from './fetchRetry.js';
+export { axisSpacing, cellPoints, cellSquares, indexBounds, normalizeLon, pickCenter, placeMapBounds } from './cells.js';
+export { isCategorical, lobeLonSpan, resolveDataset, statsTemplate, toDataset, toDatasetLon, toLongFormat, valueExpr, valueLabel, } from './dataset.js';
+export { MAX_CHUNK_DAYS, MAX_REQUEST_VALUES, chunkDaysFor, chunks, window } from './chunks.js';
+export { lit, render, template, templateNames } from './sql.js';
+export { TEMPLATES } from './sqlTemplates.js';
+export { Engine, connectBrowser, toRows } from './engine.js';
+export { isoDay, lobeAxes, lobeMasks, previewWindow, runPreview, sliceSource } from './preview.js';

package/dist/lobes.d.ts

@@ -0,0 +1,24 @@
+import type { FeatureCollection, Geometry } 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;
+}
+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;
+}
+/**
+ * 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 declare function placeLobes(place: Place): Lobe[];
+export {};