feat: add value() method to WMT reader for multi-variable point snapshots

Author: philipredstone

wmtiles-js/README.md

@@ -28,54 +28,38 @@ wmt.referenceTime;     // Date
 wmt.variables;         // ReadonlyArray<Variable>
 wmt.timeStepCount;     // 81
 wmt.timeAxis;          // { kind: "regular", start, intervalMs, count } | { kind: "irregular", times }
+```
 
-// Resolve a variable handle once, reuse for many requests.
-const t2m = wmt.variable("temperature_2m");
-
-t2m.unit;              // "K"
-t2m.range;             // { min, max }
-t2m.colormap;          // "magma"
-
-// Fetch one tile (Float32Array of tileSize² values; NaN where NoData).
-const pixels = await t2m.tile({ time: 12, z: 5, x: 16, y: 11 });
+There are two ways to pull data out of a file:
 
-// Or by absolute time — must match a step exactly.
-const pixels2 = await t2m.tile({
-  time: new Date("2026-05-06T12:00:00Z"),
-  z: 5, x: 16, y: 11,
-});
+| You want… | Use | Returns |
+|---|---|---|
+| The value of a few variables at one (lat, lon, time) | [`wmt.value()`](#point-snapshot-wmtvalue) | scalars per variable |
+| The time series of a few variables at one (lat, lon) | [`wmt.forecast()`](#point-time-series-wmtforecast) | `Float32Array` per variable |
+| Raster pixels of a tile to render on a map | [`variable.tile()` / `tiles()`](#tile-rendering-for-maps) | `Float32Array` of pixels |
 
-// Sample a single point (nearest pixel). Defaults z to maxZoom.
-const valueK = await t2m.sample({ time: 12, lat: 52.52, lon: 13.405 });
-```
+Prefer the point APIs (`value`, `forecast`) when you only need scalars. They handle variable lookup, time resolution, and missing-data NaN-filling in one call. The tile API is for map renderers that need full raster pixels per tile.
 
-### Batched tile fetch
+### Point snapshot: `wmt.value()`
 
-For UIs that paint several tiles in one frame, `tiles()` issues 1–2 coalesced
-range requests instead of one per tile (when all tiles share the same
-variable + time block):
+Many variables at one point at one time. Useful for map-click tooltips showing "temperature + wind + precip right here, right now":
 
 ```ts
-const frame = await t2m.tiles({
-  time: 12,
-  coords: [
-    { z: 5, x: 16, y: 11 },
-    { z: 5, x: 17, y: 11 },
-    { z: 5, x: 18, y: 11 },
-  ],
+const snap = await wmt.value({
+  lat: 52.52,
+  lon: 13.405,
+  time: 0,                              // step index or Date
+  variables: ["dbzh", "temperature_2m"],
 });
-// frame[i] is always a Float32Array (NaN-filled if missing/out-of-range).
-```
 
-You can tune coalescing with the `coalesce` option:
-
-```ts
-await t2m.tiles({ time: 12, coords, coalesce: { maxGapBytes: 32_000 } });
+snap.time;            // Date, the resolved absolute time
+snap.values.dbzh;     // number, NaN if missing/NoData
+snap.values.temperature_2m;
 ```
 
-### Forecast / time-series at a point
+### Point time-series: `wmt.forecast()`
 
-Sample one or more variables at a (lat, lon) point across the whole time axis:
+Many variables at one point across the time axis:
 
 ```ts
 const fc = await wmt.forecast({
@@ -84,9 +68,9 @@ const fc = await wmt.forecast({
   variables: ["dbzh", "temperature_2m"],
 });
 
-fc.times;            // Date[] — one per step, aligned with all series
-fc.values.dbzh;      // Float32Array — fc.values.dbzh[i] is at fc.times[i]
-fc.values.dbzh[0];   // NaN if missing/NoData
+fc.times;             // Date[], one per step, aligned with all series
+fc.values.dbzh;       // Float32Array; fc.values.dbzh[i] is at fc.times[i]
+fc.values.dbzh[0];    // NaN if missing/NoData
 ```
 
 Optional `z` (defaults to `maxZoom`) and `timeRange` to restrict the window:
@@ -104,9 +88,55 @@ await wmt.forecast({
 });
 ```
 
-`forecast()` fans out one parallel request per `(variable, time step)` — there is
-no cross-step coalescing, because different time steps live in different blocks.
-Units for each series stay on the variable handle (`wmt.variable("dbzh").unit`).
+`forecast()` fans out one parallel request per `(variable, time step)`. There is no cross-step coalescing, because different time steps live in different blocks. For per-variable metadata (`unit`, `colormap`, `range`) reach for the variable handle: `wmt.variable("dbzh").unit`.
+
+### Tile rendering for maps
+
+Map renderers need the actual raster pixels of a tile, not point samples. Resolve a `Variable` handle once and reuse it for every tile in every frame:
+
+```ts
+const t2m = wmt.variable("temperature_2m");
+
+t2m.unit;              // "K"
+t2m.range;             // { min, max }, feed into your colormap
+t2m.colormap;          // "magma"
+
+// Fetch one tile (Float32Array of tileSize² values; NaN where NoData).
+const pixels = await t2m.tile({ time: 12, z: 5, x: 16, y: 11 });
+
+// Or by absolute time, must match a step exactly.
+const pixels2 = await t2m.tile({
+  time: new Date("2026-05-06T12:00:00Z"),
+  z: 5, x: 16, y: 11,
+});
+```
+
+For UIs that paint several tiles in one frame, `tiles()` coalesces 1 or 2 range requests instead of one per tile (when all tiles share the same variable + time block):
+
+```ts
+const frame = await t2m.tiles({
+  time: 12,
+  coords: [
+    { z: 5, x: 16, y: 11 },
+    { z: 5, x: 17, y: 11 },
+    { z: 5, x: 18, y: 11 },
+  ],
+});
+// frame[i] is always a Float32Array (NaN-filled if missing/out-of-range).
+```
+
+Tune coalescing with the `coalesce` option:
+
+```ts
+await t2m.tiles({ time: 12, coords, coalesce: { maxGapBytes: 32_000 } });
+```
+
+If you only need one pixel and want a plain `number | null` (rather than the wrapped `wmt.value()` result), there is also:
+
+```ts
+const valueK = await t2m.sample({ time: 12, lat: 52.52, lon: 13.405 });
+// number | null  (null = out-of-range zoom / invalid coords; NaN = NoData)
+```
 
 ### Loading from a buffer
 
@@ -121,7 +151,7 @@ const wmt = await open(
 
 ### Custom byte source
 
-Implement the `ByteSource` interface — one method, async byte-range reads:
+Implement the `ByteSource` interface with one method, async byte-range reads:
 
 ```ts
 import { open, type ByteSource } from "wmtiles";
@@ -148,8 +178,8 @@ All thrown errors derive from `WMTError`:
 |---|---|
 | `SourceError` | Source/read failure, for example an HTTP server that ignores range requests. |
 | `FormatError` | Malformed file: bad magic, bad CRC, truncated buffers, unsupported version. |
-| `UnknownVariableError` | `wmt.variable("foo")` for an absent name. |
-| `TimeOutOfRangeError` | `tile()` / `sample()` with a `Date` that doesn't align to a step, or an out-of-range index. |
+| `UnknownVariableError` | `wmt.variable("foo")`, `wmt.value({ variables: ["foo"] })`, etc. for an absent name. |
+| `TimeOutOfRangeError` | A `Date` that doesn't align to a step, an out-of-range index, or `timeRange` where `start > end`. |
 
 ```ts
 import { UnknownVariableError } from "wmtiles";

wmtiles-js/src/index.ts

@@ -20,6 +20,8 @@ export {
   type SampleRequest,
   type ForecastRequest,
   type ForecastResult,
+  type ValueRequest,
+  type ValueResult,
 } from "./reader.js";
 
 // Typed errors.

wmtiles-js/src/reader.test.ts

@@ -213,6 +213,38 @@ test("WMT.forecast validates inputs and signals missing data with NaN", async ()
   for (const v of fc.values.temp) expect(Number.isNaN(v)).toBe(true);
 });
 
+test("WMT.value returns a snapshot of many variables at one time", async () => {
+  const r = await WMT.open(bytesSource(load("multistep.wmt")));
+
+  // step 2 → temp = 102, wind = 202 (offset + step from fixture)
+  const snap = await r.value({
+    lat: 0, lon: 0, time: 2, variables: ["temp", "wind"],
+  });
+  expect(snap.time.toISOString()).toBe("2026-05-03T02:00:00.000Z");
+  expect(snap.values.temp).toBe(102);
+  expect(snap.values.wind).toBe(202);
+
+  // Date-based time ref must produce the same result.
+  const byDate = await r.value({
+    lat: 0, lon: 0,
+    time: new Date("2026-05-03T02:00:00Z"),
+    variables: ["temp"],
+  });
+  expect(byDate.values.temp).toBe(102);
+
+  // Unknown variable name throws before any I/O.
+  await expect(
+    r.value({ lat: 0, lon: 0, time: 0, variables: ["nope"] }),
+  ).rejects.toBeInstanceOf(UnknownVariableError);
+
+  // Invalid coords → NaN per variable (never null).
+  const oob = await r.value({
+    lat: 91, lon: 0, time: 0, variables: ["temp", "wind"],
+  });
+  expect(Number.isNaN(oob.values.temp)).toBe(true);
+  expect(Number.isNaN(oob.values.wind)).toBe(true);
+});
+
 test("crc_corrupted.wmt falls back to previous snapshot", async () => {
   const r = await WMT.open(bytesSource(load("crc_corrupted.wmt")));
   const names = r.variables.map((v) => v.name).sort();

wmtiles-js/src/reader.ts

@@ -121,6 +121,22 @@ export interface ForecastResult {
   readonly values: Readonly<Record<string, Float32Array>>;
 }
 
+export interface ValueRequest {
+  lat: number;
+  lon: number;
+  time: TimeRef;
+  variables: readonly string[];
+  /** Defaults to maxZoom of the file. */
+  z?: number;
+}
+
+export interface ValueResult {
+  /** Resolved absolute time (matters when caller passed a step index). */
+  readonly time: Date;
+  /** NaN marks missing/NoData. Key set equals req.variables. */
+  readonly values: Readonly<Record<string, number>>;
+}
+
 // ---------- Sources ----------
 
 export function httpSource(url: string | URL, init?: RequestInit): ByteSource {
@@ -524,6 +540,27 @@ export class WMT {
     return { times, values };
   }
 
+  /**
+   * Snapshot of several variables at one point at one time. The dual of
+   * forecast(): same point, single time step, many variables. NaN = missing.
+   */
+  async value(req: ValueRequest): Promise<ValueResult> {
+    const vars = req.variables.map((name) => this.variable(name));
+    const t = this.timeIndexOf(req.time);
+    const z = req.z ?? this._header.maxZoom;
+
+    const values: Record<string, number> = {};
+    await Promise.all(
+      vars.map(async (v) => {
+        const val = await this._sample(v.id, t, req.lat, req.lon, z);
+        // null = out-of-bbox / out-of-range zoom / missing tile → NaN.
+        values[v.name] = val ?? NaN;
+      }),
+    );
+
+    return { time: this.timeAt(t), values };
+  }
+
   // ---- Internal: fetch helpers (called by Variable) ----
 
   private async _fetchTile(