@mostlyrightmd/core/discovery

Classes

DailySummaryGapsNotImplementedError

Compatibility subclass of DataAvailabilityError raised by dailySummaryGaps. Existing catch (e instanceof DailySummaryGapsNotImplementedError) sites keep working; new code should catch the parent class DataAvailabilityError and dispatch on reason === "model_unavailable".

Deprecated

Prefer catching DataAvailabilityError directly.

Extends

DataAvailabilityError

Constructors

new DailySummaryGapsNotImplementedError()

new DailySummaryGapsNotImplementedError(): DailySummaryGapsNotImplementedError

Returns

DailySummaryGapsNotImplementedError

Overrides

DataAvailabilityError.constructor

Properties

defaultErrorCode

readonly static defaultErrorCode: "DATA_AVAILABILITY" = "DATA_AVAILABILITY"

Subclass override — the stable string enum surfaced via errorCode.

Overrides

DataAvailabilityError.defaultErrorCode

errorCode

readonly errorCode: string

Inherited from

DataAvailabilityError.errorCode

hint

readonly hint: string

Inherited from

DataAvailabilityError.hint

reason

readonly reason: "model_unavailable" | "out_of_window" | "cache_miss" | "source_404" | "source_5xx" | "rate_limited"

Inherited from

DataAvailabilityError.reason

requestId

readonly requestId: null | string

Inherited from

DataAvailabilityError.requestId

source

readonly source: null | string

Inherited from

DataAvailabilityError.source

Methods

toDict()

toDict(): Record<string, unknown>

Return a JSON-safe dict suitable for MCP error.data.

Returns

Record<string, unknown>

Inherited from

DataAvailabilityError.toDict

UnknownSchemaError

Thrown by describe when schemaId is not registered.

Extends

MostlyrightError

Constructors

new UnknownSchemaError()

new UnknownSchemaError(message): UnknownSchemaError

Parameters

message

string

Returns

UnknownSchemaError

Overrides

MostlyrightError.constructor

Properties

defaultErrorCode

readonly static defaultErrorCode: "UNKNOWN_SCHEMA" = "UNKNOWN_SCHEMA"

Subclass override — the stable string enum surfaced via errorCode.

Overrides

MostlyrightError.defaultErrorCode

errorCode

readonly errorCode: string

Inherited from

MostlyrightError.errorCode

requestId

readonly requestId: null | string

Inherited from

MostlyrightError.requestId

source

readonly source: null | string

Inherited from

MostlyrightError.source

Methods

toDict()

toDict(): Record<string, unknown>

Return a JSON-safe dict suitable for MCP error.data.

Returns

Record<string, unknown>

Inherited from

MostlyrightError.toDict

Interfaces

AvailabilityOptions

Options for availability().

Properties

validate?

readonly optional validate: boolean

If true, confirm each candidate key with cache.get() before counting. Eliminates the small overcount possible on stores whose listKeys() can return keys with already-expired TTL entries (FsStore and IndexedDBStore lazy-evict on get, not on listKeys). Off by default because the v0.1.0 research() flow never writes with ttlMs, so the overcount window is empty; turn on only if you populate the cache with explicit TTLs.

Cost: one get() per matching key. On warm caches this is cheap (MemoryStore + IndexedDBStore in-memory). On FsStore it reads each candidate’s file.

AvailabilityResult

Cache-coverage summary for a station.

Mirrors Python availability() return shape.

Properties

dailySummaryYears

dailySummaryYears: number

Count of cached daily-summary years.

firstDailySummaryYear

firstDailySummaryYear: null | string

Earliest cached daily-summary year as "YYYY", or null if none.

firstMonth

firstMonth: null | string

Earliest cached month as "YYYY-MM", or null if none.

lastDailySummaryYear

lastDailySummaryYear: null | string

Latest cached daily-summary year as "YYYY", or null if none.

lastMonth

lastMonth: null | string

Latest cached month as "YYYY-MM", or null if none.

monthsCached

monthsCached: number

Count of distinct (year, month) observation cache entries.

station

station: string

BuildSnapshotOptions

Properties

dataVersion?

optional dataVersion: null | DataVersion

knowledgeTime?

optional knowledgeTime: string | Date

metadata?

optional metadata: Record<string, unknown>

rows

rows: readonly Record<string, unknown>[]

schemaId

schemaId: string

source

source: string

DailyExtreme

Properties

localDate

localDate: string

Station-local calendar date as YYYY-MM-DD.

nObs

nObs: number

Count of rows with a parseable temp_c.

precipMm

precipMm: number

Total 1-hour precipitation across the local day, in mm.

sourceTmax

sourceTmax: null | string

Source identifier of the row that produced tmax (or null on low coverage).

sourceTmin

sourceTmin: null | string

Source identifier of the row that produced tmin (or null on low coverage).

tempMaxC

tempMaxC: null | number

Max temperature in °C, or null on low coverage.

tempMaxF

tempMaxF: null | number

Max temperature in °F, or null on low coverage.

tempMeanC

tempMeanC: null | number

Mean temperature in °C, or null on low coverage.

tempMinC

tempMinC: null | number

Min temperature in °C, or null on low coverage.

tempMinF

tempMinF: null | number

Min temperature in °F, or null on low coverage.

DataSnapshot

Frozen snapshot wrapper around row data + provenance.

Properties

dataVersion

readonly dataVersion: null | DataVersion

Optional reproducibility token.

knowledgeTime

readonly knowledgeTime: string

ISO 8601 UTC instant when the snapshot was built (always ends with Z).

metadata

readonly metadata: Readonly<Record<string, unknown>>

Optional arbitrary metadata. JSON-safe-coerced on toDict.

rows

readonly rows: readonly Readonly<Record<string, unknown>>[]

Row payload — opaque to this layer. Frozen.

schemaId

readonly schemaId: string

Schema id the rows conform to.

source

readonly source: string

Source identifier (e.g. iem.archive, awc.live). Snapshot-scoped.

Methods

toDict()

toDict(): Record<string, unknown>

JSON-safe dict form.

Returns

Record<string, unknown>

toToon()

toToon(): string

TOON-v3 tabular form (rows only — provenance lives in the dict form).

Returns

string

DataVersion

Immutable reproducibility token stamping a single research() call.

Properties

codeSha

readonly codeSha: string

dataSha

readonly dataSha: string

schemaIds

readonly schemaIds: readonly string[]

sdkVersion

readonly sdkVersion: string

sources

readonly sources: readonly string[]

token

readonly token: string

DataVersionComponents

Properties

codeSha

codeSha: string

dataSha

dataSha: string

schemaIds

schemaIds: readonly string[]

sdkVersion

sdkVersion: string

sources

sources: readonly string[]

InternationalDailyExtremesOptions

Properties

minObs?

optional minObs: number

Minimum number of observations required for tmin/tmax/tmean to be populated. Defaults to 12 (the Python threshold). Tests can override.

precision?

optional precision: number

Decimal places for HALF_UP rounding. Defaults to 0 (whole °C) — the international convention. Pass 1 for US-station tenths.

stationTz

stationTz: string

IANA timezone identifier for the station, e.g. "Asia/Tokyo". Required.

InternationalRow

Minimal row shape consumed by internationalDailyExtremes.

Properties

event_time_utc?

optional event_time_utc: null | string

ISO 8601 UTC instant. Must end with Z or include an offset.

precipitation_mm_1h?

optional precipitation_mm_1h: null | number

1-hour precipitation total in millimeters.

source?

optional source: null | string

Source identifier (preserved on the tmin/tmax aggregate).

temp_c?

optional temp_c: null | number

Air temperature in degrees Celsius.

KeyEnumerableStore

Optional adapter that lets availability() enumerate keys from a store.

CacheStore’s mandatory contract is opaque key-value: get/set/delete/withLock. Discovery needs to enumerate which keys exist for a station — this is implementation-specific (Memory iterates its Map, IndexedDB uses getAllKeys, Fs walks the directory tree). Stores that support enumeration implement the optional listKeys(prefix) method and availability() uses it; stores without it return zero-coverage but never throw.

Listed keys may exceed the requested prefix in the result (callers filter); listKeys is best-effort.

Extends

CacheStore

Methods

delete()

delete(key): Promise<void>

Parameters

key

string

Returns

Promise<void>

Inherited from

CacheStore.delete

get()

get<T>(key): Promise<null | T>

Type Parameters

• T = unknown

Parameters

key

string

Returns

Promise<null | T>

Inherited from

CacheStore.get

listKeys()

listKeys(prefix): Promise<readonly string[]>

Parameters

prefix

string

Returns

Promise<readonly string[]>

set()

set<T>(key, value, opts?): Promise<void>

Type Parameters

• T = unknown

Parameters

key

string

value

T

opts?

CacheSetOptions

Returns

Promise<void>

Inherited from

CacheStore.set

withLock()

withLock<T>(key, fn): Promise<T>

Type Parameters

• T

Parameters

key

string

fn

() => Promise<T>

Returns

Promise<T>

Inherited from

CacheStore.withLock

Functions

availability()

availability(station, cache, opts): Promise<AvailabilityResult>

Return a summary of cached coverage for station.

Stores without enumeration support return a zero-coverage result with the station name populated (counts all zero, dates null).

Pass { validate: true } to confirm each candidate key via cache.get() — needed if your callers populate the cache with ttlMs and might query after expiry. The v0.1.0 research() flow does not use ttlMs, so the default (fast scan, no validation) is correct for the canonical path.

Parameters

station

string

cache

CacheStore

opts

AvailabilityOptions = {}

Returns

Promise<AvailabilityResult>

buildSnapshot()

buildSnapshot(opts): DataSnapshot

Build a frozen DataSnapshot.

Throws RangeError on invalid knowledgeTime. Row payloads are shallow- cloned and frozen so callers can’t mutate snapshot state post-build.

Parameters

opts

BuildSnapshotOptions

Returns

DataSnapshot

dailySummaryGaps()

dailySummaryGaps(_station, _fromDate, _toDate): never

Climate-gap scanning is unavailable in TypeScript because GHCNh archives are too large for the browser cache.

Parameters

_station

string

_fromDate

string

_toDate

string

Returns

never

Throws

DataAvailabilityError with reason=“model_unavailable” and a hint pointing at the Python SDK as the supported alternative.

dataVersionForResearch()

dataVersionForResearch(args): Promise<DataVersion>

Build a DataVersion for a research() call. Mirrors Python DataVersion.for_research: the codeSha encodes the call signature (research:STATION:FROM:TO) and dataSha is supplied by the caller (typically a cache fingerprint).

The schema ids + source contract match the v0.1.0 Python SDK exactly so tokens computed in TS match tokens computed in Python for the same inputs.

Parameters

args

dataSha

string

fromDate

string

sdkVersion

string

station

string

toDate

string

Returns

Promise<DataVersion>

dataVersionFromComponents()

dataVersionFromComponents(components): Promise<DataVersion>

Build a frozen DataVersion from explicit components.

Mirrors Python DataVersion.from_components: sorts schemaIds + sources internally before the canonical hash so input order does not affect the token, while the returned object keeps the caller’s order on its schemaIds and sources arrays. Sorting the stored arrays too would hide source-priority order — iem.archive, iem.live, awc.live, ghcnh, nws.cli is the precedence Python preserves on the tuple, not alphabetical order.

Parameters

components

DataVersionComponents

Returns

Promise<DataVersion>

describe()

describe(schemaId): string

Return a multi-line description of a registered schema.

Parameters

schemaId

string

Returns

string

Throws

MostlyrightError if schemaId is not registered. The error code is UNKNOWN_SCHEMA so callers can distinguish from validation/IO errors.

internationalDailyExtremes()

internationalDailyExtremes(rows, opts): DailyExtreme[]

Roll up observation rows to per-local-calendar-day temperature extremes.

Parameters

rows

readonly InternationalRow[]

raw observation rows (any source). Rows without a parseable event_time_utc are dropped.

opts

InternationalDailyExtremesOptions

stationTz is required. Optional precision (default 0; pass 1 for US-station tenths) and minObs (default 12).

Returns

DailyExtreme[]

one entry per local calendar day with at least one row. Days with fewer than minObs rows have temps set to null.

registerSchema()

registerSchema(info): void

Register or override a schema for describe(). Built-in v0.1.0 schemas are registered at module load (BUILT_IN_SCHEMAS); callers may add custom schemas or override built-ins (e.g. with richer descriptions).

Parameters

info

SchemaInfo

Returns

void