mostlyright 1.1.3 → 1.2.0

package/dist/index.mjs

@@ -8,6 +8,7 @@ import * as weather from "@mostlyrightmd/weather";
 
 // src/research.ts
 import {
+  DataAvailabilityError,
   NotFoundError,
   STATION_BY_CODE,
   STATION_BY_ICAO,
@@ -38,6 +39,63 @@ import {
   parseGhcnhPsv,
   parseIemCsv
 } from "@mostlyrightmd/weather";
+
+// src/research.types.ts
+var KNOWN_RESEARCH_OPTION_KEYS = /* @__PURE__ */ new Set([
+  // Pre-Phase-21 fetcher controls.
+  "signal",
+  "awcHours",
+  "iemPolitenessMs",
+  "ghcnhPolitenessMs",
+  "cliPolitenessMs",
+  "now",
+  "cache",
+  // Pre-Phase-21 selectors.
+  "city",
+  "contract",
+  "contracts",
+  "stationOverride",
+  "sources",
+  "source",
+  "includeTrades",
+  "onWarning",
+  // Phase 21 21-01: Python-parity composable kwargs.
+  "include_forecast",
+  "forecast_model",
+  "forecast_models",
+  "qc",
+  "tz_override",
+  "backend",
+  "return_type"
+]);
+function validateResearchKwargs(opts) {
+  const present = (v) => v !== void 0 && v !== null;
+  for (const key of Object.keys(opts)) {
+    if (!KNOWN_RESEARCH_OPTION_KEYS.has(key)) {
+      throw new TypeError(
+        `research(): unknown option key ${JSON.stringify(key)}. Valid keys: ${[...KNOWN_RESEARCH_OPTION_KEYS].sort().join(", ")}`
+      );
+    }
+  }
+  if (present(opts.sources) && present(opts.source)) {
+    throw new TypeError(
+      "research(): sources= and source= are mutually exclusive \u2014 use `sources=` for the LIVE_V1 multi-source selector or `source=` for a single-source query, not both"
+    );
+  }
+  if (present(opts.forecast_model) && present(opts.forecast_models)) {
+    throw new TypeError(
+      "research(): forecast_model= and forecast_models= are mutually exclusive \u2014 use `forecast_models=` for multi-model fan-out or `forecast_model=` for a single model, not both"
+    );
+  }
+  const wantsForecast = present(opts.forecast_model) || present(opts.forecast_models);
+  if (wantsForecast && opts.include_forecast !== true) {
+    throw new TypeError(
+      "research(): forecast_model=/forecast_models= require include_forecast=true; the model filter is otherwise silently ignored"
+    );
+  }
+}
+
+// src/research.ts
 var AWC_MAX_HOURS = 168;
 async function resolveCache(opts) {
   if (opts.cache === null) return null;
@@ -304,9 +362,9 @@ async function fetchIemAsosWithCache(stationCode, _fromYear, _extendedToYear, fr
         }
       }
     }
-    for (const obs of monthRows) {
-      const obsDate = obs.observed_at.slice(0, 10);
-      if (obsDate >= fromDate && obsDate <= extendedTo) acc.push(obs);
+    for (const obs2 of monthRows) {
+      const obsDate = obs2.observed_at.slice(0, 10);
+      if (obsDate >= fromDate && obsDate <= extendedTo) acc.push(obs2);
     }
   }
   return acc;
@@ -377,14 +435,22 @@ async function fetchGhcnhWithCache(stationCode, ghcnhId, fromDate, extendedTo, o
         }
       }
     }
-    for (const obs of monthRows) {
-      const obsDate = obs.observed_at.slice(0, 10);
-      if (obsDate >= fromDate && obsDate <= extendedTo) acc.push(obs);
+    for (const obs2 of monthRows) {
+      const obsDate = obs2.observed_at.slice(0, 10);
+      if (obsDate >= fromDate && obsDate <= extendedTo) acc.push(obs2);
     }
   }
   return acc;
 }
 async function research(station, fromDate, toDate, opts = {}) {
+  validateResearchKwargs(opts);
+  if (opts.backend === "polars") {
+    throw new DataAvailabilityError({
+      reason: "model_unavailable",
+      hint: 'polars backend not available in TypeScript SDK; use Python (mostlyrightmd) for backend="polars". TS returns plain object arrays.',
+      source: "research.backend"
+    });
+  }
   const hasCity = typeof opts.city === "string" && opts.city.length > 0;
   const hasContract = typeof opts.contract === "string" && opts.contract.length > 0;
   const hasContracts = Array.isArray(opts.contracts) && opts.contracts.length > 0;
@@ -460,8 +526,8 @@ async function research(station, fromDate, toDate, opts = {}) {
     if (opts.signal !== void 0) awcOpts.signal = opts.signal;
     const awcRaw = await fetchAwcMetars([resolved.icao], awcOpts);
     for (const m of awcRaw) {
-      const obs = awcToObservation(m);
-      if (obs !== null) awcRows.push(obs);
+      const obs2 = awcToObservation(m);
+      if (obs2 !== null) awcRows.push(obs2);
     }
   }
   const iemRows = await fetchIemAsosWithCache(
@@ -492,8 +558,8 @@ async function research(station, fromDate, toDate, opts = {}) {
   const observationsByDate = {};
   const dateLo = dates[0] ?? "";
   const dateHi = dates[dates.length - 1] ?? "";
-  for (const obs of merged) {
-    const settleDate = observedSettlementDate(obs.observed_at, resolved.code);
+  for (const obs2 of merged) {
+    const settleDate = observedSettlementDate(obs2.observed_at, resolved.code);
     if (settleDate === null) continue;
     if (settleDate < dateLo || settleDate > dateHi) continue;
     let bucket = observationsByDate[settleDate];
@@ -501,7 +567,7 @@ async function research(station, fromDate, toDate, opts = {}) {
       bucket = [];
       observationsByDate[settleDate] = bucket;
     }
-    bucket.push(obs);
+    bucket.push(obs2);
   }
   const climateByDate = {};
   for (const cli of mergedClimate) {
@@ -649,8 +715,8 @@ async function researchBySource(station, source, fromDate, toDate, opts = {}) {
       const raw = await fetchAwcMetars2([resolved.icao], awcOpts);
       const parsed = [];
       for (const m of raw) {
-        const obs = awcToObservation2(m);
-        if (obs !== null) parsed.push(obs);
+        const obs2 = awcToObservation2(m);
+        if (obs2 !== null) parsed.push(obs2);
       }
       rows = parsed.filter((r) => {
         const d = r.observed_at.slice(0, 10);
@@ -916,12 +982,21 @@ import {
   validateSource
 } from "@mostlyrightmd/weather";
 import { LiveStreamError, NoLiveDataError } from "@mostlyrightmd/core";
+import {
+  dailyExtremes
+} from "@mostlyrightmd/weather";
+import {
+  obs
+} from "@mostlyrightmd/weather";
+import * as preprocessing from "@mostlyrightmd/core/preprocessing";
+var Preprocessing = preprocessing;
 var version = "0.0.0";
 export {
   LiveStreamError,
   MODE2_SOURCES,
   NoLiveDataError,
   POLITE_FLOORS_S,
+  Preprocessing,
   SELECTOR_NAMES,
   SOURCE_ALIASES,
   SOURCE_IDENTITY_TAGS,
@@ -930,6 +1005,7 @@ export {
   assertSourceIdentity,
   buildOverrideWarning,
   core,
+  dailyExtremes,
   discover,
   helloCore,
   helloMarkets,
@@ -938,6 +1014,8 @@ export {
   isMode2Source,
   latest,
   markets,
+  obs,
+  preprocessing,
   research,
   researchBySource,
   resolveCity,