mostlyright 1.1.2 → 1.2.0

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(index_exports, {
   MODE2_SOURCES: () => MODE2_SOURCES,
   NoLiveDataError: () => import_core4.NoLiveDataError,
   POLITE_FLOORS_S: () => import_weather4.POLITE_FLOORS_S,
+  Preprocessing: () => Preprocessing,
   SELECTOR_NAMES: () => SELECTOR_NAMES,
   SOURCE_ALIASES: () => SOURCE_ALIASES,
   SOURCE_IDENTITY_TAGS: () => import_weather4.SOURCE_IDENTITY_TAGS,
@@ -42,6 +43,7 @@ __export(index_exports, {
   assertSourceIdentity: () => assertSourceIdentity,
   buildOverrideWarning: () => buildOverrideWarning,
   core: () => core,
+  dailyExtremes: () => import_weather5.dailyExtremes,
   discover: () => discover,
   helloCore: () => import_core3.helloCore,
   helloMarkets: () => import_markets2.helloMarkets,
@@ -50,6 +52,8 @@ __export(index_exports, {
   isMode2Source: () => isMode2Source,
   latest: () => import_weather4.latest,
   markets: () => markets,
+  obs: () => import_weather6.obs,
+  preprocessing: () => preprocessing,
   research: () => research,
   researchBySource: () => researchBySource,
   resolveCity: () => resolveCity,
@@ -76,6 +80,63 @@ var import_cache = require("@mostlyrightmd/core/internal/cache");
 var import_merge = require("@mostlyrightmd/core/internal/merge");
 var import_pairs = require("@mostlyrightmd/core/internal/pairs");
 var import_weather = require("@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;
@@ -342,9 +403,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;
@@ -415,14 +476,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 import_core.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;
@@ -498,8 +567,8 @@ async function research(station, fromDate, toDate, opts = {}) {
     if (opts.signal !== void 0) awcOpts.signal = opts.signal;
     const awcRaw = await (0, import_weather.fetchAwcMetars)([resolved.icao], awcOpts);
     for (const m of awcRaw) {
-      const obs = (0, import_weather.awcToObservation)(m);
-      if (obs !== null) awcRows.push(obs);
+      const obs2 = (0, import_weather.awcToObservation)(m);
+      if (obs2 !== null) awcRows.push(obs2);
     }
   }
   const iemRows = await fetchIemAsosWithCache(
@@ -530,8 +599,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];
@@ -539,7 +608,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) {
@@ -675,8 +744,8 @@ async function researchBySource(station, source, fromDate, toDate, opts = {}) {
       const raw = await (0, import_weather2.fetchAwcMetars)([resolved.icao], awcOpts);
       const parsed = [];
       for (const m of raw) {
-        const obs = (0, import_weather2.awcToObservation)(m);
-        if (obs !== null) parsed.push(obs);
+        const obs2 = (0, import_weather2.awcToObservation)(m);
+        if (obs2 !== null) parsed.push(obs2);
       }
       rows = parsed.filter((r) => {
         const d = r.observed_at.slice(0, 10);
@@ -929,6 +998,10 @@ function discover(args) {
 // src/index.ts
 var import_weather4 = require("@mostlyrightmd/weather");
 var import_core4 = require("@mostlyrightmd/core");
+var import_weather5 = require("@mostlyrightmd/weather");
+var import_weather6 = require("@mostlyrightmd/weather");
+var preprocessing = __toESM(require("@mostlyrightmd/core/preprocessing"), 1);
+var Preprocessing = preprocessing;
 var version = "0.0.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -936,6 +1009,7 @@ var version = "0.0.0";
   MODE2_SOURCES,
   NoLiveDataError,
   POLITE_FLOORS_S,
+  Preprocessing,
   SELECTOR_NAMES,
   SOURCE_ALIASES,
   SOURCE_IDENTITY_TAGS,
@@ -944,6 +1018,7 @@ var version = "0.0.0";
   assertSourceIdentity,
   buildOverrideWarning,
   core,
+  dailyExtremes,
   discover,
   helloCore,
   helloMarkets,
@@ -952,6 +1027,8 @@ var version = "0.0.0";
   isMode2Source,
   latest,
   markets,
+  obs,
+  preprocessing,
   research,
   researchBySource,
   resolveCity,