TypeScript quickstart

The TypeScript SDK ships four packages on npm. The convenience meta-package mostlyright re-exports the surfaces you usually want; the scoped packages (@mostlyrightmd/core, @mostlyrightmd/weather, @mostlyrightmd/markets) let you depend on exactly what you need.

The npm packages ship in lockstep with the Python SDK at the same version (1.13.0).

01 · Get access

Node 18+. The package is ESM-first with CJS fallback. Both import and require work; types ship in the same package.

02 · First call

1
import { dataset } from "mostlyright";
2

3
const rows = await dataset("KNYC", "2025-01-06", "2025-01-12");
4
console.log(rows[0]);

dataset() is the primary composer; research() is a fully working alias (dataset === research) for existing code. It returns Promise<ReadonlyArray<PairsRow>> — a frozen array with one row per LST day in [fromDate, toDate]. Each row carries:

1
type PairsRow = {
2
  date: string;            // YYYY-MM-DD (LST)
3
  station: string;         // 3-letter NWS code
4
  cli_high_f: number | null;
5
  cli_low_f: number | null;
6
  cli_report_type: string | null;
7
  obs_high_f: number | null;
8
  obs_low_f: number | null;
9
  obs_mean_f: number | null;
10
  obs_mean_dewpoint_f: number | null;
11
  obs_max_wind_kt: number | null;
12
  obs_max_gust_kt: number | null;
13
  obs_total_precip_in: number | null;
14
  obs_count: number;
15
  // ... plus fcst_* (null unless include_forecast) and market_close_utc
16
};

cli_* comes from the NWS CLI overnight final (the official daily climate record). obs_* comes from the merged METAR feed: AWC > IEM > GHCNh on tie-break. For the standalone CLI labels, import climate from the subpath: import { climate } from "@mostlyrightmd/weather/climate".

03 · Cache layout

The Node cache writes JSON envelopes (not parquet — parquet is a Python-only choice) to ~/.mostlyright/cache-ts/:

1
~/.mostlyright/cache-ts/
2
├── observations/{ICAO}/{YYYY}/{MM}.json
3
└── climate/{ICAO}/{YYYY}.json

Override the root with MOSTLYRIGHT_CACHE_DIR:

1
export MOSTLYRIGHT_CACHE_DIR=/data/mostlyright

The Python SDK uses cache/v1/ and the TS SDK uses cache-ts/ under the same root, so they never overwrite each other.

04 · Live streaming

For live METAR ticks, use the stream() async generator from @mostlyrightmd/weather:

1
import { stream } from "@mostlyrightmd/weather";
2

3
for await (const row of stream("KNYC")) {
4
  console.log(row.observed_at, row.temp_f);
5
}

Pass an AbortSignal to interrupt cleanly:

1
import { stream } from "@mostlyrightmd/weather";
2

3
const controller = new AbortController();
4
setTimeout(() => controller.abort(), 60_000);
5

6
for await (const row of stream("KNYC", { signal: controller.signal })) {
7
  console.log(row.observed_at, row.temp_f);
8
}

stream() never writes the cache. It dedups by observed_at so AWC’s “latest METAR” repeats between observation cycles collapse to one row per fresh tick.

05 · Browser usage

@mostlyrightmd/core is the only package designed for browser bundles — it ships under a 25 KB size budget. The weather and markets packages depend on Node-only modules (node:fs, node:path for the cache) and should not be bundled for the browser.

For a browser-side call, fetch JSON from your own backend that wraps research(), then validate with @mostlyrightmd/core/validator:

1
import { validateRows } from "@mostlyrightmd/core/validator";
2

3
const response = await fetch("/api/research?station=KNYC&from=2025-01-06&to=2025-01-12");
4
const rows = await response.json();
5
const result = validateRows(rows, "schema.observation.v1");